From b7cf79a7b90413ba4ef1a78313cb6a156684f971 Mon Sep 17 00:00:00 2001 From: Richard Berger Date: Sun, 18 Aug 2024 07:59:29 -0600 Subject: [PATCH] docs: start with howto section --- doc/src/Howto_couple.rst | 2 +- doc/src/Howto_elastic.rst | 30 ++++++++++++++++++------------ doc/src/Howto_multiple.rst | 10 +++++----- doc/src/Howto_restart.rst | 18 +++++++++--------- doc/src/Howto_viz.rst | 2 +- 5 files changed, 34 insertions(+), 28 deletions(-) diff --git a/doc/src/Howto_couple.rst b/doc/src/Howto_couple.rst index 7c8ee1e793..7e91cd59c2 100644 --- a/doc/src/Howto_couple.rst +++ b/doc/src/Howto_couple.rst @@ -36,7 +36,7 @@ the context of your application. steps, invoke the command, etc. In this scenario, the other code can be called as a library, as in - 1., or it could be a stand-alone code, invoked by a system() call + 1., or it could be a stand-alone code, invoked by a ``system()`` call made by the command (assuming your parallel machine allows one or more processors to start up another program). In the latter case the stand-alone code could communicate with LAMMPS through files that the diff --git a/doc/src/Howto_elastic.rst b/doc/src/Howto_elastic.rst index d77ff3e778..9a10e2e7d1 100644 --- a/doc/src/Howto_elastic.rst +++ b/doc/src/Howto_elastic.rst @@ -4,21 +4,27 @@ Calculate elastic constants Elastic constants characterize the stiffness of a material. The formal definition is provided by the linear relation that holds between the stress and strain tensors in the limit of infinitesimal deformation. -In tensor notation, this is expressed as s_ij = C_ijkl \* e_kl, where -the repeated indices imply summation. s_ij are the elements of the -symmetric stress tensor. e_kl are the elements of the symmetric strain -tensor. C_ijkl are the elements of the fourth rank tensor of elastic -constants. In three dimensions, this tensor has 3\^4=81 elements. Using -Voigt notation, the tensor can be written as a 6x6 matrix, where C_ij -is now the derivative of s_i w.r.t. e_j. Because s_i is itself a -derivative w.r.t. e_i, it follows that C_ij is also symmetric, with at -most 7\*6/2 = 21 distinct elements. +In tensor notation, this is expressed as + +.. math:: + + s_{ij} = C_{ijkl} e_{kl} + +where +the repeated indices imply summation. :math:`s_{ij}` are the elements of the +symmetric stress tensor. :math:`e_{kl}` are the elements of the symmetric strain +tensor. :math:`C_{ijkl}` are the elements of the fourth rank tensor of elastic +constants. In three dimensions, this tensor has :math:`3^4=81` elements. Using +Voigt notation, the tensor can be written as a 6x6 matrix, where :math:`C_{ij}` +is now the derivative of :math:`s_i` w.r.t. :math:`e_j`. Because :math:`s_i` is itself a +derivative w.r.t. :math:`e_i`, it follows that :math:`C_{ij}` is also symmetric, with at +most :math:`\frac{7 \times 6}{2}` = 21 distinct elements. At zero temperature, it is easy to estimate these derivatives by deforming the simulation box in one of the six directions using the :doc:`change_box ` command and measuring the change in the stress tensor. A general-purpose script that does this is given in the -examples/ELASTIC directory described on the :doc:`Examples ` +``examples/ELASTIC`` directory described on the :doc:`Examples ` doc page. Calculating elastic constants at finite temperature is more @@ -33,7 +39,7 @@ the :doc:`compute born/matrix ` command, which works for any bonded or non-bonded potential in LAMMPS. The most expensive part of the calculation is the sampling of the stress fluctuations. Several examples of this method are -provided in the examples/ELASTIC_T/BORN_MATRIX directory +provided in the ``examples/ELASTIC_T/BORN_MATRIX`` directory described on the :doc:`Examples ` doc page. A second way is to measure @@ -43,7 +49,7 @@ the systematic and statistical errors in this method, the magnitude of the deformation must be chosen judiciously, and care must be taken to fully equilibrate the deformed cell before sampling the stress tensor. An example of this method is provided in the -examples/ELASTIC_T/DEFORMATION directory +``examples/ELASTIC_T/DEFORMATION`` directory described on the :doc:`Examples ` doc page. Another approach is to sample the triclinic cell fluctuations diff --git a/doc/src/Howto_multiple.rst b/doc/src/Howto_multiple.rst index a0680ccd42..0deb5a2464 100644 --- a/doc/src/Howto_multiple.rst +++ b/doc/src/Howto_multiple.rst @@ -44,7 +44,7 @@ For large numbers of independent simulations, you can use :doc:`variables ` and the :doc:`next ` and :doc:`jump ` commands to loop over the same input script multiple times with different settings. For example, this -script, named in.polymer +script, named ``in.polymer`` .. code-block:: LAMMPS @@ -57,7 +57,7 @@ script, named in.polymer next d jump in.polymer -would run 8 simulations in different directories, using a data.polymer +would run 8 simulations in different directories, using a ``data.polymer`` file in each directory. The same concept could be used to run the same system at 8 different temperatures, using a temperature variable and storing the output in different log and dump files, for example @@ -83,10 +83,10 @@ partition of processors. LAMMPS can be run on multiple partitions via the :doc:`-partition command-line switch `. In the last 2 examples, if LAMMPS were run on 3 partitions, the same -scripts could be used if the "index" and "loop" variables were +scripts could be used if the ``index`` and ``loop`` variables were replaced with *universe*\ -style variables, as described in the -:doc:`variable ` command. Also, the "next t" and "next a" -commands would need to be replaced with a single "next a t" command. +:doc:`variable ` command. Also, the :lammps:`next t` and :lammps:`next a` +commands would need to be replaced with a single :lammps:`next a t` command. With these modifications, the 8 simulations of each script would run on the 3 partitions one after the other until all were finished. Initially, 3 simulations would be started simultaneously, one on each diff --git a/doc/src/Howto_restart.rst b/doc/src/Howto_restart.rst index 545e98137c..949327be0b 100644 --- a/doc/src/Howto_restart.rst +++ b/doc/src/Howto_restart.rst @@ -26,8 +26,8 @@ scripts are based on. If that script had the line restart 50 tmp.restart -added to it, it would produce 2 binary restart files (tmp.restart.50 -and tmp.restart.100) as it ran. +added to it, it would produce two binary restart files (``tmp.restart.50`` +and ``tmp.restart.100``) as it ran. This script could be used to read the first restart file and re-run the last 50 timesteps: @@ -47,21 +47,21 @@ last 50 timesteps: run 50 Note that the following commands do not need to be repeated because -their settings are included in the restart file: *units, atom_style, -special_bonds, pair_style, bond_style*. However, these commands do +their settings are included in the restart file: :lammps:`units`, :lammps:`atom_style`, +:lammps:`special_bonds`, :lammps:`pair_style`, :lammps:`bond_style`. However, these commands do need to be used, since their settings are not in the restart file: -*neighbor, fix, timestep*\ . +:lammps:`neighbor`, :lammps:`fix`, :lammps:`timestep`. If you actually use this script to perform a restarted run, you will notice that the thermodynamic data match at step 50 (if you also put a -"thermo 50" command in the original script), but do not match at step +:lammps:`thermo 50` command in the original script), but do not match at step 100. This is because the :doc:`fix langevin ` command uses random numbers in a way that does not allow for perfect restarts. As an alternate approach, the restart file could be converted to a data file as follows: -.. code-block:: LAMMPS +.. code-block:: bash lmp_g++ -r tmp.restart.50 tmp.restart.data @@ -89,8 +89,8 @@ Then, this script could be used to re-run the last 50 steps: reset_timestep 50 run 50 -Note that nearly all the settings specified in the original *in.chain* -script must be repeated, except the *pair_coeff* and *bond_coeff* +Note that nearly all the settings specified in the original ``in.chain`` +script must be repeated, except the :lammps:`pair_coeff` and :lammps:`bond_coeff` commands, since the new data file lists the force field coefficients. Also, the :doc:`reset_timestep ` command is used to tell LAMMPS the current timestep. This value is stored in restart files, but diff --git a/doc/src/Howto_viz.rst b/doc/src/Howto_viz.rst index a5aceb7437..45b807fc2d 100644 --- a/doc/src/Howto_viz.rst +++ b/doc/src/Howto_viz.rst @@ -6,7 +6,7 @@ analyzed in a variety of ways. LAMMPS snapshots are created by the :doc:`dump ` command, which can create files in several formats. The native LAMMPS dump format is a -text file (see "dump atom" or "dump custom") which can be visualized by +text file (see :lammps:`dump atom` or :lammps:`dump custom`) which can be visualized by `several visualization tools `_ for MD simulation trajectories. `OVITO `_ and `VMD `_ seem to be the most popular