use k_B consistently, fix some more math. convert some transcriptions to math

Define a computation that calculates the translational kinetic energy

of a group of particles.

The kinetic energy of each particle is computed as 1/2 m v\^2, where m

and v are the mass and velocity of the particle.

The kinetic energy of each particle is computed as :math:`\frac{1}{2} m

v^2`, where *m* and *v* are the mass and velocity of the particle.

There is a subtle difference between the quantity calculated by this

compute and the kinetic energy calculated by the *ke* or *etotal*

:doc:`thermo_style <thermo_style>` command.  For this compute, kinetic

energy is "translational" kinetic energy, calculated by the simple

formula above.  For thermodynamic output, the *ke* keyword infers

kinetic energy from the temperature of the system with 1/2 Kb T of

energy for each degree of freedom.  For the default temperature

computation via the :doc:`compute temp <compute_temp>` command, these

are the same.  But different computes that calculate temperature can

subtract out different non-thermal components of velocity and/or

include different degrees of freedom (translational, rotational, etc).

kinetic energy from the temperature of the system with

:math:`\frac{1}{2} k_B T` of energy for each degree of freedom.  For the

default temperature computation via the :doc:`compute temp

<compute_temp>` command, these are the same.  But different computes

that calculate temperature can subtract out different non-thermal

components of velocity and/or include different degrees of freedom

(translational, rotational, etc).

**Output info:**

""""""""

.. parsed-literal::

.. code-block:: LAMMPS

   compute 1 all ke/atom/eff

group.  The particles are assumed to be nuclei and electrons modeled

with the :doc:`electronic force field <pair_eff>`.

The kinetic energy for each nucleus is computed as 1/2 m v\^2, where m

corresponds to the corresponding nuclear mass, and the kinetic energy

for each electron is computed as 1/2 (me v\^2 + 3/4 me s\^2), where me

and v correspond to the mass and translational velocity of each

electron, and s to its radial velocity, respectively.

The kinetic energy for each nucleus is computed as :math:`\frac{1}{2} m

v^2`, where *m* corresponds to the corresponding nuclear mass, and the

kinetic energy for each electron is computed as :math:`\frac{1}{2} (m_e

v^2 + \frac{3}{4} m_e s^2)`, where :math:`m_e` and *v* correspond to the mass

and translational velocity of each electron, and *s* to its radial

velocity, respectively.

There is a subtle difference between the quantity calculated by this

compute and the kinetic energy calculated by the *ke* or *etotal*

energy is "translational" plus electronic "radial" kinetic energy,

calculated by the simple formula above. For thermodynamic output, the

*ke* keyword infers kinetic energy from the temperature of the system

with 1/2 Kb T of energy for each (nuclear-only) degree of freedom in

eFF.

with :math:`\frac{1}{2} k_B T` of energy for each (nuclear-only) degree

of freedom in eFF.

.. note::

   command, as shown in the following example:

.. parsed-literal::

.. code-block:: LAMMPS

   compute         effTemp all temp/eff

   thermo_style    custom step etotal pe ke temp press

group of eFF particles (nuclei and electrons), as modeled with the

:doc:`electronic force field <pair_eff>`.

The kinetic energy for each nucleus is computed as 1/2 m v\^2 and the

kinetic energy for each electron is computed as 1/2(me v\^2 + 3/4 me

s\^2), where m corresponds to the nuclear mass, me to the electron

mass, v to the translational velocity of each particle, and s to the

radial velocity of the electron, respectively.

The kinetic energy for each nucleus is computed as :math:`\frac{1}{2} m

v^2` and the kinetic energy for each electron is computed as

:math:`\frac{1}{2}(m_e v^2 + \frac{3}{4} m_e s^2)`, where *m*

corresponds to the nuclear mass, :math:`m_e` to the electron mass, *v*

to the translational velocity of each particle, and *s* to the radial

velocity of the electron, respectively.

There is a subtle difference between the quantity calculated by this

compute and the kinetic energy calculated by the *ke* or *etotal*

energy is "translational" and "radial" (only for electrons) kinetic

energy, calculated by the simple formula above.  For thermodynamic

output, the *ke* keyword infers kinetic energy from the temperature of

the system with 1/2 Kb T of energy for each degree of freedom.  For

the eFF temperature computation via the :doc:`compute temp\_eff <compute_temp_eff>` command, these are the same.  But

different computes that calculate temperature can subtract out

different non-thermal components of velocity and/or include other

degrees of freedom.

the system with :math:`\frac{1}{2} k_B T` of energy for each degree of

freedom.  For the eFF temperature computation via the :doc:`compute

temp\_eff <compute_temp_eff>` command, these are the same.  But

different computes that calculate temperature can subtract out different

non-thermal components of velocity and/or include other degrees of

freedom.

IMPRORTANT NOTE: The temperature in eFF models should be monitored via

.. warning::

   The temperature in eFF models should be monitored via

   the :doc:`compute temp/eff <compute_temp_eff>` command, which can be

   printed with thermodynamic output by using the

   :doc:`thermo_modify <thermo_modify>` command, as shown in the following

   example:

.. parsed-literal::

   compute         effTemp all temp/eff

""""""""

.. parsed-literal::

.. code-block:: LAMMPS

   compute 1 all pressure thermo_temp

   compute 1 all pressure NULL pair bond

   P = \frac{N k_B T}{V} + \frac{\sum_{i}^{N'} r_i \bullet f_i}{dV}

where N is the number of atoms in the system (see discussion of DOF

below), Kb is the Boltzmann constant, T is the temperature, d is the

dimensionality of the system (2 or 3 for 2d/3d), and V is the system

volume (or area in 2d).  The second term is the virial, equal to

where *N* is the number of atoms in the system (see discussion of DOF

below), :math:`k_B` is the Boltzmann constant, *T* is the temperature, d

is the dimensionality of the system (2 or 3 for 2d/3d), and *V* is the

system volume (or area in 2d).  The second term is the virial, equal to

-dU/dV, computed for all pairwise as well as 2-body, 3-body, 4-body,

many-body, and long-range interactions, where r\_i and f\_i are the

position and force vector of atom i, and the black dot indicates a dot

product.  When periodic boundary conditions are used, N' necessarily

includes periodic image (ghost) atoms outside the central box, and the

position and force vectors of ghost atoms are thus included in the

summation.  When periodic boundary conditions are not used, N' = N =

the number of atoms in the system.  :doc:`Fixes <fix>` that impose

constraints (e.g. the :doc:`fix shake <fix_shake>` command) also

contribute to the virial term.

many-body, and long-range interactions, where :math:`r_i` and

:math:`f_i` are the position and force vector of atom *i*, and the black

dot indicates a dot product.  When periodic boundary conditions are

used, N' necessarily includes periodic image (ghost) atoms outside the

central box, and the position and force vectors of ghost atoms are thus

included in the summation.  When periodic boundary conditions are not

used, N' = N = the number of atoms in the system.  :doc:`Fixes <fix>`

that impose constraints (e.g. the :doc:`fix shake <fix_shake>` command)

also contribute to the virial term.

A symmetric pressure tensor, stored as a 6-element vector, is also

calculated by this compute.  The 6 components of the vector are

LAMMPS starts up, as if this command were in the input script:

.. parsed-literal::

.. code-block:: LAMMPS

   compute thermo_press all pressure thermo_temp

""""""""

.. parsed-literal::

.. code-block:: LAMMPS

   fix 3 boundary langevin 1.0 1.0 1000.0 699483

   fix 1 all langevin 1.0 1.1 100.0 48279 scale 3 1.5

will have the form:

.. parsed-literal::

   F = Fc + Ff + Fr

   Ff = - (m / damp) v

   Fr is proportional to sqrt(Kb T m / (dt damp))

Fc is the conservative force computed via the usual inter-particle

interactions (:doc:`pair_style <pair_style>`,

:doc:`bond_style <bond_style>`, etc).

The Ff and Fr terms are added by this fix on a per-particle basis.

See the :doc:`pair_style dpd/tstat <pair_dpd>` command for a

thermostatting option that adds similar terms on a pairwise basis to

pairs of interacting particles.

Ff is a frictional drag or viscous damping term proportional to the

particle's velocity.  The proportionality constant for each atom is

computed as m/damp, where m is the mass of the particle and damp is

the damping factor specified by the user.

Fr is a force due to solvent atoms at a temperature T randomly bumping

into the particle.  As derived from the fluctuation/dissipation

theorem, its magnitude as shown above is proportional to sqrt(Kb T m /

dt damp), where Kb is the Boltzmann constant, T is the desired

temperature, m is the mass of the particle, dt is the timestep size,

and damp is the damping factor.  Random numbers are used to randomize

the direction and magnitude of this force as described in

:ref:`(Dunweg) <Dunweg1>`, where a uniform random number is used (instead of

a Gaussian random number) for speed.

.. math::

   F = & F_c + F_f + F_r \\

   F_f = & - \frac{m}{\mathrm{damp}} v \\

   F_r \propto & \sqrt{\frac{k_B T m}{dt~\mathrm{damp}}}

:math:`F_c` is the conservative force computed via the usual

inter-particle interactions (:doc:`pair_style <pair_style>`,

:doc:`bond_style <bond_style>`, etc).  The :math:`F_f` and :math:`F_r`

terms are added by this fix on a per-particle basis.  See the

:doc:`pair_style dpd/tstat <pair_dpd>` command for a thermostatting

option that adds similar terms on a pairwise basis to pairs of

interacting particles.

:math:`F_f` is a frictional drag or viscous damping term proportional to

the particle's velocity.  The proportionality constant for each atom is

computed as :math:`\frac{m}{\mathrm{damp}}`, where *m* is the mass of the

particle and damp is the damping factor specified by the user.

:math:`F_r` is a force due to solvent atoms at a temperature *T*

randomly bumping into the particle.  As derived from the

fluctuation/dissipation theorem, its magnitude as shown above is

proportional to :math:`\sqrt{\frac{k_B T m}{dt~\mathrm{damp}}}`, where

:math:`k_B` is the Boltzmann constant, *T* is the desired temperature,

*m* is the mass of the particle, *dt* is the timestep size, and damp is

the damping factor.  Random numbers are used to randomize the direction

and magnitude of this force as described in :ref:`(Dunweg) <Dunweg1>`,

where a uniform random number is used (instead of a Gaussian random

number) for speed.

Note that unless you use the *omega* or *angmom* keywords, the

thermostat effect of this fix is applied to only the translational

.. note::

   Unlike the :doc:`fix nvt <fix_nh>` command which performs

   Nose/Hoover thermostatting AND time integration, this fix does NOT

   perform time integration.  It only modifies forces to effect

   thermostatting.  Thus you must use a separate time integration fix,

   like :doc:`fix nve <fix_nve>` to actually update the velocities and

   positions of atoms using the modified forces.  Likewise, this fix

   should not normally be used on atoms that also have their temperature

   controlled by another fix - e.g. by :doc:`fix nvt <fix_nh>` or :doc:`fix temp/rescale <fix_temp_rescale>` commands.

   Unlike the :doc:`fix nvt <fix_nh>` command which performs Nose/Hoover

   thermostatting AND time integration, this fix does NOT perform time

   integration.  It only modifies forces to effect thermostatting.  Thus

   you must use a separate time integration fix, like :doc:`fix nve

   <fix_nve>` to actually update the velocities and positions of atoms

   using the modified forces.  Likewise, this fix should not normally be

   used on atoms that also have their temperature controlled by another

   fix - e.g. by :doc:`fix nvt <fix_nh>` or :doc:`fix temp/rescale

   <fix_temp_rescale>` commands.

See the :doc:`Howto thermostat <Howto_thermostat>` doc page for

a discussion of different ways to compute temperature and perform

in.

The *damp* parameter is specified in time units and determines how

rapidly the temperature is relaxed.  For example, a value of 100.0

means to relax the temperature in a timespan of (roughly) 100 time

units (tau or fmsec or psec - see the :doc:`units <units>` command).

The damp factor can be thought of as inversely related to the

viscosity of the solvent.  I.e. a small relaxation time implies a

hi-viscosity solvent and vice versa.  See the discussion about gamma

and viscosity in the documentation for the :doc:`fix viscous <fix_viscous>` command for more details.

rapidly the temperature is relaxed.  For example, a value of 100.0 means

to relax the temperature in a timespan of (roughly) 100 time units

(:math:`\tau` or fs or ps - see the :doc:`units <units>` command).  The

damp factor can be thought of as inversely related to the viscosity of

the solvent.  I.e. a small relaxation time implies a high-viscosity

solvent and vice versa.  See the discussion about :math:`\gamma` and

viscosity in the documentation for the :doc:`fix viscous <fix_viscous>`

command for more details.

The random # *seed* must be a positive integer.  A Marsaglia random

number generator is used.  Each processor uses the input seed to

:doc:`compute temp/sphere <compute_temp_sphere>` and :doc:`compute temp/asphere <compute_temp_asphere>` commands with their rotate

options.

For the *omega* keyword there is also a scale factor of 10.0/3.0 that

is applied as a multiplier on the Ff (damping) term in the equation

above and of sqrt(10.0/3.0) as a multiplier on the Fr term.  This does

not affect the thermostatting behavior of the Langevin formalism but

insures that the randomized rotational diffusivity of spherical

particles is correct.

For the *omega* keyword there is also a scale factor of

:math:`\frac{10.0}{3.0}` that is applied as a multiplier on the

:math:`F_f` (damping) term in the equation above and of

:math:`\sqrt{\frac{10.0}{3.0}}` as a multiplier on the :math:`F_r` term.

This does not affect the thermostatting behavior of the Langevin

formalism but insures that the randomized rotational diffusivity of

spherical particles is correct.

For the *angmom* keyword a similar scale factor is needed which is

10.0/3.0 for spherical particles, but is anisotropic for aspherical

particles (e.g. ellipsoids).  Currently LAMMPS only applies an

isotropic scale factor, and you can choose its magnitude as the

:math:`\frac{10.0}{3.0}` for spherical particles, but is anisotropic for

aspherical particles (e.g. ellipsoids).  Currently LAMMPS only applies

an isotropic scale factor, and you can choose its magnitude as the

specified value of the *angmom* keyword.  If your aspherical particles

are (nearly) spherical than a value of 10.0/3.0 = 3.333 is a good

choice.  If they are highly aspherical, a value of 1.0 is as good a

choice as any, since the effects on rotational diffusivity of the

particles will be incorrect regardless.  Note that for any reasonable

scale factor, the thermostatting effect of the *angmom* keyword on the

rotational temperature of the aspherical particles should still be

valid.

are (nearly) spherical than a value of :math:`\frac{10.0}{3.0} =

3.\overline{3}` is a good choice.  If they are highly aspherical, a

value of 1.0 is as good a choice as any, since the effects on rotational

diffusivity of the particles will be incorrect regardless.  Note that

for any reasonable scale factor, the thermostatting effect of the

*angmom* keyword on the rotational temperature of the aspherical

particles should still be valid.

The keyword *scale* allows the damp factor to be scaled up or down by

the specified factor for atoms of that type.  This can be useful when

different atom types have different sizes or masses.  It can be used

multiple times to adjust damp for several atom types.  Note that

specifying a ratio of 2 increases the relaxation time which is

equivalent to the solvent's viscosity acting on particles with 1/2 the

diameter.  This is the opposite effect of scale factors used by the

:doc:`fix viscous <fix_viscous>` command, since the damp factor in fix

*langevin* is inversely related to the gamma factor in fix *viscous*\ .

Also note that the damping factor in fix *langevin* includes the

particle mass in Ff, unlike fix *viscous*\ .  Thus the mass and size of

different atom types should be accounted for in the choice of ratio

values.

equivalent to the solvent's viscosity acting on particles with

:math:`\frac{1}{2}` the diameter.  This is the opposite effect of scale

factors used by the :doc:`fix viscous <fix_viscous>` command, since the

damp factor in fix *langevin* is inversely related to the :math:`\gamma`

factor in fix *viscous*\ .  Also note that the damping factor in fix

*langevin* includes the particle mass in Ff, unlike fix *viscous*\ .

Thus the mass and size of different atom types should be accounted for

in the choice of ratio values.

The keyword *tally* enables the calculation of the cumulative energy

added/subtracted to the atoms as they are thermostatted.  Effectively