diff --git a/doc/src/bond_bpm_spring.rst b/doc/src/bond_bpm_spring.rst index 81582bd5ea..4bc5cd3463 100644 --- a/doc/src/bond_bpm_spring.rst +++ b/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 ` 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` (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) `, + +.. 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 ` 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` (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).