ICODE-ADC/lammps
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

minor editing changes

Browse Source
This commit is contained in:
Steve Plimpton
2023-05-12 11:18:07 -06:00
parent a6f60405b6
commit b54d39adf9
5 changed files with 348 additions and 337 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
doc/src/Modify.rst
View File

@ -10,15 +10,15 @@ functions and classes are given in :doc:`Developer`.
If you add a new feature to LAMMPS and think it will be of general If you add a new feature to LAMMPS and think it will be of general
interest to other users, we encourage you to submit it for inclusion in interest to other users, we encourage you to submit it for inclusion in
LAMMPS. This process is explained in the following three pages: LAMMPS. This process is explained in the following three pages:
:doc:`how to prepare and submit your code <Modify_contribute>`,
:doc:`requirements for submissions <Modify_requirements>`, and * :doc:`how to prepare and submit your code <Modify_contribute>`
:doc:`style guidelines <Modify_style>`. * :doc:`requirements for submissions <Modify_requirements>`
* :doc:`style guidelines <Modify_style>`
A summary description of various types of styles in LAMMPS follows. A summary description of various types of styles in LAMMPS follows.
A discussion of implementing specific styles from scratch is given A discussion of implementing specific styles from scratch is given
in :doc:`writing new styles <Developer_write>`. in :doc:`writing new styles <Developer_write>`.
.. toctree:: .. toctree::
:maxdepth: 1 :maxdepth: 1

148
doc/src/Modify_contribute.rst
View File

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

83
doc/src/Modify_overview.rst
View File

@ -1,42 +1,44 @@
Overview Overview
======== ========
The best way to add a new feature to LAMMPS is to find a similar feature The best way to add a new feature to LAMMPS is to find a similar
and look at the corresponding source and header files to figure out what feature and look at the corresponding source and header files to
it does. You will need some knowledge of C++ to be able to understand figure out what it does. You will need some knowledge of C++ to
the high-level structure of LAMMPS and its class organization. understand the high-level structure of LAMMPS and its class
Functions (class methods) that do actual computations are mostly written organization. Functions (class methods) that do actual computations
in C-style code and operate on simple C-style data structures (vectors are mostly written in C-style code and operate on simple C-style data
and arrays). A high-level overview of the programming style choices in structures (vectors and arrays). A high-level overview of the
LAMMPS is :doc:`given elsewhere <Developer_code_design>`. programming style choices in LAMMPS is :doc:`given elsewhere
<Developer_code_design>`.
Most of the new features described on the :doc:`Modify <Modify>` doc Most of the new features described on the :doc:`Modify <Modify>` doc
page require you to write a new C++ derived class (except for exceptions page require you to write a new C++ derived class (except for
described below, where you can make small edits to existing files). exceptions described below, where you can make small edits to existing
Creating a new class requires 2 files, a source code file (\*.cpp) and a files). Creating a new class requires 2 files, a source code file
header file (\*.h). The derived class must provide certain methods to (\*.cpp) and a header file (\*.h). The derived class must provide
work as a new option. Depending on how different your new feature is certain methods to work as a new option. Depending on how different
compared to existing features, you can either derive from the base class your new feature is compared to existing features, you can either
itself, or from a derived class that already exists. Enabling LAMMPS to derive from the base class itself, or from a derived class that
invoke the new class is as simple as putting the two source files in the already exists. Enabling LAMMPS to invoke the new class is as simple
src directory and re-building LAMMPS. as putting the two source files in the src directory and re-building
LAMMPS.
The advantage of C++ and its object-orientation is that all the code and The advantage of C++ and its object-orientation is that all the code
variables needed to define the new feature are in the 2 files you write. and variables needed to define the new feature are in the 2 files you
Thus, it should not make the rest of LAMMPS more complex or cause bugs write. Thus, it should not make the rest of LAMMPS more complex or
through unwanted side effects. cause bugs through unwanted side effects.
Here is a concrete example. Suppose you write 2 files ``pair_foo.cpp`` Here is a concrete example. Suppose you write 2 files
and ``pair_foo.h`` that define a new class ``PairFoo`` that computes ``pair_foo.cpp`` and ``pair_foo.h`` that define a new class
pairwise potentials described in the classic 1997 :ref:`paper <Foo>` by ``PairFoo`` which computes pairwise potentials described in the
Foo, *et al.* If you wish to invoke those potentials in a LAMMPS input classic 1997 :ref:`paper <Foo>` by Foo, *et al.* If you wish to invoke
script with a command like: those potentials in a LAMMPS input script with a command like:
.. code-block:: LAMMPS .. code-block:: LAMMPS
pair_style foo 0.1 3.5 pair_style foo 0.1 3.5
Then your ``pair_foo.h`` file should be structured as follows: then your ``pair_foo.h`` file should be structured as follows:
.. code-block:: c++ .. code-block:: c++
@ -59,20 +61,19 @@ the executable and can be invoked with a pair_style command like the
example above. Arguments like 0.1 and 3.5 can be defined and example above. Arguments like 0.1 and 3.5 can be defined and
processed by your new class. processed by your new class.
As illustrated by this example pair style, many kinds of options are As illustrated by this example, many features referred to in the
referred to in the LAMMPS documentation as the "style" of a particular LAMMPS documentation are called a "style" of a particular command.
command.
The :doc:`Modify page <Modify>` lists all the common styles in LAMMPS, The :doc:`Modify page <Modify>` lists all the common styles in LAMMPS,
and discusses the header file for the base class that these styles are and discusses the header file for the base class that these styles
derived from. Public variables in that file are ones used and set by derive from. Public variables in that file can be used and set by the
the derived classes, which are also used by the base class. Sometimes derived classes, and may also be used by the base class. Sometimes
they are also used by the rest of LAMMPS. Pure functions, which means they are also accessed by the rest of LAMMPS. Pure functions, which
functions declared as virtual in the base class header file which are means functions declared as virtual in the base class header file and
also set to 0, are functions you **must** implement in your new derived which are also set to 0, are functions you **must** implement in your
class to give it the functionality LAMMPS expects. Virtual functions new derived class to give it the functionality LAMMPS expects. Virtual
that are not set to 0 are functions you may override or not. Those functions that are not set to 0 are functions you may override or not.
are usually defined with an empty function body. Those are usually defined with an empty function body.
Additionally, new output options can be added directly to the Additionally, new output options can be added directly to the
thermo.cpp, dump_custom.cpp, and variable.cpp files. These are also thermo.cpp, dump_custom.cpp, and variable.cpp files. These are also
@ -86,8 +87,8 @@ functionality:
quickly done that way. quickly done that way.
* Do not try to do anything within the timestepping of a run that is not * Do not try to do anything within the timestepping of a run that is not
parallel. For example, do not accumulate a bunch of data on a single parallel. For example, do not accumulate a bunch of data on a single
processor and analyze it. You run the risk of seriously degrading processor and analyze it. That would run the risk of seriously degrading
the parallel efficiency this way. the parallel efficiency.
* If your new feature reads arguments or writes output, make sure you * If your new feature reads arguments or writes output, make sure you
follow the unit conventions discussed by the :doc:`units <units>` follow the unit conventions discussed by the :doc:`units <units>`
command. command.

303
doc/src/Modify_requirements.rst
View File

@ -10,23 +10,23 @@ Motivation
The LAMMPS developers are committed to provide a software package that The LAMMPS developers are committed to provide a software package that
is versatile, reliable, high-quality, efficient, portable, and easy to is versatile, reliable, high-quality, efficient, portable, and easy to
maintain and modify. Achieving all of these goals is challenging since maintain and modify. Achieving all of these goals is challenging
a large part of LAMMPS consists of contributed code from many different since a large part of LAMMPS consists of contributed code from many
authors and not many of them are professionally trained programmers and different authors who may not be professionally trained programmers or
familiar with the idiosyncrasies of maintaining a large software familiar with the idiosyncrasies of maintaining a large software
package. In addition, changes that interfere with the parallel package. In addition, changes that interfere with the parallel
efficiency of the core code must be avoided. As LAMMPS continues to efficiency of the core code must be avoided. As LAMMPS continues to
grow and more features and functionality are added, it becomes a grow and more features and functionality are added, it's necessary to
necessity to be more discriminating with new contributions while also follow established guidelines when accepting new contributions while
working at the same time to improve the existing code. also working at the same time to improve the existing code.
The following requirements and recommendations are provided as a guide The following requirements and recommendations are provided as a
to maintain or improve that status. It is indicated which individual guide. They indicate which individual requirements are strict, and
requirements are strict, and which represent a preference and thus are which represent a preference and thus are negotiable or optional.
negotiable or optional. Please feel free to contact the LAMMPS core Please feel free to contact the LAMMPS core developers in case you
developers in case you need additional explanations or clarifications, need additional explanations or clarifications, or you need assistance
or in case you need assistance in realizing the (strict) requirements in implementing the (strict) requirements for your contributions.
for your contributions. Requirements include: Requirements include:
* :ref:`Licensing requirements <ReqLicense>` (strict) * :ref:`Licensing requirements <ReqLicense>` (strict)
* :ref:`Integration testing <ReqIntegrationTesting>` (strict) * :ref:`Integration testing <ReqIntegrationTesting>` (strict)
@ -48,44 +48,44 @@ Licensing requirements (strict)
Contributing authors agree when submitting a pull request that their Contributing authors agree when submitting a pull request that their
contributions can be distributed under the LAMMPS license conditions. contributions can be distributed under the LAMMPS license conditions.
This is the GNU public license in version 2 (not 3 or later) for the This is the GNU public license in version 2 (not 3 or later) for the
publicly distributed versions, e.g. on the LAMMPS homepage or on GitHub. publicly distributed versions, e.g. on the LAMMPS homepage or on
We also make a version of LAMMPS under LGPL 2.1 terms available on GitHub. We also make a version of LAMMPS under LGPL 2.1 terms whcih
request; this will usually be the latest available or a previous stable is available on request; this will usually be the latest available or
version with a few LGPL 2.1 incompatible files removed. More details a previous stable version with a few LGPL 2.1 incompatible files
are found on the :doc:`LAMMPS open-source license page removed. More details are found on the :doc:`LAMMPS open-source
<Intro_opensource>`. license page <Intro_opensource>`.
Your new source files should have the LAMMPS copyright, GPL notice, and Your new source files should have the LAMMPS copyright and GPL notice,
your name and email address at the top, like other user-contributed followed by your name and email address at the top, like other
LAMMPS source files. user-contributed LAMMPS source files.
Contributions may be under a different license as long as that Contributions may be under a different license as long as that license
license does not conflict with the aforementioned terms. Contributions does not conflict with the aforementioned terms. Contributions that
that use code with a conflicting license can be split into two parts: use code with a conflicting license can be split into two parts:
1. the core parts (i.e. parts that must be in the `src` tree) that are 1. the core parts (i.e. parts that must be in the `src` tree) that are
licensed under compatible terms and bundled with the LAMMPS sources licensed under compatible terms and bundled with the LAMMPS sources
2. an external library that must be downloaded and compiled (either 2. an external library that must be downloaded and compiled (either
separately or as part of the LAMMPS compilation) separately or as part of the LAMMPS compilation)
Please note, that this split licensed mode may complicate including the Please note, that this split licensing mode may complicate including
contribution in binary packages. the contribution in binary packages.
.. _ReqIntegrationTesting: .. _ReqIntegrationTesting:
Integration testing (strict) Integration testing (strict)
---------------------------- ----------------------------
Where possible we utilize available continuous integration tools to Where possible we use available continuous integration tools to search
search for common programming mistakes, portability limitations, for common programming mistakes, portability limitations, incompatible
incompatible formatting, and undesired side effects. Contributed code formatting, and undesired side effects. Contributed code must pass the
must pass the automated tests on GitHub before it can be merged with automated tests on GitHub before it can be merged with the LAMMPS
the LAMMPS distribution. These tests compile LAMMPS in a variety of distribution. These tests compile LAMMPS in a variety of environments
environments and settings and run the bundled unit tests. At the and settings and run the bundled unit tests. At the discretion of the
discretion of the LAMMPS developer managing the pull request, LAMMPS developer managing the pull request, additional tests may be
additional tests may be activated that test for "side effects" on activated that test for "side effects" on running a collection of
running a collection of input decks and create consistent results. input decks and create consistent results. The translation of the
The translation of the documentation to HTML and PDF is also tested. documentation to HTML and PDF is also tested.
This means that contributed source code **must** compile with the most This means that contributed source code **must** compile with the most
current version of LAMMPS with ``-DLAMMPS_BIGBIG`` in addition to the current version of LAMMPS with ``-DLAMMPS_BIGBIG`` in addition to the
@ -94,8 +94,8 @@ correctly in both cases, and also in serial and parallel using MPI.
Some "disruptive" changes may break tests and require updates to the Some "disruptive" changes may break tests and require updates to the
testing tools or scripts or tests themselves. This is rare. If in testing tools or scripts or tests themselves. This is rare. If in
doubt, contact the LAMMPS developer that is assigned to the pull request. doubt, contact the LAMMPS developer that is assigned to the pull
request.
.. _ReqDocumentation: .. _ReqDocumentation:
@ -105,60 +105,62 @@ Documentation (strict)
Contributions that add new styles or commands or augment existing ones Contributions that add new styles or commands or augment existing ones
must include the corresponding new or modified documentation in must include the corresponding new or modified documentation in
`ReStructuredText format <rst_>`_ (.rst files in the ``doc/src/`` `ReStructuredText format <rst_>`_ (.rst files in the ``doc/src/``
folder). The documentation shall be written in American English and the folder). The documentation should be written in American English and
.rst file must use only ASCII characters, so it can be cleanly translated the .rst file must only ues ASCII characters, so it can be cleanly
to PDF files (via `sphinx <https://www.sphinx-doc.org>`_ and PDFLaTeX). translated to PDF files (via `sphinx <https://www.sphinx-doc.org>`_
Special characters may be included via embedded math expression typeset and PDFLaTeX). Special characters may be included via embedded math
in a LaTeX subset. expression typeset in a LaTeX subset.
.. _rst: https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html .. _rst: https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html
When adding new commands, they need to be integrated into the sphinx When adding new commands, they need to be integrated into the sphinx
documentation system, and the corresponding command tables and lists documentation system, and the corresponding command tables and lists
updated. When translating the documentation into html files there should updated. When translating the documentation into html files there
be no warnings. When adding a new package also some lists describing should be no warnings. When adding a new package, some lists
packages must be updated as well as a package specific description added describing packages must also be updated as well as a package specific
and, if necessary, some package specific build instructions included. description added. Likewise, if necessary, some package specific
build instructions should be included.
As appropriate, the text files with the documentation can include inline As appropriate, the text files with the documentation can include
mathematical expressions or figures (see ``doc/JPG`` for examples). inline mathematical expressions or figures (see ``doc/JPG`` for
Additional PDF files with further details (see ``doc/PDF`` for examples) examples). Additional PDF files with further details may also be
may also be included. The page should also include literature citations included; see ``doc/PDF`` for examples. The page should also include
as appropriate; see the bottom of ``doc/fix_nh.rst`` for examples and literature citations as appropriate; see the bottom of
the earlier part of the same file for how to format the cite itself. ``doc/fix_nh.rst`` for examples and the earlier part of the same file
Citation labels must be unique across **all** .rst files. The for how to format the cite itself. Citation labels must be unique
"Restrictions" section of the page should indicate if your command is across **all** .rst files. The "Restrictions" section of the page
only available if LAMMPS is built with the appropriate FOO package. See should indicate if your command is only available if LAMMPS is built
other package doc files for examples of how to do this. with the appropriate package. See other command doc files for
examples of how to do this.
Please run at least "make html" and "make spelling" and carefully Please run at least "make html" and "make spelling" from within the
inspect and proofread the resulting HTML format doc page before doc/src directory, and carefully inspect and proofread the resulting
submitting your code. Upon submission of a pull request, checks for HTML format doc page before submitting your code. Upon submission of
error free completion of the HTML and PDF build will be performed and a pull request, checks for error free completion of the HTML and PDF
also a spell check, a check for correct anchors and labels, and a check build will be performed and also a spell check, a check for correct
for completeness of references to all styles in their corresponding anchors and labels, and a check for completeness of references to all
tables and lists is run. In case the spell check reports false styles in their corresponding tables and lists is run. In case the
positives, they can be added to the file spell check reports false positives, they can be added to the file
``doc/utils/sphinx-config/false_positives.txt`` ``doc/utils/sphinx-config/false_positives.txt``
Contributions that add or modify the library interface or "public" APIs Contributions that add or modify the library interface or "public"
from the C++ code or the Fortran module must include suitable doxygen APIs from the C++ code or the Fortran module must include suitable
comments in the source and corresponding changes to the documentation doxygen comments in the source and corresponding changes to the
sources for the "Programmer Guide" guide section of the LAMMPS manual. documentation sources for the "Programmer Guide" guide section of the
LAMMPS manual.
If your feature requires some more complex steps and explanations to be If your feature requires some more complex steps and explanations to
used correctly or some external or bundled tools or scripts, we be used correctly or some external or bundled tools or scripts, we
recommend that you also contribute a :doc:`Howto document <Howto>` recommend that you also contribute a :doc:`Howto document <Howto>`
providing some more background information and some tutorial material. providing some more background information and some tutorial material.
This can also be used to provide more in-depth explanations for bundled This can also be used to provide more in-depth explanations of models
examples. that require use of multiple commands.
As a rule-of-thumb, the more clear and self-explanatory you make As a rule-of-thumb, the more clear and self-explanatory you make your
your documentation, README files and examples, and the easier you make documentation, README files and examples, and the easier you make it
it for people to get started, the more likely it is that users will try for people to get started, the more likely it is that users will try
out your new feature. out your new feature.
.. _ReqProgrammingStandards: .. _ReqProgrammingStandards:
Programming language standards (strict) Programming language standards (strict)
@ -166,30 +168,29 @@ Programming language standards (strict)
The core of LAMMPS is written in C++11 in a style that can be mostly The core of LAMMPS is written in C++11 in a style that can be mostly
described as "C with classes". Advanced C++ features like operator described as "C with classes". Advanced C++ features like operator
overloading or excessive use of templates are avoided with the intent to overloading or excessive use of templates are avoided with the intent
keep the code readable to programmers that have limited C++ programming to keep the code readable to programmers that have limited C++
experience. C++ constructs are acceptable when they help improve the programming experience. C++ constructs are acceptable when they help
readability and reliability of the code, e.g. when using the improve the readability and reliability of the code, e.g. when using
`std::string` class instead of manipulating pointers and calling the the `std::string` class instead of manipulating pointers and calling
string functions of the C library. In addition, a collection of the string functions of the C library. In addition, a collection of
convenient :doc:`utility functions and classes <Developer_utils>` for convenient :doc:`utility functions and classes <Developer_utils>` for
recurring tasks and a collection of recurring tasks and a collection of :doc:`platform neutral functions
:doc:`platform neutral functions <Developer_platform>` for improved <Developer_platform>` for improved portability are provided.
portability are provided.
Included Fortran code has to be compatible with the Fortran 2003 Included Fortran code has to be compatible with the Fortran 2003
standard. Python code must be compatible with Python 3.5. Large parts standard. Python code must be compatible with Python 3.5. Large
of LAMMPS (including the :ref:`PYTHON package <PKG-PYTHON>`) are also parts of LAMMPS (including the :ref:`PYTHON package <PKG-PYTHON>`) are
compatible with Python 2.7. Compatibility with Python 2.7 is also compatible with Python 2.7. Compatibility with Python 2.7 is
desirable, but compatibility with Python 3.5 is **required**. desirable, but compatibility with Python 3.5 is **required**.
Compatibility with these older programming language standards is very Compatibility with these older programming language standards is very
important to maintain portability and availability of LAMMPS on many important to maintain portability and availability of LAMMPS on many
platforms. This applies especially to HPC cluster environments, which platforms. This applies especially to HPC cluster environments, which
tend to be running older software stacks and LAMMPS users may be tend to be running older software stacks and where LAMMPS users may be
required to use those older tools for access to advanced hardware required to use those older tools for access to advanced hardware
features or not have the option to install newer compilers or libraries. features or not have the option to install newer compilers or
libraries.
.. _ReqBuildSystem: .. _ReqBuildSystem:
@ -206,18 +207,19 @@ independent feature, it is usually only required to add them to
`src/.gitignore``. `src/.gitignore``.
For traditional make, if your contributed files or package depend on For traditional make, if your contributed files or package depend on
other LAMMPS style files or packages also being installed (e.g. because other LAMMPS style files or packages also being installed
your file is a derived class from the other LAMMPS class), then an (e.g. because your file is a derived class from the other LAMMPS
Install.sh file is also needed to check for those dependencies and class), then an Install.sh file is also needed to check for those
modifications to src/Depend.sh to trigger the checks. See other README dependencies and modifications to src/Depend.sh to trigger the checks.
and Install.sh files in other directories as examples. See other README and Install.sh files in other directories as
examples.
Similarly, for CMake support, changes may need to be made to Similarly, for CMake support, changes may need to be made to
cmake/CMakeLists.txt, some of the files in cmake/presets, and possibly a cmake/CMakeLists.txt, some of the files in cmake/presets, and possibly
file with specific instructions needs to be added to a file with specific instructions needs to be added to
cmake/Modules/Packages/. Please check out how this is handled for cmake/Modules/Packages/. Please check out how this is handled for
existing packages and ask the LAMMPS developers if you need assistance. existing packages and ask the LAMMPS developers if you need
assistance.
.. _ReqNaming: .. _ReqNaming:
@ -229,33 +231,33 @@ should only use letters, numbers, or forward slashes. They should be
descriptive and initialisms should be avoided unless they are well descriptive and initialisms should be avoided unless they are well
established (e.g. lj for Lennard-Jones). For a compute style established (e.g. lj for Lennard-Jones). For a compute style
"some/name" the source files must be called `compute_some_name.h` and "some/name" the source files must be called `compute_some_name.h` and
`compute_some_name.cpp`. The "include guard" would then be `compute_some_name.cpp`. The "include guard" in the header file would
`LMP_COMPUTE_SOME_NAME_H` and the class name `ComputeSomeName`. then be `LMP_COMPUTE_SOME_NAME_H` and the class name
`ComputeSomeName`.
.. _ReqProgrammingStyle: .. _ReqProgrammingStyle:
Programming style requirements (varied) Programming style requirements (varied)
--------------------------------------- ---------------------------------------
To maintain consistency across contributions from many people, there are To maintain source code consistency across contributions from many
various programming style requirements for contributions to LAMMPS. people, there are various programming style requirements for
Some of these requirements are strict and must be followed, while others contributions to LAMMPS. Some of these requirements are strict and
are only preferred and thus may be skipped. An in-depth discussion of must be followed, while others are only preferred and thus may be
the style guidelines is provided in the :doc:`programming style doc skipped. An in-depth discussion of the style guidelines is provided
page <Modify_style>`. in the :doc:`programming style doc page <Modify_style>`.
.. _ReqExamples: .. _ReqExamples:
Examples (preferred) Examples (preferred)
-------------------- --------------------
In most cases, it is preferred that example scripts (simple, small, fast For many new features, it is preferred that example scripts (simple,
to complete on 1 CPU) are included that demonstrate the use of new or small, fast to complete on 1 CPU) are included that demonstrate the
extended functionality. These are typically under the examples or use of new or extended functionality. These are typically include
examples/PACKAGES directory are further described on the :doc:`examples under the examples or examples/PACKAGES directory and are further
page <Examples>`. Guidelines for input scripts include: described on the :doc:`examples page <Examples>`. Guidelines for
input scripts include:
- commands that generate output should be commented out (except when the - commands that generate output should be commented out (except when the
output is the sole purpose or the feature, e.g. for a new compute) output is the sole purpose or the feature, e.g. for a new compute)
@ -279,7 +281,6 @@ page <Examples>`. Guidelines for input scripts include:
- where possible, potential files from the "potentials" folder or data - where possible, potential files from the "potentials" folder or data
file from other folders should be re-used through symbolic links file from other folders should be re-used through symbolic links
.. _ReqErrorMessages: .. _ReqErrorMessages:
Error or warning messages and explanations (preferred) Error or warning messages and explanations (preferred)
@ -321,13 +322,12 @@ commands and that may create :ref:`"Unknown identifier in data file" <err0001>`
errors that may have multiple possible reasons which complicates debugging, errors that may have multiple possible reasons which complicates debugging,
and thus require some additional explanation. and thus require some additional explanation.
The transformation of existing LAMMPS code to this new scheme is ongoing The transformation of existing LAMMPS code to this new scheme is
and - given the size of the LAMMPS source code - will take a significant ongoing. Given the size of the LAMMPS code base, it will take a
amount of time until completion. For new code, however, following the significant amount of time to complete. For new code, however,
new approach is strongly preferred. The expectation is that the new following the new approach is strongly preferred. The expectation is
scheme will make it easier for LAMMPS users, developers, and that the new scheme will make understanding errors easier for LAMMPS
maintainers. users, developers, and maintainers.
.. _ReqCitation: .. _ReqCitation:
@ -338,38 +338,39 @@ If there is a paper of yours describing your feature (either the
algorithm/science behind the feature itself, or its initial usage, or algorithm/science behind the feature itself, or its initial usage, or
its implementation in LAMMPS), you can add the citation to the \*.cpp its implementation in LAMMPS), you can add the citation to the \*.cpp
source file. See ``src/DIFFRACTION/compute_saed.cpp`` for an example. source file. See ``src/DIFFRACTION/compute_saed.cpp`` for an example.
A BibTeX format citation is stored in a string variable at the top A BibTeX format citation is stored in a string variable at the top of
of the file, and a single line of code registering this variable is the file, and a single line of code registering this variable is added
added to the constructor of the class. When your feature is used, to the constructor of the class. When your feature is used, then
by default, LAMMPS will print the brief info and the DOI LAMMPS (by default) will print the brief info and the DOI in the first
in the first line to the screen and the full citation to the log file. line to the screen and the full citation to the log file.
If there is additional functionality (which may have been added later) If there is additional functionality (which may have been added later)
described in a different publication, additional citation descriptions described in a different publication, additional citation descriptions
may be added for as long as they are only registered when the may be added so long as they are only registered when the
corresponding keyword activating this functionality is used. With these corresponding keyword activating this functionality is used.
options, it is possible to have LAMMPS output a specific citation
reminder whenever a user invokes your feature from their input script. With these options, it is possible to have LAMMPS output a specific
Please note that you should *only* use this for the *most* relevant citation reminder whenever a user invokes your feature from their
paper for a feature and a publication that you or your group authored. input script. Please note that you should *only* use this for the
E.g. adding a citation in the code for a paper by Nose and Hoover if you *most* relevant paper for a feature and a publication that you or your
write a fix that implements their integrator is not the intended usage. group authored. E.g. adding a citation in the source code for a paper
That latter kind of citation should just be included in the by Nose and Hoover if you write a fix that implements their integrator
documentation page you provide describing your contribution. If you are is not the intended usage. That kind of citation should just be
not sure what the best option would be, please contact the LAMMPS included in the documentation page you provide describing your
developers for advice. contribution. If you are not sure what the best option would be,
please contact the LAMMPS developers for advice.
.. _ReqUnitTesting: .. _ReqUnitTesting:
Testing (optional) Testing (optional)
------------------ ------------------
If your contribution contains new utility functions or a supporting class If your contribution contains new utility functions or a supporting
(i.e. anything that does not depend on a LAMMPS object), new unit tests class (i.e. anything that does not depend on a LAMMPS object), new
should be added to a suitable folder in the ``unittest`` tree. unit tests should be added to a suitable folder in the ``unittest``
When adding a new LAMMPS style computing forces or selected fixes, tree. When adding a new LAMMPS style computing forces or selected
a ``.yaml`` file with a test configuration and reference data should be fixes, a ``.yaml`` file with a test configuration and reference data
added for the styles where a suitable tester program already exists should be added for the styles where a suitable tester program already
(e.g. pair styles, bond styles, etc.). Please see exists (e.g. pair styles, bond styles, etc.). Please see :ref:`this
:ref:`this section in the manual <testing>` for more information on section in the manual <testing>` for more information on how to
how to enable, run, and expand testing. enable, run, and expand testing.

143
doc/src/Modify_style.rst
View File

@ -1,55 +1,58 @@
LAMMPS programming style LAMMPS programming style
======================== ========================
The LAMMPS developers aim to employ a consistent programming style and The aim of the LAMMPS developers is to use a consistent programming
naming conventions across the entire code base, as this helps with style and naming conventions across the entire code base, as this
maintenance, debugging, and understanding the code, both for developers helps with maintenance, debugging, and understanding the code, both
and users. This page provides a list of standard style choices used in for developers and users. This page provides a list of standard style
LAMMPS. Some of these standards are required, while others are just choices used in LAMMPS. Some of these standards are required, while
preferred. Following these conventions will make it much easier to others are just preferred. Following these conventions will make it
integrate your contribution. If you are uncertain, please ask. much easier to integrate your contribution. If you are uncertain,
please ask.
The files `pair_lj_cut.h`, `pair_lj_cut.cpp`, `utils.h`, and `utils.cpp` The files `pair_lj_cut.h`, `pair_lj_cut.cpp`, `utils.h`, and
may serve as representative examples. `utils.cpp` may serve as representative examples.
Include files (varied) Include files (varied)
^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^
- Header files that define a new LAMMPS style (i.e. that have a - Header files that define a new LAMMPS style (i.e. that have a
``SomeStyle(some/name,SomeName);`` macro in them) should only use the ``SomeStyle(some/name,SomeName);`` macro in them) should only use
include file for the base class and otherwise use forward declarations the include file for the base class and otherwise use forward
and pointers; when interfacing to a library use the PIMPL (pointer declarations and pointers; when interfacing to a library use the
to implementation) approach where you have a pointer to a struct PIMPL (pointer to implementation) approach where you have a pointer
that contains all library specific data (and thus requires the library to a struct that contains all library specific data (and thus
header) but use a forward declaration and define the struct only in requires the library header) but use a forward declaration and
the implementation file. This is a **strict** requirement since this define the struct only in the implementation file. This is a
is where type clashes between packages and hard to find bugs have **strict** requirement since this is where type clashes between
regularly manifested in the past. packages and hard-to-find bugs have regularly manifested in the
past.
- Header files, especially those defining a "style", should only use the - Header files, especially those defining a "style", should only use
absolute minimum number of include files and **must not** contain any the absolute minimum number of include files and **must not**
``using`` statements. Typically, that would be only the header for the contain any ``using`` statements. Typically, that would only be the
base class. Instead, any include statements should be put into the header for the base class. Instead, any include statements should
corresponding implementation files and forward declarations be used. be put in the corresponding implementation files and forward
For implementation files, the "include what you use" principle should declarations be used. For implementation files, the "include what
be employed. However, there is the notable exception that when the you use" principle should be employed. However, there is the
``pointers.h`` header is included (or one of the base classes derived notable exception that when the ``pointers.h`` header is included
from it) certain headers will always be included and thus do not need (or one of the base classes derived from it) certain headers will
to be explicitly specified. These are: `mpi.h`, `cstddef`, `cstdio`, always be included and thus do not need to be explicitly specified.
`cstdlib`, `string`, `utils.h`, `vector`, `fmt/format.h`, `climits`, These are: `mpi.h`, `cstddef`, `cstdio`, `cstdlib`, `string`,
`cinttypes`. This also means any such file can assume that `FILE`, `utils.h`, `vector`, `fmt/format.h`, `climits`, `cinttypes`. This
`NULL`, and `INT_MAX` are defined. also means any such file can assume that `FILE`, `NULL`, and
`INT_MAX` are defined.
- System headers or from installed libraries are include with angular - System headers or headers from installed libraries are included with
brackets (example: ``#include <vector>``), while local include files angular brackets (example: ``#include <vector>``), while local
use double quotes (example: ``#include "atom.h"``) include files use double quotes (example: ``#include "atom.h"``)
- When including system header files from the C library use the - When including system header files from the C library use the
C++-style names (``<cstdlib>`` or ``<cstring>``) instead of the C++-style names (``<cstdlib>`` or ``<cstring>``) instead of the
C-style names (``<stdlib.h>`` or ``<string.h>``) C-style names (``<stdlib.h>`` or ``<string.h>``)
- The order of ``#include`` statements in a file ``some_name.cpp`` that - The order of ``#include`` statements in a file ``some_name.cpp``
implements a class ``SomeName`` defined in a header file that implements a class ``SomeName`` defined in a header file
``some_name.h`` should be as follows: ``some_name.h`` should be as follows:
- ``#include "some_name.h"`` followed by an empty line - ``#include "some_name.h"`` followed by an empty line
@ -62,25 +65,23 @@ Include files (varied)
- ``using namespace LAMMPS_NS`` or other namespace imports. - ``using namespace LAMMPS_NS`` or other namespace imports.
Whitespace (preferred) Whitespace (preferred)
^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^
Source files should not contain TAB characters unless required by the Source files should not contain TAB characters unless required by the
syntax (e.g. in makefiles) and no trailing whitespace. Text files syntax (e.g. in makefiles) and no trailing whitespace. Text files
should be added with Unix-style line endings (LF-only). Git will should have Unix-style line endings (LF-only). Git will automatically
automatically convert those in both directions when running on Windows; convert those in both directions when running on Windows; use dos2unix
use dos2unix on Linux machines to convert files. Text files should have on Linux machines to convert files to Unix-style line endings. The
a line ending on the last line. last line of text files include a line ending.
You can check for these issues with the python scripts in the You can check for these issues with the python scripts in the
:ref:`"tools/coding_standard" <coding_standard>` folder. When run :ref:`"tools/coding_standard" <coding_standard>` folder. When run
normally with a source file or a source folder as argument, they will normally with a source file or a source folder as argument, they will
list all non-conforming lines. By adding the `-f` flag to the command list all non-conforming lines. By adding the `-f` flag to the command
line, they will modify the flagged files to try removing the detected line, they will modify the flagged files to try to remove the detected
issues. issues.
Placement of braces (strongly preferred) Placement of braces (strongly preferred)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -89,12 +90,11 @@ For new files added to the "src" tree, a `clang-format
provided under the name `.clang-format`. This file is compatible with provided under the name `.clang-format`. This file is compatible with
clang-format version 8 and later. With that file present, files can be clang-format version 8 and later. With that file present, files can be
reformatted according to the configuration with a command like: reformatted according to the configuration with a command like:
`clang-format -i new-file.cpp`. Ideally, this is done while writing the `clang-format -i new-file.cpp`. Ideally, this is done while writing
code or before a pull request is submitted. Blocks of code where the the code or before a pull request is submitted. Blocks of code where
reformatting from clang-format yields undesirable output may be the reformatting from clang-format yields hard-to-read or otherwise
protected with placing a pair `// clang-format off` and `// clang-format undesirable output may be protected with placing a pair `//
on` comments around that block. clang-format off` and `// clang-format on` comments around that block.
Miscellaneous standards (varied) Miscellaneous standards (varied)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -104,24 +104,26 @@ Miscellaneous standards (varied)
- Do not use so-called "alternative tokens" like ``and``, ``or``, - Do not use so-called "alternative tokens" like ``and``, ``or``,
``not`` and similar, but rather use the corresponding operators ``not`` and similar, but rather use the corresponding operators
``&&``, ``||``, and ``!``. The alternative tokens are not available ``&&``, ``||``, and ``!``. The alternative tokens are not available
by default on all compilers, and also we want to maintain a consistent by default on all compilers.
programming style.
- Output to the screen and the logfile should be using the corresponding - Output to the screen and the logfile should use the corresponding
FILE pointers and only be done on MPI rank 0. Use the :cpp:func:`utils::logmesg` FILE pointers and only be done on MPI rank 0. Use the
convenience function where possible. :cpp:func:`utils::logmesg` convenience function where possible.
- Usage of C++11 `virtual`, `override`, `final` keywords: Please follow the - Usage of C++11 `virtual`, `override`, `final` keywords: Please
`C++ Core Guideline C.128 <https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rh-override>`_. follow the `C++ Core Guideline C.128
<https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rh-override>`_.
That means, you should only use `virtual` to declare a new virtual That means, you should only use `virtual` to declare a new virtual
function, `override` to indicate you are overriding an existing virtual function, `override` to indicate you are overriding an existing
function, and `final` to prevent any further overriding. virtual function, and `final` to prevent any further overriding.
- Trivial destructors: Prefer not writing destructors when they are empty and `default`. - Trivial destructors: Do not write destructors when they are empty
and `default`.
.. code-block:: c++ .. code-block:: c++
// don't write destructors for A or B like this // don't write destructors for A or B like this
class A : protected Pointers { class A : protected Pointers {
public: public:
A(); A();
@ -135,6 +137,7 @@ Miscellaneous standards (varied)
}; };
// instead, let the compiler create the implicit default destructor by not writing it // instead, let the compiler create the implicit default destructor by not writing it
class A : protected Pointers { class A : protected Pointers {
public: public:
A(); A();
@ -147,9 +150,9 @@ Miscellaneous standards (varied)
- Please use clang-format only to reformat files that you have - Please use clang-format only to reformat files that you have
contributed. For header files containing a ``SomeStyle(keyword, contributed. For header files containing a ``SomeStyle(keyword,
ClassName)`` macros it is required to have this macro embedded with a ClassName)`` macros it is required to have this macro embedded with
pair of ``// clang-format off``, ``// clang-format on`` comments and a pair of ``// clang-format off``, ``// clang-format on`` comments
the line must be terminated with a semicolon (;). Example: and the line must be terminated with a semicolon (;). Example:
.. code-block:: c++ .. code-block:: c++
@ -162,10 +165,10 @@ Miscellaneous standards (varied)
#ifndef LMP_RUN_H #ifndef LMP_RUN_H
[...] [...]
You may also use ``// clang-format on/off`` throughout your files You may also use ``// clang-format on/off`` throughout your files to
to protect individual sections from being reformatted. protect individual sections from being reformatted.
- All files should have 0644 permissions, i.e. writable to the user only - All files should have 0644 permissions, i.e. writable by the user
and readable by all and no executable permissions. Executable only and readable by all and no executable permissions. Executable
permissions (0755) should only be on shell scripts or python or similar permissions (0755) should only be for shell scripts or python or
scripts for interpreted script languages. similar scripts for interpreted script languages.