122 lines
6.1 KiB
ReStructuredText
122 lines
6.1 KiB
ReStructuredText
Submitting new features for inclusion in LAMMPS
|
|
===============================================
|
|
|
|
We encourage LAMMPS users to submit new features they wrote for LAMMPS
|
|
to be included into the LAMMPS distribution and thus become easily
|
|
accessible to all LAMMPS users. The LAMMPS source code is managed with
|
|
git and public development is hosted on `GitHub
|
|
<https://github.com/lammps/lammps>`_. You can monitor the repository to
|
|
be notified of releases, follow the ongoing development, and comment on
|
|
topics of interest to you. This section contains general information
|
|
regarding the preparation and submission of new features to LAMMPS. If
|
|
you are new to development in LAMMPS, we recommend you read one of the
|
|
tutorials on developing a new :doc:`pair style <Developer_write_pair>` or
|
|
:doc:`fix style <Developer_write_fix>` which provide a friendly
|
|
introduction to what LAMMPS development entails and common vocabulary
|
|
used in this chapter.
|
|
|
|
|
|
Communication with the LAMMPS developers
|
|
----------------------------------------
|
|
|
|
For any larger modifications or programming project, you are encouraged
|
|
to contact the LAMMPS developers ahead of time to discuss implementation
|
|
strategies. That will make it easier to integrate your contribution and
|
|
results in less work for everybody involved. You are also encouraged to
|
|
search through the list of `open issues on GitHub
|
|
<https://github.com/lammps/lammps/issues>`_ and submit a new issue for a
|
|
planned feature, to avoid duplicating work (and possibly being scooped).
|
|
|
|
For informal communication with the LAMMPS developers you may ask to
|
|
join the `LAMMPS developers on Slack <https://lammps.slack.com>`_. This
|
|
slack work space is by invitation only. Thus for access, please send an
|
|
e-mail to ``slack@lammps.org`` explaining what part of LAMMPS you are
|
|
working on. Only discussions related to LAMMPS development are
|
|
tolerated in that work space, so this is **NOT** for people that look
|
|
for help with compiling, installing, or using LAMMPS. Please post a
|
|
message to the `LAMMPS forum <https://www.lammps.org/forum.html>`_ for
|
|
those purposes.
|
|
|
|
|
|
Time and effort required
|
|
------------------------
|
|
|
|
How quickly your contribution will be integrated can vary a lot. It
|
|
depends largely on how much effort it will cause the LAMMPS developers
|
|
to integrate and test it, how many and what kind of changes to the core
|
|
code are required, how quickly you can address them and of how much
|
|
interest it is to the larger LAMMPS community. This process can be
|
|
streamlined by following the :doc:`requirements <Modify_requirements>` and :doc:`style guidelines<Modify_style>`. A small, modular, well written
|
|
contribution may be integrated within hours, but a complex change that
|
|
requires a redesign of some core functionality in LAMMPS can take months
|
|
before inclusion (though this is rare).
|
|
|
|
|
|
Submission procedure
|
|
--------------------
|
|
|
|
All changes to LAMMPS (including those from LAMMPS developers) are
|
|
integrated via pull requests on GitHub and cannot be merged without
|
|
passing the automated testing and an approving review by a LAMMPS core
|
|
developer. Thus before submitting your contribution, you should first
|
|
make certain, that your added or modified code compiles and works
|
|
correctly with the latest development version of LAMMPS and contains all
|
|
bug fixes from it.
|
|
|
|
Once you have prepared everything, see the :doc:`LAMMPS GitHub Tutorial
|
|
<Howto_github>` page for instructions on how to submit your changes or
|
|
new files through a GitHub pull request. If you are unable or unwilling
|
|
to submit via GitHub yourself, you may also submit patch files
|
|
or full files to the LAMMPS developers and ask them to submit a pull
|
|
request on GitHub on your behalf. If this is the case, create a gzipped
|
|
tar file of all new or changed files or a corresponding patch file using
|
|
'diff -u' or 'diff -c' format and compress it with gzip. Please only
|
|
use gzip compression, as this works well and is available on all platforms.
|
|
This latter way of submission may delay the integration as it depends on
|
|
the LAMMPS developer having free time available.
|
|
|
|
|
|
External contributions
|
|
----------------------
|
|
|
|
If you prefer to do so, you can also develop and support your add-on
|
|
feature **without** having it included in the LAMMPS distribution, for
|
|
example as a download from a website of your own. See the `External
|
|
LAMMPS packages and tools <https://www.lammps.org/external.html>`_ page
|
|
of the LAMMPS website for examples of groups that do this. We are happy
|
|
to advertise your package and website from that page. Simply email the
|
|
`developers <https://www.lammps.org/authors.html>`_ with info about your
|
|
package and we will post it there. We recommend to name external
|
|
packages USER-\<name\> so they can be easily distinguished from bundled
|
|
packages that do not have the USER- prefix.
|
|
|
|
|
|
Location of files: individual files and packages
|
|
------------------------------------------------
|
|
|
|
We rarely accept new styles in the core src folder. Thus please review
|
|
the list of :doc:`available Packages <Packages_details>` to see if your
|
|
contribution could be added to be added to one of them. It should fit
|
|
into the general purposed of that package. If it does not fit well, it
|
|
may be added to one of the EXTRA- packages or the MISC package.
|
|
|
|
However if your project includes many related features that are not
|
|
covered by one of the existing packages or is dependent on a library
|
|
(bundled or external), it is best to create a package with its own
|
|
directory (labeled with a name like FOO). In addition to your new
|
|
files, the directory should contain a README text file containing your
|
|
name and contact information and a brief description of what your new
|
|
package does.
|
|
|
|
|
|
Changes to core LAMMPS files
|
|
--------------------------------
|
|
|
|
If designed correctly, many additions do not require any changes to the
|
|
core code of LAMMPS; they are simply add-on files that are compiled with
|
|
the rest of LAMMPS. To make those styles work, you may need some trivial
|
|
changes to the core code; an example of a trivial change is making a
|
|
parent-class method "virtual" when you derive a new child class from it.
|
|
If your features involve changes to the core LAMMPS files, it is particularly
|
|
encouraged that you communicate with the LAMMPS developers early in development.
|