From 1c33aec5dc64d0da59368d42a81b71679ca011cc Mon Sep 17 00:00:00 2001 From: Germain Clavier Date: Wed, 17 May 2023 18:28:49 +0200 Subject: [PATCH] Wrote the documentation for fix_press_langevin --- doc/src/Commands_fix.rst | 1 + doc/src/fix.rst | 1 + doc/src/fix_press_langevin.rst | 230 +++++++++++++++++++++++++++++++++ 3 files changed, 232 insertions(+) create mode 100644 doc/src/fix_press_langevin.rst diff --git a/doc/src/Commands_fix.rst b/doc/src/Commands_fix.rst index c74b1fd037..f7b85a5d12 100644 --- a/doc/src/Commands_fix.rst +++ b/doc/src/Commands_fix.rst @@ -181,6 +181,7 @@ OPT. * :doc:`pour ` * :doc:`precession/spin ` * :doc:`press/berendsen ` + * :doc:`press/langevin ` * :doc:`print ` * :doc:`propel/self ` * :doc:`property/atom (k) ` diff --git a/doc/src/fix.rst b/doc/src/fix.rst index 8cee9dd687..c4abbd6c21 100644 --- a/doc/src/fix.rst +++ b/doc/src/fix.rst @@ -333,6 +333,7 @@ accelerated styles exist. * :doc:`pour ` - pour new atoms/molecules into a granular simulation domain * :doc:`precession/spin ` - apply a precession torque to each magnetic spin * :doc:`press/berendsen ` - pressure control by Berendsen barostat +* :doc:`press/langevin ` - pressure control by Langevin barostat * :doc:`print ` - print text and variables during a simulation * :doc:`propel/self ` - model self-propelled particles * :doc:`property/atom ` - add customized per-atom values diff --git a/doc/src/fix_press_langevin.rst b/doc/src/fix_press_langevin.rst new file mode 100644 index 0000000000..cb46d2b7d9 --- /dev/null +++ b/doc/src/fix_press_langevin.rst @@ -0,0 +1,230 @@ +.. index:: fix press/langevin + +fix press/langevin command +=========================== + +Syntax +"""""" + +.. parsed-literal:: + + fix ID group-ID press/langevin keyword value ... + +* ID, group-ID are documented in :doc:`fix ` command +* press/langevin = style name of this fix command + + .. parsed-literal:: + + one or more keyword value pairs may be appended + keyword = *iso* or *aniso* or *x* or *y* or *z* or *couple* or *dilate* or *modulus* or *temp* + *iso* or *aniso* values = Pstart Pstop Pdamp + Pstart,Pstop = scalar external pressure at start/end of run (pressure units) + Pdamp = pressure damping parameter + *x* or *y* or *z* values = Pstart Pstop Pdamp + Pstart,Pstop = external stress tensor component at start/end of run (pressure units) + Pdamp = stress damping parameter + *couple* = *none* or *xyz* or *xy* or *yz* or *xz* + *friction* value = Friction to apply to the barostat + *temp* values = Tstart, Tstop + Tstart, Tstop = target temperature used for the barostat at start/end of run + *dilate* value = *all* or *partial* + +Examples +"""""""" + +.. code-block:: LAMMPS + + fix 1 all press/langevin iso 0.0 0.0 1000.0 temp 300 300 + fix 2 all press/langevin aniso 0.0 0.0 1000.0 temp 100 300 dilate partial + +Description +""""""""""" + +Reset the pressure of the system by using a Langevin stochastic barostat +:ref:`(Grønbech) `, which rescales the system volume and +(optionally) the atoms coordinates within the simulation box every +timestep. + +The Langevin barostat couple each direction *L* with a pseudo-particle that obeys +the Langevin equation such as: + +.. math:: + + f_P = & \frac{N k_B T_{target}}{V} + \frac{1}{V d}\sum_{i=1}^{N} \vec r_i \cdot \vec f_i - P_{target} \\ + Q\ddot{L} + \alpha{}\dot{L} = & f_P + \beta(t)\\ + L^{n+1} = & L^{n} + bdt\dot{L}^{n} \frac{bdt^{2}}{2Q} \\ + \dot{L}^{n+1} = & \alpha\dot{L}^{n} + \frac{dt}{2Q}\left(a f^{n}_{P} + f^{n+1}_{P}\right) + \frac{b}{Q}\beta^{n+1} \\ + a = & \frac{1-\frac{\alpha{}dt}{2Q}}{1+\frac{\alpha{}dt}{2Q}} \\ + b = & \frac{1}{1+\frac{\alpha{}dt}{2Q}} \\ + \left< \beta(t)\beta(t') \right> = & 2\alpha k_B Tdt + +Where :math:`dt` is the timestep :math:`\dot{L}` and :math:`\ddot{L}` the first +and second derivatives of the coupled direction with regard to time, +:math:`\alpha` is a friction coefficient, :math:`\beta` is a random gaussian +variable and :math:`Q` the effective mass of the coupled pseudoparticle. The +two first terms on the righthand side of the first equation are the virial +expression of the canonical pressure. It is to be noted that the temperature +used to compute the pressure is not the velocity of the atom but the canonical +target temperature directly. This temperature is specified using the *temp* +keyword parameter and should be close to the current target temperature of the +system. + +Regardless of what atoms are in the fix group, a global pressure is +computed for all atoms. Similarly, when the size of the simulation +box is changed, all atoms are re-scaled to new positions, unless the +keyword *dilate* is specified with a value of *partial*, in which case +only the atoms in the fix group are re-scaled. The latter can be +useful for leaving the coordinates of atoms in a solid substrate +unchanged and controlling the pressure of a surrounding fluid. + +.. note:: + + Unlike the :doc:`fix npt ` or :doc:`fix nph ` commands which + perform Nose/Hoover barostatting AND time integration, this fix does NOT + perform time integration of the atoms but only of the barostat coupled + coordinate. It then only modifies the box size and atom coordinates to + effect barostatting. Thus you must use a separate time integration fix, + like :doc:`fix nve ` or :doc:`fix nvt ` to actually update + the positions and velocities of atoms. This fix can be used in conjunction + with thermostatting fixes to control the temperature, such as :doc:`fix nvt + ` or :doc:`fix langevin ` or :doc:`fix temp/berendsen + `. + +See the :doc:`Howto barostat ` page for a +discussion of different ways to perform barostatting. + +---------- + +The barostat is specified using one or more of the *iso*, *aniso*, +*x*, *y*, *z*, and *couple* keywords. These keywords give you the +ability to specify the 3 diagonal components of an external stress +tensor, and to couple various of these components together so that the +dimensions they represent are varied together during a +constant-pressure simulation. Unlike the :doc:`fix npt ` and +:doc:`fix nph ` commands, this fix cannot be used with triclinic +(non-orthogonal) simulation boxes to control all 6 components of the +general pressure tensor. + +The target pressures for each of the 3 diagonal components of the +stress tensor can be specified independently via the *x*, *y*, *z*, +keywords, which correspond to the 3 simulation box dimensions. For +each component, the external pressure or tensor component at each +timestep is a ramped value during the run from *Pstart* to *Pstop*\ . +If a target pressure is specified for a component, then the +corresponding box dimension will change during a simulation. For +example, if the *y* keyword is used, the y-box length will change. A +box dimension will not change if that component is not specified, +although you have the option to change that dimension via the :doc:`fix deform ` command. + +For all barostat keywords, the *Pdamp* parameter determines the "mass" of the +pseudo particle acting as a barostat. The relation is such that :math:`P_{damp} += \frac{1}{Q}` where Q is the mass. + +---------- + +The *couple* keyword allows two or three of the diagonal components of +the pressure tensor to be "coupled" together. The value specified +with the keyword determines which are coupled. For example, *xz* +means the *Pxx* and *Pzz* components of the stress tensor are coupled. +*Xyz* means all 3 diagonal components are coupled. Coupling means two +things: the instantaneous stress will be computed as an average of the +corresponding diagonal components, and the coupled box dimensions will +be changed together in lockstep, meaning coupled dimensions will be +dilated or contracted by the same percentage every timestep. The +*Pstart*, *Pstop*, *Pdamp* parameters for any coupled dimensions must +be identical. *Couple xyz* can be used for a 2d simulation; the *z* +dimension is simply ignored. + +---------- + +The *iso* and *aniso* keywords are simply shortcuts that are +equivalent to specifying several other keywords together. + +The keyword *iso* means couple all 3 diagonal components together when +pressure is computed (hydrostatic pressure), and dilate/contract the +dimensions together. Using "iso Pstart Pstop Pdamp" is the same as +specifying these 4 keywords: + +.. parsed-literal:: + + x Pstart Pstop Pdamp + y Pstart Pstop Pdamp + z Pstart Pstop Pdamp + couple xyz + +The keyword *aniso* means *x*, *y*, and *z* dimensions are controlled +independently using the *Pxx*, *Pyy*, and *Pzz* components of the +stress tensor as the driving forces, and the specified scalar external +pressure. Using "aniso Pstart Pstop Pdamp" is the same as specifying +these 4 keywords: + +.. parsed-literal:: + + x Pstart Pstop Pdamp + y Pstart Pstop Pdamp + z Pstart Pstop Pdamp + couple none + +---------- + +This fix computes pressure each timestep. To do +this, the fix creates its own computes of style "pressure", +as if this command had been issued: + +.. code-block:: LAMMPS + + compute fix-ID_press group-ID pressure fix-ID_NULL virial + +See the :doc:`compute pressure ` command for details. Note +that the IDs of the new compute is the fix-ID + underscore + "press" and the +group for the new computes 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_press*. +This means you can change the attributes of this fix's pressure via the +:doc:`compute_modify ` command or print this temperature +or pressure during thermodynamic output via the :doc:`thermo_style custom ` command using the appropriate compute-ID. +It also means that changing attributes of *thermo_temp* or +*thermo_press* will have no effect on this fix. + +Restart, fix_modify, output, run start/stop, minimize info +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +No information about this fix is written to :doc:`binary restart files `. + +The :doc:`fix_modify ` *press* option is +supported by this fix. You can use it to assign a +:doc:`compute ` you have defined to this fix which will be used +in its pressure calculations. + +No global or per-atom quantities are stored by this fix for access by +various :doc:`output commands `. + +This fix can ramp its target pressure over multiple runs, using the +*start* and *stop* keywords of the :doc:`run ` command. See the +:doc:`run ` command for details of how to do this. + +This fix is not invoked during :doc:`energy minimization `. + +Restrictions +"""""""""""" + +Any dimension being adjusted by this fix must be periodic. + +Related commands +"""""""""""""""" + +:doc:`fix nve `, :doc:`fix nph `, :doc:`fix npt `, :doc:`fix langevin `, +:doc:`fix_modify ` + +Default +""""""" + +The keyword defaults are dilate = all, friction = 0.0001 in units of +pressure for whatever :doc:`units ` are defined. + +---------- + +.. _Grønbech: + +**(Grønbech)** Grønbech-Jensen, Farago, J Chem Phys, 141, 194108 (2014).