diff --git a/doc/src/Commands_parse.rst b/doc/src/Commands_parse.rst index 497bc9e5d3..f6aa859ac2 100644 --- a/doc/src/Commands_parse.rst +++ b/doc/src/Commands_parse.rst @@ -123,14 +123,15 @@ LAMMPS: .. _six: 6. If you want text with spaces to be treated as a single argument, it - can be enclosed in either single or double or triple quotes. A long - single argument enclosed in single or double quotes can span multiple - lines if the "&" character is used, as described above. When the - lines are concatenated together (and the "&" characters and line - breaks removed), the text will become a single line. If you want - multiple lines of an argument to retain their line breaks, the text - can be enclosed in triple quotes, in which case "&" characters are - not needed. For example: + can be enclosed in either single (') or double (") or triple (""") + quotes. A long single argument enclosed in single or double quotes + can span multiple lines if the "&" character is used, as described + in :ref:`1 ` above. When the lines are concatenated together + by LAMMPS (and the "&" characters and line breaks removed), the + combined text will become a single line. If you want multiple lines + of an argument to retain their line breaks, the text can be enclosed + in triple quotes, in which case "&" characters are not needed and do + not function as line continuation character. For example: .. code-block:: LAMMPS @@ -144,8 +145,9 @@ LAMMPS: System temperature = $t """ - In each case, the single, double, or triple quotes are removed when - the single argument they enclose is stored internally. + In each of these cases, the single, double, or triple quotes are + removed and the enclosed text stored internally as a single + argument. See the :doc:`dump modify format `, :doc:`print `, :doc:`if `, and :doc:`python ` commands for diff --git a/doc/src/fix_npt_sphere.rst b/doc/src/fix_npt_sphere.rst index bd52ca9dc5..afaa2c9d67 100644 --- a/doc/src/fix_npt_sphere.rst +++ b/doc/src/fix_npt_sphere.rst @@ -22,7 +22,7 @@ Syntax *disc* value = none = treat particles as 2d discs, not spheres -* additional thermostat and barostat related keyword/value pairs from the :doc:`fix npt ` command can be appended +* NOTE: additional thermostat and barostat and dipole related keyword/value pairs from the :doc:`fix npt ` command can be appended Examples """""""" @@ -33,6 +33,7 @@ Examples fix 2 all npt/sphere temp 300.0 300.0 100.0 x 5.0 5.0 1000.0 fix 2 all npt/sphere temp 300.0 300.0 100.0 x 5.0 5.0 1000.0 disc fix 2 all npt/sphere temp 300.0 300.0 100.0 x 5.0 5.0 1000.0 drag 0.2 + fix 2 all npt/sphere temp 300.0 300.0 100.0 x 5.0 5.0 1000.0 update dipole fix 2 water npt/sphere temp 300.0 300.0 100.0 aniso 0.0 0.0 1000.0 dilate partial Description @@ -61,8 +62,9 @@ The only difference between discs and spheres in this context is their moment of inertia, as used in the time integration. Additional parameters affecting the thermostat and barostat are -specified by keywords and values documented with the :doc:`fix npt ` command. See, for example, discussion of the *temp*, -*iso*, *aniso*, and *dilate* keywords. +specified by keywords and values documented with the :doc:`fix npt +` command. See, for example, discussion of the *temp*, *iso*, +*aniso*, and *dilate* keywords. The particles in the fix group are the only ones whose velocities and positions are updated by the velocity/position update portion of the @@ -87,8 +89,10 @@ this, the fix creates its own computes of style "temp/sphere" and compute fix-ID_temp all temp/sphere compute fix-ID_press all pressure fix-ID_temp -See the :doc:`compute temp/sphere ` and :doc:`compute pressure ` commands for details. Note that the -IDs of the new computes are the fix-ID + underscore + "temp" or fix_ID +See the :doc:`compute temp/sphere ` and +:doc:`compute pressure ` commands for details. Note +that the IDs of the new computes are the fix-ID + underscore + "temp" +or fix_ID + underscore + "press", and the group for the new computes is "all" since pressure is computed for the entire system. @@ -170,7 +174,9 @@ defined by the :doc:`dimension ` keyword. Related commands """""""""""""""" -:doc:`fix npt `, :doc:`fix nve_sphere `, :doc:`fix nvt_sphere `, :doc:`fix npt_asphere `, :doc:`fix_modify ` +:doc:`fix npt `, :doc:`fix nve_sphere `, + :doc:`fix nvt_sphere `, :doc:`fix npt_asphere + `, :doc:`fix_modify ` Default """"""" diff --git a/doc/src/fix_nve_sphere.rst b/doc/src/fix_nve_sphere.rst index 0230255b42..df177a2eca 100644 --- a/doc/src/fix_nve_sphere.rst +++ b/doc/src/fix_nve_sphere.rst @@ -51,7 +51,8 @@ If the *update* keyword is used with the *dipole* value, then the orientation of the dipole moment of each particle is also updated during the time integration. This option should be used for models where a dipole moment is assigned to finite-size particles, -e.g. spheroids via use of the :doc:`atom_style hybrid sphere dipole ` command. +e.g. spheroids via use of the :doc:`atom_style hybrid sphere dipole +` command. The default dipole orientation integrator can be changed to the Dullweber-Leimkuhler-McLachlan integration scheme @@ -75,11 +76,13 @@ moment of inertia, as used in the time integration. Restart, fix_modify, output, run start/stop, minimize info """"""""""""""""""""""""""""""""""""""""""""""""""""""""""" -No information about this fix is written to :doc:`binary restart files `. None of the :doc:`fix_modify ` options -are relevant to this fix. No global or per-atom quantities are stored -by this fix for access by various :doc:`output commands `. +No information about this fix is written to :doc:`binary restart files +`. None of the :doc:`fix_modify ` options are +relevant to this fix. No global or per-atom quantities are stored by +this fix for access by various :doc:`output commands `. No parameter of this fix can be used with the *start/stop* keywords of -the :doc:`run ` command. This fix is not invoked during :doc:`energy minimization `. +the :doc:`run ` command. This fix is not invoked during +:doc:`energy minimization `. Restrictions """""""""""" diff --git a/doc/src/fix_nvt_sphere.rst b/doc/src/fix_nvt_sphere.rst index 91575d4c48..f107940af9 100644 --- a/doc/src/fix_nvt_sphere.rst +++ b/doc/src/fix_nvt_sphere.rst @@ -22,7 +22,7 @@ Syntax *disc* value = none = treat particles as 2d discs, not spheres -* additional thermostat related keyword/value pairs from the :doc:`fix nvt ` command can be appended +* NOTE: additional thermostat and dipole related keyword/value pairs from the :doc:`fix nvt ` command can be appended Examples """""""" @@ -32,6 +32,7 @@ Examples fix 1 all nvt/sphere temp 300.0 300.0 100.0 fix 1 all nvt/sphere temp 300.0 300.0 100.0 disc fix 1 all nvt/sphere temp 300.0 300.0 100.0 drag 0.2 + fix 1 all nvt/sphere temp 300.0 300.0 100.0 update dipole Description """"""""""" @@ -77,13 +78,13 @@ underscore + "temp", and the group for the new compute is the same as the fix group. Note that this is NOT the compute used by thermodynamic output (see -the :doc:`thermo_style ` command) with ID = *thermo_temp*. -This means you can change the attributes of this fix's temperature -(e.g. its degrees-of-freedom) via the -:doc:`compute_modify ` command or print this temperature -during thermodynamic output via the :doc:`thermo_style custom ` command using the appropriate compute-ID. -It also means that changing attributes of *thermo_temp* will have no -effect on this fix. +the :doc:`thermo_style ` command) with ID = +*thermo_temp*. This means you can change the attributes of this fix's +temperature (e.g. its degrees-of-freedom) via the :doc:`compute_modify +` command or print this temperature during +thermodynamic output via the :doc:`thermo_style custom ` +command using the appropriate compute-ID. It also means that changing +attributes of *thermo_temp* will have no effect on this fix. Like other fixes that perform thermostatting, this fix can be used with :doc:`compute commands ` that remove a "bias" from the @@ -148,7 +149,9 @@ defined by the :doc:`dimension ` keyword. Related commands """""""""""""""" -:doc:`fix nvt `, :doc:`fix nve_sphere `, :doc:`fix nvt_asphere `, :doc:`fix npt_sphere `, :doc:`fix_modify ` +:doc:`fix nvt `, :doc:`fix nve_sphere `, + :doc:`fix nvt_asphere `, :doc:`fix npt_sphere + `, :doc:`fix_modify ` Default """"""" diff --git a/doc/src/pair_dipole.rst b/doc/src/pair_dipole.rst index 372ea26794..a8eb9b4c3a 100644 --- a/doc/src/pair_dipole.rst +++ b/doc/src/pair_dipole.rst @@ -78,12 +78,12 @@ Examples Description """"""""""" -Style *lj/cut/dipole/cut* computes interactions between pairs of particles -that each have a charge and/or a point dipole moment. In addition to -the usual Lennard-Jones interaction between the particles (Elj) the -charge-charge (Eqq), charge-dipole (Eqp), and dipole-dipole (Epp) -interactions are computed by these formulas for the energy (E), force -(F), and torque (T) between particles I and J. +Style *lj/cut/dipole/cut* computes interactions between pairs of +particles that each have a charge and/or a point dipole moment. In +addition to the usual Lennard-Jones interaction between the particles +(Elj) the charge-charge (Eqq), charge-dipole (Eqp), and dipole-dipole +(Epp) interactions are computed by these formulas for the energy (E), +force (F), and torque (T) between particles I and J. .. math:: @@ -112,18 +112,18 @@ interactions are computed by these formulas for the energy (E), force \frac{3}{r^5} (\vec{p_i} \bullet \vec{r}) (\vec{p_j} \times \vec{r}) -where :math:`q_i` and :math:`q_j` are the charges on the two particles, -:math:`\vec{p_i}` and :math:`\vec{p_j}` are the dipole moment vectors of -the two particles, r is their separation distance, and the vector r = -Ri - Rj is the separation vector between the two particles. Note that -Eqq and Fqq are simply Coulombic energy and force, Fij = -Fji as -symmetric forces, and Tij != -Tji since the torques do not act -symmetrically. These formulas are discussed in :ref:`(Allen) ` -and in :ref:`(Toukmaji) `. +where :math:`q_i` and :math:`q_j` are the charges on the two +particles, :math:`\vec{p_i}` and :math:`\vec{p_j}` are the dipole +moment vectors of the two particles, r is their separation distance, +and the vector r = Ri - Rj is the separation vector between the two +particles. Note that Eqq and Fqq are simply Coulombic energy and +force, Fij = -Fji as symmetric forces, and Tij != -Tji since the +torques do not act symmetrically. These formulas are discussed in +:ref:`(Allen) ` and in :ref:`(Toukmaji) `. Also note, that in the code, all of these terms (except Elj) have a -:math:`C/\epsilon` prefactor, the same as the Coulombic term in the LJ + -Coulombic pair styles discussed :doc:`here `. C is an +:math:`C/\epsilon` prefactor, the same as the Coulombic term in the +LJ + Coulombic pair styles discussed :doc:`here `. C is an energy-conversion constant and epsilon is the dielectric constant which can be set by the :doc:`dielectric ` command. The same is true of the equations that follow for other dipole pair @@ -135,11 +135,11 @@ moment. In general, a shifted-force potential is a (slightly) modified potential containing extra terms that make both the energy and its derivative go to zero at the cutoff distance; this removes (cutoff-related) problems in energy conservation and any numerical -instability in the equations of motion :ref:`(Allen) `. Shifted-force -interactions for the Lennard-Jones (E_LJ), charge-charge (Eqq), -charge-dipole (Eqp), dipole-charge (Epq) and dipole-dipole (Epp) -potentials are computed by these formulas for the energy (E), force -(F), and torque (T) between particles I and J: +instability in the equations of motion :ref:`(Allen) +`. Shifted-force interactions for the Lennard-Jones (E_LJ), +charge-charge (Eqq), charge-dipole (Eqp), dipole-charge (Epq) and +dipole-dipole (Epp) potentials are computed by these formulas for the +energy (E), force (F), and torque (T) between particles I and J: .. math:: @@ -207,65 +207,52 @@ potentials are computed by these formulas for the energy (E), force where :math:`\epsilon` and :math:`\sigma` are the standard LJ parameters, :math:`r_c` is the cutoff, :math:`q_i` and :math:`q_j` are the charges on the two particles, :math:`\vec{p_i}` and -:math:`\vec{p_j}` are the dipole moment vectors of the two particles, r -is their separation distance, and the vector r = Ri - Rj is the -separation vector between the two particles. Note that Eqq and Fqq are -simply Coulombic energy and force, Fij = -Fji as symmetric forces, and -Tij != -Tji since the torques do not act symmetrically. The +:math:`\vec{p_j}` are the dipole moment vectors of the two particles, +r is their separation distance, and the vector r = Ri - Rj is the +separation vector between the two particles. Note that Eqq and Fqq +are simply Coulombic energy and force, Fij = -Fji as symmetric forces, +and Tij != -Tji since the torques do not act symmetrically. The shifted-force formula for the Lennard-Jones potential is reported in :ref:`(Stoddard) `. The original (non-shifted) formulas for the electrostatic potentials, forces and torques can be found in -:ref:`(Price) `. The shifted-force electrostatic potentials have -been obtained by applying equation 5.13 of :ref:`(Allen) `. The -formulas for the corresponding forces and torques have been obtained by -applying the 'chain rule' as in appendix C.3 of :ref:`(Allen) `. +:ref:`(Price) `. The shifted-force electrostatic potentials +have been obtained by applying equation 5.13 of :ref:`(Allen) +`. The formulas for the corresponding forces and torques have +been obtained by applying the 'chain rule' as in appendix C.3 of +:ref:`(Allen) `. If one cutoff is specified in the pair_style command, it is used for both the LJ and Coulombic (q,p) terms. If two cutoffs are specified, they are used as cutoffs for the LJ and Coulombic (q,p) terms -respectively. This pair style also supports an optional *scale* keyword -as part of a pair_coeff statement, where the interactions can be -scaled according to this factor. This scale factor is also made available -for use with fix adapt. +respectively. This pair style also supports an optional *scale* +keyword as part of a pair_coeff statement, where the interactions can +be scaled according to this factor. This scale factor is also made +available for use with fix adapt. -Style *lj/cut/dipole/long* computes long-range point-dipole -interactions as discussed in :ref:`(Toukmaji) `. Dipole-dipole, -dipole-charge, and charge-charge interactions are all supported, along -with the standard 12/6 Lennard-Jones interactions, which are computed -with a cutoff. A :doc:`kspace_style ` must be defined to -use this pair style. Currently, only :doc:`kspace_style ewald/disp ` support long-range point-dipole -interactions. +Style *lj/cut/dipole/long* computes the short-range portion of +point-dipole interactions as discussed in :ref:`(Toukmaji) +`. Dipole-dipole, dipole-charge, and charge-charge +interactions are all supported, along with the standard 12/6 +Lennard-Jones interactions, which are computed with a cutoff. A +:doc:`kspace_style ` must be defined to use this pair +style. If only dipoles (not point charges) are included in the model, +the kspace style can be one of these 3 options, all of which compute +the long-range portion of dipole-dipole interactions. If the model +includes point charges only the first of these kspace styles can be +used: -Style *lj/long/dipole/long* also computes point-dipole interactions as -discussed in :ref:`(Toukmaji) `. Long-range dipole-dipole, -dipole-charge, and charge-charge interactions are all supported, along -with the standard 12/6 Lennard-Jones interactions. LJ interactions -can be cutoff or long-ranged. +* :doc:`kspace_style ewald/disp ` +* :doc:`kspace_style ewald/dipole ` +* :doc:`kspace_style pppm/dipole ` -For style *lj/long/dipole/long*, if *flag_lj* is set to *long*, no -cutoff is used on the LJ 1/r\^6 dispersion term. The long-range -portion is calculated by using the :doc:`kspace_style ewald_disp ` command. The specified LJ cutoff then -determines which portion of the LJ interactions are computed directly -by the pair potential versus which part is computed in reciprocal -space via the Kspace style. If *flag_lj* is set to *cut*, the LJ -interactions are simply cutoff, as with :doc:`pair_style lj/cut `. If *flag_lj* is set to *off*, LJ interactions -are not computed at all. +Style *lj/long/dipole/long* has the same functionality as style +*lj/cut/dipole/long*, except it also has an option to compute 12/6 +Lennard-Jones interactions for use with a long-range dispersion kspace +style. This is done by setting its *flag_lj* argument to *long*. For +long-range LJ interactions, the doc:`kspace_style ewald/disp +` command must be used. -If *flag_coul* is set to *long*, no cutoff is used on the Coulombic or -dipole interactions. The long-range portion is calculated by using -*ewald_disp* of the :doc:`kspace_style ` command. If -*flag_coul* is set to *off*, Coulombic and dipole interactions are not -computed at all. - -Atoms with dipole moments should be integrated using the :doc:`fix nve/sphere update dipole ` or the :doc:`fix nvt/sphere update dipole ` command to rotate the -dipole moments. The *omega* option on the :doc:`fix langevin ` command can be used to thermostat the -rotational motion. The :doc:`compute temp/sphere ` -command can be used to monitor the temperature, since it includes -rotational degrees of freedom. The :doc:`atom_style hybrid dipole sphere ` command should be used since -it defines the point dipoles and their rotational state. -The magnitude and orientation of the dipole moment for each particle -can be defined by the :doc:`set ` command or in the "Atoms" section -of the data file read in by the :doc:`read_data ` command. +---------- The following coefficients must be defined for each pair of atoms types via the :doc:`pair_coeff ` command as in the examples @@ -287,6 +274,40 @@ type pair. ---------- +Note that for systems using these pair styles, typically particles +should be able to exert torque on each other via their dipole moments +so that the particle and its dipole moment can rotate. This requires +they not be point particles, but finite-size spheres. Thus you should +use a command like :doc:`atom_style hybrid sphere dipole ` +to use particles with both attributes. + +The magnitude and orientation of the dipole moment for each particle +can be defined by the :doc:`set ` command or in the "Atoms" +section of the data file read in by the :doc:`read_data ` +command. + +Rotating finite-size particles have 6 degrees of freedom (DOFs), +translation and rotational. You can use the :doc:`compute temp/sphere +` command to monitor a temperature which includes +all these DOFs. + +Finite-size particles with dipole moments should be integrated using +one of these options: + +* :doc:`fix nve/sphere update dipole ` +* :doc:`fix nve/sphere update dipole ` plus :doc:`fix langevin omega yes ` +* :doc:`fix nvt/sphere update dipole ` +* :doc:`fix npt/sphere update dipole ` + +In all cases the "update dipole" setting insures the dipole moments +are also rotated when the finite-size spheres rotate. The 2nd and 3rd +bullets perform thermostatting; in the case of a Langevin thermostat +the "omega yes" option also thermostats the rotational degrees of +freedom (if desired). The 4th bullet performs thermostatting and +barostatting. + +---------- + .. include:: accel_styles.rst ----------