\(\renewcommand{\AA}{\text{Å}}\)

4.8.20. Writing or updating documentation

Every contribution that adds a new style or command, or that changes the behavior or the arguments of an existing one, must come with matching documentation. This is a strict requirement for inclusion into the LAMMPS distribution. The documentation sources are written in reStructuredText (files with a .rst suffix in the doc/src/ folder) and translated to HTML and PDF with Sphinx. All text must be written in American English and the .rst files may only contain 7-bit ASCII characters, so they can be cleanly converted to PDF via PDFLaTeX. Special characters and formulas can be included as embedded math typeset in a LaTeX subset.

This page complements the previous sections on writing new styles: where those describe the C++ code of a style, this one describes the documentation that has to accompany it. We use the pair_style born/gauss page (file doc/src/pair_born_gauss.rst) and the fix nve page (file doc/src/fix_nve.rst) as running examples, since both follow the established conventions closely and are short enough to quote in full.

A documentation page is not complete by itself: a new style also has to be registered in the corresponding command tables and overview lists, and the build and consistency checks described at the bottom of this page must pass without errors or warnings.

4.8.21. Anatomy of a style documentation page

A typical per-style documentation page is built from a fixed sequence of elements. The order and the exact wording of the section headers matter, because several of them are verified by automated checks and because common include files (like accel_styles.rst) are shared across all pages. The most reliable way to create a new page is to copy the page of a similar, existing style and adapt it.

Index entries

The very first lines of a documentation page are the Sphinx index directives. There must be one .. index:: entry for every style that is documented on the page, including every accelerated variant (/gpu, /intel, /kk, /omp, /opt).

.. index:: pair_style born/gauss
.. index:: pair_style born/gauss/kk
.. index:: pair_style born/gauss/omp

A single documentation file may describe several closely related styles (for example doc/src/pair_born.rst documents born, born/coul/long, born/coul/msm, and born/coul/wolf). In that case each of those styles, and each of their accelerated variants, needs its own .. index:: line. The completeness of these index entries is verified by make style_check (see below), which parses the ...Style(name,class) macros from the C++ headers and reports any style or accelerated variant whose index entry is missing.

Title and command heading

The page title is the name of the command followed by the word “command”, underlined with a row of = characters that must be at least as long as the title text.

pair_style born/gauss command
=============================

When a page documents multiple styles, it is customary to list the primary style in the title (or to use a more generic title), and to make sure each documented style has an index entry and is reachable through the command tables.

In reStructuredText a heading is indicated by underlining it with characters and the the level of a heading is set by kind of character used. The underline must be at least as long as the heading text; a shorter underline will trigger an error message, and the convention is to match the length exactly. LAMMPS uses a fixed set of characters for the heading levels so that pages nest consistently. This matters in particular for the combined PDF/LaTeX manual, where all pages are concatenated into a single document and therefore have to share one global hierarchy. From the outermost to the innermost level the characters are:

• ====== – the title of an individual page

• ------ – a section

• ^^^^^^ – a subsection

• """""" – a subsubsection

A per-style reference page needs only two of these levels: ====== for the page title (the line ending in “command”) and """""" for each of the standard section headers (Syntax, Examples, Description, …). Pages with a deeper structure – such as Howto or Programmer Guide pages, and this developer page – additionally use ------ and ^^^^^^ for the intermediate levels.

The page title and the section headers show up as collapsible, expandable entries in the navigation sidebar of the HTML manual (the theme is configured with a navigation depth of three levels) and in the table of contents of the PDF manual.

Accelerator Variants line

If, and only if, one or more accelerated variants of the style exist, an “Accelerator Variants:” line follows the title. It lists the full names of the accelerated styles in italics.

Accelerator Variants: *born/gauss/kk*, *born/gauss/omp*

This line and the .. index:: entries for the accelerated variants must be kept consistent with each other and with the actual accelerated styles present in the source tree. Further down the page, the shared file accel_styles.rst is included (see below); make style_check enforces that a page which lists accelerated index entries also includes accel_styles.rst and, conversely, that a page without accelerated styles does not.

Syntax, Examples, and Description

The body of the page begins with a “Syntax” section. It shows the command in a LAMMPS code block and then explains each argument with a bullet list.

Syntax
""""""

.. code-block:: LAMMPS

   pair_style born/gauss cutoff

* born/gauss = name of the pair style
* cutoff = global cutoff (distance units)

The “Examples” section gives one or more short, realistic command sequences, again in a LAMMPS code block.

Examples
""""""""

.. code-block:: LAMMPS

   pair_style born/gauss 10.0
   pair_coeff 1 1 8.2464e13 12.48 0.042644277 0.44 3.56

The “Description” section is the main explanatory text. It describes the model or behavior, typically including the functional form as a .. math:: block and a list of the coefficients with their units.

Description
"""""""""""

.. versionadded:: TBD

Pair style *born/gauss* computes pairwise interactions ...

.. math::

   E = A_0 \exp \left( -\alpha r \right) - A_1 \exp\left[ -\beta \left(r - r_0 \right)^2 \right]

Version markers

New publicly visible commands or newly added keywords must be marked with .. versionadded:: TBD; behavior that changed for an existing command uses .. versionchanged:: TBD. The literal text TBD is replaced automatically with the upcoming version date at release time. These directives are standalone markers: any explanatory text follows as an ordinary, unindented paragraph below the directive, not as the indented body of the directive. Version markers do not apply to internal (uppercase) style names.

Accelerator styles include

For any page that has accelerated variants, a standard block describing how to use accelerated styles is pulled in from the shared file accel_styles.rst, set off by horizontal rules:

----------

.. include:: accel_styles.rst

----------

Using the shared include keeps the description of the accelerator suffixes uniform across all pages, so this text should never be written out by hand.

Category-specific information sections

After the description, most styles have one or more information sections whose header and content are largely standardized per style category. Copy the wording from a closely related style and adjust it for the behavior of your style. Common examples are:

• For pair styles: a section titled “Mixing, shift, table, tail correction, restart, rRESPA info” describing whether the style supports pair_modify mixing, the shift, table, and tail options, whether it writes to binary restart files, and which run_style respa keywords it supports.

• For fix styles: a section titled “Restart, fix_modify, output, run start/stop, minimize info” describing what (if anything) the fix writes to restart files, which fix_modify options it honors, what global or per-atom quantities it makes available to output commands, and whether it is invoked during energy minimization.

• For compute styles: an “Output info” section describing the shape and meaning of the computed scalar, vector, or array and its units.

These sections should be present even when the answer is “none” or “not supported”; the fix nve page is a good template for the minimal case.

Restrictions, related commands, and defaults

Three short sections close out the page.

The “Restrictions” section documents any conditions that must be met for the style to be usable. The most common one is a package requirement: the style is only available when LAMMPS was built with a particular package, with a pointer to the Build package page.

Restrictions
""""""""""""

This pair style is only enabled if LAMMPS was built with the EXTRA-PAIR
package.  See the :doc:`Build package <Build_package>` page for more
info.

Restrictions are not limited to package membership, however. Many styles impose additional conditions; copy the exact wording from the page of a similar style. The most common categories are:

• Package requirement: only enabled when built with a given package (almost all styles outside the core); always link to Build package.

• Newton setting: the style requires the newton setting to be “on” (common for many-body and communication-heavy pair styles) or, more rarely, “off”.

• Command ordering: the command must appear before or after another command – for example before the simulation box is defined by create_box or read_data, after a prerequisite fix, or before any pair_coeff commands.

• Atom style requirement: the style needs an atom style that stores particular per-atom data (e.g. charge, finite size/radius, torque and angular momentum, density or temperature, or support for bonds and angles).

• Dependency on another command: the style only works in conjunction with a specific fix, pair style, bond style, or kspace_style.

• Uniqueness or mutual exclusivity: only a single instance of the style may be defined, or certain keyword combinations cannot be used together.

• Geometry and dimensionality: the style only works for 2d or only for 3d systems, or only for orthogonal (not triclinic) simulation boxes.

• Integrator and parallel constraints: the style is incompatible with run_style respa, is not invoked during energy minimization, or has limitations under MPI domain decomposition.

If there are no restrictions at all, the section contains only the single word none.

The “Related commands” section is a comma-separated list of links (:doc: roles) to closely related commands. The “Default” section describes the default settings of any optional keywords, or the single word none if there are none.

Typical section order

Putting it together, the canonical order of a per-style page is:

1. .. index:: entries (one per documented style and accelerated variant)

2. title with the command suffix

3. “Accelerator Variants:” line (only if accelerated styles exist)

4. Syntax

5. Examples

6. Description (with a versionadded/versionchanged marker if applicable)

7. .. include:: accel_styles.rst block (only if accelerated styles exist)

8. category-specific info section(s) (Mixing… / Restart… / Output info / …)

9. Restrictions

10. Related commands

11. Default

12. literature citations (if any)

Literature citations

If the page cites publications, the citations are placed at the very bottom of the file behind a horizontal rule, each with a unique anchor label and a bold key.

----------

.. _Bomont:

**(Bomont)** Bomont, Bretonnet, J. Chem. Phys. 124, 054504 (2006)

The in-text reference then uses :ref:`(Bomont) <Bomont>`. Citation anchor labels must be unique across all .rst files, so a distinctive label (often including a number or the style name) is needed; make anchor_check reports duplicate labels. See the bottom of doc/fix_nh.rst for more elaborate examples of citation formatting.

4.8.22. Integrating a new style into the command lists

Creating the per-style page is not enough: a new style must also be added to the compact command table and to the alphabetical overview list for its category, or the documentation will build with warnings and make style_check will fail. For a pair style, two files need an entry:

• Commands_pair.rst contains a multi-column table. Add the style in alphabetical order; the accelerator suffix letters are appended in parentheses (g = GPU, i = INTEL, k = KOKKOS, o = OPENMP, t = OPT) and the link target is the documentation file:

  * :doc:`born/gauss (ko) <pair_born_gauss>`
  

• pair_style.rst contains the alphabetical overview list with a short, one-line description after the link:

  * :doc:`born/gauss <pair_born_gauss>` - Born-Mayer / Gaussian potential
  

The other style categories follow the same pattern with different files. make style_check (via utils/check-styles.py) checks exactly these files for completeness:

Category	Compact table file	Overview list file
pair	Commands_pair.rst	pair_style.rst
bond	Commands_bond.rst	bond_style.rst
angle	Commands_bond.rst	angle_style.rst
dihedral	Commands_bond.rst	dihedral_style.rst
improper	Commands_bond.rst	improper_style.rst
compute	Commands_compute.rst	compute.rst
fix	Commands_fix.rst	fix.rst
kspace	Commands_kspace.rst	(none)
dump	Commands_dump.rst	(none)
command	Commands_all.rst	(none)

The suffix letters in the compact table must be listed in the canonical order g i k o t, with no separators (for example ko, never ok or o,k).

4.8.23. Documenting an accelerated variant of an existing style

When a new accelerated variant (e.g. a /kk or /omp version) is added for a style that already exists and is already documented, several small edits are required rather than a new page:

1. Add a .. index:: line for the new accelerated style near the top of the existing page.

2. Add or extend the “Accelerator Variants:” line below the title so it lists the new variant.

3. Make sure the page includes the shared accel_styles.rst block; if the style previously had no accelerated variants, add that include (with surrounding horizontal rules).

4. Add the corresponding suffix letter to the style’s entry in the compact command table (Commands_pair.rst, Commands_fix.rst, …), keeping the canonical g i k o t letter order.

The overview list file (pair_style.rst, fix.rst, …) does not encode the suffix letters and therefore does not need to change for a new accelerated variant.

4.8.24. Adding and referencing example inputs

For most new features it is preferred (see the examples requirement) to add a small, fast example input under the examples or examples/PACKAGES directory. The documentation page should point the reader to it. Two conventions are in common use; both are acceptable:

• mention the directory inside the “Description” or “Examples” section, for instance a line like Example input scripts available: examples/PACKAGES/foo;

• reference specific input files by their path in the relevant discussion.

4.8.25. Other documentation that may need updating

Depending on the nature of the contribution, additional documentation may have to be created or updated:

• New package: add a description to Packages_details.rst and an entry to the package list, and, if the package needs special build steps, add the corresponding build instructions.

• Complex features: if a feature needs more background or a multi-command workflow to be used correctly, contribute a Howto document and add it to the toctree in Howto.rst.

• Library or API changes: additions or changes to the C++ library interface or the Fortran module require doxygen comments in the source and matching updates to the “Programmer Guide” section of the manual.

• Error explanations: errors with multiple possible causes can be given a detailed explanation on the Error_details page with an error code anchor, referenced from the code via utils::errorurl() (see the error message requirements).

• Figures and PDFs: inline figures live in doc/JPG and supplementary PDF files in doc/PDF; see existing pages for how to embed them.

4.8.26. Building and checking the documentation

Before submitting, build and proofread the documentation from within the doc directory:

make html          # build the HTML manual; there should be no warnings
make spelling      # run the spell checker
make anchor_check  # check for duplicate anchors and labels
make style_check   # check completeness of style tables and index entries
make check         # run all consistency checks at once

The make check target bundles anchor_check, style_check, package_check, char_check, and role_check. The char_check target rejects any non-ASCII character in the .rst files, and the role_check target catches malformed roles and directives (for example a :doc: or :ref: role not immediately followed by a backtick, a text <target> hyperlink missing its role, or a directive written with a single colon instead of ::). Carefully read and proofread the generated HTML page before opening the pull request.

If the spell checker reports a false positive (such as an author surname or an established acronym), add it to doc/utils/sphinx-config/false_positives.txt.