documentation updates for JSON format in general and molecule files in particular

doc/src/Tools.rst

@@ -92,6 +92,7 @@ Miscellaneous tools
    * :ref:`LAMMPS coding standards <coding_standard>`
    * :ref:`emacs <emacs>`
    * :ref:`i-PI <ipi>`
+   * :ref:`JSON support <json>`
    * :ref:`kate <kate>`
    * :ref:`LAMMPS-GUI <lammps_gui>`
    * :ref:`LAMMPS magic patterns for file(1) <magic>`
@@ -364,7 +365,7 @@ These tools were provided by Aidan Thompson at Sandia
 .. _fep:
 
 fep tool
-------------------
+--------
 
 The tools/fep directory contains Python scripts useful for
 post-processing results from performing free-energy perturbation
@@ -379,7 +380,7 @@ See README file in the tools/fep directory.
 .. _ipi:
 
 i-PI tool
--------------------
+---------
 
 .. versionchanged:: 27June2024
 
@@ -432,6 +433,64 @@ tools/createatoms tool's input file.
 
 ----------
 
+.. _json:
+
+JSON support files
+------------------
+
+.. versionadded:: 12June2025
+
+The ``tools/json`` directory contains files and tools to support
+using `JSON format <https://www.json.org/>`_ files in LAMMPS.
+Currently only the :doc:`molecule command <molecule>` supports
+files in JSON format directly, but this is planned to be expanded
+in the future.
+
+JSON file validation
+^^^^^^^^^^^^^^^^^^^^
+
+The JSON syntax is independent of its content, and thus the data in the
+file must follow suitable conventions to be correctly parsed during
+input.  This can be done in a portable fashion using a `JSON schema file
+<https://json-schema.org/>`_ (which is in JSON format as well) to define
+those conventions.  A suitable JSON validator software can then validate
+JSON files against the requirements.  Validating a particular JSON file
+against a schema ensures that both, the syntax *and* the conventions
+are followed.  This is useful when writing or editing JSON files in a
+text editor or when writing a pre-processing script or tool to create
+JSON files for a specific purpose in LAMMPS.  It **cannot** check
+whether the file contents are physically meaningful, though.
+
+One such validator tool is `check-jsonschema
+<https://check-jsonschema.readthedocs.io/>`_ which is written in Python
+and can be installed using the `pip Python package manager
+<https://pypi.org/>`_, best in a virtual environment as shown below (for
+a Bourne Shell command line):
+
+.. code-block:: sh
+
+   python -m venv validate-json
+   source validate-json/bin/activate
+   pip install --upgrade pip
+   pip install check-jsonschema
+
+To validate a specific JSON file against a provided schema (here for
+a :doc:`molecule command file <molecule>` you would then run for example:
+
+.. code-block:: sh
+
+   check-jsonschema --schemafile molecule-schema.json tip3p.json
+
+The latest schema files are also maintained and available for download
+at https://download.lammps.org/json .  This enables validation of JSON
+files even if the LAMMPS sources are not locally available. Example:
+
+.. code-block:: sh
+
+   check-jsonschema --schemafile https://download.lammps.org/json/molecule-schema.json tip3p.json
+
+----------
+
 .. _kate:
 
 kate tool

doc/src/molecule.rst

@@ -34,7 +34,7 @@ Syntax
        *ioff* value = Ioff
          Ioff = offset to add to improper types
        *scale* value = sfactor
-         sfactor = scale factor to apply to the size and mass of the molecule
+         sfactor = scale factor to apply to the size, mass, and dipole of the molecule
 
 Examples
 """"""""
@@ -66,7 +66,7 @@ templates include:
 * :doc:`atom_style template <atom_style>`
 
 The ID of a molecule template can only contain alphanumeric characters
-and underscores.
+and underscores, same as other IDs in LAMMPS.
 
 A single template can contain multiple molecules, listed one per file.
 Some of the commands listed above currently use only the first
@@ -75,7 +75,7 @@ contains multiple molecules.  The :doc:`atom_style template
 <atom_style>` command allows multiple-molecule templates to define a
 system with more than one templated molecule.
 
-The molecule file can be either in *native* format or in `JSON format
+The molecule file can be either in a *native* format or in `JSON format
 <https://www.json.org/>`_.  The details of the two formats are described
 below.  When referencing multiple molecule files in a single *molecule*
 command, each of those files may be either format.
@@ -101,31 +101,35 @@ use that attribute (e.g. no bonds).
    labels will determine the actual types directly depending on the
    current :doc:`labelmap <labelmap>` settings.
 
-The *scale* keyword scales the size of the molecule.  This can be
+The *scale* keyword scales the size of the molecule.  This can be useful
-useful for modeling polydisperse granular rigid bodies.  The scale
+for modeling polydisperse granular rigid bodies.  The scale factor is
-factor is applied to each of these properties in the molecule file, if
+applied to each of these properties in the molecule file, if they are
-they are defined: the individual particle coordinates (Coords
+defined: the individual particle coordinates (Coords or "coords"
-section), the individual mass of each particle (Masses section), the
+section), the individual mass of each particle (Masses or "masses"
-individual diameters of each particle (Diameters section), the total
+section), the individual diameters of each particle (Diameters or
-mass of the molecule (header keyword = mass), the center-of-mass of
+"diameters" section), the per-atom dipoles (Dipoles or "dipoles"
-the molecule (header keyword = com), and the moments of inertia of the
+section) the total mass of the molecule (header keyword = mass), the
-molecule (header keyword = inertia).
+center-of-mass of the molecule (header keyword = com), and the moments
+of inertia of the molecule (header keyword = inertia).
 
 .. note::
 
    The molecule command can be used to define molecules with bonds,
-   angles, dihedrals, impropers, or special bond lists of neighbors
+   angles, dihedrals, impropers, and special bond lists of neighbors
    within a molecular topology, so that you can later add the molecules
    to your simulation, via one or more of the commands listed above.
-   Since this topology-related information requires that suitable storage
+   Since this topology-related information requires that suitable
-   is reserved when LAMMPS creates the simulation box (e.g. when using
+   storage is reserved when LAMMPS creates the simulation box (e.g. when
-   the :doc:`create_box <create_box>` command or the
+   using the :doc:`create_box <create_box>` command or the
-   :doc:`read_data <read_data>` command) suitable space has to be reserved
+   :doc:`read_data <read_data>` command) suitable space has to be
-   so you do not overflow those pre-allocated data structures when adding
+   reserved at that step so you do not overflow those pre-allocated data
-   molecules later.  Both the :doc:`create_box <create_box>` command and
+   structures when adding molecules later.  Both the :doc:`create_box
-   the :doc:`read_data <read_data>` command have "extra" options which
+   <create_box>` command and the :doc:`read_data <read_data>` command
-   ensure space is allocated for storing topology info for molecules that
+   have "extra" options which ensure extra space is allocated for
-   are added later.
+   storing topology info for molecules that are added later.  This
+   feature is *not* available for the :doc:`read_restart command
+   <read_restart>`, thus binary restart files need to be converted
+   to data files first.
 
 ----------
 
@@ -133,8 +137,9 @@ Format of a native molecule file
 """"""""""""""""""""""""""""""""
 
 The format of an "native" individual molecule file looks similar but is
-different than that of a data file read by the :doc:`read_data <read_data>`
+*different* from that of a data file read by the :doc:`read_data
-commands.  Here is a simple example for a TIP3P water molecule:
+<read_data>` commands.  Here is a simple example for a TIP3P water
+molecule:
 
 .. code-block::
 
@@ -678,20 +683,23 @@ the file format.
 Format of a JSON molecule file
 """"""""""""""""""""""""""""""
 
-The format of a JSON format individual molecule file must follow
+The format of a JSON format individual molecule file must follow the
-the `JSON format <https://www.json.org/>`_, which evolved from the
+`JSON format <https://www.json.org/>`_, which evolved from the
 JavaScript programming language as a programming-language-neutral data
 interchange language.  The JSON syntax is independent of its content,
 and thus the data in the file must follow suitable conventions to be
-correctly parsed during input.  LAMMPS provides a `JSON schema file
+correctly processed.  LAMMPS provides a `JSON schema file
-<https://json-schema.org/>`_ to define those conventions so that files
+<https://json-schema.org/>`_ for JSON format molecule files in the
-can be validated against the requirements.  Validating a particular
+:ref:`tools/json folder <json>` to represent those conventions.  Using
-molecule file against this schema ensures that both, the syntax *and*
+the schema file any JSON format molecule files can be validated.
-the conventions are followed, but it **cannot** check whether the
+Validating a particular JSON format molecule file against this schema
-file contents are physically meaningful.
+ensures that both, the JSON syntax requirement *and* the LAMMPS
+conventions for molecule templates are followed.  This is a formal check
+only and thus it **cannot** check whether the file contents are
+physically meaningful.
 
 Here is a simple example for the same TIP3P water molecule from above in
-JSON format and also using :doc:`type lables <labelmap>` instead of
+JSON format and also using :doc:`type labels <labelmap>` instead of
 numeric types:
 
 .. code-block:: json
@@ -742,6 +750,12 @@ numeric types:
        }
    }
 
+Unlike with the native molecule file format, there are no header or body sections, just a list
+of keywords with associated data.  That data is either provided directly following the keyword
+or as a data block.  A data block has to include two keywords, "format" and "data", where the
+former lists the properties that are stored in the "data" lists.  The names and order of entries
+in the "format" list (and thus how the data is interpreted) are currently fixed.
+
 ----------
 
 Restrictions

doc/utils/sphinx-config/false_positives.txt

@@ -4072,6 +4072,7 @@ Vaiwala
 valent
 Valeriu
 valgrind
+validator
 Valone
 valuev
 Valuev