From 6239a579e8ff8f4439ca4013fcf94ef757d6612e Mon Sep 17 00:00:00 2001 From: Steve Plimpton Date: Tue, 7 Jul 2020 15:19:17 -0600 Subject: [PATCH] clarify units for energy terms with angles --- doc/src/angle_charmm.rst | 7 +++--- doc/src/angle_class2.rst | 42 +++++++++++++++++++--------------- doc/src/angle_cross.rst | 9 ++++---- doc/src/angle_harmonic.rst | 15 +++++++----- doc/src/angle_mm3.rst | 14 +++++++----- doc/src/angle_quartic.rst | 11 +++++---- doc/src/angle_sdk.rst | 15 +++++++----- doc/src/dihedral_class2.rst | 38 +++++++++++++++--------------- doc/src/dihedral_quadratic.rst | 6 ++++- doc/src/fix_restrain.rst | 8 ++++--- doc/src/improper_class2.rst | 33 ++++++++++++++------------ doc/src/improper_harmonic.rst | 15 +++++++----- 12 files changed, 121 insertions(+), 92 deletions(-) diff --git a/doc/src/angle_charmm.rst b/doc/src/angle_charmm.rst index 98b2f468a8..f0e9200fa0 100644 --- a/doc/src/angle_charmm.rst +++ b/doc/src/angle_charmm.rst @@ -49,13 +49,14 @@ The following coefficients must be defined for each angle type via the the data file or restart files read by the :doc:`read_data ` or :doc:`read_restart ` commands: -* :math:`K` (energy/radian\^2) +* :math:`K` (energy) * :math:`\theta_0` (degrees) * :math:`K_{ub}` (energy/distance\^2) * :math:`r_{ub}` (distance) -:math:`\theta_0` is specified in degrees, but LAMMPS converts it to radians -internally; hence the units of :math:`K` are in energy/radian\^2. +:math:`\theta_0` is specified in degrees, but LAMMPS converts it to +radians internally; hence :math:`K` is effectively energy per +radian\^2. ---------- diff --git a/doc/src/angle_class2.rst b/doc/src/angle_class2.rst index afacfb7c1d..0aa5debe37 100644 --- a/doc/src/angle_class2.rst +++ b/doc/src/angle_class2.rst @@ -41,27 +41,29 @@ The *class2* angle style uses the potential E_{bb} & = M (r_{ij} - r_1) (r_{jk} - r_2) \\ E_{ba} & = N_1 (r_{ij} - r_1) (\theta - \theta_0) + N_2(r_{jk} - r_2)(\theta - \theta_0) -where :math:`E_a` is the angle term, :math:`E_{bb}` is a bond-bond term, and :math:`E_{ba}` is a -bond-angle term. :math:`\theta_0` is the equilibrium angle and :math:`r_1` and :math:`r_2` are -the equilibrium bond lengths. +where :math:`E_a` is the angle term, :math:`E_{bb}` is a bond-bond +term, and :math:`E_{ba}` is a bond-angle term. :math:`\theta_0` is +the equilibrium angle and :math:`r_1` and :math:`r_2` are the +equilibrium bond lengths. See :ref:`(Sun) ` for a description of the COMPASS class2 force field. -Coefficients for the :math:`E_a`, :math:`E_{bb}`, and :math:`E_{ba}` formulas must be defined for -each angle type via the :doc:`angle_coeff ` command as in -the example above, or in the data file or restart files read by the -:doc:`read_data ` or :doc:`read_restart ` -commands. +Coefficients for the :math:`E_a`, :math:`E_{bb}`, and :math:`E_{ba}` +formulas must be defined for each angle type via the :doc:`angle_coeff +` command as in the example above, or in the data file or +restart files read by the :doc:`read_data ` or +:doc:`read_restart ` commands. These are the 4 coefficients for the :math:`E_a` formula: * :math:`\theta_0` (degrees) -* :math:`K_2` (energy/radian\^2) -* :math:`K_3` (energy/radian\^3) -* :math:`K_4` (energy/radian\^4) +* :math:`K_2` (energy) +* :math:`K_3` (energy) +* :math:`K_4` (energy) -:math:`\theta_0` is specified in degrees, but LAMMPS converts it to radians -internally; hence the units of the various :math:`K` are in per-radian. +:math:`\theta_0` is specified in degrees, but LAMMPS converts it to +radians internally; hence the various :math:`K` are effectively energy +per radian\^2 or radian\^3 or radian\^4. For the :math:`E_{bb}` formula, each line in a :doc:`angle_coeff ` command in the input script lists 4 coefficients, the first of which @@ -122,11 +124,15 @@ The *class2/p6* angle style uses the *class2* potential expanded to sixth order: In this expanded term 6 coefficients for the :math:`E_a` formula need to be set: * :math:`\theta_0` (degrees) -* :math:`K_2` (energy/radian\^2) -* :math:`K_3` (energy/radian\^3) -* :math:`K_4` (energy/radian\^4) -* :math:`K_5` (energy/radian\^5) -* :math:`K_6` (energy/radian\^6) +* :math:`K_2` (energy) +* :math:`K_3` (energy) +* :math:`K_4` (energy) +* :math:`K_5` (energy) +* :math:`K_6` (energy) + +:math:`\theta_0` is specified in degrees, but LAMMPS converts it to +radians internally; hence the various :math:`K` are effectively energy +per radian\^2 or radian\^3 or radian\^4 or radian\^5 or radian\^6. The bond-bond and bond-angle terms remain unchanged. diff --git a/doc/src/angle_cross.rst b/doc/src/angle_cross.rst index 4fa95481ac..75fba2632b 100644 --- a/doc/src/angle_cross.rst +++ b/doc/src/angle_cross.rst @@ -40,14 +40,15 @@ the data file or restart files read by the :doc:`read_data ` or :doc:`read_restart ` commands: * :math:`K_{SS}` (energy/distance\^2) -* :math:`K_{BS0}` (energy/distance/rad) -* :math:`K_{BS1}` (energy/distance/rad) +* :math:`K_{BS0}` (energy/distance) +* :math:`K_{BS1}` (energy/distance) * :math:`r_{12,0}` (distance) * :math:`r_{32,0}` (distance) * :math:`\theta_0` (degrees) -:math:`\theta_0` is specified in degrees, but LAMMPS converts it to radians -internally; hence the units of :math:`K_{BS0}` and :math:`K_{BS1}` are in energy/distance/radian. +:math:`\theta_0` is specified in degrees, but LAMMPS converts it to +radians internally; hence the :math:`K_{BS0}` and :math:`K_{BS1}` are +effectively energy/distance per radian. Restrictions """""""""""" diff --git a/doc/src/angle_harmonic.rst b/doc/src/angle_harmonic.rst index 4110f01d9b..04a3361d7b 100644 --- a/doc/src/angle_harmonic.rst +++ b/doc/src/angle_harmonic.rst @@ -44,11 +44,12 @@ The following coefficients must be defined for each angle type via the the data file or restart files read by the :doc:`read_data ` or :doc:`read_restart ` commands: -* :math:`K` (energy/radian\^2) +* :math:`K` (energy) * :math:`\theta_0` (degrees) -:math:`\theta_0` is specified in degrees, but LAMMPS converts it to radians -internally; hence the units of :math:`K` are in energy/radian\^2. +:math:`\theta_0` is specified in degrees, but LAMMPS converts it to +radians internally; hence :math:`K` is effectively energy per +radian\^2. ---------- @@ -61,11 +62,13 @@ produce the same results, except for round-off and precision issues. These accelerated styles are part of the GPU, USER-INTEL, KOKKOS, USER-OMP and OPT packages, respectively. They are only enabled if -LAMMPS was built with those packages. See the :doc:`Build package ` doc page for more info. +LAMMPS was built with those packages. See the :doc:`Build package +` doc page for more info. You can specify the accelerated styles explicitly in your input script -by including their suffix, or you can use the :doc:`-suffix command-line switch ` when you invoke LAMMPS, or you can use the -:doc:`suffix ` command in your input script. +by including their suffix, or you can use the :doc:`-suffix +command-line switch ` when you invoke LAMMPS, or you can +use the :doc:`suffix ` command in your input script. See the :doc:`Speed packages ` doc page for more instructions on how to use the accelerated styles effectively. diff --git a/doc/src/angle_mm3.rst b/doc/src/angle_mm3.rst index cc6ee120cd..988deb8ddc 100644 --- a/doc/src/angle_mm3.rst +++ b/doc/src/angle_mm3.rst @@ -28,20 +28,22 @@ as defined in :ref:`(Allinger) ` E = K (\theta - \theta_0)^2 \left[ 1 - 0.014(\theta - \theta_0) + 5.6(10)^{-5} (\theta - \theta_0)^2 - 7.0(10)^{-7} (\theta - \theta_0)^3 + 9(10)^{-10} (\theta - \theta_0)^4 \right] -where :math:`\theta_0` is the equilibrium value of the angle, and :math:`K` is a -prefactor. The anharmonic prefactors have units :math:`\deg^{-n}`, for example -:math:`-0.014 \deg^{-1}`, :math:`5.6 \cdot 10^{-5} \deg^{-2}`, ... +where :math:`\theta_0` is the equilibrium value of the angle, and +:math:`K` is a prefactor. The anharmonic prefactors have units +:math:`\deg^{-n}`, for example :math:`-0.014 \deg^{-1}`, :math:`5.6 +\cdot 10^{-5} \deg^{-2}`, ... The following coefficients must be defined for each angle type via the :doc:`angle_coeff ` command as in the example above, or in the data file or restart files read by the :doc:`read_data ` or :doc:`read_restart ` commands: -* :math:`K` (energy/radian\^2) +* :math:`K` (energy) * :math:`\theta_0` (degrees) -:math:`\theta_0` is specified in degrees, but LAMMPS converts it to radians -internally; hence the units of :math:`K` are in energy/radian\^2. +:math:`\theta_0` is specified in degrees, but LAMMPS converts it to +radians internally; hence :math:`K` is effectively energy per +radian\^2. Restrictions """""""""""" diff --git a/doc/src/angle_quartic.rst b/doc/src/angle_quartic.rst index 4559389a2a..a9a4f4215a 100644 --- a/doc/src/angle_quartic.rst +++ b/doc/src/angle_quartic.rst @@ -39,12 +39,13 @@ the data file or restart files read by the :doc:`read_data ` or :doc:`read_restart ` commands: * :math:`\theta_0` (degrees) -* :math:`K_2` (energy/radian\^2) -* :math:`K_3` (energy/radian\^3) -* :math:`K_4` (energy/radian\^4) +* :math:`K_2` (energy) +* :math:`K_3` (energy) +* :math:`K_4` (energy) -:math:`\theta_0` is specified in degrees, but LAMMPS converts it to radians -internally; hence the units of :math:`K` are in energy/radian\^2. +:math:`\theta_0` is specified in degrees, but LAMMPS converts it to +radians internally; hence the various :math:`K` are effectively energy +per radian\^2 or radian\^3 or radian\^4. ---------- diff --git a/doc/src/angle_sdk.rst b/doc/src/angle_sdk.rst index 5601e4f245..f986133774 100644 --- a/doc/src/angle_sdk.rst +++ b/doc/src/angle_sdk.rst @@ -44,13 +44,15 @@ is included in :math:`K`. The following coefficients must be defined for each angle type via the :doc:`angle_coeff ` command as in the example above: -* :math:`K` (energy/radian\^2) +* :math:`K` (energy) * :math:`\theta_0` (degrees) -:math:`\theta_0` is specified in degrees, but LAMMPS converts it to radians -internally; hence the units of :math:`K` are in energy/radian\^2. -The also required *lj/sdk* parameters will be extracted automatically -from the pair_style. +:math:`\theta_0` is specified in degrees, but LAMMPS converts it to +radians internally; hence :math:`K` is effectively energy per +radian\^2. + +The required *lj/sdk* parameters are extracted automatically from the +pair_style. ---------- @@ -63,7 +65,8 @@ produce the same results, except for round-off and precision issues. These accelerated styles are part of the GPU, USER-INTEL, KOKKOS, USER-OMP and OPT packages, respectively. They are only enabled if -LAMMPS was built with those packages. See the :doc:`Build package ` doc page for more info. +LAMMPS was built with those packages. See the :doc:`Build package +` doc page for more info. You can specify the accelerated styles explicitly in your input script by including their suffix, or you can use the :doc:`-suffix command-line switch ` when you invoke LAMMPS, or you can use the diff --git a/doc/src/dihedral_class2.rst b/doc/src/dihedral_class2.rst index 034020429b..efc835b619 100644 --- a/doc/src/dihedral_class2.rst +++ b/doc/src/dihedral_class2.rst @@ -111,34 +111,34 @@ be listed under a *AngleTorsion Coeffs* heading and you must leave out the *at*, i.e. only list 8 coefficients after the dihedral type. * *at* -* :math:`D_1` (energy/radian) -* :math:`D_2` (energy/radian) -* :math:`D_3` (energy/radian) -* :math:`E_1` (energy/radian) -* :math:`E_2` (energy/radian) -* :math:`E_3` (energy/radian) +* :math:`D_1` (energy) +* :math:`D_2` (energy) +* :math:`D_3` (energy) +* :math:`E_1` (energy) +* :math:`E_2` (energy) +* :math:`E_3` (energy) * :math:`\theta_1` (degrees) * :math:`\theta_2` (degrees) -:math:`\theta_1` and :math:`\theta_2` are specified in degrees, but LAMMPS converts -them to radians internally; hence the units of :math:`D` and :math:`E` are in -energy/radian. +:math:`\theta_1` and :math:`\theta_2` are specified in degrees, but +LAMMPS converts them to radians internally; hence the various +:math:`D` and :math:`E` are effectively energy per radian. -For the :math:`E_{aat}` formula, each line in a -:doc:`dihedral_coeff ` command in the input script lists -4 coefficients, the first of which is *aat* to indicate they are -AngleAngleTorsion coefficients. In a data file, these coefficients -should be listed under a *AngleAngleTorsion Coeffs* heading and you -must leave out the *aat*, i.e. only list 3 coefficients after the -dihedral type. +For the :math:`E_{aat}` formula, each line in a :doc:`dihedral_coeff +` command in the input script lists 4 coefficients, +the first of which is *aat* to indicate they are AngleAngleTorsion +coefficients. In a data file, these coefficients should be listed +under a *AngleAngleTorsion Coeffs* heading and you must leave out the +*aat*, i.e. only list 3 coefficients after the dihedral type. * *aat* -* :math:`M` (energy/radian\^2) +* :math:`M` (energy) * :math:`\theta_1` (degrees) * :math:`\theta_2` (degrees) -:math:`\theta_1` and :math:`\theta_2` are specified in degrees, but LAMMPS converts -them to radians internally; hence the units of M are in energy/radian\^2. +:math:`\theta_1` and :math:`\theta_2` are specified in degrees, but +LAMMPS converts them to radians internally; hence :math:`M` is +effectively energy per radian\^2. For the :math:`E_{bb13}` formula, each line in a :doc:`dihedral_coeff ` command in the input script lists diff --git a/doc/src/dihedral_quadratic.rst b/doc/src/dihedral_quadratic.rst index bdc5f79559..2b95e6ff30 100644 --- a/doc/src/dihedral_quadratic.rst +++ b/doc/src/dihedral_quadratic.rst @@ -39,9 +39,13 @@ above, or in the data file or restart files read by the :doc:`read_data ` or :doc:`read_restart ` commands: -* :math:`K` (energy/radian\^2) +* :math:`K` (energy) * :math:`\phi_0` (degrees) +:math:`\phi_0` is specified in degrees, but LAMMPS converts it to +radians internally; hence :math:`K` is effectively energy per +radian\^2. + ---------- Styles with a *gpu*\ , *intel*\ , *kk*\ , *omp*\ , or *opt* suffix are diff --git a/doc/src/fix_restrain.rst b/doc/src/fix_restrain.rst index d3cdecd46a..fdc5be06bc 100644 --- a/doc/src/fix_restrain.rst +++ b/doc/src/fix_restrain.rst @@ -183,11 +183,13 @@ the restraint is with the following coefficients: -* :math:`K` (energy/radian\^2) +* :math:`K` (energy) * :math:`\theta_0` (degrees) -:math:`K` and :math:`\theta_0` are specified with the fix. Note that the usual 1/2 -factor is included in :math:`K`. +:math:`K` and :math:`\theta_0` are specified with the fix. +:math:`\theta_0` is specified in degrees, but LAMMPS converts it to +radians internally; hence :math:`K` is effectively energy per +radian\^2. Note that the usual 1/2 factor is included in :math:`K`. ---------- diff --git a/doc/src/improper_class2.rst b/doc/src/improper_class2.rst index be50a18299..1345a1ed6f 100644 --- a/doc/src/improper_class2.rst +++ b/doc/src/improper_class2.rst @@ -74,29 +74,31 @@ commands. These are the 2 coefficients for the :math:`E_i` formula: -* :math:`K` (energy/radian\^2) +* :math:`K` (energy) * :math:`\chi_0` (degrees) -:math:`\chi_0` is specified in degrees, but LAMMPS converts it to radians -internally; hence the units of K are in energy/radian\^2. +:math:`\chi_0` is specified in degrees, but LAMMPS converts it to +radians internally; hence :math:`K` is effectively energy per +radian\^2. -For the :math:`E_{aa}` formula, each line in a -:doc:`improper_coeff ` command in the input script lists -7 coefficients, the first of which is *aa* to indicate they are -AngleAngle coefficients. In a data file, these coefficients should be -listed under a *AngleAngle Coeffs* heading and you must leave out the -*aa*, i.e. only list 6 coefficients after the improper type. +For the :math:`E_{aa}` formula, each line in a :doc:`improper_coeff +` command in the input script lists 7 coefficients, +the first of which is *aa* to indicate they are AngleAngle +coefficients. In a data file, these coefficients should be listed +under a *AngleAngle Coeffs* heading and you must leave out the *aa*, +i.e. only list 6 coefficients after the improper type. * *aa* -* :math:`M_1` (energy/distance) -* :math:`M_2` (energy/distance) -* :math:`M_3` (energy/distance) +* :math:`M_1` (energy) +* :math:`M_2` (energy) +* :math:`M_3` (energy) * :math:`\theta_1` (degrees) * :math:`\theta_2` (degrees) * :math:`\theta_3` (degrees) -The theta values are specified in degrees, but LAMMPS converts them to -radians internally; hence the units of M are in energy/radian\^2. +The :math:`\theta` values are specified in degrees, but LAMMPS +converts them to radians internally; hence the hence the various +:math:`M` are effectively energy per radian\^2. ---------- @@ -109,7 +111,8 @@ produce the same results, except for round-off and precision issues. These accelerated styles are part of the GPU, USER-INTEL, KOKKOS, USER-OMP and OPT packages, respectively. They are only enabled if -LAMMPS was built with those packages. See the :doc:`Build package ` doc page for more info. +LAMMPS was built with those packages. See the :doc:`Build package +` doc page for more info. You can specify the accelerated styles explicitly in your input script by including their suffix, or you can use the :doc:`-suffix command-line switch ` when you invoke LAMMPS, or you can use the diff --git a/doc/src/improper_harmonic.rst b/doc/src/improper_harmonic.rst index 0f525ff34b..204d7e95c4 100644 --- a/doc/src/improper_harmonic.rst +++ b/doc/src/improper_harmonic.rst @@ -59,11 +59,12 @@ above, or in the data file or restart files read by the :doc:`read_data ` or :doc:`read_restart ` commands: -* :math:`K` (energy/radian\^2) +* :math:`K` (energy) * :math:`\chi_0` (degrees) -:math:`\chi_0` is specified in degrees, but LAMMPS converts it to radians -internally; hence the units of K are in energy/radian\^2. +:math:`\chi_0` is specified in degrees, but LAMMPS converts it to +radians internally; hence :math:`K` is effectively energy per +radian\^2. ---------- @@ -76,11 +77,13 @@ produce the same results, except for round-off and precision issues. These accelerated styles are part of the GPU, USER-INTEL, KOKKOS, USER-OMP and OPT packages, respectively. They are only enabled if -LAMMPS was built with those packages. See the :doc:`Build package ` doc page for more info. +LAMMPS was built with those packages. See the :doc:`Build package +` doc page for more info. You can specify the accelerated styles explicitly in your input script -by including their suffix, or you can use the :doc:`-suffix command-line switch ` when you invoke LAMMPS, or you can use the -:doc:`suffix ` command in your input script. +by including their suffix, or you can use the :doc:`-suffix +command-line switch ` when you invoke LAMMPS, or you can +use the :doc:`suffix ` command in your input script. See the :doc:`Speed packages ` doc page for more instructions on how to use the accelerated styles effectively.