documentation updates for JSON format in general and molecule files in particular
This commit is contained in:
Axel Kohlmeyer
@ -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
|
||||
|
||||
@ -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
|
||||
useful for modeling polydisperse granular rigid bodies. The scale
|
||||
factor is applied to each of these properties in the molecule file, if
|
||||
they are defined: the individual particle coordinates (Coords
|
||||
section), the individual mass of each particle (Masses section), the
|
||||
individual diameters of each particle (Diameters section), the total
|
||||
mass of the molecule (header keyword = mass), the center-of-mass of
|
||||
the molecule (header keyword = com), and the moments of inertia of the
|
||||
molecule (header keyword = inertia).
|
||||
The *scale* keyword scales the size of the molecule. This can be useful
|
||||
for modeling polydisperse granular rigid bodies. The scale factor is
|
||||
applied to each of these properties in the molecule file, if they are
|
||||
defined: the individual particle coordinates (Coords or "coords"
|
||||
section), the individual mass of each particle (Masses or "masses"
|
||||
section), the individual diameters of each particle (Diameters or
|
||||
"diameters" section), the per-atom dipoles (Dipoles or "dipoles"
|
||||
section) the total mass of the molecule (header keyword = mass), the
|
||||
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
|
||||
is reserved when LAMMPS creates the simulation box (e.g. when using
|
||||
the :doc:`create_box <create_box>` command or the
|
||||
:doc:`read_data <read_data>` command) suitable space has to be reserved
|
||||
so you do not overflow those pre-allocated data structures when adding
|
||||
molecules later. Both the :doc:`create_box <create_box>` command and
|
||||
the :doc:`read_data <read_data>` command have "extra" options which
|
||||
ensure space is allocated for storing topology info for molecules that
|
||||
are added later.
|
||||
Since this topology-related information requires that suitable
|
||||
storage is reserved when LAMMPS creates the simulation box (e.g. when
|
||||
using the :doc:`create_box <create_box>` command or the
|
||||
:doc:`read_data <read_data>` command) suitable space has to be
|
||||
reserved at that step so you do not overflow those pre-allocated data
|
||||
structures when adding molecules later. Both the :doc:`create_box
|
||||
<create_box>` command and the :doc:`read_data <read_data>` command
|
||||
have "extra" options which ensure extra space is allocated for
|
||||
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>`
|
||||
commands. Here is a simple example for a TIP3P water molecule:
|
||||
*different* from that of a data file read by the :doc:`read_data
|
||||
<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 `JSON format <https://www.json.org/>`_, which evolved from the
|
||||
The format of a JSON format individual molecule file must follow 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
|
||||
<https://json-schema.org/>`_ to define those conventions so that files
|
||||
can be validated against the requirements. Validating a particular
|
||||
molecule file against this schema ensures that both, the syntax *and*
|
||||
the conventions are followed, but it **cannot** check whether the
|
||||
file contents are physically meaningful.
|
||||
correctly processed. LAMMPS provides a `JSON schema file
|
||||
<https://json-schema.org/>`_ for JSON format molecule files in the
|
||||
:ref:`tools/json folder <json>` to represent those conventions. Using
|
||||
the schema file any JSON format molecule files can be validated.
|
||||
Validating a particular JSON format molecule file against this schema
|
||||
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
|
||||
|
||||
@ -4072,6 +4072,7 @@ Vaiwala
|
||||
valent
|
||||
Valeriu
|
||||
valgrind
|
||||
validator
|
||||
Valone
|
||||
valuev
|
||||
Valuev
|
||||
|
||||
Reference in New Issue
Block a user