From 24e5fafd7f52d920fda2f763df6fd07ecfc205fa Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Sat, 24 Dec 2022 15:31:57 -0500 Subject: [PATCH] more documentation tweaks and corrections. make consistent across package styles --- doc/src/angle_lepton.rst | 40 ++++++++++++++++++----------------- doc/src/bond_lepton.rst | 34 +++++++++++++++-------------- doc/src/lepton_expression.rst | 11 +++++++--- doc/src/pair_lepton.rst | 38 +++++++++++++++++---------------- 4 files changed, 67 insertions(+), 56 deletions(-) diff --git a/doc/src/angle_lepton.rst b/doc/src/angle_lepton.rst index d65f3b6d73..7365dd9ed9 100644 --- a/doc/src/angle_lepton.rst +++ b/doc/src/angle_lepton.rst @@ -20,30 +20,31 @@ Examples angle_style lepton - angle_coeff 1 120.0 "k*theta^2; k=250.0" - angle_coeff 2 90.0 "k2*theta^2 + k3*theta^3 + k4*theta^4; k2=300.0; k3=-100.0; k4=50.0" - angle_coeff 3 109.45 "k*theta^2; k=350.0" + angle_coeff 1 120.0 "k*theta^2; k=250.0" + angle_coeff 2 90.0 "k2*theta^2 + k3*theta^3 + k4*theta^4; k2=300.0; k3=-100.0; k4=50.0" + angle_coeff 3 109.47 "k*theta^2; k=350.0" Description """"""""""" .. versionadded:: TBD -Angle style *lepton* computes angular interactions between three atoms -based on evaluating strings. The potential function must be provided as an -expression string using "theta" as the angle variable relative to the -reference angle :math:`\theta_0` which is provided as an angle coefficient. -For example `"200.0*(theta)^2"` represents a harmonic potential with a -force constant *K* of 200.0 energy units: +Angle style *lepton* computes angular interactions between three atoms, +between which an angle has been defined, based on evaluating strings. +The potential function must be provided as an expression string using +"theta" as the angle variable relative to the reference angle +:math:`\theta_0` which is provided as an angle coefficient. For example +`"200.0*theta^2"` represents a harmonic potential with a force constant +*K* of 200.0 energy units: .. math:: - U_{angle,i} = K (\theta_i - \theta_0)^2 = K \theta^2 \qquad theta = \theta_i - \theta_0 + U_{angle,i} = K (\theta_i - \theta_0)^2 = K \theta^2 \qquad \theta = \theta_i - \theta_0 The `Lepton library `_, that the *lepton* angle style interfaces with, evaluates this expression string at run time to compute the pairwise energy. It also creates an analytical -representation of the differentiation of this expression with respect to +representation of the first derivative of this expression with respect to "r" and then uses that to compute the force between the pairs atoms forming angles as defined by the topology data. @@ -59,10 +60,10 @@ The Lepton expression must be either enclosed in quotes or must not contain any whitespace so that LAMMPS recognizes it as a single keyword. More on valid Lepton expressions below. The :math:`\theta_0` coefficient is the "equilibrium angle". It is entered in degrees, but -internally converted to radians. Thus the expression must assume "theta" -is in radians. The potential energy function in the Lepton expression -is shifted in such a way, that the potential energy is 0 for a angle -:math:`\theta_i == \theta_0`. +internally converted to radians. Thus the expression must assume +"theta" is in radians. The potential energy function in the Lepton +expression is shifted in such a way, that the potential energy is 0 for +a angle :math:`\theta_i == \theta_0`. ---------- @@ -77,14 +78,15 @@ is shifted in such a way, that the potential energy is 0 for a angle Restrictions """""""""""" -This angle style can only be used if LAMMPS was built with the LEPTON -package. See the :doc:`Build package ` page for more -info. +This angle style is part of the LEPTON package and only enabled if LAMMPS +was built with this package. See the :doc:`Build package +` page for more info. Related commands """""""""""""""" -:doc:`angle_coeff ` +:doc:`angle_coeff `, :doc:`angle_style table `, +:doc:`bond_style lepton ` Default """"""" diff --git a/doc/src/bond_lepton.rst b/doc/src/bond_lepton.rst index faa4101f47..bcd10e8033 100644 --- a/doc/src/bond_lepton.rst +++ b/doc/src/bond_lepton.rst @@ -20,21 +20,22 @@ Examples bond_style lepton - 1 1.5 "k*r^2; k=250.0" - 2 1.1 "k2*r^2 + k3*r^3 + k4*r^4; k2=300.0; k3=-100.0; k4=50.0" - 3 1.3 "k*r^2; k=350.0" + bond_coeff 1 1.5 "k*r^2; k=250.0" + bond_coeff 2 1.1 "k2*r^2 + k3*r^3 + k4*r^4; k2=300.0; k3=-100.0; k4=50.0" + bond_coeff 3 1.3 "k*r^2; k=350.0" Description """"""""""" .. versionadded:: TBD -Bond style *lepton* computes bonded interactions between two atom based -on evaluating strings. The potential function must be provided as an -expression string using "r" as the distance variable relative to the -reference distance :math:`r_0` which is provided as a bond coefficient. -For example `"200.0*(r)^2"` represents a harmonic potential with a force -constant *K* of 200.0 energy units: +Bond style *lepton* computes bonded interactions between two atoms, +between which a bond has been defined, based on evaluating strings. The +potential function must be provided as an expression string using "r" as +the distance variable relative to the reference distance :math:`r_0` +which is provided as a bond coefficient. For example `"200.0*r^2"` +represents a harmonic potential with a force constant *K* of 200.0 +energy units: .. math:: @@ -43,12 +44,12 @@ constant *K* of 200.0 energy units: The `Lepton library `_, that the *lepton* bond style interfaces with, evaluates this expression string at run time to compute the pairwise energy. It also creates an analytical -representation of the differentiation of this expression with respect to +representation of the first derivative of this expression with respect to "r" and then uses that to compute the force between the pairs atoms forming bonds as defined by the topology data. The following coefficients must be defined for each bond type via the -:doc:`bond_coeff ` command as in the example above, or in +:doc:`bond_coeff ` command as in the examples above, or in the data file or restart files read by the :doc:`read_data ` or :doc:`read_restart ` commands: @@ -57,7 +58,7 @@ or :doc:`read_restart ` commands: The Lepton expression must be either enclosed in quotes or must not contain any whitespace so that LAMMPS recognizes it as a single keyword. -More on valid Lepton expressions below. The :math:`r_0` it the +More on valid Lepton expressions below. The :math:`r_0` is the "equilibrium distance". The potential energy function in the Lepton expression is shifted in such a way, that the potential energy is 0 for a bond length :math:`r_i == r_0`. @@ -75,14 +76,15 @@ a bond length :math:`r_i == r_0`. Restrictions """""""""""" -This bond style can only be used if LAMMPS was built with the LEPTON -package. See the :doc:`Build package ` page for more -info. +This bond style is part of the LEPTON package and only enabled if LAMMPS +was built with this package. See the :doc:`Build package +` page for more info. Related commands """""""""""""""" -:doc:`bond_coeff `, :doc:`delete_bonds ` +:doc:`bond_coeff `, :doc:`bond_style table `, +:doc:`bond_write `, :doc:`angle_style lepton ` Default """"""" diff --git a/doc/src/lepton_expression.rst b/doc/src/lepton_expression.rst index 618c5239f8..9ecebc921e 100644 --- a/doc/src/lepton_expression.rst +++ b/doc/src/lepton_expression.rst @@ -84,7 +84,7 @@ variables. If necessary, a custom scalar variable needs to be defined that can access the desired (single) item from a non-scalar variable. As an example, the following lines will instruct LAMMPS to ramp the force constant for a harmonic bond from 100.0 to 200.0 during the -next run; +next run: .. code-block:: LAMMPS @@ -113,5 +113,10 @@ definition. For efficiency reasons, the expression string is parsed, optimized, and then stored in an internal, pre-parsed representation for evaluation. -Evaluating Lepton expressions is typically between 2.5 and 5 times -slower than the corresponding compiled and optimized C++ code. +Evaluating a Lepton expression is typically between 2.5 and 5 times +slower than the corresponding compiled and optimized C++ code. If +additional speed or GPU acceleration (via GPU or KOKKOS) is required, +the interaction can be represented as a table. Suitable table files +can be created either internally using the :doc:`pair_write ` +or :doc:`bond_write ` command or through the Python scripts +in the :ref:`tools/tabulate ` folder. diff --git a/doc/src/pair_lepton.rst b/doc/src/pair_lepton.rst index 570388dc13..5cf11b6f91 100644 --- a/doc/src/pair_lepton.rst +++ b/doc/src/pair_lepton.rst @@ -27,9 +27,10 @@ Examples .. code-block:: LAMMPS pair_style lepton 2.5 - pair_coeff * * "k*((r-r0)^2*step(r0-r)); k=200; r0=1.5" 2.0 - pair_coeff 1 2 "4.0*eps*((sig/r)^12 - (sig/r)^6);eps=1.0;sig=1.0" 1.12246204830937 - pair_coeff 2 2 "eps*(2.0*(sig/r)^9 - 3.0*(sig/r)^6);eps=1.0;sig=1.0" + + pair_coeff * * "k*((r-r0)^2*step(r0-r)); k=200; r0=1.5" 2.0 + pair_coeff 1 2 "4.0*eps*((sig/r)^12 - (sig/r)^6);eps=1.0;sig=1.0" 1.12246204830937 + pair_coeff 2 2 "eps*(2.0*(sig/r)^9 - 3.0*(sig/r)^6);eps=1.0;sig=1.0" Description """"""""""" @@ -37,11 +38,11 @@ Description .. versionadded:: TBD Pair style *lepton* computes spherical pairwise interactions based on -evaluating strings. The potential function must be provided as an -expression string using "r" as the distance variable, for example -`"200.0*(r-1.5)^2"` represents a harmonic potential with equilibrium -distance :math:`r_0` of 1.5 distance units and a force constant *K* of -200.0 energy units: +evaluating strings between neighboring atoms within the given cutoff. +The potential function must be provided as an expression string using +"r" as the distance variable. For example `"200.0*(r-1.5)^2"` represents +a harmonic potential around the distance :math:`r_0` of 1.5 distance +units and a force constant *K* of 200.0 energy units: .. math:: @@ -50,7 +51,7 @@ distance :math:`r_0` of 1.5 distance units and a force constant *K* of The `Lepton library `_, that the *lepton* pair style interfaces with, evaluates this expression string at run time to compute the pairwise energy. It also creates an -analytical representation of the differentiation of this expression with +analytical representation of the first derivative of this expression with respect to "r" and then uses that to compute the force between the pairs of particles within the given cutoff. @@ -81,18 +82,19 @@ different value than the global cutoff. Mixing, shift, table, tail correction, restart, rRESPA info """"""""""""""""""""""""""""""""""""""""""""""""""""""""""" -Pair style *lepton* does **not** support mixing. Thus, expressions for -all I,J pairs must be specified explicitly. +Pair style *lepton* does not support mixing. Thus, expressions for +*all* I,J pairs must be specified explicitly. -This pair style supports the :doc:`pair_modify ` -shift option for the energy of the pair interaction. +This pair style does supports the :doc:`pair_modify shift ` +option for shifting the energy of the pair interaction so that it is +0 at the cutoff. -The :doc:`pair_modify ` table options are not relevant for +The :doc:`pair_modify table ` options are not relevant for the this pair style. -This pair style does not support the :doc:`pair_modify ` -tail option for adding long-range tail corrections to energy and -pressure. +This pair style does not support the :doc:`pair_modify tail +` option for adding long-range tail corrections to energy +and pressure. This pair style writes its information to :doc:`binary restart files `, so pair_style and pair_coeff commands do not need to be @@ -107,7 +109,7 @@ This pair style can only be used via the *pair* keyword of the Restrictions """""""""""" -The *lepton* pair style is part of the LEPTON package and only enabled if +This pair style is part of the LEPTON package and only enabled if LAMMPS was built with this package. See the :doc:`Build package ` page for more info.