diff --git a/doc/src/JPG/uef_frames.jpg b/doc/src/JPG/uef_frames.jpg new file mode 100644 index 0000000000..3b3bfc3a24 Binary files /dev/null and b/doc/src/JPG/uef_frames.jpg differ diff --git a/doc/src/Section_commands.txt b/doc/src/Section_commands.txt index 3ac9c05e5c..fd7d6b4399 100644 --- a/doc/src/Section_commands.txt +++ b/doc/src/Section_commands.txt @@ -715,13 +715,13 @@ package"_Section_start.html#start_3. "nve/manifold/rattle"_fix_nve_manifold_rattle.html, "nvk"_fix_nvk.html, "nvt/manifold/rattle"_fix_nvt_manifold_rattle.html, -"nvt/uef"_fix_nh_uef.html, "nph/eff"_fix_nh_eff.html, "npt/eff"_fix_nh_eff.html, -"npt/uef"_fix_nh_uef.html, "nve/eff"_fix_nve_eff.html, "nvt/eff"_fix_nh_eff.html, "nvt/sllod/eff"_fix_nvt_sllod_eff.html, +"npt/uef"_fix_nh_uef.html, +"nvt/uef"_fix_nh_uef.html, "phonon"_fix_phonon.html, "pimd"_fix_pimd.html, "qbmsst"_fix_qbmsst.html, diff --git a/doc/src/Section_packages.txt b/doc/src/Section_packages.txt index 45cdd8ff48..58e41fc4ed 100644 --- a/doc/src/Section_packages.txt +++ b/doc/src/Section_packages.txt @@ -150,7 +150,7 @@ Package, Description, Doc page, Example, Library "USER-SMTBQ"_#USER-SMTBQ, second moment tight binding QEq potential,"pair_style smtbq"_pair_smtbq.html, USER/smtbq, - "USER-SPH"_#USER-SPH, smoothed particle hydrodynamics,"SPH User Guide"_PDF/SPH_LAMMPS_userguide.pdf, USER/sph, - "USER-TALLY"_#USER-TALLY, pairwise tally computes,"compute XXX/tally"_compute_tally.html, USER/tally, - -"USER-UEF"_#USER-UEF, NEMD under extensional flow,"fix nvt/uef"_fix_nh_uef.html, USER/uef, - +"USER-UEF"_#USER-UEF, extensional flow,"fix nvt/uef"_fix_nh_uef.html, USER/uef, - "USER-VTK"_#USER-VTK, dump output via VTK, "compute vtk"_dump_vtk.html, -, ext :tb(ea=c,ca1=l) :line @@ -2771,7 +2771,7 @@ examples/USER/tally :ul :line -UEF package :link(UEF),h4 +USER-UEF package :link(USER-UEF),h4 [Contents:] @@ -2779,6 +2779,8 @@ A fix style for the integration of the equations of motion under extensional flow with proper boundary conditions, as well as several supporting compute styles and an output option. +[Author:] David Nicholson (MIT). + [Install or un-install:] make yes-user-uef @@ -2790,6 +2792,7 @@ make machine :pre [Supporting info:] src/USER-UEF: filenames -> commands +src/USER-UEF/README "fix nvt/uef"_fix_nh_uef.html "compute pressure/uef"_compute_pressure_uef.html "compute temp/uef"_compute_temp_uef.html diff --git a/doc/src/compute_pressure_uef.txt b/doc/src/compute_pressure_uef.txt new file mode 100644 index 0000000000..e2e49da26d --- /dev/null +++ b/doc/src/compute_pressure_uef.txt @@ -0,0 +1,61 @@ +"LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c + +:link(lws,http://lammps.sandia.gov) +:link(ld,Manual.html) +:link(lc,Section_commands.html#comm) + +:line + +compute pressure/uef command :h3 + +[Syntax:] + +compute ID group-ID pressure/uef temp-ID keyword ... :pre + +ID, group-ID are documented in "compute"_compute.html command +pressure = style name of this compute command +temp-ID = ID of compute that calculates temperature, can be NULL if not needed +zero or more keywords may be appended +keyword = {ke} or {pair} or {bond} or {angle} or {dihedral} or {improper} or {kspace} or {fix} or {virial} :ul + +[Examples:] + +compute 1 all pressure/uef my_temp_uef +compute 2 all pressure/uef my_temp_uef virial :pre + +[Description:] + +This command is used to compute the pressure tensor in +the reference frame of the applied flow field when +"fix nvt/uef"_fix_nh_uef.html" or +"fix npt/uef"_fix_nh_uef.html" is used. +It is not necessary to use this command to compute the scalar +value of the pressure. A "compute pressure"_compute_pressure.html +may be used for that purpose. + +The keywords and output information are documented in +"compute_pressure"_compute_pressure.html. + +[Restrictions:] + +This fix is part of the USER-UEF package. It is only enabled if +LAMMPS was built with that package. See the +"Making LAMMPS"_Section_start.html#start_3 section for more info. + +This command can only be used when "fix nvt/uef"_fix_nh_uef.html +or "fix npt/uef"_fix_nh_uef.html is active. + +The kinetic contribution to the pressure tensor +will be accurate only when +the compute specificed by {temp-ID} is a +"compute temp/uef"_compute_temp_uef.html. + +[Related commands:] + +"compute pressure"_compute_pressure.html, +"fix nvt/uef"_fix_nh_uef.html, +"compute temp/uef"_compute_temp_uef.html + +[Default:] none + + diff --git a/doc/src/compute_temp_uef.txt b/doc/src/compute_temp_uef.txt index 33f847af35..562ad89b66 100644 --- a/doc/src/compute_temp_uef.txt +++ b/doc/src/compute_temp_uef.txt @@ -6,30 +6,30 @@ :line -compute temp command :h3 -compute temp/kk command :h3 +compute temp/uef command :h3 [Syntax:] -compute ID group-ID temp :pre +compute ID group-ID temp/uef :pre ID, group-ID are documented in "compute"_compute.html command temp = style name of this compute command :ul [Examples:] -compute 1 all temp/uef +compute 1 all temp/uef +compute 2 sel temp/uef :pre [Description:] This command is used to compute the kinetic energy tensor in -the correct reference frame when the USER-UEF package is used. +the reference frame of the applied flow field when +"fix nvt/uef"_fix_nh_uef.html" or +"fix npt/uef"_fix_nh_uef.html" is used. It is not necessary to use this command to compute the scalar value of the temperature. A "compute temp"_compute_temp.html may be used for that purpose. -[Output info:] - Output information for this command can be found in the documentation for "compute temp"_compute_temp.html. @@ -37,13 +37,13 @@ documentation for "compute temp"_compute_temp.html. This fix is part of the USER-UEF package. It is only enabled if LAMMPS was built with that package. See the -"Making LAMMPS"_Section_start.html#start-3 section for more info. - +"Making LAMMPS"_Section_start.html#start_3 section for more info. This command can only be used when "fix nvt/uef"_fix_nh_uef.html or "fix npt/uef"_fix_nh_uef.html is active. [Related commands:] + "compute temp"_compute_temp.html, "fix nvt/uef"_fix_nh_uef.html, "compute pressure/uef"_compute_pressure_uef.html diff --git a/doc/src/computes.txt b/doc/src/computes.txt index c443bfaba2..1b64e2e5b4 100644 --- a/doc/src/computes.txt +++ b/doc/src/computes.txt @@ -65,6 +65,7 @@ Computes :h1 compute_pe_atom compute_plasticity_atom compute_pressure + compute_pressure_uef compute_property_atom compute_property_chunk compute_property_local @@ -114,6 +115,7 @@ Computes :h1 compute_temp_region_eff compute_temp_rotate compute_temp_sphere + compute_temp_uef compute_ti compute_torque_chunk compute_vacf diff --git a/doc/src/dump_cfg_uef.txt b/doc/src/dump_cfg_uef.txt index a857ea4820..e257f9c4f1 100644 --- a/doc/src/dump_cfg_uef.txt +++ b/doc/src/dump_cfg_uef.txt @@ -23,7 +23,7 @@ args = same as args for "dump custom"_dump.html :pre [Examples:] dump 1 all cfg/uef 10 dump.*.cfg mass type xs ys zs -dump 2 all cfg/uef 100 dump.*.cfg mass type xs ys zs id c_stress +dump 2 all cfg/uef 100 dump.*.cfg mass type xs ys zs id c_stress :pre [Description:] diff --git a/doc/src/fix_nh_uef.txt b/doc/src/fix_nh_uef.txt index 38d01edccf..250d5624d0 100644 --- a/doc/src/fix_nh_uef.txt +++ b/doc/src/fix_nh_uef.txt @@ -15,15 +15,15 @@ fix ID group-ID style_name erate eps_x eps_y temp Tstart Tstop Tdamp keyword val ID, group-ID are documented in "fix"_fix.html command :ulb,l style_name = {nvt/uef} or {npt/uef} :l -Tstart, Tstop, and Tdamp are documented in the "fix_npt"_fix_nh.html command :l -edot_x and edot_y are the strain rates in the x and y directions (1/(time units)) :l +{Tstart}, {Tstop}, and {Tdamp} are documented in the "fix npt"_fix_nh.html command :l +{edot_x} and {edot_y} are the strain rates in the x and y directions (1/(time units)) :l one or more keyword/value pairs may be appended :l keyword = {ext} or {strain} or {iso} or {x} or {y} or {z} or {tchain} or {pchain} or {tloop} or {ploop} or {mtk} {ext} value = {x} or {y} or {z} or {xy} or {yz} or {xz} = external dimensions This keyword sets the external dimensions used to calculate the scalar pressure {strain} values = e_x e_y = initial strain Use of this keyword is usually not necessary, but may be needed to resume a run with a data file. - The {iso}, {x}, {y}, {z}, {tchain}, {pchain}, {tloop}, {ploop}, and {mtk} keywords are documented in the "fix_npt"_fix_nh.html command. :pre + The {iso}, {x}, {y}, {z}, {tchain}, {pchain}, {tloop}, {ploop}, and {mtk} keywords are documented in the "fix npt"_fix_nh.html command. :pre :ule [Examples:] @@ -46,8 +46,13 @@ as was proposed by "(Hunt)"_#Hunt. The lattice reduction algorithm is from homogeneous flows, and integrates the SLLOD equations of motion, originally proposed by Hoover and Ladd (see "(Evans and Morriss)"_#Sllod). +The applied flow field is set by the {eps} keyword. The values {edot_x} +and {edot_y} correspond to the strain rates in the xx and yy directions. +It is implicitly assumed that the flow field is traceless, and therefore +the strain rate in the zz direction is eqal to -({edot_x} + {edot_y}). + NOTE: Due to an instability in the SLLOD equations under extension, -"fix_momentum"_fix_momentum.html should be used to regularly reset the +"fix momentum"_fix_momentum.html should be used to regularly reset the linear momentum. The boundary conditions require a simulation box that does not have a @@ -58,47 +63,49 @@ This fix keeps track of two coordinate systems: the flow frame, and the upper triangular LAMMPS frame. The coordinate systems are related to each other through the QR decomposition, as is illustrated in the image below. -image +:c,image(JPG/uef_frames.jpg) During most molecular dynamics operations, the system is represented in the LAMMPS frame. Only when the positions and velocities are updated is the system rotated to the flow frame, and it is rotated back to the LAMMPS frame immediately afterwards. For this reason, all vector-valued quantities -(except for the tensors from compute pressure/uef and compute temp/uef) will +(except for the tensors from "compute_pressure/uef"_compute_pressure_uef.html +and "compute_temp/uef"_compute_temp_uef.html) will be computed in the LAMMPS frame. Rotationally invariant scalar quantities like -the temperature and hydrostatic pressure, on the other hand, will be computed -correctly. Additionally, the system is in the LAMMPS frame during all of the +the temperature and hydrostatic pressure are frame-invariant and will be +computed correctly. Additionally, the system is in the LAMMPS frame during all of the output steps, and therefore trajectory files made using the dump command -will be in the LAMMPS frame unless the dump cfg/uef command is used. +will be in the LAMMPS frame unless the "dump_cfg/uef"_dump_cfg_uef.html command is used. :line Temperature control is achieved with the default Nose-Hoover style -thermostat documented in "fix_npt"_fix_nh.html. When this fix is active, +thermostat documented in "fix npt"_fix_nh.html. When this fix is active, only the peculiar velocity of each atom is stored, defined as the velocity relative to the streaming velocity. This is in contrast to -"fix_nvt/sllod"_fix_nvt_sllod.html, which uses a lab-frame velocity, and +"fix nvt/sllod"_fix_nvt_sllod.html, which uses a lab-frame velocity, and removes the contribution from the streaming velocity in order to compute the temperature. Pressure control is achieved using the default Nose-Hoover barostat documented -in "fix_npt"_fix_npt.html. There are two ways to control the pressure using this +in "fix npt"_fix_nh.html. There are two ways to control the pressure using this fix. The first method involves using the {ext} keyword along with the {iso} pressure style. With this method, the pressure is controlled by scaling the simulation box -isotropically to achieve the average pressure in the directions specified by {ext}. -For example, if {ext xy} is used, the average pressure (Pxx+Pyy)/2 will be controlled. +isotropically to achieve the average pressure only in the directions specified by {ext}. +For example, if the {ext} values is set to {xy}, the average pressure (Pxx+Pyy)/2 +will be controlled. -This command will control the total hydrostatic pressure under uniaxial tension: +This example command will control the total hydrostatic pressure under uniaxial tension: fix f1 all npt/uef temp 0.7 0.7 0.5 iso 1 1 5 erate -0.5 -0.5 ext xyz :pre -This command will control the average stress in compression directions, which would -correspond to free surfaces for fiber drawing, under uniaxial tension: +This example command will control the average stress in compression directions, which would +typically correspond to free surfaces under drawing with uniaxial tension: fix f2 all npt/uef temp 0.7 0.7 0.5 iso 1 1 5 erate -0.5 -0.5 ext xy :pre The second method for pressure control involves setting the normal stresses using -the x, y , and/or z keywords. When using this method, the same pressure must be +the {x}, {y} , and/or {z} keywords. When using this method, the same pressure must be specified via {Pstart} and {Pstop} for all dimensions controlled. Any choice of pressure conditions that would cause LAMMPS to compute a deviatoric stress are not permissible and will result in an error. Additionally, all dimensions with @@ -117,19 +124,74 @@ fix f6 all npt/uef temp 0.7 0.7 0.5 x 1 1 5 z 2 2 5 erate 0.5 0.5 :pre :line +These fix computes a temperature and pressure each timestep. To do +this, it creates its own computes of style "temp/uef" and "pressure/uef", +as if one of these two sets of commands had been issued: + +compute fix-ID_temp group-ID temp/uef +compute fix-ID_press group-ID pressure/uef fix-ID_temp :pre + +compute fix-ID_temp all temp/uef +compute fix-ID_press all pressure/uef fix-ID_temp :pre + +See the "compute temp/uef"_compute_temp_uef.html and "compute +pressure/uef"_compute_pressure_uef.html commands for details. Note that the +IDs of the new computes are the fix-ID + underscore + "temp" or fix_ID ++ underscore + "press". + +[Restart, fix_modify, output, run start/stop, minimize info:] + +The fix writes the state of all the thermostat and barostat +variables, as well as the cumulative strain applied, to +"binary restart files"_restart.html. See the +"read_restart"_read_restart.html command for info on how to re-specify +a fix in an input script that reads a restart file, so that the +operation of the fix continues in an uninterrupted fashion. + +NOTE: It is not necessary to set the {strain} keyword when resuming +a run from a restart file. Only for resuming from data files, +which do not contain the cumulative applied strain, will +this keyword be necessary. + +This fix can be used with the "fix_modify"_fix_modify.html +{temp} and {press} options. The temperature and pressure computes +used must be of type {temp/uef} and {pressure/uef}. + +This fix computes the same global scalar and vecor quantities +as "fix npt"_fix_nh.html. + +The fix is not invoked during "energy +minimization"_minimize.html. [Restrictions:] -Due to requirements of the boundary conditions, when the strain keyword -is unset, or set to zero, the initial simulation box must be cubic and +This fix is part of the USER-UEF package. It is only enabled if +LAMMPS was built with that package. See the +"Making LAMMPS"_Section_start.html#start_3 section for more info. + +Due to requirements of the boundary conditions, when the {strain} keyword +is set to zero (or unset), the initial simulation box must be cubic and have style triclinic. If the box is initially of type ortho, use "change_box"_change_box.html before invoking the fix. -When this fix is applied, any orientation-dependent vector or -tensor-valued quantities computed, except for the tensors from -compute pressure/uef/compute temp/uef and coordinates from -dump cfg/uef, will not be in the same coordinate system as -the flow field. +NOTE: When resuming from restart files, you may need to use "box tilt large"_box.html +since lammps has internal criteria from lattice reduction that are not +the same as the criteria in the numerical lattice reduction algorithm. + +[Related commands:] +"fix nvt"_fix_nh.html, +"fix nvt/sllod"_fix_nvt_sllod.html, +"compute temp/uef"_compute_temp_uef.html, +"compute pressure/uef"_compute_pressure_uef.html, +"dump cfg/uef"_dump_cfg_uef.html + +[Default:] + +The default keyword values specific to this fix are exy = xyz, strain = 0 0. +The remaining defaults are the same as for {fix npt}_fix_nh.html except tchain = 1. +The reason for this change is given in "fix nvt/sllod"_fix_nvt_sllod.html. + +:line :link(Dobson) [(Dobson)] Dobson, J Chem Phys, 141, 184103 (2014). @@ -142,574 +204,3 @@ the flow field. :link(Sllod) [(Evans and Morriss)] Evans and Morriss, Phys Rev A, 30, 1528 (1984). - -These commands perform time integration on Nose-Hoover style -non-Hamiltonian equations of motion which are designed to generate -positions and velocities sampled from the canonical (nvt), -isothermal-isobaric (npt), and isenthalpic (nph) ensembles. This -updates the position and velocity for atoms in the group each -timestep. - -The thermostatting and barostatting is achieved by adding some dynamic -variables which are coupled to the particle velocities -(thermostatting) and simulation domain dimensions (barostatting). In -addition to basic thermostatting and barostatting, these fixes can -also create a chain of thermostats coupled to the particle thermostat, -and another chain of thermostats coupled to the barostat -variables. The barostat can be coupled to the overall box volume, or -to individual dimensions, including the {xy}, {xz} and {yz} tilt -dimensions. The external pressure of the barostat can be specified as -either a scalar pressure (isobaric ensemble) or as components of a -symmetric stress tensor (constant stress ensemble). When used -correctly, the time-averaged temperature and stress tensor of the -particles will match the target values specified by Tstart/Tstop and -Pstart/Pstop. - -The equations of motion used are those of Shinoda et al in -"(Shinoda)"_#nh-Shinoda, which combine the hydrostatic equations of -Martyna, Tobias and Klein in "(Martyna)"_#nh-Martyna with the strain -energy proposed by Parrinello and Rahman in -"(Parrinello)"_#nh-Parrinello. The time integration schemes closely -follow the time-reversible measure-preserving Verlet and rRESPA -integrators derived by Tuckerman et al in "(Tuckerman)"_#nh-Tuckerman. - -:line - -The thermostat parameters for fix styles {nvt} and {npt} is specified -using the {temp} keyword. Other thermostat-related keywords are -{tchain}, {tloop} and {drag}, which are discussed below. - -The thermostat is applied to only the translational degrees of freedom -for the particles. The translational degrees of freedom can also have -a bias velocity removed before thermostatting takes place; see the -description below. The desired temperature at each timestep is a -ramped value during the run from {Tstart} to {Tstop}. The {Tdamp} -parameter is specified in time units and determines how rapidly the -temperature is relaxed. For example, a value of 10.0 means to relax -the temperature in a timespan of (roughly) 10 time units (e.g. tau or -fmsec or psec - see the "units"_units.html command). The atoms in the -fix group are the only ones whose velocities and positions are updated -by the velocity/position update portion of the integration. - -NOTE: A Nose-Hoover thermostat will not work well for arbitrary values -of {Tdamp}. If {Tdamp} is too small, the temperature can fluctuate -wildly; if it is too large, the temperature will take a very long time -to equilibrate. A good choice for many models is a {Tdamp} of around -100 timesteps. Note that this is NOT the same as 100 time units for -most "units"_units.html settings. - -:line - -The barostat parameters for fix styles {npt} and {nph} is specified -using one or more of the {iso}, {aniso}, {tri}, {x}, {y}, {z}, {xy}, -{xz}, {yz}, and {couple} keywords. These keywords give you the -ability to specify all 6 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. - -Other barostat-related keywords are {pchain}, {mtk}, {ploop}, -{nreset}, {drag}, and {dilate}, which are discussed below. - -Orthogonal simulation boxes have 3 adjustable dimensions (x,y,z). -Triclinic (non-orthogonal) simulation boxes have 6 adjustable -dimensions (x,y,z,xy,xz,yz). The "create_box"_create_box.html, "read -data"_read_data.html, and "read_restart"_read_restart.html commands -specify whether the simulation box is orthogonal or non-orthogonal -(triclinic) and explain the meaning of the xy,xz,yz tilt factors. - -The target pressures for each of the 6 components of the stress tensor -can be specified independently via the {x}, {y}, {z}, {xy}, {xz}, {yz} -keywords, which correspond to the 6 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. If -the {xy} keyword is used, the xy tilt factor 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 "fix -deform"_fix_deform.html command. - -Note that in order to use the {xy}, {xz}, or {yz} keywords, the -simulation box must be triclinic, even if its initial tilt factors are -0.0. - -For all barostat keywords, the {Pdamp} parameter operates like the -{Tdamp} parameter, determining the time scale on which pressure is -relaxed. For example, a value of 10.0 means to relax the pressure in -a timespan of (roughly) 10 time units (e.g. tau or fmsec or psec - see -the "units"_units.html command). - -NOTE: A Nose-Hoover barostat will not work well for arbitrary values -of {Pdamp}. If {Pdamp} is too small, the pressure and volume can -fluctuate wildly; if it is too large, the pressure will take a very -long time to equilibrate. A good choice for many models is a {Pdamp} -of around 1000 timesteps. However, note that {Pdamp} is specified in -time units, and that timesteps are NOT the same as time units for most -"units"_units.html settings. - -Regardless of what atoms are in the fix group (the only atoms which -are time integrated), a global pressure or stress tensor 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 {dilate-group-ID} for a group that -represents a subset of the atoms. This can be useful, for example, to -leave the coordinates of atoms in a solid substrate unchanged and -controlling the pressure of a surrounding fluid. This option should -be used with care, since it can be unphysical to dilate some atoms and -not others, because it can introduce large, instantaneous -displacements between a pair of atoms (one dilated, one not) that are -far from the dilation origin. Also note that for atoms not in the fix -group, a separate time integration fix like "fix nve"_fix_nve.html or -"fix nvt"_fix_nh.html can be used on them, independent of whether they -are dilated or not. - -:line - -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. - -:line - -The {iso}, {aniso}, and {tri} 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: - -x Pstart Pstop Pdamp -y Pstart Pstop Pdamp -z Pstart Pstop Pdamp -couple xyz :pre - -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: - -x Pstart Pstop Pdamp -y Pstart Pstop Pdamp -z Pstart Pstop Pdamp -couple none :pre - -The keyword {tri} means {x}, {y}, {z}, {xy}, {xz}, and {yz} dimensions -are controlled independently using their individual stress components -as the driving forces, and the specified scalar pressure as the -external normal stress. Using "tri Pstart Pstop Pdamp" is the same as -specifying these 7 keywords: - -x Pstart Pstop Pdamp -y Pstart Pstop Pdamp -z Pstart Pstop Pdamp -xy 0.0 0.0 Pdamp -yz 0.0 0.0 Pdamp -xz 0.0 0.0 Pdamp -couple none :pre - -:line - -In some cases (e.g. for solids) the pressure (volume) and/or -temperature of the system can oscillate undesirably when a Nose/Hoover -barostat and thermostat is applied. The optional {drag} keyword will -damp these oscillations, although it alters the Nose/Hoover equations. -A value of 0.0 (no drag) leaves the Nose/Hoover formalism unchanged. -A non-zero value adds a drag term; the larger the value specified, the -greater the damping effect. Performing a short run and monitoring the -pressure and temperature is the best way to determine if the drag term -is working. Typically a value between 0.2 to 2.0 is sufficient to -damp oscillations after a few periods. Note that use of the drag -keyword will interfere with energy conservation and will also change -the distribution of positions and velocities so that they do not -correspond to the nominal NVT, NPT, or NPH ensembles. - -An alternative way to control initial oscillations is to use chain -thermostats. The keyword {tchain} determines the number of thermostats -in the particle thermostat. A value of 1 corresponds to the original -Nose-Hoover thermostat. The keyword {pchain} specifies the number of -thermostats in the chain thermostatting the barostat degrees of -freedom. A value of 0 corresponds to no thermostatting of the -barostat variables. - -The {mtk} keyword controls whether or not the correction terms due to -Martyna, Tuckerman, and Klein are included in the equations of motion -"(Martyna)"_#nh-Martyna. Specifying {no} reproduces the original -Hoover barostat, whose volume probability distribution function -differs from the true NPT and NPH ensembles by a factor of 1/V. Hence -using {yes} is more correct, but in many cases the difference is -negligible. - -The keyword {tloop} can be used to improve the accuracy of integration -scheme at little extra cost. The initial and final updates of the -thermostat variables are broken up into {tloop} substeps, each of -length {dt}/{tloop}. This corresponds to using a first-order -Suzuki-Yoshida scheme "(Tuckerman)"_#nh-Tuckerman. The keyword {ploop} -does the same thing for the barostat thermostat. - -The keyword {nreset} controls how often the reference dimensions used -to define the strain energy are reset. If this keyword is not used, -or is given a value of zero, then the reference dimensions are set to -those of the initial simulation domain and are never changed. If the -simulation domain changes significantly during the simulation, then -the final average pressure tensor will differ significantly from the -specified values of the external stress tensor. A value of {nstep} -means that every {nstep} timesteps, the reference dimensions are set -to those of the current simulation domain. - -The {scaleyz}, {scalexz}, and {scalexy} keywords control whether or -not the corresponding tilt factors are scaled with the associated box -dimensions when barostatting triclinic periodic cells. The default -values {yes} will turn on scaling, which corresponds to adjusting the -linear dimensions of the cell while preserving its shape. Choosing -{no} ensures that the tilt factors are not scaled with the box -dimensions. See below for restrictions and default values in different -situations. In older versions of LAMMPS, scaling of tilt factors was -not performed. The old behavior can be recovered by setting all three -scale keywords to {no}. - -The {flip} keyword allows the tilt factors for a triclinic box to -exceed half the distance of the parallel box length, as discussed -below. If the {flip} value is set to {yes}, the bound is enforced by -flipping the box when it is exceeded. If the {flip} value is set to -{no}, the tilt will continue to change without flipping. Note that if -applied stress induces large deformations (e.g. in a liquid), this -means the box shape can tilt dramatically and LAMMPS will run less -efficiently, due to the large volume of communication needed to -acquire ghost atoms around a processor's irregular-shaped sub-domain. -For extreme values of tilt, LAMMPS may also lose atoms and generate an -error. - -The {fixedpoint} keyword specifies the fixed point for barostat volume -changes. By default, it is the center of the box. Whatever point is -chosen will not move during the simulation. For example, if the lower -periodic boundaries pass through (0,0,0), and this point is provided -to {fixedpoint}, then the lower periodic boundaries will remain at -(0,0,0), while the upper periodic boundaries will move twice as -far. In all cases, the particle trajectories are unaffected by the -chosen value, except for a time-dependent constant translation of -positions. - -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 "atom_style hybrid sphere -dipole"_atom_style.html command. - -The default dipole orientation integrator can be changed to the -Dullweber-Leimkuhler-McLachlan integration scheme -"(Dullweber)"_#nh-Dullweber when using {update} with the value -{dipole/dlm}. This integrator is symplectic and time-reversible, -giving better energy conservation and allows slightly longer timesteps -at only a small additional computational cost. - -:line - -NOTE: Using a barostat coupled to tilt dimensions {xy}, {xz}, {yz} can -sometimes result in arbitrarily large values of the tilt dimensions, -i.e. a dramatically deformed simulation box. LAMMPS allows the tilt -factors to grow a small amount beyond the normal limit of half the box -length (0.6 times the box length), and then performs a box "flip" to -an equivalent periodic cell. See the discussion of the {flip} keyword -above, to allow this bound to be exceeded, if desired. - -The flip operation is described in more detail in the doc page for -"fix deform"_fix_deform.html. Both the barostat dynamics and the atom -trajectories are unaffected by this operation. However, if a tilt -factor is incremented by a large amount (1.5 times the box length) on -a single timestep, LAMMPS can not accomodate this event and will -terminate the simulation with an error. This error typically indicates -that there is something badly wrong with how the simulation was -constructed, such as specifying values of {Pstart} that are too far -from the current stress value, or specifying a timestep that is too -large. Triclinic barostatting should be used with care. This also is -true for other barostat styles, although they tend to be more -forgiving of insults. In particular, it is important to recognize that -equilibrium liquids can not support a shear stress and that -equilibrium solids can not support shear stresses that exceed the -yield stress. - -One exception to this rule is if the 1st dimension in the tilt factor -(x for xy) is non-periodic. In that case, the limits on the tilt -factor are not enforced, since flipping the box in that dimension does -not change the atom positions due to non-periodicity. In this mode, -if you tilt the system to extreme angles, the simulation will simply -become inefficient due to the highly skewed simulation box. - -NOTE: Unlike the "fix temp/berendsen"_fix_temp_berendsen.html command -which performs thermostatting but NO time integration, these fixes -perform thermostatting/barostatting AND time integration. Thus you -should not use any other time integration fix, such as "fix -nve"_fix_nve.html on atoms to which this fix is applied. Likewise, -fix nvt and fix npt should not normally be used on atoms that also -have their temperature controlled by another fix - e.g. by "fix -langevin"_fix_nh.html or "fix temp/rescale"_fix_temp_rescale.html -commands. - -See "this howto section"_Section_howto.html#howto_16 of the manual for -a discussion of different ways to compute temperature and perform -thermostatting and barostatting. - -:line - -These fixes compute a temperature and pressure each timestep. To do -this, the fix creates its own computes of style "temp" and "pressure", -as if one of these two sets of commands had been issued: - -compute fix-ID_temp group-ID temp -compute fix-ID_press group-ID pressure fix-ID_temp :pre - -compute fix-ID_temp all temp -compute fix-ID_press all pressure fix-ID_temp :pre - -See the "compute temp"_compute_temp.html and "compute -pressure"_compute_pressure.html commands for details. Note that the -IDs of the new computes are the fix-ID + underscore + "temp" or fix_ID -+ underscore + "press". For fix nvt, the group for the new computes -is the same as the fix group. For fix nph and fix npt, the group for -the new computes is "all" since pressure is computed for the entire -system. - -Note that these are NOT the computes used by thermodynamic output (see -the "thermo_style"_thermo_style.html command) with ID = {thermo_temp} -and {thermo_press}. This means you can change the attributes of this -fix's temperature or pressure via the -"compute_modify"_compute_modify.html command or print this temperature -or pressure during thermodynamic output via the "thermo_style -custom"_thermo_style.html 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. - -Like other fixes that perform thermostatting, fix nvt and fix npt can -be used with "compute commands"_compute.html that calculate a -temperature after removing a "bias" from the atom velocities. -E.g. removing the center-of-mass velocity from a group of atoms or -only calculating temperature on the x-component of velocity or only -calculating temperature for atoms in a geometric region. This is not -done by default, but only if the "fix_modify"_fix_modify.html command -is used to assign a temperature compute to this fix that includes such -a bias term. See the doc pages for individual "compute -commands"_compute.html to determine which ones include a bias. In -this case, the thermostat works in the following manner: the current -temperature is calculated taking the bias into account, bias is -removed from each atom, thermostatting is performed on the remaining -thermal degrees of freedom, and the bias is added back in. - -:line - -These fixes can be used with either the {verlet} or {respa} -"integrators"_run_style.html. When using one of the barostat fixes -with {respa}, LAMMPS uses an integrator constructed -according to the following factorization of the Liouville propagator -(for two rRESPA levels): - -:c,image(Eqs/fix_nh1.jpg) - -This factorization differs somewhat from that of Tuckerman et al, in -that the barostat is only updated at the outermost rRESPA level, -whereas Tuckerman's factorization requires splitting the pressure into -pieces corresponding to the forces computed at each rRESPA level. In -theory, the latter method will exhibit better numerical stability. In -practice, because Pdamp is normally chosen to be a large multiple of -the outermost rRESPA timestep, the barostat dynamics are not the -limiting factor for numerical stability. Both factorizations are -time-reversible and can be shown to preserve the phase space measure -of the underlying non-Hamiltonian equations of motion. - -NOTE: This implementation has been shown to conserve linear momentum -up to machine precision under NVT dynamics. Under NPT dynamics, -for a system with zero initial total linear momentum, the total -momentum fluctuates close to zero. It may occasionally undergo brief -excursions to non-negligible values, before returning close to zero. -Over long simulations, this has the effect of causing the center-of-mass -to undergo a slow random walk. This can be mitigated by resetting -the momentum at infrequent intervals using the -"fix momentum"_fix_momentum.html command. - -:line - -The fix npt and fix nph commands can be used with rigid bodies or -mixtures of rigid bodies and non-rigid particles (e.g. solvent). But -there are also "fix rigid/npt"_fix_rigid.html and "fix -rigid/nph"_fix_rigid.html commands, which are typically a more natural -choice. See the doc page for those commands for more discussion of -the various ways to do this. - -:line - -Styles with a {gpu}, {intel}, {kk}, {omp}, or {opt} suffix are -functionally the same as the corresponding style without the suffix. -They have been optimized to run faster, depending on your available -hardware, as discussed in "Section 5"_Section_accelerate.html -of the manual. The accelerated styles take the same arguments and -should produce the same results, except for round-off and precision -issues. - -These accelerated styles are part of the GPU, USER-INTEL, KOKKOS, -USER-OMP and OPT packages, respectively. They are only enabled if -LAMMPS was built with those packages. See the "Making -LAMMPS"_Section_start.html#start_3 section for more info. - -You can specify the accelerated styles explicitly in your input script -by including their suffix, or you can use the "-suffix command-line -switch"_Section_start.html#start_6 when you invoke LAMMPS, or you can -use the "suffix"_suffix.html command in your input script. - -See "Section 5"_Section_accelerate.html of the manual for -more instructions on how to use the accelerated styles effectively. - -:line - -[Restart, fix_modify, output, run start/stop, minimize info:] - -These fixes writes the state of all the thermostat and barostat -variables to "binary restart files"_restart.html. See the -"read_restart"_read_restart.html command for info on how to re-specify -a fix in an input script that reads a restart file, so that the -operation of the fix continues in an uninterrupted fashion. - -The "fix_modify"_fix_modify.html {temp} and {press} options are -supported by these fixes. You can use them to assign a -"compute"_compute.html you have defined to this fix which will be used -in its thermostatting or barostatting procedure, as described above. -If you do this, note that the kinetic energy derived from the compute -temperature should be consistent with the virial term computed using -all atoms for the pressure. LAMMPS will warn you if you choose to -compute temperature on a subset of atoms. - -NOTE: If both the {temp} and {press} keywords are used in a single -thermo_modify command (or in two separate commands), then the order in -which the keywords are specified is important. Note that a "pressure -compute"_compute_pressure.html defines its own temperature compute as -an argument when it is specified. The {temp} keyword will override -this (for the pressure compute being used by fix npt), but only if the -{temp} keyword comes after the {press} keyword. If the {temp} keyword -comes before the {press} keyword, then the new pressure compute -specified by the {press} keyword will be unaffected by the {temp} -setting. - -The "fix_modify"_fix_modify.html {energy} option is supported by these -fixes to add the energy change induced by Nose/Hoover thermostatting -and barostatting to the system's potential energy as part of -"thermodynamic output"_thermo_style.html. - -These fixes compute a global scalar and a global vector of quantities, -which can be accessed by various "output -commands"_Section_howto.html#howto_15. The scalar value calculated by -these fixes is "extensive"; the vector values are "intensive". - -The scalar is the cumulative energy change due to the fix. - -The vector stores internal Nose/Hoover thermostat and barostat -variables. The number and meaning of the vector values depends on -which fix is used and the settings for keywords {tchain} and {pchain}, -which specify the number of Nose/Hoover chains for the thermostat and -barostat. If no thermostatting is done, then {tchain} is 0. If no -barostatting is done, then {pchain} is 0. In the following list, -"ndof" is 0, 1, 3, or 6, and is the number of degrees of freedom in -the barostat. Its value is 0 if no barostat is used, else its value -is 6 if any off-diagonal stress tensor component is barostatted, else -its value is 1 if {couple xyz} is used or {couple xy} for a 2d -simulation, otherwise its value is 3. - -The order of values in the global vector and their meaning is as -follows. The notation means there are tchain values for eta, followed -by tchain for eta_dot, followed by ndof for omega, etc: - -eta\[tchain\] = particle thermostat displacements (unitless) -eta_dot\[tchain\] = particle thermostat velocities (1/time units) -omega\[ndof\] = barostat displacements (unitless) -omega_dot\[ndof\] = barostat velocities (1/time units) -etap\[pchain\] = barostat thermostat displacements (unitless) -etap_dot\[pchain\] = barostat thermostat velocities (1/time units) -PE_eta\[tchain\] = potential energy of each particle thermostat displacement (energy units) -KE_eta_dot\[tchain\] = kinetic energy of each particle thermostat velocity (energy units) -PE_omega\[ndof\] = potential energy of each barostat displacement (energy units) -KE_omega_dot\[ndof\] = kinetic energy of each barostat velocity (energy units) -PE_etap\[pchain\] = potential energy of each barostat thermostat displacement (energy units) -KE_etap_dot\[pchain\] = kinetic energy of each barostat thermostat velocity (energy units) -PE_strain\[1\] = scalar strain energy (energy units) :ul - -These fixes can ramp their external temperature and pressure over -multiple runs, using the {start} and {stop} keywords of the -"run"_run.html command. See the "run"_run.html command for details of -how to do this. - -These fixes are not invoked during "energy -minimization"_minimize.html. - -:line - -[Restrictions:] - -{X}, {y}, {z} cannot be barostatted if the associated dimension is not -periodic. {Xy}, {xz}, and {yz} can only be barostatted if the -simulation domain is triclinic and the 2nd dimension in the keyword -({y} dimension in {xy}) is periodic. {Z}, {xz}, and {yz}, cannot be -barostatted for 2D simulations. The "create_box"_create_box.html, -"read data"_read_data.html, and "read_restart"_read_restart.html -commands specify whether the simulation box is orthogonal or -non-orthogonal (triclinic) and explain the meaning of the xy,xz,yz -tilt factors. - -For the {temp} keyword, the final Tstop cannot be 0.0 since it would -make the external T = 0.0 at some timestep during the simulation which -is not allowed in the Nose/Hoover formulation. - -The {scaleyz yes} and {scalexz yes} keyword/value pairs can not be used -for 2D simulations. {scaleyz yes}, {scalexz yes}, and {scalexy yes} options -can only be used if the 2nd dimension in the keyword is periodic, -and if the tilt factor is not coupled to the barostat via keywords -{tri}, {yz}, {xz}, and {xy}. - -These fixes can be used with dynamic groups as defined by the -"group"_group.html command. Likewise they can be used with groups to -which atoms are added or deleted over time, e.g. a deposition -simulation. However, the conservation properties of the thermostat -and barostat are defined for systems with a static set of atoms. You -may observe odd behavior if the atoms in a group vary dramatically -over time or the atom count becomes very small. - -[Related commands:] - -"fix nve"_fix_nve.html, "fix_modify"_fix_modify.html, -"run_style"_run_style.html - -[Default:] - -The keyword defaults are tchain = 3, pchain = 3, mtk = yes, tloop = -ploop = 1, nreset = 0, drag = 0.0, dilate = all, couple = none, -scaleyz = scalexz = scalexy = yes if periodic in 2nd dimension and -not coupled to barostat, otherwise no. - -:line - -:link(nh-Martyna) -[(Martyna)] Martyna, Tobias and Klein, J Chem Phys, 101, 4177 (1994). - -:link(nh-Parrinello) -[(Parrinello)] Parrinello and Rahman, J Appl Phys, 52, 7182 (1981). - -:link(nh-Tuckerman) -[(Tuckerman)] Tuckerman, Alejandre, Lopez-Rendon, Jochim, and -Martyna, J Phys A: Math Gen, 39, 5629 (2006). - -:link(nh-Shinoda) -[(Shinoda)] Shinoda, Shiga, and Mikami, Phys Rev B, 69, 134103 (2004). - -:link(nh-Dullweber) -[(Dullweber)] Dullweber, Leimkuhler and McLachlan, J Chem Phys, 107, -5840 (1997). diff --git a/doc/src/fixes.txt b/doc/src/fixes.txt index 7000a66c51..b93bb9d0a2 100644 --- a/doc/src/fixes.txt +++ b/doc/src/fixes.txt @@ -76,6 +76,7 @@ Fixes :h1 fix_neb fix_nh fix_nh_eff + fix_nh_uef fix_nph_asphere fix_nph_body fix_nph_sphere