From b54d39adf9b39bd2f93cf2901f1af3816141e4e4 Mon Sep 17 00:00:00 2001 From: Steve Plimpton Date: Fri, 12 May 2023 11:18:07 -0600 Subject: [PATCH] minor editing changes --- doc/src/Modify.rst | 8 +- doc/src/Modify_contribute.rst | 148 ++++++++-------- doc/src/Modify_overview.rst | 83 ++++----- doc/src/Modify_requirements.rst | 303 ++++++++++++++++---------------- doc/src/Modify_style.rst | 143 +++++++-------- 5 files changed, 348 insertions(+), 337 deletions(-) diff --git a/doc/src/Modify.rst b/doc/src/Modify.rst index b10e307b14..0d7d4d6b97 100644 --- a/doc/src/Modify.rst +++ b/doc/src/Modify.rst @@ -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 `, -:doc:`requirements for submissions `, and -:doc:`style guidelines `. + +* :doc:`how to prepare and submit your code ` +* :doc:`requirements for submissions ` +* :doc:`style guidelines ` 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 `. - .. toctree:: :maxdepth: 1 diff --git a/doc/src/Modify_contribute.rst b/doc/src/Modify_contribute.rst index 21bee1722b..8992e63c00 100644 --- a/doc/src/Modify_contribute.rst +++ b/doc/src/Modify_contribute.rst @@ -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 -`_. 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 ` -or :doc:`fix style ` 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 +`_. 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 ` or :doc:`fix +style ` 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 -`_ 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 `_ 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 `_. 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 `_. +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 `_ 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 ` -and :doc:`style guidelines`. 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 ` and :doc:`style +guidelines`. 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 -` 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 ` 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 +`_ 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 `_ page -of the LAMMPS website for examples of groups that do this. We are happy -to advertise your package and website from that page. Simply email the -`developers `_ with info about your -package, and we will post it there. We recommend naming external -packages USER-\ so they can be easily distinguished from bundled -packages that do not have the USER- prefix. +LAMMPS packages and tools `_ +page of the LAMMPS website for examples of groups that do this. We +are happy to advertise your package and website from that page. +Simply email the `developers `_ +with info about your package, and we will post it there. We recommend +naming external packages USER-\ 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 ` 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 ` 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. diff --git a/doc/src/Modify_overview.rst b/doc/src/Modify_overview.rst index a3d8e9737d..ab1fa43ed4 100644 --- a/doc/src/Modify_overview.rst +++ b/doc/src/Modify_overview.rst @@ -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 `. +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 +`. Most of the new features described on the :doc:`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 ` 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 ` 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 ` 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 ` command. diff --git a/doc/src/Modify_requirements.rst b/doc/src/Modify_requirements.rst index 9d5ffd38b2..15edafb26c 100644 --- a/doc/src/Modify_requirements.rst +++ b/doc/src/Modify_requirements.rst @@ -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 ` (strict) * :ref:`Integration testing ` (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 -`. +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 `. -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 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 `_ 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 `_ +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 ` 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 ` for -recurring tasks and a collection of -:doc:`platform neutral functions ` for improved -portability are provided. +recurring tasks and a collection of :doc:`platform neutral functions +` 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 `) 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 `) 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 `. - +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 `. .. _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 `. 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 `. 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 `. 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" ` 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 ` 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 ` for more information on how to +enable, run, and expand testing. diff --git a/doc/src/Modify_style.rst b/doc/src/Modify_style.rst index b853ccd721..4da8501f12 100644 --- a/doc/src/Modify_style.rst +++ b/doc/src/Modify_style.rst @@ -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 ``), 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 ``), 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 (```` or ````) instead of the - C-style names (```` or ````) + C++-style names (```` or ````) instead of the + C-style names (```` or ````) -- 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" ` 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 `_. +- Usage of C++11 `virtual`, `override`, `final` keywords: Please + follow the `C++ Core Guideline C.128 + `_. 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.