From 787399f5e399be0eda2aaabfd25b9487cd4a7404 Mon Sep 17 00:00:00 2001 From: Joel Thomas Clemmer Date: Thu, 27 Apr 2023 09:25:58 -0600 Subject: [PATCH 01/10] Reorganizing the programming manual and editing some text --- doc/src/Modify.rst | 15 +- doc/src/Modify_contribute.rst | 108 ++++--- doc/src/Modify_requirements.rst | 362 +++++++++++++++++++++++ doc/src/Modify_style.rst | 503 +++++--------------------------- 4 files changed, 497 insertions(+), 491 deletions(-) create mode 100644 doc/src/Modify_requirements.rst diff --git a/doc/src/Modify.rst b/doc/src/Modify.rst index 8ea7850fc5..31e67a66ca 100644 --- a/doc/src/Modify.rst +++ b/doc/src/Modify.rst @@ -3,21 +3,24 @@ Modifying & extending LAMMPS LAMMPS is designed in a modular fashion and to be easy to modify or extend with new functionality. In fact, about 95% of its source code -are optional. The following pages give basic instructions on what -is required when adding new styles of different kinds to LAMMPS. +is optional. The following pages give basic instructions on adding new +features to LAMMPS. 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 as a pull request on our `GitHub site -`_, after reading about :doc:`how to -prepare your code for submission ` and :doc:`the -style requirements and recommendations `. +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 `. A discussion of the various +types of styles in LAMMPS is then provided. + .. toctree:: :maxdepth: 1 Modify_overview Modify_contribute + Modify_requirements Modify_style .. toctree:: diff --git a/doc/src/Modify_contribute.rst b/doc/src/Modify_contribute.rst index d3d270fe3b..51692248a3 100644 --- a/doc/src/Modify_contribute.rst +++ b/doc/src/Modify_contribute.rst @@ -7,20 +7,25 @@ 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. +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. + Communication with the LAMMPS developers ---------------------------------------- For any larger modifications or programming project, you are encouraged -to contact the LAMMPS developers ahead of time in order to discuss -implementation strategies and coding guidelines. That will make it -easier to integrate your contribution and results in less work for -everybody involved. You are also encouraged to search through the list -of `open issues on GitHub `_ -and submit a new issue for a planned feature, so you would not duplicate -the work of others (and possibly get scooped by them) or have your work -duplicated by others. +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 informal communication with the LAMMPS developers you may ask to join the `LAMMPS developers on Slack `_. This @@ -32,29 +37,6 @@ for help with compiling, installing, or using LAMMPS. Please post a message to the `LAMMPS forum `_ for those purposes. -Packages versus individual files --------------------------------- - -The remainder of this chapter describes how to add new "style" files of -various kinds to LAMMPS. Packages are simply collections of one or more -such new class files which are invoked as a new style within a LAMMPS -input script. In some cases collections of supporting functions or -classes are also included as separate files in a package, especially when -they can be shared between multiple styles. If designed correctly, these -additions typically do not require any changes to the core code of -LAMMPS; they are simply add-on files that are compiled with the rest of -LAMMPS. To make those styles work, you may need some trivial changes to -the core code; an example of a trivial change is making a parent-class -method "virtual" when you derive a new child class from it. - -If you think your new feature or package requires some non-trivial -changes in core LAMMPS files, you should communicate with the LAMMPS -developers `on Slack `_, `on GitHub -`_, or `via email -`_, since we may have -recommendations about what changes to do where, or may not want to -include certain changes for some reason and thus you would need to look -for alternatives. Time and effort required ------------------------ @@ -63,13 +45,11 @@ How quickly your contribution will be integrated can vary a lot. It depends largely on how much effort it will cause the LAMMPS developers to integrate and test it, how many and what kind of changes to the core code are required, how quickly you can address them and of how much -interest it is to the larger LAMMPS community. Please see the section -on :doc:`LAMMPS programming style and requirements ` for -instructions, recommendations, and formal requirements. A small, -modular, well written contribution may be integrated within hours, but a -complex change that will require a redesign of some core functionality -in LAMMPS for a clean integration can take many months until it is -considered ready for inclusion (though this is rare). +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). Submission procedure @@ -85,29 +65,16 @@ 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 yourself. If you are unable or -unwilling to submit via GitHub yourself, you may also submit patch files +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. -If the new features/files are broadly useful we may add them as core -files to LAMMPS or as part of a :doc:`package `. All -packages are listed and described on the :doc:`Packages details -` doc page. - -Licensing ---------- - -Note that by providing us files to release, you agree to make them -open-source, i.e. we can release them under the terms of the GPL -(version 2) with the rest of LAMMPS. And similarly as part of a LGPL -(version 2.1) distribution of LAMMPS that we make available to -developers on request only and with files that are not authorized for -that kind of distribution removed (e.g. interface to FFTW). See the -:doc:`LAMMPS license ` page for details. External contributions ---------------------- @@ -123,3 +90,32 @@ package and we will post it there. We recommend to name external packages USER-\ so they can be easily distinguished from bundled 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 the list of :doc:`available Packages ` 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 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 (labelled +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. diff --git a/doc/src/Modify_requirements.rst b/doc/src/Modify_requirements.rst new file mode 100644 index 0000000000..8c5869c929 --- /dev/null +++ b/doc/src/Modify_requirements.rst @@ -0,0 +1,362 @@ +Requirements for contributions to LAMMPS +=========================================================== + + +The following is a summary of the current requirements and +recommendations for including contributed source code or documentation +into the LAMMPS software distribution. + +Motivation +---------- + +The LAMMPS developers are committed to providing 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 +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. + +The following requirements and recommendations are provided to help +maintaining or improving that status. It is indicated which 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: +* :ref:`Licensing requirements ` (strict) +* :ref:`Integration testing ` (strict) +* :ref:`Documentation ` (strict) +* :ref:`Programming language standards ` (strict) +* :ref:`Build system ` (strict) +* :ref:`Command or style names ` (strict) +* :ref:`Programming style requirements ` (varied) +* :ref:`Examples ` (preferred) +* :ref:`Error or warning messages and explanations ` (preferred) +* :ref:`Citation reminder ` (optional) +* :ref:`Testing ` (optional) + + +.. _License: +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 `. + +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. + +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. + + +.. _IntegrationTesting +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. + +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. + +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. + + +.. _Documentation +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. + +.. _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. + +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. +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. + +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 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. + +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. + +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. + + +.. _ProgrammingStandards +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 +convenient :doc:`utility functions and classes ` for +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 +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 +required to use those older tools for access to advanced hardware +features or not have the option to install newer compilers or libraries. + + +.. _BuildSystem +Build system (strict) +--------------------------------- + +LAMMPS currently supports two build systems: one that is based on +:doc:`traditional Makefiles ` and one that is based on +:doc:`CMake `. Thus your contribution must be compatible +with and support both. + +For a single pair of header and implementation files that are an +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. + +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 +existing packages and ask the LAMMPS developers if you need assistance. + + +.. _Naming +Command or Style names, file names, and keywords (strict) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +All user-visible command or style names should be all lower case and +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`. + + +.. _ProgrammingStyle +Programming style requirements (varied) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To maintain a consistency, there are various programming style +requirements for contributions to LAMMPS. Some of these requirements +are strict while some are only preferred. An indepth discussion of +the style guidelines are provided in the :doc:`programming style +doc page `. + + +.. _Examples +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 `. Guidlines 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) + +- commands like :doc:`log `, :doc:`echo `, :doc:`package + `, :doc:`processors `, :doc:`suffix ` may + **not** be used in the input file (exception: "processors * * 1" or + similar is acceptable when used to avoid unwanted domain decomposition + of empty volumes) + +- outside of the log files, no generated output should be included + +- custom thermo_style settings may not include output measuring CPU or other + time as it complicates comparisons between different runs + +- input files should be named ``in.name``, data files should be named + ``data.name`` and log files should be named ``log.version.name..`` + +- the total file size of all the inputs and outputs should be small + +- where possible, potential files from the "potentials" folder or data + file from other folders should be re-used through symbolic links + + +.. _ErrorMessages +Error or warning messages and explanations (preferred) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. versionchanged:: 4May2022 + +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 +the class header files with an explanation. Those would then be +regularly "harvested" and transferred to alphabetically sorted lists in +the manual. To avoid excessively long lists and to reduce effort, this +came with a requirement to have rather generic error messages (e.g. +"Illegal ... command"). To identify the specific cause, the name of the +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 `_ 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. + +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() ` can be used +to generate an 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() +` convenience function. +An example for this approach would be the +``src/read_data.cpp`` and ``src/atom.cpp`` files that implement the +:doc:`read_data ` and :doc:`atom_modify ` +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. However, for new code following the +new approach is strongly preferred. The expectation is that the new +scheme will make it easier for LAMMPS users, developers, and +maintainers. + + +.. _Citation +Citation reminder (optional) +----------------------------- + +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. + +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. + +.. _Testing +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. diff --git a/doc/src/Modify_style.rst b/doc/src/Modify_style.rst index 2feffe56c2..2603df8242 100644 --- a/doc/src/Modify_style.rst +++ b/doc/src/Modify_style.rst @@ -1,344 +1,25 @@ -LAMMPS programming style and requirements for contributions +LAMMPS programming style =========================================================== -The following is a summary of the current requirements and -recommendations for including contributed source code or documentation -into the LAMMPS software distribution. - -Motivation ----------- - -The LAMMPS developers are committed to providing 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 -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. - -The following requirements and recommendations are provided to help -maintaining or improving that status. Where possible we utilize -available continuous integration tools to search for common programming -mistakes, portability limitations, incompatible formatting, and -undesired side effects. It is indicated which 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. - -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 `. - -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. - -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. - -Using pull requests on GitHub (preferred) ------------------------------------------ - -All contributions to LAMMPS are processed as pull requests on GitHub -(this also applies to the work of the core LAMMPS developers). A -:doc:`tutorial for submitting pull requests on GitHub ` is -provided. If this is still problematic, contributors may contact any of -the core LAMMPS developers for help or to create a pull request on their -behalf. This latter way of submission may delay the integration as it -depends on the amount of time required to prepare the pull request and -free time available by the LAMMPS developer in question to spend on this -task. - -Integration testing (strict) ----------------------------- - -Contributed code, like all pull requests, 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. Also, the translation of the documentation to HTML -and PDF is tested for. - -More specifically, 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. - -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 -for further details and explanations and suggestions of what needs to be -done. - -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. - -.. _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. - -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. -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. - -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 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. - -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. A few guidelines for such example input -decks. - -- 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). - -- commands like :doc:`log `, :doc:`echo `, :doc:`package - `, :doc:`processors `, :doc:`suffix ` may - **not** be used in the input file (exception: "processors * * 1" or - similar is acceptable when used to avoid unwanted domain decomposition - of empty volumes). - -- outside of the log files, no generated output should be included - -- custom thermo_style settings may not include output measuring CPU or other time - as that makes comparing the thermo output between different runs more complicated. - -- input files should be named ``in.name``, data files should be named - ``data.name`` and log files should be named ``log.version.name..`` - -- the total file size of all the inputs and outputs should be small - -- where possible, potential files from the "potentials" folder or data - file from other folders should be re-used through symbolic links - -Howto document (optional) -------------------------- - -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. - -As a general 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. - -Programming style requirements (varied) ---------------------------------------- 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. +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. -Command or Style names, file names, and keywords (mostly strict) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -All user-visible command or style names should be all lower case and -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`. - -Whitespace and permissions (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. - -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. - -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 -issues. - -Indentation and placement of braces (strongly preferred) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -LAMMPS uses 2 characters per indentation level and lines should be -kept within 100 characters wide. - -For new files added to the "src" tree, a `clang-format -`_ configuration file is -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. - -Error or warning messages and explanations (preferred) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. versionchanged:: 4May2022 - -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 -the class header files with an explanation. Those would then be -regularly "harvested" and transferred to alphabetically sorted lists in -the manual. To avoid excessively long lists and to reduce effort, this -came with a requirement to have rather generic error messages (e.g. -"Illegal ... command"). To identify the specific cause, the name of the -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 and no further lookup would be needed. -This is aided by using the `{fmt} library `_ 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 kept to a single line or two lines at the 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() ` can be used -to generate an 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() -` convenience function. - -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 -new approach is strongly preferred. The expectation is that the new -scheme will make it easier for LAMMPS users, developers, and -maintainers. - -An example for this approach would be the -``src/read_data.cpp`` and ``src/atom.cpp`` files that implement the -:doc:`read_data ` and :doc:`atom_modify ` -commands and that may create :ref:`"Unknown identifier in data file" ` -errors that seem difficult to debug for users because they may have -one of multiple possible reasons, and thus require some additional explanations. - -Programming language standards (required) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -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 -convenient :doc:`utility functions and classes ` for -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 -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 -required to use those older tools for access to advanced hardware -features or not have the option to install newer compilers or libraries. - -Programming conventions (varied) +Include files (varied) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The following is a collection of conventions that should be applied when -writing code for LAMMPS. Following these steps will make it much easier -to integrate your contribution. Please have a look at the existing files -in packages in the src directory for examples. As a demonstration for -how can be adapted to these conventions you may compare the REAXFF -package with the what it looked like when it was called USER-REAXC. If -you are uncertain, please ask. - - system headers or from installed libraries are include with angular brackets (example: ``#include ``), while local include file - use double quotes (example: ``#include "atom.h"``). + 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 @@ -358,6 +39,36 @@ you are uncertain, please ask. - ``using namespace LAMMPS_NS`` or other namespace imports. +- 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 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. + + +Miscellaneous standards (varied) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + - I/O is done via the C-style stdio library and **not** iostreams. - Do not use so-called "alternative tokens" like ``and``, ``or``, @@ -404,32 +115,6 @@ you are uncertain, please ask. B(); }; -- 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 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. - - 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 @@ -450,89 +135,49 @@ you are uncertain, please ask. You may also use ``// clang-format on/off`` throughout your files to protect individual sections from being reformatted. -- 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 into the general purposed of that package. If it does not - fit well, it may be added to one of the EXTRA- packages or the MISC - package. +- 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. + +Whitespace (preferred) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Contributing a package ----------------------- +LAMMPS uses 2 characters per indentation level and lines should be +kept within 100 characters wide. -If your contribution has several 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 make it a package directory with a name like -FOO. In addition to your new files, the directory should contain a -README text file. The README should contain your name and contact -information and a brief description of what your new package does. +Spacing before brackets, after commas, etc. + +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. + +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 +issues. -Build system (strongly preferred) ---------------------------------- +Placement of braces (strongly preferred) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -LAMMPS currently supports two build systems: one that is based on -:doc:`traditional Makefiles ` and one that is based on -:doc:`CMake `. Thus your contribution must be compatible -with and support both. +On new lines for methods, when to use, etc. -For a single pair of header and implementation files that are an -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. - -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 -existing packages and ask the LAMMPS developers if you need assistance. +For new files added to the "src" tree, a `clang-format +`_ configuration file is +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. -Citation reminder (suggested) ------------------------------ - -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. - -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. - - -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. From 77ea3ed215fb0cdeff24e1150574d3ffcad03af1 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Thu, 4 May 2023 16:35:49 -0400 Subject: [PATCH 02/10] reduce sphinx warnings --- doc/src/Modify.rst | 14 +++++++++----- doc/src/Modify_requirements.rst | 7 ++++--- doc/src/Modify_style.rst | 9 ++++----- 3 files changed, 17 insertions(+), 13 deletions(-) diff --git a/doc/src/Modify.rst b/doc/src/Modify.rst index 31e67a66ca..38cf58cbf5 100644 --- a/doc/src/Modify.rst +++ b/doc/src/Modify.rst @@ -1,18 +1,22 @@ Modifying & extending LAMMPS **************************** -LAMMPS is designed in a modular fashion and to be easy to modify or -extend with new functionality. In fact, about 95% of its source code +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. +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 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 `. A discussion of the various -types of styles in LAMMPS is then provided. +: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:`Developer_write`. .. toctree:: diff --git a/doc/src/Modify_requirements.rst b/doc/src/Modify_requirements.rst index 8c5869c929..8c50bea94e 100644 --- a/doc/src/Modify_requirements.rst +++ b/doc/src/Modify_requirements.rst @@ -1,7 +1,6 @@ Requirements for contributions to LAMMPS =========================================================== - The following is a summary of the current requirements and recommendations for including contributed source code or documentation into the LAMMPS software distribution. @@ -41,6 +40,7 @@ include: .. _License: + Licensing requirements (strict) ------------------------------- @@ -69,8 +69,8 @@ that use code with a conflicting license can be split into two parts: Please note, that this split licensed mode may complicate including the contribution in binary packages. +.. _IntegrationTesting: -.. _IntegrationTesting Integration testing (strict) ---------------------------- @@ -95,7 +95,8 @@ testing tools or scripts or tests themselves. This is rare. If in doubt, contact the LAMMPS developer that is assigned to the pull request. -.. _Documentation +.. _Documentation: + Documentation (strict) ---------------------- diff --git a/doc/src/Modify_style.rst b/doc/src/Modify_style.rst index 2603df8242..41f7748e9f 100644 --- a/doc/src/Modify_style.rst +++ b/doc/src/Modify_style.rst @@ -1,5 +1,5 @@ LAMMPS programming style -=========================================================== +======================== The LAMMPS developers aim to employ a consistent programming style and @@ -15,7 +15,7 @@ may serve as representative examples. Include files (varied) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^ - system headers or from installed libraries are include with angular brackets (example: ``#include ``), while local include file @@ -141,8 +141,7 @@ Miscellaneous standards (varied) scripts for interpreted script languages. Whitespace (preferred) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - +^^^^^^^^^^^^^^^^^^^^^^ LAMMPS uses 2 characters per indentation level and lines should be kept within 100 characters wide. @@ -165,7 +164,7 @@ issues. Placement of braces (strongly preferred) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ On new lines for methods, when to use, etc. From 269f07a13784ce5d100fe4b3df91a1d1cd17d40d Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Thu, 4 May 2023 16:42:39 -0400 Subject: [PATCH 03/10] fix a few more sphinx issues and inconsistencies --- doc/src/Modify_contribute.rst | 26 +++++++------- doc/src/Modify_requirements.rst | 60 +++++++++++++++++++-------------- 2 files changed, 48 insertions(+), 38 deletions(-) diff --git a/doc/src/Modify_contribute.rst b/doc/src/Modify_contribute.rst index 51692248a3..0d3c17c9a6 100644 --- a/doc/src/Modify_contribute.rst +++ b/doc/src/Modify_contribute.rst @@ -92,21 +92,21 @@ 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 the list of :doc:`available Packages ` 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 may be added to one of the EXTRA- packages or the MISC -package. +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 +into the general purposed 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 (labelled -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. +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. Changes to core LAMMPS files diff --git a/doc/src/Modify_requirements.rst b/doc/src/Modify_requirements.rst index 8c50bea94e..837e2a3360 100644 --- a/doc/src/Modify_requirements.rst +++ b/doc/src/Modify_requirements.rst @@ -1,5 +1,5 @@ Requirements for contributions to LAMMPS -=========================================================== +======================================== The following is a summary of the current requirements and recommendations for including contributed source code or documentation @@ -21,11 +21,12 @@ 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 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: +maintaining or improving that status. It is indicated which +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: * :ref:`Licensing requirements ` (strict) * :ref:`Integration testing ` (strict) * :ref:`Documentation ` (strict) @@ -36,7 +37,7 @@ include: * :ref:`Examples ` (preferred) * :ref:`Error or warning messages and explanations ` (preferred) * :ref:`Citation reminder ` (optional) -* :ref:`Testing ` (optional) +* :ref:`Testing ` (optional) .. _License: @@ -156,7 +157,8 @@ it for people to get started, the more likely it is that users will try out your new feature. -.. _ProgrammingStandards +.. _ProgrammingStandards: + Programming language standards (strict) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -187,9 +189,10 @@ required to use those older tools for access to advanced hardware features or not have the option to install newer compilers or libraries. -.. _BuildSystem +.. _BuildSystem: + Build system (strict) ---------------------------------- +--------------------- LAMMPS currently supports two build systems: one that is based on :doc:`traditional Makefiles ` and one that is based on @@ -214,9 +217,10 @@ cmake/Modules/Packages/. Please check out how this is handled for existing packages and ask the LAMMPS developers if you need assistance. -.. _Naming +.. _Naming: + Command or Style names, file names, and keywords (strict) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +--------------------------------------------------------- All user-visible command or style names should be all lower case and should only use letters, numbers, or forward slashes. They should be @@ -227,18 +231,21 @@ established (e.g. lj for Lennard-Jones). For a compute style `LMP_COMPUTE_SOME_NAME_H` and the class name `ComputeSomeName`. -.. _ProgrammingStyle +.. _ProgrammingStyle: + Programming style requirements (varied) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +--------------------------------------- -To maintain a consistency, there are various programming style -requirements for contributions to LAMMPS. Some of these requirements -are strict while some are only preferred. An indepth discussion of -the style guidelines are provided in the :doc:`programming style -doc page `. +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 +are only preferred and thus may be skipped. An in-depth discussion of +the style guidelines are provided in the :doc:`programming style doc +page `. -.. _Examples +.. _Examples: + Examples (preferred) -------------------- @@ -246,7 +253,7 @@ 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 `. Guidlines for input scripts include: +: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) @@ -271,9 +278,10 @@ examples/PACKAGES directory are are further described on the file from other folders should be re-used through symbolic links -.. _ErrorMessages +.. _ErrorMessages: + Error or warning messages and explanations (preferred) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +------------------------------------------------------ .. versionchanged:: 4May2022 @@ -319,7 +327,8 @@ scheme will make it easier for LAMMPS users, developers, and maintainers. -.. _Citation +.. _Citation: + Citation reminder (optional) ----------------------------- @@ -348,7 +357,8 @@ 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. -.. _Testing +.. _UnitTesting: + Testing (optional) ------------------ From 56f06bc9e090a3cb58acec75383a3a7cd8bb6f15 Mon Sep 17 00:00:00 2001 From: Joel Thomas Clemmer Date: Fri, 5 May 2023 09:41:54 -0600 Subject: [PATCH 04/10] Reordering styles by priority, misc clean ups --- doc/src/Modify_requirements.rst | 44 +++++------ doc/src/Modify_style.rst | 136 +++++++++++++++----------------- 2 files changed, 86 insertions(+), 94 deletions(-) diff --git a/doc/src/Modify_requirements.rst b/doc/src/Modify_requirements.rst index 837e2a3360..91a17789b6 100644 --- a/doc/src/Modify_requirements.rst +++ b/doc/src/Modify_requirements.rst @@ -27,20 +27,20 @@ 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: -* :ref:`Licensing requirements ` (strict) -* :ref:`Integration testing ` (strict) -* :ref:`Documentation ` (strict) -* :ref:`Programming language standards ` (strict) -* :ref:`Build system ` (strict) -* :ref:`Command or style names ` (strict) -* :ref:`Programming style requirements ` (varied) -* :ref:`Examples ` (preferred) -* :ref:`Error or warning messages and explanations ` (preferred) -* :ref:`Citation reminder ` (optional) -* :ref:`Testing ` (optional) +* :ref:`Licensing requirements ` (strict) +* :ref:`Integration testing ` (strict) +* :ref:`Documentation ` (strict) +* :ref:`Programming language standards ` (strict) +* :ref:`Build system ` (strict) +* :ref:`Command or style names ` (strict) +* :ref:`Programming style requirements ` (varied) +* :ref:`Examples ` (preferred) +* :ref:`Error or warning messages and explanations ` (preferred) +* :ref:`Citation reminder ` (optional) +* :ref:`Testing ` (optional) -.. _License: +.. _ReqLicense: Licensing requirements (strict) ------------------------------- @@ -70,7 +70,7 @@ that use code with a conflicting license can be split into two parts: Please note, that this split licensed mode may complicate including the contribution in binary packages. -.. _IntegrationTesting: +.. _ReqIntegrationTesting: Integration testing (strict) ---------------------------- @@ -96,7 +96,7 @@ testing tools or scripts or tests themselves. This is rare. If in doubt, contact the LAMMPS developer that is assigned to the pull request. -.. _Documentation: +.. _ReqDocumentation: Documentation (strict) ---------------------- @@ -157,7 +157,7 @@ it for people to get started, the more likely it is that users will try out your new feature. -.. _ProgrammingStandards: +.. _ReqProgrammingStandards: Programming language standards (strict) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -189,7 +189,7 @@ required to use those older tools for access to advanced hardware features or not have the option to install newer compilers or libraries. -.. _BuildSystem: +.. _ReqBuildSystem: Build system (strict) --------------------- @@ -217,7 +217,7 @@ cmake/Modules/Packages/. Please check out how this is handled for existing packages and ask the LAMMPS developers if you need assistance. -.. _Naming: +.. _ReqNaming: Command or Style names, file names, and keywords (strict) --------------------------------------------------------- @@ -231,7 +231,7 @@ established (e.g. lj for Lennard-Jones). For a compute style `LMP_COMPUTE_SOME_NAME_H` and the class name `ComputeSomeName`. -.. _ProgrammingStyle: +.. _ReqProgrammingStyle: Programming style requirements (varied) --------------------------------------- @@ -244,7 +244,7 @@ the style guidelines are provided in the :doc:`programming style doc page `. -.. _Examples: +.. _ReqExamples: Examples (preferred) -------------------- @@ -278,7 +278,7 @@ examples/PACKAGES directory are are further described on the file from other folders should be re-used through symbolic links -.. _ErrorMessages: +.. _ReqErrorMessages: Error or warning messages and explanations (preferred) ------------------------------------------------------ @@ -327,7 +327,7 @@ scheme will make it easier for LAMMPS users, developers, and maintainers. -.. _Citation: +.. _ReqCitation: Citation reminder (optional) ----------------------------- @@ -357,7 +357,7 @@ 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. -.. _UnitTesting: +.. _ReqUnitTesting: Testing (optional) ------------------ diff --git a/doc/src/Modify_style.rst b/doc/src/Modify_style.rst index 41f7748e9f..a42bdd0d1f 100644 --- a/doc/src/Modify_style.rst +++ b/doc/src/Modify_style.rst @@ -17,27 +17,16 @@ may serve as representative examples. Include files (varied) ^^^^^^^^^^^^^^^^^^^^^^ -- system headers or from installed libraries are include with angular - brackets (example: ``#include ``), while local include file - 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 ````) - -- 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 - - - LAMMPS include files e.g. ``#include "comm.h"`` or ``#include - "modify.h"`` in alphabetical order followed by an empty line - - - system header files from the C++ or C standard library followed by - an empty line - - - ``using namespace LAMMPS_NS`` or other namespace imports. +- 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. - Header files, especially those defining a "style", should only use the absolute minimum number of include files and **must not** contain @@ -54,16 +43,60 @@ Include files (varied) This also means any such file can assume that `FILE`, `NULL`, and `INT_MAX` are defined. -- 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. +- System headers or from installed libraries are include with angular + brackets (example: ``#include ``), while local include file + 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 ````) + +- 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 + + - LAMMPS include files e.g. ``#include "comm.h"`` or ``#include + "modify.h"`` in alphabetical order followed by an empty line + + - System header files from the C++ or C standard library followed by + an empty line + + - ``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. + +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 +issues. + + +Placement of braces (strongly preferred) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +For new files added to the "src" tree, a `clang-format +`_ configuration file is +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. Miscellaneous standards (varied) @@ -139,44 +172,3 @@ Miscellaneous standards (varied) 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. - -Whitespace (preferred) -^^^^^^^^^^^^^^^^^^^^^^ - -LAMMPS uses 2 characters per indentation level and lines should be -kept within 100 characters wide. - -Spacing before brackets, after commas, etc. - -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. - -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 -issues. - - -Placement of braces (strongly preferred) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -On new lines for methods, when to use, etc. - -For new files added to the "src" tree, a `clang-format -`_ configuration file is -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. - - From a6f60405b6c6c14cfe9c02551df4550028a62afa Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Mon, 8 May 2023 05:52:18 -0400 Subject: [PATCH 05/10] resolve formatting issues and add a few style tweaks from languagetool.org --- doc/src/Modify.rst | 12 ++--- doc/src/Modify_contribute.rst | 56 +++++++++++---------- doc/src/Modify_overview.rst | 32 ++++++------ doc/src/Modify_requirements.rst | 88 +++++++++++++++++---------------- doc/src/Modify_style.rst | 33 ++++++------- doc/src/kspace_modify.rst | 3 +- 6 files changed, 113 insertions(+), 111 deletions(-) diff --git a/doc/src/Modify.rst b/doc/src/Modify.rst index 38cf58cbf5..b10e307b14 100644 --- a/doc/src/Modify.rst +++ b/doc/src/Modify.rst @@ -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 `. .. toctree:: diff --git a/doc/src/Modify_contribute.rst b/doc/src/Modify_contribute.rst index 0d3c17c9a6..21bee1722b 100644 --- a/doc/src/Modify_contribute.rst +++ b/doc/src/Modify_contribute.rst @@ -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 ` or -:doc:`fix style ` which provide a friendly +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. @@ -27,9 +27,9 @@ 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 +For informal communication with the LAMMPS developers, you may ask to join the `LAMMPS developers on Slack `_. This -slack work space is by invitation only. Thus for access, please send an +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 ` 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). +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). 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 ` 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 `_ page of the LAMMPS website for examples of groups that do this. We are happy to advertise your package and website from that page. Simply email the `developers `_ with info about your -package and we will post it there. We recommend to name external +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. @@ -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 ` 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. diff --git a/doc/src/Modify_overview.rst b/doc/src/Modify_overview.rst index ed7ff1a8ac..a3d8e9737d 100644 --- a/doc/src/Modify_overview.rst +++ b/doc/src/Modify_overview.rst @@ -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 `. @@ -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 ` 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 ` 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 ` 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 diff --git a/doc/src/Modify_requirements.rst b/doc/src/Modify_requirements.rst index 91a17789b6..9d5ffd38b2 100644 --- a/doc/src/Modify_requirements.rst +++ b/doc/src/Modify_requirements.rst @@ -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 ` (strict) * :ref:`Integration testing ` (strict) * :ref:`Documentation ` (strict) @@ -39,20 +40,20 @@ your contributions. Requirements include: * :ref:`Citation reminder ` (optional) * :ref:`Testing ` (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 `. +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 +`. 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 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 `_ 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 ` for recurring tasks and a collection of :doc:`platform neutral functions ` for improved @@ -196,8 +198,8 @@ Build system (strict) LAMMPS currently supports two build systems: one that is based on :doc:`traditional Makefiles ` and one that is based on -:doc:`CMake `. Thus your contribution must be compatible -with and support both. +:doc:`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 `. @@ -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 `. Guidelines for input scripts include: +examples/PACKAGES directory 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) @@ -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 `_ 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 `_ 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() ` 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() ` 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. diff --git a/doc/src/Modify_style.rst b/doc/src/Modify_style.rst index a42bdd0d1f..b853ccd721 100644 --- a/doc/src/Modify_style.rst +++ b/doc/src/Modify_style.rst @@ -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 ``), while local include file + 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 @@ -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. diff --git a/doc/src/kspace_modify.rst b/doc/src/kspace_modify.rst index 2d3921e281..351e387c0f 100644 --- a/doc/src/kspace_modify.rst +++ b/doc/src/kspace_modify.rst @@ -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 ` discussion. +parameters, see the :doc:`long-range dispersion howto ` +discussion. ---------- From b54d39adf9b39bd2f93cf2901f1af3816141e4e4 Mon Sep 17 00:00:00 2001 From: Steve Plimpton Date: Fri, 12 May 2023 11:18:07 -0600 Subject: [PATCH 06/10] 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. From 0abb217d597f66221f194e6c17bea4a639a2dbe2 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Fri, 12 May 2023 15:13:29 -0400 Subject: [PATCH 07/10] whitespace --- doc/src/Modify_style.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/src/Modify_style.rst b/doc/src/Modify_style.rst index 4da8501f12..c5aef71597 100644 --- a/doc/src/Modify_style.rst +++ b/doc/src/Modify_style.rst @@ -123,7 +123,7 @@ Miscellaneous standards (varied) .. code-block:: c++ // don't write destructors for A or B like this - + class A : protected Pointers { public: A(); @@ -137,7 +137,7 @@ Miscellaneous standards (varied) }; // instead, let the compiler create the implicit default destructor by not writing it - + class A : protected Pointers { public: A(); From aa069b2cfb4e35ca8796bee3591b7b17cb5687bd Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Fri, 12 May 2023 15:44:54 -0400 Subject: [PATCH 08/10] fix typos --- doc/src/Modify_requirements.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/src/Modify_requirements.rst b/doc/src/Modify_requirements.rst index 15edafb26c..5484040689 100644 --- a/doc/src/Modify_requirements.rst +++ b/doc/src/Modify_requirements.rst @@ -49,7 +49,7 @@ 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 whcih +GitHub. We also have a version of LAMMPS under LGPL 2.1 terms which 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 @@ -105,10 +105,10 @@ 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 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 +folder). The documentation should be written in American English and the +.rst file must only use 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 From cd792763090254cf7639eb5a1ecd2571c931fb9d Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Fri, 12 May 2023 15:45:24 -0400 Subject: [PATCH 09/10] small formatting tweaks --- doc/src/Modify_requirements.rst | 25 ++++++++++++------------- 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/doc/src/Modify_requirements.rst b/doc/src/Modify_requirements.rst index 5484040689..15d7e089af 100644 --- a/doc/src/Modify_requirements.rst +++ b/doc/src/Modify_requirements.rst @@ -16,7 +16,7 @@ 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's necessary to +grow and more features and functionality are added, it is necessary to follow established guidelines when accepting new contributions while also working at the same time to improve the existing code. @@ -204,22 +204,21 @@ 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 -`src/.gitignore``. +``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. +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/Modules/Packages/. Please check out how this is handled for -existing packages and ask the LAMMPS developers if you need -assistance. +``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. .. _ReqNaming: @@ -230,10 +229,10 @@ All user-visible command or style names should be all lower case and 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" in the header file would -then be `LMP_COMPUTE_SOME_NAME_H` and the class name -`ComputeSomeName`. +"some/name" the source files must be called ``compute_some_name.h`` and +``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: From 96af466f4af08af1f90b0bed5554233fa84ff88f Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Fri, 12 May 2023 15:45:55 -0400 Subject: [PATCH 10/10] as a few details to the discussion of programming languages and their standards --- doc/src/Modify_requirements.rst | 35 +++++++++++++++++++++------------ 1 file changed, 22 insertions(+), 13 deletions(-) diff --git a/doc/src/Modify_requirements.rst b/doc/src/Modify_requirements.rst index 15d7e089af..0637c860ab 100644 --- a/doc/src/Modify_requirements.rst +++ b/doc/src/Modify_requirements.rst @@ -168,29 +168,38 @@ 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. +Contributions with code requiring more recent C++ standards are only +accepted as packages with the post C++11 standard code confined to the +package so that it is optional. 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 -desirable, but compatibility with Python 3.5 is **required**. +standard. Since not all platforms supported by LAMMPS provide good +support for compiling Fortran files, it should be considered to rewrite +these parts as C++ code, if possible and thus allow for a wider adoption +of the contribution. As of January 2023, all previously included +Fortran code for the LAMMPS executable has been replaced by equivalent +C++ code. -Compatibility with these older programming language standards is very +Python code must be compatible with Python 3.5 and later. 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 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 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: