3.2. 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. You can monitor the repository to be notified of releases, follow the ongoing development, and comment on topics of interest to you.
3.2.1. Communication with the LAMMPS developers¶
For any larger modifications or programming project, you are encouraged to contact the LAMMPS developers ahead of time in order to discuss implementation strategies and coding guidelines. 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 and submit a new issue for a planned feature, so you would not duplicate the work of others (and possibly get scooped by them) or have your work duplicated by others.
For informal communication with the LAMMPS developers you may ask to
join the LAMMPS developers on Slack. This
slack work space is by invitation only. Thus for access, please send an
firstname.lastname@example.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-users mailing list
or the LAMMPS forum for those
3.2.2. Packages versus individual files¶
The remainder of this chapter describes how to add new “style” files of various kinds to LAMMPS. Packages are simply collections of one or more such new class files which are invoked as a new style within a LAMMPS input script. In some cases also collections of supporting functions or classes are included as separate files in a package, especially when they can be shared between multiple styles. If designed correctly, these additions typically 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 you think your new feature or package requires some non-trivial changes in core LAMMPS files, you should communicate with the LAMMPS developers on Slack, on GitHub, or via email, since we may have recommendations about what changes to do where, or may not want to include certain changes for some reason and thus you would need to look for alternatives.
3.2.3. 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. Please see the section on LAMMPS programming style and requirements for instructions, recommendations, and formal requirements. A small, modular, well written contribution may be integrated within hours, but a complex change that will require a redesign of some core functionality in LAMMPS for a clean integration can take many months until it is considered ready for inclusion (though this is rare).
3.2.4. 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 patch-level or development version of LAMMPS and contains all bug fixes from it.
Once you have prepared everything, see the LAMMPS GitHub Tutorial page for instructions on how to submit your changes or new files through a GitHub pull request yourself. 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. Then create a gzipped tar file of all changed or added 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.
Note that by providing us files to release, you agree to make them open-source, i.e. we can release them under the terms of the GPL (version 2) with the rest of LAMMPS. And similarly as part of a LGPL (version 2.1) distribution of LAMMPS that we make available to developers on request only and with files that are not authorized for that kind of distribution removed (e.g. interface to FFTW). See the LAMMPS license page for details.
3.2.6. 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 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 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.