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
interest to other users, we encourage you to submit it for inclusion in
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:`style guidelines <Modify_style>`.
* :doc:`how to prepare and submit your code <Modify_contribute>`
* :doc:`requirements for submissions <Modify_requirements>`
* :doc:`style guidelines <Modify_style>`
A summary description of various types of styles in LAMMPS follows.
A discussion of implementing specific styles from scratch is given
in :doc:`writing new styles <Developer_write>`.
.. toctree::
: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
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.
to be included in 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 on this
section.
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 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 typically results in less work for everyone 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. 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
join the `LAMMPS developers on Slack <https://lammps.slack.com>`_.
This slack work space is by invitation only. 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 looking
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.
@ -41,16 +44,17 @@ 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).
How quickly your contribution will be integrated can vary widely. It
depends largely on how much effort is required by the LAMMPS
developers to integrate and test it, if any and what kind of changes
to the core code are required, how quickly you can address them, and
how much interest the contribution 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 re-design of a core functionality in LAMMPS can take months
before inclusion (though this is rare).
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
passing the automated testing and an approving review by a LAMMPS core
developer. Before submitting your contribution, you should therefore
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.
first ensure 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.
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 send patch
files or full files to the `LAMMPS developers
<https://www.lammps.org/authors.html>`_ 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 mode of submission may delay the integration
as it depends more on the LAMMPS developers.
External contributions
@ -83,41 +88,42 @@ 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 naming external
packages USER-\<name\> so they can be easily distinguished from bundled
packages that do not have the USER- prefix.
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
naming external packages USER-\<name\> so they can be easily
distinguished from packages in the LAMMPS distribution which 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
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 should be added to one of them. It should fit
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.
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.
(bundled or external), it is best to create a new package with its own
directory (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.
If designed correctly, most 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 more substantive
changes to the core LAMMPS files, it is particularly encouraged that
you communicate with the LAMMPS developers early in development.

83
doc/src/Modify_overview.rst
View File

@ -1,42 +1,44 @@
Overview
========
The best way to add a new feature to LAMMPS is to find a similar feature
and look at the corresponding source and header files to figure out what
it does. You will need some knowledge of C++ to be able to understand
the high-level structure of LAMMPS and its class organization.
Functions (class methods) that do actual computations are mostly written
in C-style code and operate on simple C-style data structures (vectors
and arrays). A high-level overview of the programming style choices in
LAMMPS is :doc:`given elsewhere <Developer_code_design>`.
The best way to add a new feature to LAMMPS is to find a similar
feature and look at the corresponding source and header files to
figure out what it does. You will need some knowledge of C++ to
understand the high-level structure of LAMMPS and its class
organization. Functions (class methods) that do actual computations
are mostly written in C-style code and operate on simple C-style data
structures (vectors and arrays). A high-level overview of the
programming style choices in LAMMPS is :doc:`given elsewhere
<Developer_code_design>`.
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
described below, where you can make small edits to existing files).
Creating a new class requires 2 files, a source code file (\*.cpp) and a
header file (\*.h). The derived class must provide certain methods to
work as a new option. Depending on how different your new feature is
compared to existing features, you can either derive from the base class
itself, or from a derived class that already exists. Enabling LAMMPS to
invoke the new class is as simple as putting the two source files in the
src directory and re-building LAMMPS.
page require you to write a new C++ derived class (except for
exceptions described below, where you can make small edits to existing
files). Creating a new class requires 2 files, a source code file
(\*.cpp) and a header file (\*.h). The derived class must provide
certain methods to work as a new option. Depending on how different
your new feature is compared to existing features, you can either
derive from the base class itself, or from a derived class that
already exists. Enabling LAMMPS to invoke the new class is as simple
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
variables needed to define the new feature are in the 2 files you write.
Thus, it should not make the rest of LAMMPS more complex or cause bugs
through unwanted side effects.
The advantage of C++ and its object-orientation is that all the code
and variables needed to define the new feature are in the 2 files you
write. Thus, it should not make the rest of LAMMPS more complex or
cause bugs through unwanted side effects.
Here is a concrete example. Suppose you write 2 files ``pair_foo.cpp``
and ``pair_foo.h`` that define a new class ``PairFoo`` that computes
pairwise potentials described in the classic 1997 :ref:`paper <Foo>` by
Foo, *et al.* If you wish to invoke those potentials in a LAMMPS input
script with a command like:
Here is a concrete example. Suppose you write 2 files
``pair_foo.cpp`` and ``pair_foo.h`` that define a new class
``PairFoo`` which computes pairwise potentials described in the
classic 1997 :ref:`paper <Foo>` by Foo, *et al.* If you wish to invoke
those potentials in a LAMMPS input script with a command like:
.. code-block:: LAMMPS
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++
@ -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
processed by your new class.
As illustrated by this example pair style, many kinds of options are
referred to in the LAMMPS documentation as the "style" of a particular
command.
As illustrated by this example, many features referred to in the
LAMMPS documentation are called a "style" of a particular command.
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
derived from. Public variables in that file are ones used and set by
the derived classes, which are also used by the base class. Sometimes
they are also used by the rest of LAMMPS. Pure functions, which means
functions declared as virtual in the base class header file which are
also set to 0, are functions you **must** implement in your new derived
class to give it the functionality LAMMPS expects. Virtual functions
that are not set to 0 are functions you may override or not. Those
are usually defined with an empty function body.
and discusses the header file for the base class that these styles
derive from. Public variables in that file can be used and set by the
derived classes, and may also be used by the base class. Sometimes
they are also accessed by the rest of LAMMPS. Pure functions, which
means functions declared as virtual in the base class header file and
which are also set to 0, are functions you **must** implement in your
new derived class to give it the functionality LAMMPS expects. Virtual
functions that are not set to 0 are functions you may override or not.
Those are usually defined with an empty function body.
Additionally, new output options can be added directly to the
thermo.cpp, dump_custom.cpp, and variable.cpp files. These are also
@ -86,8 +87,8 @@ functionality:
quickly done that way.
* 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
processor and analyze it. You run the risk of seriously degrading
the parallel efficiency this way.
processor and analyze it. That would run the risk of seriously degrading
the parallel efficiency.
* If your new feature reads arguments or writes output, make sure you
follow the unit conventions discussed by the :doc:`units <units>`
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
is versatile, reliable, high-quality, efficient, portable, and easy to
maintain and modify. Achieving all of these goals is challenging since
a large part of LAMMPS consists of contributed code from many different
authors and not many of them are professionally trained programmers and
maintain and modify. Achieving all of these goals is challenging
since a large part of LAMMPS consists of contributed code from many
different authors who may not be professionally trained programmers or
familiar with the idiosyncrasies of maintaining a large software
package. In addition, changes that interfere with the parallel
efficiency of the core code must be avoided. As LAMMPS continues to
grow and more features and functionality are added, it becomes a
necessity to be more discriminating with new contributions while also
working at the same time to improve the existing code.
grow and more features and functionality are added, it's necessary to
follow established guidelines when accepting new contributions while
also working at the same time to improve the existing code.
The following requirements and recommendations are provided as a guide
to maintain or improve that status. It is indicated which individual
requirements are strict, and which represent a preference and thus are
negotiable or optional. Please feel free to contact the LAMMPS core
developers in case you need additional explanations or clarifications,
or in case you need assistance in realizing the (strict) requirements
for your contributions. Requirements include:
The following requirements and recommendations are provided as a
guide. They indicate which individual requirements are strict, and
which represent a preference and thus are negotiable or optional.
Please feel free to contact the LAMMPS core developers in case you
need additional explanations or clarifications, or you need assistance
in implementing the (strict) requirements for your contributions.
Requirements include:
* :ref:`Licensing requirements <ReqLicense>` (strict)
* :ref:`Integration testing <ReqIntegrationTesting>` (strict)
@ -48,44 +48,44 @@ Licensing requirements (strict)
Contributing authors agree when submitting a pull request that their
contributions can be distributed under the LAMMPS license conditions.
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.
We also make a version of LAMMPS under LGPL 2.1 terms available on
request; this will usually be the latest available or a previous stable
version with a few LGPL 2.1 incompatible files removed. More details
are found on the :doc:`LAMMPS open-source license page
<Intro_opensource>`.
publicly distributed versions, e.g. on the LAMMPS homepage or on
GitHub. We also make a version of LAMMPS under LGPL 2.1 terms whcih
is available on request; this will usually be the latest available or
a previous stable version with a few LGPL 2.1 incompatible files
removed. More details are found on the :doc:`LAMMPS open-source
license page <Intro_opensource>`.
Your new source files should have the LAMMPS copyright, GPL notice, and
your name and email address at the top, like other user-contributed
LAMMPS source files.
Your new source files should have the LAMMPS copyright and GPL notice,
followed by your name and email address at the top, like other
user-contributed LAMMPS source files.
Contributions may be under a different license as long as that
license does not conflict with the aforementioned terms. Contributions
that use code with a conflicting license can be split into two parts:
Contributions may be under a different license as long as that license
does not conflict with the aforementioned terms. Contributions that
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
licensed under compatible terms and bundled with the LAMMPS sources
2. an external library that must be downloaded and compiled (either
separately or as part of the LAMMPS compilation)
Please note, that this split licensed mode may complicate including the
contribution in binary packages.
Please note, that this split licensing mode may complicate including
the contribution in binary packages.
.. _ReqIntegrationTesting:
Integration testing (strict)
----------------------------
Where possible we utilize available continuous integration tools to
search for common programming mistakes, portability limitations,
incompatible formatting, and undesired side effects. Contributed code
must pass the automated tests on GitHub before it can be merged with
the LAMMPS distribution. These tests compile LAMMPS in a variety of
environments and settings and run the bundled unit tests. At the
discretion of the LAMMPS developer managing the pull request,
additional tests may be activated that test for "side effects" on
running a collection of input decks and create consistent results.
The translation of the documentation to HTML and PDF is also tested.
Where possible we use available continuous integration tools to search
for common programming mistakes, portability limitations, incompatible
formatting, and undesired side effects. Contributed code must pass the
automated tests on GitHub before it can be merged with the LAMMPS
distribution. These tests compile LAMMPS in a variety of environments
and settings and run the bundled unit tests. At the discretion of the
LAMMPS developer managing the pull request, additional tests may be
activated that test for "side effects" on running a collection of
input decks and create consistent results. The translation of the
documentation to HTML and PDF is also tested.
This means that contributed source code **must** compile with the most
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
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:
@ -105,60 +105,62 @@ Documentation (strict)
Contributions that add new styles or commands or augment existing ones
must include the corresponding new or modified documentation in
`ReStructuredText format <rst_>`_ (.rst files in the ``doc/src/``
folder). The documentation shall be written in American English and the
.rst file must use only ASCII characters, so it can be cleanly translated
to PDF files (via `sphinx <https://www.sphinx-doc.org>`_ and PDFLaTeX).
Special characters may be included via embedded math expression typeset
in a LaTeX subset.
folder). The documentation should be written in American English and
the .rst file must only ues ASCII characters, so it can be cleanly
translated to PDF files (via `sphinx <https://www.sphinx-doc.org>`_
and PDFLaTeX). Special characters may be included via embedded math
expression typeset in a LaTeX subset.
.. _rst: https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html
When adding new commands, they need to be integrated into the sphinx
documentation system, and the corresponding command tables and lists
updated. When translating the documentation into html files there should
be no warnings. When adding a new package also some lists describing
packages must be updated as well as a package specific description added
and, if necessary, some package specific build instructions included.
updated. When translating the documentation into html files there
should be no warnings. When adding a new package, some lists
describing packages must also be updated as well as a package specific
description added. Likewise, if necessary, some package specific
build instructions should be included.
As appropriate, the text files with the documentation can include inline
mathematical expressions or figures (see ``doc/JPG`` for examples).
Additional PDF files with further details (see ``doc/PDF`` for examples)
may also be included. The page should also include literature citations
as appropriate; see the bottom of ``doc/fix_nh.rst`` for examples and
the earlier part of the same file for how to format the cite itself.
Citation labels must be unique across **all** .rst files. The
"Restrictions" section of the page should indicate if your command is
only available if LAMMPS is built with the appropriate FOO package. See
other package doc files for examples of how to do this.
As appropriate, the text files with the documentation can include
inline mathematical expressions or figures (see ``doc/JPG`` for
examples). Additional PDF files with further details may also be
included; see ``doc/PDF`` for examples. The page should also include
literature citations as appropriate; see the bottom of
``doc/fix_nh.rst`` for examples and the earlier part of the same file
for how to format the cite itself. Citation labels must be unique
across **all** .rst files. The "Restrictions" section of the page
should indicate if your command is only available if LAMMPS is built
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
inspect and proofread the resulting HTML format doc page before
submitting your code. Upon submission of a pull request, checks for
error free completion of the HTML and PDF build will be performed and
also a spell check, a check for correct anchors and labels, and a check
for completeness of references to all styles in their corresponding
tables and lists is run. In case the spell check reports false
positives, they can be added to the file
Please run at least "make html" and "make spelling" from within the
doc/src directory, and carefully inspect and proofread the resulting
HTML format doc page before submitting your code. Upon submission of
a pull request, checks for error free completion of the HTML and PDF
build will be performed and also a spell check, a check for correct
anchors and labels, and a check for completeness of references to all
styles in their corresponding tables and lists is run. In case the
spell check reports false positives, they can be added to the file
``doc/utils/sphinx-config/false_positives.txt``
Contributions that add or modify the library interface or "public" APIs
from the C++ code or the Fortran module must include suitable doxygen
comments in the source and corresponding changes to the documentation
sources for the "Programmer Guide" guide section of the LAMMPS manual.
Contributions that add or modify the library interface or "public"
APIs from the C++ code or the Fortran module must include suitable
doxygen comments in the source and corresponding changes to the
documentation sources for the "Programmer Guide" guide section of the
LAMMPS manual.
If your feature requires some more complex steps and explanations to be
used correctly or some external or bundled tools or scripts, we
If your feature requires some more complex steps and explanations to
be used correctly or some external or bundled tools or scripts, we
recommend that you also contribute a :doc:`Howto document <Howto>`
providing some more background information and some tutorial material.
This can also be used to provide more in-depth explanations for bundled
examples.
This can also be used to provide more in-depth explanations of models
that require use of multiple commands.
As a rule-of-thumb, the more clear and self-explanatory you make
your documentation, README files and examples, and the easier you make
it for people to get started, the more likely it is that users will try
As a rule-of-thumb, the more clear and self-explanatory you make your
documentation, README files and examples, and the easier you make it
for people to get started, the more likely it is that users will try
out your new feature.
.. _ReqProgrammingStandards:
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
described as "C with classes". Advanced C++ features like operator
overloading or excessive use of templates are avoided with the intent to
keep the code readable to programmers that have limited C++ programming
experience. C++ constructs are acceptable when they help improve the
readability and reliability of the code, e.g. when using the
`std::string` class instead of manipulating pointers and calling the
string functions of the C library. In addition, a collection of
overloading or excessive use of templates are avoided with the intent
to keep the code readable to programmers that have limited C++
programming experience. C++ constructs are acceptable when they help
improve the readability and reliability of the code, e.g. when using
the `std::string` class instead of manipulating pointers and calling
the string functions of the C library. In addition, a collection of
convenient :doc:`utility functions and classes <Developer_utils>` for
recurring tasks and a collection of
:doc:`platform neutral functions <Developer_platform>` for improved
portability are provided.
recurring tasks and a collection of :doc:`platform neutral functions
<Developer_platform>` for improved portability are provided.
Included Fortran code has to be compatible with the Fortran 2003
standard. Python code must be compatible with Python 3.5. Large parts
of LAMMPS (including the :ref:`PYTHON package <PKG-PYTHON>`) are also
compatible with Python 2.7. Compatibility with Python 2.7 is
standard. Python code must be compatible with Python 3.5. Large
parts of LAMMPS (including the :ref:`PYTHON package <PKG-PYTHON>`) are
also compatible with Python 2.7. Compatibility with Python 2.7 is
desirable, but compatibility with Python 3.5 is **required**.
Compatibility with these older programming language standards is very
important to maintain portability and availability of LAMMPS on many
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
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:
@ -206,18 +207,19 @@ independent feature, it is usually only required to add them to
`src/.gitignore``.
For traditional make, if your contributed files or package depend on
other LAMMPS style files or packages also being installed (e.g. because
your file is a derived class from the other LAMMPS class), then an
Install.sh file is also needed to check for those dependencies and
modifications to src/Depend.sh to trigger the checks. See other README
and Install.sh files in other directories as examples.
other LAMMPS style files or packages also being installed
(e.g. because your file is a derived class from the other LAMMPS
class), then an Install.sh file is also needed to check for those
dependencies and modifications to src/Depend.sh to trigger the checks.
See other README and Install.sh files in other directories as
examples.
Similarly, for CMake support, changes may need to be made to
cmake/CMakeLists.txt, some of the files in cmake/presets, and possibly a
file with specific instructions needs to be added to
cmake/CMakeLists.txt, some of the files in cmake/presets, and possibly
a file with specific instructions needs to be added to
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:
@ -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
established (e.g. lj for Lennard-Jones). For a compute style
"some/name" the source files must be called `compute_some_name.h` and
`compute_some_name.cpp`. The "include guard" would then be
`LMP_COMPUTE_SOME_NAME_H` and the class name `ComputeSomeName`.
`compute_some_name.cpp`. The "include guard" in the header file would
then be `LMP_COMPUTE_SOME_NAME_H` and the class name
`ComputeSomeName`.
.. _ReqProgrammingStyle:
Programming style requirements (varied)
---------------------------------------
To maintain consistency across contributions from many people, there are
various programming style requirements for contributions to LAMMPS.
Some of these requirements are strict and must be followed, while others
are only preferred and thus may be skipped. An in-depth discussion of
the style guidelines is provided in the :doc:`programming style doc
page <Modify_style>`.
To maintain source code consistency across contributions from many
people, there are various programming style requirements for
contributions to LAMMPS. Some of these requirements are strict and
must be followed, while others are only preferred and thus may be
skipped. An in-depth discussion of the style guidelines is provided
in the :doc:`programming style doc page <Modify_style>`.
.. _ReqExamples:
Examples (preferred)
--------------------
In most cases, it is preferred that example scripts (simple, small, fast
to complete on 1 CPU) are included that demonstrate the use of new or
extended functionality. These are typically under the examples or
examples/PACKAGES directory are further described on the :doc:`examples
page <Examples>`. Guidelines for input scripts include:
For many new features, it is preferred that example scripts (simple,
small, fast to complete on 1 CPU) are included that demonstrate the
use of new or extended functionality. These are typically include
under the examples or examples/PACKAGES directory and are further
described on the :doc:`examples page <Examples>`. Guidelines for
input scripts include:
- 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)
@ -279,7 +281,6 @@ page <Examples>`. Guidelines for input scripts include:
- where possible, potential files from the "potentials" folder or data
file from other folders should be re-used through symbolic links
.. _ReqErrorMessages:
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,
and thus require some additional explanation.
The transformation of existing LAMMPS code to this new scheme is ongoing
and - given the size of the LAMMPS source code - will take a significant
amount of time until completion. For new code, however, following the
new approach is strongly preferred. The expectation is that the new
scheme will make it easier for LAMMPS users, developers, and
maintainers.
The transformation of existing LAMMPS code to this new scheme is
ongoing. Given the size of the LAMMPS code base, it will take a
significant amount of time to complete. For new code, however,
following the new approach is strongly preferred. The expectation is
that the new scheme will make understanding errors easier for LAMMPS
users, developers, and maintainers.
.. _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
its implementation in LAMMPS), you can add the citation to the \*.cpp
source file. See ``src/DIFFRACTION/compute_saed.cpp`` for an example.
A BibTeX format citation is stored in a string variable at the top
of the file, and a single line of code registering this variable is
added to the constructor of the class. When your feature is used,
by default, LAMMPS will print the brief info and the DOI
in the first line to the screen and the full citation to the log file.
A BibTeX format citation is stored in a string variable at the top of
the file, and a single line of code registering this variable is added
to the constructor of the class. When your feature is used, then
LAMMPS (by default) will print the brief info and the DOI in the first
line to the screen and the full citation to the log file.
If there is additional functionality (which may have been added later)
described in a different publication, additional citation descriptions
may be added for as long as they are only registered when the
corresponding keyword activating this functionality is used. With these
options, it is possible to have LAMMPS output a specific citation
reminder whenever a user invokes your feature from their input script.
Please note that you should *only* use this for the *most* relevant
paper for a feature and a publication that you or your group authored.
E.g. adding a citation in the code for a paper by Nose and Hoover if you
write a fix that implements their integrator is not the intended usage.
That latter kind of citation should just be included in the
documentation page you provide describing your contribution. If you are
not sure what the best option would be, please contact the LAMMPS
developers for advice.
may be added so long as they are only registered when the
corresponding keyword activating this functionality is used.
With these options, it is possible to have LAMMPS output a specific
citation reminder whenever a user invokes your feature from their
input script. Please note that you should *only* use this for the
*most* relevant paper for a feature and a publication that you or your
group authored. E.g. adding a citation in the source code for a paper
by Nose and Hoover if you write a fix that implements their integrator
is not the intended usage. That kind of citation should just be
included in the documentation page you provide describing your
contribution. If you are not sure what the best option would be,
please contact the LAMMPS developers for advice.
.. _ReqUnitTesting:
Testing (optional)
------------------
If your contribution contains new utility functions or a supporting class
(i.e. anything that does not depend on a LAMMPS object), new unit tests
should be added to a suitable folder in the ``unittest`` tree.
When adding a new LAMMPS style computing forces or selected fixes,
a ``.yaml`` file with a test configuration and reference data should be
added for the styles where a suitable tester program already exists
(e.g. pair styles, bond styles, etc.). Please see
:ref:`this section in the manual <testing>` for more information on
how to enable, run, and expand testing.
If your contribution contains new utility functions or a supporting
class (i.e. anything that does not depend on a LAMMPS object), new
unit tests should be added to a suitable folder in the ``unittest``
tree. When adding a new LAMMPS style computing forces or selected
fixes, a ``.yaml`` file with a test configuration and reference data
should be added for the styles where a suitable tester program already
exists (e.g. pair styles, bond styles, etc.). Please see :ref:`this
section in the manual <testing>` for more information on how to
enable, run, and expand testing.

143
doc/src/Modify_style.rst
View File

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