From 308ecaef1c81814114076b9c9408d0166fae3388 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Wed, 14 Aug 2024 01:34:42 -0400 Subject: [PATCH] more doc reformatting --- doc/src/fix_bocs.rst | 7 +- doc/src/fix_box_relax.rst | 18 +--- doc/src/fix_colvars.rst | 180 +++++++++++++++++--------------- doc/src/fix_damping_cundall.rst | 32 +++--- 4 files changed, 118 insertions(+), 119 deletions(-) diff --git a/doc/src/fix_bocs.rst b/doc/src/fix_bocs.rst index bb50cd1761..b3b6a8b021 100644 --- a/doc/src/fix_bocs.rst +++ b/doc/src/fix_bocs.rst @@ -122,6 +122,10 @@ This fix is not invoked during :doc:`energy minimization `. Restrictions """""""""""" +This fix is part of the BOCS package. It is only enabled if +LAMMPS was built with that package. See the +:doc:`Build package ` page for more info. + As this is computing a (modified) pressure, group-ID should be *all*\ . The pressure correction has only been tested for use with an isotropic @@ -135,9 +139,6 @@ the examples. For the last argument in the command, you should put XXXX_press, where XXXX is the ID given to the fix bocs command (in the example, the ID of the fix bocs command is 1). -This fix is part of the BOCS package. It is only enabled if -LAMMPS was built with that package. See the :doc:`Build package ` page for more info. - Further information """"""""""""""""""" diff --git a/doc/src/fix_box_relax.rst b/doc/src/fix_box_relax.rst index 9f1dade765..7e9ccb2c2d 100644 --- a/doc/src/fix_box_relax.rst +++ b/doc/src/fix_box_relax.rst @@ -159,10 +159,7 @@ these 4 keywords: .. parsed-literal:: - x Ptarget - y Ptarget - z Ptarget - couple xyz + x Ptarget y Ptarget z Ptarget couple xyz The keyword *aniso* means *x*, *y*, and *z* dimensions are controlled independently using the *Pxx*, *Pyy*, and *Pzz* components of the @@ -172,10 +169,7 @@ keywords: .. parsed-literal:: - x Ptarget - y Ptarget - z Ptarget - couple none + x Ptarget y Ptarget z Ptarget couple none The keyword *tri* means *x*, *y*, *z*, *xy*, *xz*, and *yz* dimensions are controlled independently using their individual stress components @@ -185,13 +179,7 @@ these 7 keywords: .. parsed-literal:: - x Ptarget - y Ptarget - z Ptarget - xy 0.0 - yz 0.0 - xz 0.0 - couple none + x Ptarget y Ptarget z Ptarget xy 0.0 yz 0.0 xz 0.0 couple none ---------- diff --git a/doc/src/fix_colvars.rst b/doc/src/fix_colvars.rst index f62ae0e85a..4cfa9688c0 100644 --- a/doc/src/fix_colvars.rst +++ b/doc/src/fix_colvars.rst @@ -46,25 +46,26 @@ Description """"""""""" This fix interfaces LAMMPS to the collective variables `Colvars -`_ library, which allows to accelerate sampling of -rare events and the computation of free energy surfaces and potentials of -mean force (PMFs) for any set of collective variables using a variety of -sampling methods (e.g. umbrella-sampling, metadynamics, ABF...). +`_ library, which allows to accelerate +sampling of rare events and the computation of freeenergy surfaces and +potentials of mean force (PMFs) for any set of collective variables +using a variety of sampling methods (e.g. umbrella-sampling, +metadynamics, ABF...). -This documentation describes only the "fix colvars" command itself in -a LAMMPS script. The Colvars library is fully documented in the included +This documentation describes only the "fix colvars" command itself in a +LAMMPS script. The Colvars library is fully documented in the included `PDF manual `_ or in the webpage `https://colvars.github.io/colvars-refman-lammps/colvars-refman-lammps.html `_. The Colvars library is developed at `https://github.com/Colvars/colvars -`_ A detailed discussion of its +`_. A detailed discussion of its implementation is in :ref:`(Fiorin) `; additional citations for specific features are printed at runtime if these features are used. -There are example scripts on the `Colvars website `_ -as well as in the ``examples/PACKAGES/colvars`` directory in the LAMMPS -source tree. +There are example scripts on the `Colvars website +`_ as well as in the +``examples/PACKAGES/colvars`` directory in the LAMMPS source tree. ---------- @@ -75,42 +76,44 @@ units that are specific to each engine. In LAMMPS, the units used by Colvars are consistent with those specified by the :doc:`units ` command. -.. versionadded:: Colvars_2023-06-04 The special value "*none*" - (lowercase) initializes an empty Colvars module, which - allows loading configuration dynamically using - :doc:`fix_modify ` (see below). +.. versionadded:: Colvars_2023-06-04 -The *group-ID* entry is ignored. "fix colvars" will always apply to -the entire system, but specific atoms will be selected based on -selection keywords in the Colvars configuration file or files. There is -no need to define multiple "fix colvars" instances and it is not -allowed. + The special value "*none*" (lowercase) initializes an empty Colvars + module, which allows loading configuration dynamically using + :doc:`fix_modify ` (see below). -The "output" keyword allows to specify the prefix of output files generated -by Colvars, for example "*output*.colvars.traj" or "output.pmf". Supplying -an empty string suppresses any file output from Colvars to file, except for -data saved into the LAMMPS :doc:`binary restart ` files. +The *group-ID* entry is ignored. "fix colvars" will always apply to the +entire system, but specific atoms will be selected based on selection +keywords in the Colvars configuration file or files. There is no need +to define multiple "fix colvars" instances and it is not allowed. -The "input" keyword allows to specify an optional state file that contains -the restart information needed to continue a previous simulation state. -However, because "fix colvars" records its state in LAMMPS :doc:`binary -restart ` files, this is usually not needed when using the -:doc:`read_restart ` command. +The "output" keyword allows to specify the prefix of output files +generated by Colvars, for example "*output*.colvars.traj" or +"output.pmf". Supplying an empty string suppresses any file output from +Colvars to file, except for data saved into the LAMMPS :doc:`binary +restart ` files. -The *unwrap* keyword controls whether wrapped or unwrapped coordinates are -passed to the Colvars library for calculation of the collective variables and -the resulting forces. The default is *yes*, i.e. the image flags are used to -reconstruct the absolute atom positions. Setting this to *no* will use the -current local coordinates that are wrapped back into the simulation cell at -each re-neighboring step instead. For information about when and how this -affects results, please see +The "input" keyword allows to specify an optional state file that +contains the restart information needed to continue a previous +simulation state. However, because "fix colvars" records its state in +LAMMPS :doc:`binary restart ` files, this is usually not needed +when using the :doc:`read_restart ` command. + +The *unwrap* keyword controls whether wrapped or unwrapped coordinates +are passed to the Colvars library for calculation of the collective +variables and the resulting forces. The default is *yes*, i.e. the +image flags are used to reconstruct the absolute atom positions. +Setting this to *no* will use the current local coordinates that are +wrapped back into the simulation cell at each re-neighboring step +instead. For information about when and how this affects results, +please see `https://colvars.github.io/colvars-refman-lammps/colvars-refman-lammps.html#sec:colvar_atom_groups_wrapping `_. -The *tstat* keyword can be either "NULL" or the label of a thermostatting -fix that thermostats all atoms in the fix colvars group. This will be -used to provide the colvars module with the current thermostat target -temperature. +The *tstat* keyword can be either "NULL" or the label of a +thermostatting fix that thermostats all atoms in the fix colvars +group. This will be used to provide the colvars module with the current +thermostat target temperature. The *seed* keyword contains the seed for the random number generator that will be used in the colvars module. @@ -119,36 +122,38 @@ that will be used in the colvars module. Restarting """""""""" -This fix writes the current state of the Colvars module into :doc:`binary -restart files `. This is in addition to the text-mode -".colvars.state" state file that is written by the Colvars module itself. -The information contained in both files is identical, and the binary LAMMPS -restart file is also used by fix colvars when :doc:`read_restart -` is called in a LAMMPS script. In that case, there is -typically no need to specify the *input* keyword. +This fix writes the current state of the Colvars module into +:doc:`binary restart files `. This is in addition to the +text-mode ".colvars.state" state file that is written by the Colvars +module itself. The information contained in both files is identical, +and the binary LAMMPS restart file is also used by fix colvars when +:doc:`read_restart ` is called in a LAMMPS script. In +that case, there is typically no need to specify the *input* keyword. -As long as LAMMPS binary restarts will be used to continue a simulation, it -is safe to delete the ".colvars.state" files to save space. However, when a -LAMMPS simulation is restarted using :doc:`read_data `, the -Colvars state file must be available and loaded via the "input" keyword or -via a "fix_modify Colvars load" command (see below). +As long as LAMMPS binary restarts will be used to continue a simulation, +it is safe to delete the ".colvars.state" files to save space. However, +when a LAMMPS simulation is restarted using :doc:`read_data +`, the Colvars state file must be available and loaded via +the "input" keyword or via a "fix_modify Colvars load" command (see +below). When restarting, the fix and the Colvars module should be created and -configured using either the original configuration file(s). +configured using the original configuration file(s). Output """""" This fix computes a global scalar which can be accessed by various -:doc:`output commands `. The scalar is the energy due to all -external potentials defined in the Colvars configuration. The scalar value -calculated by this fix is "extensive". +:doc:`output commands `. The scalar is the energy due to +all external potentials defined in the Colvars configuration. The +scalar value calculated by this fix is "extensive". Aside from the state information in a ".colvars.state" file, other -`output files `_ -are produced by Colvars depending on the type of simulation. -For this reason, the "output" keyword is required for fix colvars. +`output files +`_ +are produced by Colvars depending on the type of simulation. For this +reason, the "output" keyword is required for fix colvars. Controlling Colvars via `fix_modify` @@ -156,18 +161,18 @@ Controlling Colvars via `fix_modify` .. versionadded:: Colvars_2023-06-04 -The :doc:`fix_modify ` command may be used on "fix colvars" in -either one of two ways: +The :doc:`fix_modify ` command may be used on "fix colvars" +in either one of two ways: -(1) Provide updated values for the fix parameters, such as *output*, *input*, - *unwrap*, *tstat* and *seed*. Additionally, the :doc:`fix_modify - ` *energy* keyword is supported by this fix to add the energy - change from the biasing force added by Colvars to the global potential - energy of the system as part of :doc:`thermodynamic output ` - (the default is :doc:`fix_modify energy no `). - For example, in a multi-step LAMMPS script involving multiple thermostats - (e.g. fix nvt followed by fix npt), Colvars can read a new thermostat's - target temperature like this: +(1) Provide updated values for the fix parameters, such as *output*, + *input*, *unwrap*, *tstat* and *seed*. Additionally, the + :doc:`fix_modify ` *energy* keyword is supported by this fix + to add the energy change from the biasing force added by Colvars to the + global potential energy of the system as part of :doc:`thermodynamic + output ` (the default is :doc:`fix_modify energy no + `). For example, in a multi-step LAMMPS script involving + multiple thermostats (e.g. fix nvt followed by fix npt), Colvars can + read a new thermostat's target temperature like this: .. code-block:: LAMMPS @@ -186,10 +191,11 @@ either one of two ways: LAMMPS variables referenced by their string representation "${variable}" will be expanded immediately. Note also that this - variable expansion *will also happen within quotes*, similar to what the - :doc:`mdi ` command provides. This feature makes it possible to use - the values of certain LAMMPS variables in Colvars configuration strings. - For example, to synchronize the LAMMPS and Colvars dump frequencies: + variable expansion *will also happen within quotes*, similar to what + the :doc:`mdi ` command provides. This feature makes it + possible to use the values of certain LAMMPS variables in Colvars + configuration strings. For example, to synchronize the LAMMPS and + Colvars dump frequencies: .. code-block:: LAMMPS @@ -199,27 +205,27 @@ either one of two ways: .. note:: - Although it is possible to use :doc:`fix_modify ` at any time, - its results will only reflect the state of the Colvars module at the end - of the most recent "run" or "minimize" command. Any new configuration - added via "fix_modify Colvars configfile" or "fix_modify Colvars config" - will only be loaded when the simulation resumes. Configuration files or - strings will be parsed in the same sequence as they were provided in the - LAMMPS script. + Although it is possible to use :doc:`fix_modify ` at any + time, its results will only reflect the state of the Colvars module + at the end of the most recent "run" or "minimize" command. Any new + configuration added via "fix_modify Colvars configfile" or + "fix_modify Colvars config" will only be loaded when the simulation + resumes. Configuration files or strings will be parsed in the same + sequence as they were provided in the LAMMPS script. Restrictions """""""""""" -This fix is provided by the COLVARS package and is only available if LAMMPS -was built with that package (default in most builds). Some of the features -also require code available from the LEPTON package. See the :doc:`Build -package ` page for more info. +This fix is provided by the COLVARS package and is only available if +LAMMPS was built with that package (default in most builds). Some of +the features also require code available from the LEPTON package. See +the :doc:`Build package ` page for more info. There can only be one Colvars instance defined at a time. Since the -interface communicates only the minimum required amount of information, and -the Colvars module itself can handle an arbitrary number of collective -variables, this is not a limitation of functionality. +interface communicates only the minimum required amount of information, +and the Colvars module itself can handle an arbitrary number of +collective variables, this is not a limitation of functionality. Related commands diff --git a/doc/src/fix_damping_cundall.rst b/doc/src/fix_damping_cundall.rst index 5c532f08d0..19c1e29a6a 100644 --- a/doc/src/fix_damping_cundall.rst +++ b/doc/src/fix_damping_cundall.rst @@ -85,9 +85,12 @@ using an :doc:`atom-style variable `. This non-viscous damping presents the following advantages: -1. damping is independent of velocity, equally damping regions with distinct natural frequencies, -2. damping affects acceleration and vanishes for steady uniform motion of the particles, -3. damping parameter :math:`\gamma` is dimensionless and does not require scaling. +#. damping is independent of velocity, equally damping regions with + distinct natural frequencies, +#. damping affects acceleration and vanishes for steady uniform motion + of the particles, +#. damping parameter :math:`\gamma` is dimensionless and does not + require scaling. ---------- @@ -95,27 +98,28 @@ Restart, fix_modify, output, run start/stop, minimize info """"""""""""""""""""""""""""""""""""""""""""""""""""""""""" No information about this fix is written to :doc:`binary restart files -`. None of the :doc:`fix_modify ` options are -relevant to this fix. No global or per-atom quantities are stored by -this fix for access by various :doc:`output commands `. -No parameter of this fix can be used with the *start/stop* keywords of -the :doc:`run ` command. +`. No global or per-atom quantities are stored by this fix for +access by various :doc:`output commands `. No parameter +of this fix can be used with the *start/stop* keywords of the :doc:`run +` command. The :doc:`fix_modify ` *respa* option is supported by this fix. This allows to set at which level of the :doc:`r-RESPA ` -integrator the fix is modifying forces/torques. Default is the outermost level. +integrator the fix is modifying forces/torques. Default is the outermost +level. -The forces/torques due to this fix are imposed during an energy minimization, -invoked by the :doc:`minimize ` command. This fix should only -be used with damped dynamics minimizers that allow for +The forces/torques due to this fix are imposed during an energy +minimization, invoked by the :doc:`minimize ` command. This +fix should only be used with damped dynamics minimizers that allow for non-conservative forces. See the :doc:`min_style ` command for details. Restrictions """""""""""" -This fix is part of the GRANULAR package. It is only enabled if -LAMMPS was built with that package. See the :doc:`Build package ` page for more info. +This fix is part of the GRANULAR package. It is only enabled if LAMMPS +was built with that package. See the :doc:`Build package +` page for more info. This fix requires that atoms store torque and a radius as defined by the :doc:`atom_style sphere ` command.