Equal-style variables can specify formulas with various mathematical functions, and include thermo_style command diff --git a/doc/fix_addforce.txt b/doc/fix_addforce.txt index 3ce5a5d3e0..37fd62fd9e 100644 --- a/doc/fix_addforce.txt +++ b/doc/fix_addforce.txt @@ -42,8 +42,8 @@ Any of the 3 quantities defining the force components can be specified as an equal-style or atom-style "variable"_variable.html, namely {fx}, {fy}, {fz}. If the value is a variable, it should be specified as v_name, where name is the variable name. In this case, the variable -will be evaluated each timestep, and its value used to determine the -force component. +will be evaluated each timestep, and its value(s) used to determine +the force component. Equal-style variables can specify formulas with various mathematical functions, and include "thermo_style"_thermo_style.html command diff --git a/doc/fix_heat.html b/doc/fix_heat.html index 44295c0cce..aa963c6e8c 100644 --- a/doc/fix_heat.html +++ b/doc/fix_heat.html @@ -42,11 +42,11 @@ fix 4 qout heat 1 -1.0 region top
Description:
-Add non-translational kinetic energy (heat) to a group of atoms such -that their aggregate momentum is conserved. Two of these fixes can be -used to establish a temperature gradient across a simulation domain by -adding heat (energy) to one group of atoms (hot reservoir) and -subtracting heat from another (cold reservoir). E.g. a simulation +
Add non-translational kinetic energy (heat) to a group of atoms in a +manner that conserves their aggregate momentum. Two of these fixes +can be used to establish a temperature gradient across a simulation +domain by adding heat (energy) to one group of atoms (hot reservoir) +and subtracting heat from another (cold reservoir). E.g. a simulation sampling from the McDLT ensemble.
If the region keyword is used, the atom must be in both the group @@ -55,27 +55,43 @@ energy added or subtracted to it. If not specified, then the atoms in the group are affected wherever they may move to.
Heat addition/subtraction is performed every N timesteps. The eflux -parameter determines the change in aggregate energy of the entire -group of atoms per unit time, e.g. in eV/psec for metal -units. Thus it is an "extensive" quantity, meaning its -magnitude should be scaled with the number of atoms in the group. -Since eflux is independent of N or the timestep, a -larger value of N will add/subtract a larger amount of energy each -time the fix is invoked. If heat is subtracted from the system too -aggressively so that the group's kinetic energy would go to zero, -LAMMPS halts with an error message. +parameter can be specified as a numeric constant or as a variable (see +below). If it is a numeric constant or equal-style variable which +evaluates to a scalar value, then the eflux determines the change in +aggregate energy of the entire group of atoms per unit time, e.g. in +eV/psec for metal units. In this case it is an +"extensive" quantity, meaning its magnitude should be scaled with the +number of atoms in the group. Note that since eflux has per-time +units (i.e. it is a flux), this means that a larger value of N will +add/subtract a larger amount of energy each time the fix is invoked.
-The eflux parameter can be specified as an equal-style -variable. If the value is a variable, it should be -specified as v_name, where name is the variable name. In this case, -the variable will be evaluated each timestep, and its value used to -determine the flux. +
If eflux is specified as an atom-style variable (see below), then +the variable computes one value per atom. In this case, each value is +the energy flux for a single atom, again in units of energy per unit +time. In this case, each value is an "intensive" quantity, which need +not be scaled with the number of atoms in the group. +
+As mentioned above, the eflux parameter can be specified as an +equal-style or atom_style variable. If the value is a +variable, it should be specified as v_name, where name is the variable +name. In this case, the variable will be evaluated each timestep, and +its value(s) used to determine the flux.
Equal-style variables can specify formulas with various mathematical functions, and include thermo_style command keywords for the simulation box parameters and timestep and elapsed time. Thus it is easy to specify a time-dependent flux.
+Atom-style variables can specify the same formulas as equal-style +variables but can also include per-atom values, such as atom +coordinates. Thus it is easy to specify a spatially-dependent flux +with optional time-dependence as well. +
+IMPORTANT NOTE: If heat is subtracted from the system too aggressively +so that the group's kinetic energy would go to zero, or any individual +atom's kinetic energy would go to zero for the case where eflux is +an atom-style variable, then LAMMPS will halt with an error message. +
Fix heat is different from a thermostat such as fix nvt or fix temp/rescale in that energy is added/subtracted continually. Thus if there isn't another mechanism @@ -102,6 +118,8 @@ are relevant to this fix. most recent value by which velocites were scaled. The scalar value calculated by this fix is "intensive".
+// NOTE: what is the scalar output for an atom-style variable? +
No parameter of this fix can be used with the start/stop keywords of the run command. This fix is not invoked during energy minimization. diff --git a/doc/fix_heat.txt b/doc/fix_heat.txt index 51a26b4278..a1629e8cb8 100644 --- a/doc/fix_heat.txt +++ b/doc/fix_heat.txt @@ -31,11 +31,11 @@ fix 4 qout heat 1 -1.0 region top :pre [Description:] -Add non-translational kinetic energy (heat) to a group of atoms such -that their aggregate momentum is conserved. Two of these fixes can be -used to establish a temperature gradient across a simulation domain by -adding heat (energy) to one group of atoms (hot reservoir) and -subtracting heat from another (cold reservoir). E.g. a simulation +Add non-translational kinetic energy (heat) to a group of atoms in a +manner that conserves their aggregate momentum. Two of these fixes +can be used to establish a temperature gradient across a simulation +domain by adding heat (energy) to one group of atoms (hot reservoir) +and subtracting heat from another (cold reservoir). E.g. a simulation sampling from the McDLT ensemble. If the {region} keyword is used, the atom must be in both the group @@ -44,27 +44,43 @@ energy added or subtracted to it. If not specified, then the atoms in the group are affected wherever they may move to. Heat addition/subtraction is performed every N timesteps. The {eflux} -parameter determines the change in aggregate energy of the entire -group of atoms per unit time, e.g. in eV/psec for "metal -units"_units.html. Thus it is an "extensive" quantity, meaning its -magnitude should be scaled with the number of atoms in the group. -Since {eflux} is independent of N or the "timestep"_timestep.html, a -larger value of N will add/subtract a larger amount of energy each -time the fix is invoked. If heat is subtracted from the system too -aggressively so that the group's kinetic energy would go to zero, -LAMMPS halts with an error message. +parameter can be specified as a numeric constant or as a variable (see +below). If it is a numeric constant or equal-style variable which +evaluates to a scalar value, then the {eflux} determines the change in +aggregate energy of the entire group of atoms per unit time, e.g. in +eV/psec for "metal units"_units.html. In this case it is an +"extensive" quantity, meaning its magnitude should be scaled with the +number of atoms in the group. Note that since {eflux} has per-time +units (i.e. it is a flux), this means that a larger value of N will +add/subtract a larger amount of energy each time the fix is invoked. -The {eflux} parameter can be specified as an equal-style -"variable"_variable.html. If the value is a variable, it should be -specified as v_name, where name is the variable name. In this case, -the variable will be evaluated each timestep, and its value used to -determine the flux. +If {eflux} is specified as an atom-style variable (see below), then +the variable computes one value per atom. In this case, each value is +the energy flux for a single atom, again in units of energy per unit +time. In this case, each value is an "intensive" quantity, which need +not be scaled with the number of atoms in the group. + +As mentioned above, the {eflux} parameter can be specified as an +equal-style or atom_style "variable"_variable.html. If the value is a +variable, it should be specified as v_name, where name is the variable +name. In this case, the variable will be evaluated each timestep, and +its value(s) used to determine the flux. Equal-style variables can specify formulas with various mathematical functions, and include "thermo_style"_thermo_style.html command keywords for the simulation box parameters and timestep and elapsed time. Thus it is easy to specify a time-dependent flux. +Atom-style variables can specify the same formulas as equal-style +variables but can also include per-atom values, such as atom +coordinates. Thus it is easy to specify a spatially-dependent flux +with optional time-dependence as well. + +IMPORTANT NOTE: If heat is subtracted from the system too aggressively +so that the group's kinetic energy would go to zero, or any individual +atom's kinetic energy would go to zero for the case where {eflux} is +an atom-style variable, then LAMMPS will halt with an error message. + Fix heat is different from a thermostat such as "fix nvt"_fix_nh.html or "fix temp/rescale"_fix_temp_rescale.html in that energy is added/subtracted continually. Thus if there isn't another mechanism @@ -91,6 +107,8 @@ This fix computes a global scalar which can be accessed by various most recent value by which velocites were scaled. The scalar value calculated by this fix is "intensive". +// NOTE: what is the scalar output for an atom-style variable? + No parameter of this fix can be used with the {start/stop} keywords of the "run"_run.html command. This fix is not invoked during "energy minimization"_minimize.html.