resolve formatting issues and add a few style tweaks from languagetool.org
This commit is contained in:
Axel Kohlmeyer
@ -1,11 +1,11 @@
|
||||
Modifying & extending LAMMPS
|
||||
****************************
|
||||
|
||||
LAMMPS is designed in a modular fashion and easy to be modified or
|
||||
extended with new functionality. In fact, about 95% of its source code
|
||||
is optional. The following pages give basic instructions on adding new
|
||||
features to LAMMPS. More in-depth explanations and documentation of
|
||||
individual functions and classes are given in :doc:`Developer`.
|
||||
LAMMPS has a modular design, so that it is easy to modify or extend with
|
||||
new functionality. In fact, about 95% of its source code is optional.
|
||||
The following pages give basic instructions on adding new features to
|
||||
LAMMPS. More in-depth explanations and documentation of individual
|
||||
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
|
||||
@ -16,7 +16,7 @@ LAMMPS. This process is explained in the following three pages:
|
||||
|
||||
A summary description of various types of styles in LAMMPS follows.
|
||||
A discussion of implementing specific styles from scratch is given
|
||||
in :doc:`Developer_write`.
|
||||
in :doc:`writing new styles <Developer_write>`.
|
||||
|
||||
|
||||
.. toctree::
|
||||
|
||||
@ -10,8 +10,8 @@ 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
|
||||
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.
|
||||
|
||||
@ -27,9 +27,9 @@ 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
|
||||
For informal communication with the LAMMPS developers, you may ask to
|
||||
join the `LAMMPS developers on Slack <https://lammps.slack.com>`_. This
|
||||
slack work space is by invitation only. Thus for access, please send an
|
||||
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
|
||||
@ -46,10 +46,11 @@ 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).
|
||||
streamlined by following the :doc:`requirements <Modify_requirements>`
|
||||
and :doc:`style guidelines<Modify_style>`. A small, modular, well
|
||||
written contribution may be integrated within hours, but a complex
|
||||
change that requires a redesign of some core functionality in LAMMPS can
|
||||
take months before inclusion (though this is rare).
|
||||
|
||||
|
||||
Submission procedure
|
||||
@ -58,22 +59,22 @@ Submission procedure
|
||||
All changes to LAMMPS (including those from LAMMPS developers) are
|
||||
integrated via pull requests on GitHub and cannot be merged without
|
||||
passing the automated testing and an approving review by a LAMMPS core
|
||||
developer. Thus before submitting your contribution, you should first
|
||||
make certain, that your added or modified code compiles and works
|
||||
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.
|
||||
|
||||
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.
|
||||
to submit via GitHub yourself, you may also submit patch files or full
|
||||
files to the LAMMPS developers and ask them to submit a pull request on
|
||||
GitHub on your behalf. If this is the case, create a gzipped tar file
|
||||
of all new or changed files or a corresponding patch file using 'diff
|
||||
-u' or 'diff -c' format and compress it with gzip. Please only use gzip
|
||||
compression, as this works well and is available on all platforms. This
|
||||
latter way of submission may delay the integration as it depends on the
|
||||
LAMMPS developer having free time available.
|
||||
|
||||
|
||||
External contributions
|
||||
@ -86,7 +87,7 @@ LAMMPS packages and tools <https://www.lammps.org/external.html>`_ page
|
||||
of the LAMMPS website for examples of groups that do this. We are happy
|
||||
to advertise your package and website from that page. Simply email the
|
||||
`developers <https://www.lammps.org/authors.html>`_ with info about your
|
||||
package and we will post it there. We recommend to name external
|
||||
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.
|
||||
|
||||
@ -94,13 +95,13 @@ packages that do not have the USER- prefix.
|
||||
Location of files: individual files and packages
|
||||
------------------------------------------------
|
||||
|
||||
We rarely accept new styles in the core src folder. Thus please review
|
||||
We rarely accept new styles in the core src folder. Thus, please review
|
||||
the list of :doc:`available Packages <Packages_details>` to see if your
|
||||
contribution could be added to be added to one of them. It should fit
|
||||
into the general purposed of that package. If it does not fit well, it
|
||||
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
|
||||
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
|
||||
@ -114,8 +115,9 @@ 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.
|
||||
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.
|
||||
|
||||
@ -4,8 +4,8 @@ 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, but
|
||||
functions (class methods) that do actual computations are mostly written
|
||||
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>`.
|
||||
@ -21,22 +21,22 @@ 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, and thus should not make the rest of LAMMPS more complex or
|
||||
cause side-effect bugs.
|
||||
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`` 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:
|
||||
|
||||
.. 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++
|
||||
|
||||
@ -51,8 +51,8 @@ then your pair_foo.h file should be structured as follows:
|
||||
#endif
|
||||
|
||||
where "foo" is the style keyword in the pair_style command, and
|
||||
PairFoo is the class name defined in your pair_foo.cpp and pair_foo.h
|
||||
files.
|
||||
``PairFoo`` is the class name defined in your ``pair_foo.cpp`` and
|
||||
``pair_foo.h`` files.
|
||||
|
||||
When you re-build LAMMPS, your new pairwise potential becomes part of
|
||||
the executable and can be invoked with a pair_style command like the
|
||||
@ -66,7 +66,7 @@ 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
|
||||
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
|
||||
@ -85,7 +85,7 @@ functionality:
|
||||
post-processing step. Many computations are more easily and more
|
||||
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
|
||||
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.
|
||||
* If your new feature reads arguments or writes output, make sure you
|
||||
|
||||
@ -8,7 +8,7 @@ into the LAMMPS software distribution.
|
||||
Motivation
|
||||
----------
|
||||
|
||||
The LAMMPS developers are committed to providing 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
|
||||
maintain and modify. Achieving all of these goals is challenging since
|
||||
a large part of LAMMPS consists of contributed code from many different
|
||||
@ -20,13 +20,14 @@ 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.
|
||||
|
||||
The following requirements and recommendations are provided to help
|
||||
maintaining or improving that status. It is indicated which
|
||||
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:
|
||||
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:
|
||||
|
||||
* :ref:`Licensing requirements <ReqLicense>` (strict)
|
||||
* :ref:`Integration testing <ReqIntegrationTesting>` (strict)
|
||||
* :ref:`Documentation <ReqDocumentation>` (strict)
|
||||
@ -39,20 +40,20 @@ your contributions. Requirements include:
|
||||
* :ref:`Citation reminder <ReqCitation>` (optional)
|
||||
* :ref:`Testing <ReqUnitTesting>` (optional)
|
||||
|
||||
|
||||
.. _ReqLicense:
|
||||
|
||||
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. On request we also make a version of LAMMPS available under
|
||||
LGPL 2.1 terms; 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>`.
|
||||
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>`.
|
||||
|
||||
Your new source files should have the LAMMPS copyright, GPL notice, and
|
||||
your name and email address at the top, like other user-contributed
|
||||
@ -89,7 +90,7 @@ 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
|
||||
default setting of ``-DLAMMPS_SMALLBIG``. The code needs to work
|
||||
correctly in both cases and also in serial and parallel using MPI.
|
||||
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
|
||||
@ -105,7 +106,7 @@ 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
|
||||
.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.
|
||||
@ -120,11 +121,11 @@ packages must be updated as well as a package specific description added
|
||||
and, if necessary, some package specific build instructions included.
|
||||
|
||||
As appropriate, the text files with the documentation can include inline
|
||||
mathematical expression 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.
|
||||
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
|
||||
@ -135,9 +136,10 @@ 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 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``
|
||||
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
|
||||
@ -169,7 +171,7 @@ 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
|
||||
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
|
||||
@ -196,8 +198,8 @@ Build system (strict)
|
||||
|
||||
LAMMPS currently supports two build systems: one that is based on
|
||||
:doc:`traditional Makefiles <Build_make>` and one that is based on
|
||||
:doc:`CMake <Build_cmake>`. Thus your contribution must be compatible
|
||||
with and support both.
|
||||
:doc:`CMake <Build_cmake>`. Therefore, your contribution must be
|
||||
compatible with and support both build systems.
|
||||
|
||||
For a single pair of header and implementation files that are an
|
||||
independent feature, it is usually only required to add them to
|
||||
@ -210,7 +212,7 @@ 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
|
||||
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/Modules/Packages/. Please check out how this is handled for
|
||||
@ -219,7 +221,7 @@ existing packages and ask the LAMMPS developers if you need assistance.
|
||||
|
||||
.. _ReqNaming:
|
||||
|
||||
Command or Style names, file names, and keywords (strict)
|
||||
Command or style names, file names, and keywords (strict)
|
||||
---------------------------------------------------------
|
||||
|
||||
All user-visible command or style names should be all lower case and
|
||||
@ -238,9 +240,9 @@ 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 some
|
||||
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 are provided in the :doc:`programming style doc
|
||||
the style guidelines is provided in the :doc:`programming style doc
|
||||
page <Modify_style>`.
|
||||
|
||||
|
||||
@ -252,8 +254,8 @@ 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 are further described on the
|
||||
:doc:`examples page <Examples>`. Guidelines for input scripts include:
|
||||
examples/PACKAGES directory 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)
|
||||
@ -285,7 +287,7 @@ Error or warning messages and explanations (preferred)
|
||||
|
||||
.. versionchanged:: 4May2022
|
||||
|
||||
Starting with LAMMPS version 4 May 2022 the LAMMPS developers have
|
||||
Starting with LAMMPS version 4 May 2022, the LAMMPS developers have
|
||||
agreed on a new policy for error and warning messages.
|
||||
|
||||
Previously, all error and warning strings were supposed to be listed in
|
||||
@ -298,17 +300,17 @@ source file and the line number of the error location would be printed,
|
||||
so that one could look up the cause by reading the source code.
|
||||
|
||||
The new policy encourages more specific error messages that ideally
|
||||
indicate the cause directly requiring no further lookup. This is aided
|
||||
by the `{fmt} library <https://fmt.dev>`_ to convert the Error class
|
||||
commands so that they take a variable number of arguments and error
|
||||
text will be treated like a {fmt} syntax format string. Error messages
|
||||
should still preferably be kept to a single line or two lines at most.
|
||||
indicate the cause directly, and requiring no further lookup. This is
|
||||
aided by the `{fmt} library <https://fmt.dev>`_ enabling Error class
|
||||
methods that take a variable number of arguments and an error text that
|
||||
will be treated like a {fmt} syntax format string. Error messages should
|
||||
still preferably be kept to a single line or two lines at most.
|
||||
|
||||
For more complex explanations or errors that have multiple possible
|
||||
reasons, a paragraph should be added to the `Error_details` page with an
|
||||
error code reference (e.g. ``.. _err0001:``) then the utility function
|
||||
:cpp:func:`utils::errorurl() <LAMMPS_NS::utils::errorurl>` can be used
|
||||
to generate an URL that will directly lead to that paragraph. An error
|
||||
to generate a URL that will directly lead to that paragraph. An error
|
||||
for missing arguments can be easily generated using the
|
||||
:cpp:func:`utils::missing_cmd_args()
|
||||
<LAMMPS_NS::utils::missing_cmd_args>` convenience function.
|
||||
@ -321,7 +323,7 @@ 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. However, for new code following the
|
||||
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.
|
||||
@ -337,7 +339,7 @@ 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
|
||||
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.
|
||||
@ -346,7 +348,7 @@ 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
|
||||
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.
|
||||
|
||||
@ -1,19 +1,17 @@
|
||||
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.
|
||||
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.
|
||||
|
||||
|
||||
Include files (varied)
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
@ -28,23 +26,22 @@ Include files (varied)
|
||||
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
|
||||
- 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.
|
||||
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 file
|
||||
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
|
||||
@ -152,7 +149,7 @@ Miscellaneous standards (varied)
|
||||
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 semi-colon (;). Example:
|
||||
the line must be terminated with a semicolon (;). Example:
|
||||
|
||||
.. code-block:: c++
|
||||
|
||||
@ -168,7 +165,7 @@ Miscellaneous standards (varied)
|
||||
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
|
||||
- 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.
|
||||
|
||||
@ -142,7 +142,8 @@ the code will stop with an error message. When this option is set to
|
||||
For a typical application, using the automatic parameter generation
|
||||
will provide simulations that are either inaccurate or slow. Using this
|
||||
option is thus not recommended. For guidelines on how to obtain good
|
||||
parameters, see the :doc:`How-To <Howto_dispersion>` discussion.
|
||||
parameters, see the :doc:`long-range dispersion howto <Howto_dispersion>`
|
||||
discussion.
|
||||
|
||||
----------
|
||||
|
||||
|
||||
Reference in New Issue
Block a user