Merge pull request #3573 from akohlmey/angle-write

Implement angle_write and dihedral_write commands

doc/src/Commands_all.rst

@@ -24,6 +24,7 @@ table above.
 
    * :doc:`angle_coeff <angle_coeff>`
    * :doc:`angle_style <angle_style>`
+   * :doc:`angle_write <angle_write>`
    * :doc:`atom_modify <atom_modify>`
    * :doc:`atom_style <atom_style>`
    * :doc:`balance <balance>`
@@ -45,6 +46,7 @@ table above.
    * :doc:`dielectric <dielectric>`
    * :doc:`dihedral_coeff <dihedral_coeff>`
    * :doc:`dihedral_style <dihedral_style>`
+   * :doc:`dihedral_write <dihedral_write>`
    * :doc:`dimension <dimension>`
    * :doc:`displace_atoms <displace_atoms>`
    * :doc:`dump <dump>`

doc/src/angle_table.rst

@@ -59,9 +59,12 @@ format of this file is described below.
 
 ----------
 
-Suitable tables for use with this angle style can be created using the
-Python code in the ``tools/tabulate`` folder of the LAMMPS source code
-distribution.
+Suitable tables for use with this angle style can be created by LAMMPS
+itself from existing angle styles using the :doc:`angle_write
+<angle_write>` command.  This can be useful to have a template file for
+testing the angle style settings and to build a compatible custom file.
+Another option to generate tables is the Python code in the
+``tools/tabulate`` folder of the LAMMPS source code distribution.
 
 The format of a tabulated file is as follows (without the
 parenthesized comments):
@@ -154,7 +157,7 @@ for more info.
 Related commands
 """"""""""""""""
 
-:doc:`angle_coeff <angle_coeff>`
+:doc:`angle_coeff <angle_coeff>`, :doc:`angle_write <angle_write>`
 
 Default
 """""""

doc/src/angle_write.rst

@@ -0,0 +1,99 @@
+.. index:: angle_write
+
+angle_write command
+===================
+
+Syntax
+""""""
+
+.. code-block:: LAMMPS
+
+   angle_write atype N file keyword
+
+* atype = angle type
+* N = # of values
+* file = name of file to write values to
+* keyword = section name in file for this set of tabulated values
+
+Examples
+""""""""
+
+.. code-block:: LAMMPS
+
+   angle_write 1  500 table.txt Harmonic_1
+   angle_write 3 1000 table.txt Harmonic_3
+
+Description
+"""""""""""
+
+.. versionadded:: TBD
+
+Write energy and force values to a file as a function of angle for the
+currently defined angle potential.  Force in this context means the
+force with respect to the angle, not the force on individual atoms.
+This is useful for plotting the potential function or otherwise
+debugging its values.  The resulting file can also be used as input for
+use with :doc:`angle style table <angle_table>`.
+
+If the file already exists, the table of values is appended to the end
+of the file to allow multiple tables of energy and force to be included
+in one file.  The individual sections may be identified by the *keyword*.
+
+The energy and force values are computed for angles ranging from 0
+degrees to 180 degrees for 3 interacting atoms forming an angle type
+atype, using the appropriate :doc:`angle_coeff <angle_coeff>`
+coefficients. N evenly spaced angles are used.
+
+For example, for N = 6, values are computed at :math:`\theta = 0, 36,
+72, 108, 144, 180`.
+
+The file is written in the format used as input for the
+:doc:`angle_style table <angle_table>` option with *keyword* as the
+section name.  Each line written to the file lists an index number
+(1-N), an angle (in degrees), an energy (in energy units), and a force
+(in force units per radians^2).  In case a new file is created, the
+first line will be a comment with a "DATE:" and "UNITS:" tag with the
+current date and :doc:`units <units>` settings.  For subsequent
+invocations of the *angle_write* command for the same file, data will be
+appended and the current units settings will be compared to the data
+from the header, if present. The *angle_write* will refuse to add a
+table to an existing file if the units are not the same.
+
+Restrictions
+""""""""""""
+
+All force field coefficients for angle and other kinds of interactions
+must be set before this command can be invoked.
+
+The table of the angle energy and force data data is created by using a
+separate, internally created, new LAMMPS instance with a dummy system of
+3 atoms for which the angle potential energy is computed after
+transferring the angle style and coefficients and arranging the 3 atoms
+into the corresponding geometries.  The angle force is then determined
+from the potential energies through numerical differentiation.  As a
+consequence of this approach, not all angle styles are compatible. The
+following conditions must be met:
+
+- The angle style must be able to write its coefficients to a data file.
+  This condition excludes for example :doc:`angle style hybrid <angle_hybrid>` and
+  :doc:`angle style table <angle_table>`.
+- The potential function must not have any terms that depend on geometry
+  properties other than the angle. This condition excludes for example
+  :doc:`angle style class2 <angle_class2>` all angle types for
+  :doc:`angle style charmm <angle_charmm>` that have non-zero
+  Urey-Bradley terms.  Please note that the *write_angle* command has no
+  way of checking for this condition, so the resulting tables may be
+  bogus if the requirement is not met.  It is thus recommended to make
+  careful tests for any created tables.
+
+Related commands
+""""""""""""""""
+
+:doc:`angle_style table <angle_table>`, :doc:`bond_write <bond_write>`,
+:doc:`dihedral_write <dihedral_write>`, :doc:`angle_style <angle_style>`,
+:doc:`angle_coeff <angle_coeff>`
+
+Default
+"""""""
+
+none

doc/src/bond_write.rst

@@ -67,7 +67,7 @@ be specified even if the potential has a finite value at r = 0.0.
 Related commands
 """"""""""""""""
 
-:doc:`bond_style table <bond_table>`,
+:doc:`bond_style table <bond_table>`, `angle_write <angle_write>`,
 :doc:`bond_style <bond_style>`, :doc:`bond_coeff <bond_coeff>`
 
 Default

doc/src/commands_list.rst

@@ -6,6 +6,7 @@ Commands
 
    angle_coeff
    angle_style
+   angle_write
    atom_modify
    atom_style
    balance
@@ -27,6 +28,7 @@ Commands
    dielectric
    dihedral_coeff
    dihedral_style
+   dihedral_write
    dimension
    displace_atoms
    dump

doc/src/dihedral_write.rst

@@ -0,0 +1,101 @@
+.. index:: dihedral_write
+
+dihedral_write command
+======================
+
+Syntax
+""""""
+
+.. code-block:: LAMMPS
+
+   dihedral_write dtype N file keyword
+
+* dtype = dihedral type
+* N = # of values
+* file = name of file to write values to
+* keyword = section name in file for this set of tabulated values
+
+Examples
+""""""""
+
+.. code-block:: LAMMPS
+
+   dihedral_write 1  500 table.txt Harmonic_1
+   dihedral_write 3 1000 table.txt Harmonic_3
+
+Description
+"""""""""""
+
+.. versionadded:: TBD
+
+Write energy and force values to a file as a function of the dihedral
+angle for the currently defined dihedral potential.  Force in this
+context means the force with respect to the dihedral angle, not the
+force on individual atoms.  This is useful for plotting the potential
+function or otherwise debugging its values.  The resulting file can also
+be used as input for use with :doc:`dihedral style table
+<dihedral_table>`.
+
+If the file already exists, the table of values is appended to the end
+of the file to allow multiple tables of energy and force to be included
+in one file.  The individual sections may be identified by the *keyword*.
+
+The energy and force values are computed for dihedrals ranging from 0
+degrees to 360 degrees for 4 interacting atoms forming an dihedral type
+dtype, using the appropriate :doc:`dihedral_coeff <dihedral_coeff>`
+coefficients. N evenly spaced dihedrals are used.  Since 0 and 360
+degrees are the same dihedral angle, the latter entry is skipped.
+
+For example, for N = 6, values would be computed at
+:math:`\phi = 0, 60, 120, 180, 240, 300`.
+
+The file is written in the format used as input for the
+:doc:`dihedral_style table <dihedral_table>` option with *keyword* as
+the section name.  Each line written to the file lists an index number
+(1-N), an dihedral angle (in degrees), an energy (in energy units), and
+a force (in force units per radians^2).  In case a new file is created,
+the first line will be a comment with a "DATE:" and "UNITS:" tag with
+the current date and :doc:`units <units>` settings.  For subsequent
+invocations of the *dihedral_write* command for the same file, data will
+be appended and the current units settings will be compared to the data
+from the header, if present. The *dihedral_write* will refuse to add a
+table to an existing file if the units are not the same.
+
+Restrictions
+""""""""""""
+
+All force field coefficients for dihedrals and other kinds of interactions
+must be set before this command can be invoked.
+
+The table of the dihedral energy and force data data is created by using a
+separate, internally created, new LAMMPS instance with a dummy system of
+4 atoms for which the dihedral potential energy is computed after
+transferring the dihedral style and coefficients and arranging the 4 atoms
+into the corresponding geometries.  The dihedral force is then determined
+from the potential energies through numerical differentiation.  As a
+consequence of this approach, not all dihedral styles are compatible. The
+following conditions must be met:
+
+- The dihedral style must be able to write its coefficients to a data file.
+  This condition excludes for example :doc:`dihedral style hybrid <dihedral_hybrid>` and
+  :doc:`dihedral style table <dihedral_table>`.
+- The potential function must not have any terms that depend on geometry
+  properties other than the dihedral.  This condition excludes for
+  example :doc:`dihedral style class2 <dihedral_class2>`.  Please note
+  that the *write_dihedral* command has no way of checking for this
+  condition.  It will check the style name against an internal list of
+  known to be incompatible styles.  The resulting tables may be bogus
+  for unlisted dihedral styles if the requirement is not met.  It is
+  thus recommended to make careful tests for any created tables.
+
+Related commands
+""""""""""""""""
+
+:doc:`dihedral_style table <dihedral_table>`, :doc:`bond_write <bond_write>`,
+:doc:`angle_write <angle_write>`, :doc:`dihedral_style <dihedral_style>`,
+:doc:`dihedral_coeff <dihedral_coeff>`
+
+Default
+"""""""
+
+none

doc/utils/sphinx-config/false_positives.txt

@@ -174,6 +174,7 @@ attrac
 Atw
 Atwater
 atwt
+atype
 augt
 AuO
 automagically
@@ -828,6 +829,7 @@ dtemp
 dtgrow
 dtheta
 dtshrink
+dtype
 du
 dU
 Ducastelle