documenting bpm multibody

doc/src/bond_bpm_spring.rst

@@ -10,7 +10,7 @@ Syntax
 
    bond_style bpm/spring keyword value attribute1 attribute2 ...
 
-* optional keyword = *overlay/pair* or *store/local* or *smooth* or *break*
+* optional keyword = *overlay/pair* or *store/local* or *smooth* or *break* or *volume/factor*
 
   .. parsed-literal::
 
@@ -36,6 +36,9 @@ Syntax
        *break* value = *yes* or *no*
           indicates whether bonds break during a run
 
+       *volume/factor* value = *yes* or *no*
+          indicates whether forces include the volumetric contribution
+
 Examples
 """"""""
 
@@ -44,6 +47,9 @@ Examples
    bond_style bpm/spring
    bond_coeff 1 1.0 0.05 0.1
 
+   bond_style bpm/spring volume/factor yes
+   bond_coeff 1 1.0 0.05 0.1 0.5
+
    bond_style bpm/spring myfix 1000 time id1 id2
    dump 1 all local 1000 dump.broken f_myfix[1] f_myfix[2] f_myfix[3]
    dump_modify 1 write_header no
@@ -97,15 +103,6 @@ approach the critical strain
 
    w = 1.0 - \left( \frac{r - r_0}{r_0 \epsilon_c} \right)^8 .
 
-The following coefficients must be defined for each bond type via the
-:doc:`bond_coeff <bond_coeff>` command as in the example above, or in
-the data file or restart files read by the :doc:`read_data
-<read_data>` or :doc:`read_restart <read_restart>` commands:
-
-* :math:`k`             (force/distance units)
-* :math:`\epsilon_c`    (unit less)
-* :math:`\gamma`        (force/velocity units)
-
 If the *normalize* keyword is set to *yes*, the elastic bond force will be
 normalized by :math:`r_0` such that :math:`k` must be given in force units.
 
@@ -123,6 +120,43 @@ during a simulation run. This will prevent some unnecessary calculation.
 However, if a bond reaches a strain greater than :math:`\epsilon_c`,
 it will trigger an error.
 
+.. versionadded:: TBD
+
+The *volume/factor* keyword toggles whether an additional multibody
+contribution is added to he force using the formulation in
+:ref:`(Clemmer2) <multibody-Clemmer>`,
+
+.. math::
+
+   \alpha_v \left(\left[\frac{V_i + V_j}{V_{0,i} + V_{0,j}}\right]^{1/3} - \frac{r_{ij}}{r_{0,ij}}\right)
+
+where :math:`\alpha_v` is a user specified coefficient and :math:`V_i`
+and :math:`V_{0,i}` are estimates of the current and local volume
+of atom :math:`i`. These volumes are calculated as the sum of current
+or initial bond lengths cubed. In 2D, the volume is replaced with an area
+calculated using bond lengths squared and the cube root in the above equation
+is accordingly replaced with a square root. This approximation assumes bonds
+are evenly distributed on a spherical surface and neglects constant prefactors
+which are irrelevant since only the ratio of volumes matters. This term may be
+used to adjust the Poisson's ratio.
+
+If a bond is broken (or created), :math:`V_{0,i}` is updated by subtracting
+(or adding) that bond's contribution.
+
+The following coefficients must be defined for each bond type via the
+:doc:`bond_coeff <bond_coeff>` command as in the example above, or in
+the data file or restart files read by the :doc:`read_data
+<read_data>` or :doc:`read_restart <read_restart>` commands:
+
+* :math:`k`             (force/distance units)
+* :math:`\epsilon_c`    (unit less)
+* :math:`\gamma`        (force/velocity units)
+
+Additionally, if *volume/factor* is set to *yes*, a fourth coefficient
+must be provided:
+
+* :math:`a_v`           (force units)
+
 If the *store/local* keyword is used, an internal fix will track bonds that
 break during the simulation. Whenever a bond breaks, data is processed
 and transferred to an internal fix labeled *fix_ID*. This allows the
@@ -213,7 +247,7 @@ Related commands
 Default
 """""""
 
-The option defaults are *overlay/pair* = *no*, *smooth* = *yes*, *normalize* = *no*, and *break* = *yes*
+The option defaults are *overlay/pair* = *no*, *smooth* = *yes*, *normalize* = *no*, *break* = *yes*, and *volume/factor* = *no*
 
 ----------
 
@@ -224,3 +258,7 @@ The option defaults are *overlay/pair* = *no*, *smooth* = *yes*, *normalize* = *
 .. _Groot4:
 
 **(Groot)** Groot and Warren, J Chem Phys, 107, 4423-35 (1997).
+
+.. _multibody-Clemmer:
+
+**(Clemmer2)** Clemmer, Monti, Lechman, Soft Matter, 20, 1702 (2024).