These are compute styles contributed by users, which can be used if diff --git a/doc/Section_commands.txt b/doc/Section_commands.txt index 0004339cc0..9dfb33cff7 100644 --- a/doc/Section_commands.txt +++ b/doc/Section_commands.txt @@ -528,7 +528,8 @@ each style or click on the style itself for a full description: "temp/profile"_compute_temp_profile.html, "temp/ramp"_compute_temp_ramp.html, "temp/region"_compute_temp_region.html, -"temp/sphere"_compute_temp_sphere.html :tb(c=6,ea=c) +"temp/sphere"_compute_temp_sphere.html, +"ti"_compute_ti.html :tb(c=6,ea=c) These are compute styles contributed by users, which can be used if "LAMMPS is built with the appropriate package"_Section_start.html#2_3. diff --git a/doc/compute_ti.html b/doc/compute_ti.html new file mode 100644 index 0000000000..404f33e821 --- /dev/null +++ b/doc/compute_ti.html @@ -0,0 +1,124 @@ + +
Syntax: +
+compute ID group ti keyword args ... ++
pair style args = v_name1 v_name2 + v_name1 = variable with name1 that is energy scale factor and function of lambda + v_name2 = variable with name2 that is derivative of v_name1 with respect to lambda + tail args = v_name1 v_name2 + v_name1 = variable with name1 that is energy tail correction scale factor and function of lambda + v_name2 = variable with name2 that is derivative of v_name1 with respect to lambda + kspace args = v_name1 v_name2 + v_name1 = variable with name1 that is K-Space scale factor and function of lambda + v_name2 = variable with name2 that is derivative of v_name1 with respect to lambda ++ +
Examples: +
+compute 1 all ti lj/cut v_lj v_dlj coul/long v_c v_dc kspace v_ks v_dks ++
Description: +
+Define a computation that calculates the derivative of the interaction +potential with respect to lambda, the coupling parameter used in a +thermodynamic integration. This derivative can be used to infer a +free energy difference resulting from an alchemical simulation, as +described in Eike. +
+Typically this compute will be used in conjunction with the fix +adapt command which can perform alchemical +transformations by adusting the strength of an interaction potential +as a simulation runs, as defined by one or more +pair_style or kspace_style +commands. This scaling is done via a prefactor on the energy, forces, +virial calculated by the pair or K-Space style. The prefactor is +often a function of a lambda parameter which may be adjusted from 0 +to 1 (or vice versa) over the course of a run. The +time-dependent adjustment is what the fix adapt +command does. +
+Assume that the unscaled energy of a pair_style or kspace_style is +given by U. Then the scaled energy is +
+Us = f(lambda) U ++
where f() is some function of lambda. What this compute calculates is +
+dUs / d(lambda) = U df(lambda)/dlambda = Us / f(lambda) df(lambda)/dlambda ++
which is the derivative of the system's scaled potential energy Us +with respect to lambda. +
+To do this calculation, you provide two functions, as equal-style +variables. The first is specified as v_name1, where +name1 is the name of the variable, and is f(lambda) in the notation +above. The second is specified as v_name2, where name2 is the +name of the variable, and is df(lambda) / dlambda in the notation +above. I.e. it is the analytic derivative of f() with respect to +lambda. Note that the name1 variable is also typically given as an +argument to the fix adapt command. +
+An alchemical simulation may use several pair potentials together, +invoked via the pair_style hybrid or hybrid/overlay +command. The total dUs/dlambda for the overall system is calculated +as the sum of each contributing term as listed by the keywords in the +compute ti command. Individual pair potentials can be listed, which +will be sub-styles in the hybrid case. You can also include a K-space +term via the kspace keyword. You can also include a pairwise +long-range tail correction to the energy via the tail keyword. +
+For each term you can specify a different (or the same) scale factor +by the two variables that you list. Again, these will typically +correspond toe the scale factors applied to these various potentials +and the K-Space contribution via the fix_adapt +command. +
+More details about the exact functional forms for the computation of +du/dl can be found in the paper by Eike. +
+Output info: +
+This compute calculates a global scalar, namely dUs/dlambda. This +value can be used by any command that uses a global scalar value from +a compute as input. See this section for an +overview of LAMMPS output options. +
+The scalar value calculated by this compute is "extensive". +
+The scalar value will be in energy units. +
+Restrictions: none +
+Related commands: +
+ +Default: none +
+ + +(Eike) Eike and Maginn, Journal of Chemical Physics, 124, 164503 (2006). +
+ diff --git a/doc/compute_ti.txt b/doc/compute_ti.txt new file mode 100644 index 0000000000..39078cbd28 --- /dev/null +++ b/doc/compute_ti.txt @@ -0,0 +1,113 @@ +"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 ti command :h3 + +[Syntax:] + +compute ID group ti keyword args ... :pre + +ID, group-ID are documented in "compute"_compute.html command :ulb,l +ti = style name of this compute command :l +one or more attribute/arg pairs may be appended :l +keyword = pair style (lj/cut, gauss, born, etc) or {tail} or {kspace} :l + pair style args = v_name1 v_name2 + v_name1 = variable with name1 that is energy scale factor and function of lambda + v_name2 = variable with name2 that is derivative of v_name1 with respect to lambda + {tail} args = v_name1 v_name2 + v_name1 = variable with name1 that is energy tail correction scale factor and function of lambda + v_name2 = variable with name2 that is derivative of v_name1 with respect to lambda + {kspace} args = v_name1 v_name2 + v_name1 = variable with name1 that is K-Space scale factor and function of lambda + v_name2 = variable with name2 that is derivative of v_name1 with respect to lambda :pre +:ule + +[Examples:] + +compute 1 all ti lj/cut v_lj v_dlj coul/long v_c v_dc kspace v_ks v_dks :pre + +[Description:] + +Define a computation that calculates the derivative of the interaction +potential with respect to {lambda}, the coupling parameter used in a +thermodynamic integration. This derivative can be used to infer a +free energy difference resulting from an alchemical simulation, as +described in "Eike"_#Eike. + +Typically this compute will be used in conjunction with the "fix +adapt"_fix_adapt.html command which can perform alchemical +transformations by adusting the strength of an interaction potential +as a simulation runs, as defined by one or more +"pair_style"_pair_style.html or "kspace_style"_kspace_style.html +commands. This scaling is done via a prefactor on the energy, forces, +virial calculated by the pair or K-Space style. The prefactor is +often a function of a {lambda} parameter which may be adjusted from 0 +to 1 (or vice versa) over the course of a "run"_run.html. The +time-dependent adjustment is what the "fix adapt"_fix_adapt.html +command does. + +Assume that the unscaled energy of a pair_style or kspace_style is +given by U. Then the scaled energy is + +Us = f(lambda) U :pre + +where f() is some function of lambda. What this compute calculates is + +dUs / d(lambda) = U df(lambda)/dlambda = Us / f(lambda) df(lambda)/dlambda :pre + +which is the derivative of the system's scaled potential energy Us +with respect to {lambda}. + +To do this calculation, you provide two functions, as "equal-style +variables"_variable.html. The first is specified as {v_name1}, where +{name1} is the name of the variable, and is f(lambda) in the notation +above. The second is specified as {v_name2}, where {name2} is the +name of the variable, and is df(lambda) / dlambda in the notation +above. I.e. it is the analytic derivative of f() with respect to +lambda. Note that the {name1} variable is also typically given as an +argument to the "fix adapt"_fix_adapt.html command. + +An alchemical simulation may use several pair potentials together, +invoked via the "pair_style hybrid or hybrid/overlay"_pair_hybrid.html +command. The total dUs/dlambda for the overall system is calculated +as the sum of each contributing term as listed by the keywords in the +compute ti command. Individual pair potentials can be listed, which +will be sub-styles in the hybrid case. You can also include a K-space +term via the {kspace} keyword. You can also include a pairwise +long-range tail correction to the energy via the {tail} keyword. + +For each term you can specify a different (or the same) scale factor +by the two variables that you list. Again, these will typically +correspond toe the scale factors applied to these various potentials +and the K-Space contribution via the "fix_adapt"_fix_adapt.html +command. + +More details about the exact functional forms for the computation of +du/dl can be found in the paper by "Eike"_#Eike. + +[Output info:] + +This compute calculates a global scalar, namely dUs/dlambda. This +value can be used by any command that uses a global scalar value from +a compute as input. See "this section"_Section_howto.html#4_15 for an +overview of LAMMPS output options. + +The scalar value calculated by this compute is "extensive". + +The scalar value will be in energy "units"_units.html. + +[Restrictions:] none + +[Related commands:] + +"fix adapt"_fix_adapt.html + +[Default:] none + +:link(Eike) +[(Eike)] Eike and Maginn, Journal of Chemical Physics, 124, 164503 (2006). diff --git a/doc/fix_adapt.html b/doc/fix_adapt.html index 3b392729ce..cafbf0eec0 100644 --- a/doc/fix_adapt.html +++ b/doc/fix_adapt.html @@ -13,7 +13,7 @@Syntax:
-fix ID group-ID adapt N keyword values ... +fix ID group-ID adapt N attribute args ... keyword value ...
pair args = pstyle pparam I J v_name
pstyle = pair style name, e.g. lj/cut
pparam = parameter to adapt over time
I,J = type pair(s) to set parameter for
v_name = variable with name that calculates value of pparam
+ kspace arg = v_name
+ v_name = variable with name that calculates scale factor on K-space terms
atom args = aparam v_name
aparam = parameter to adapt over time
v_name = variable with name that calculates value of aparam
+scale value = no or yes + no = the variable value is the new setting + yes = the variable value multiplies the original setting ++
reset value = no or yes + no = values will remain altered at the end of a run + yes = reset altered values to their original values at the end of a run +
Examples:
fix 1 all adapt 1 pair soft a 1 1 v_prefactor fix 1 all adapt 1 pair soft a 2* 3 v_prefactor -fix 1 all adapt 1 pair soft a * * v_prefactor soft a 3 3 v_prefactor2 +fix 1 all adapt 1 pair lj/cut epsilon * * v_scale1 coul/cut pre 3 3 v_scale2 scale yes reset yes fix 1 all adapt 10 atom diameter v_size
Description:
-Change or adapt one or more specific simulation settings over time as -a simulation runs. Pair potential and atom attribute parameters which -can be varied by this fix are discussed below. Many other fixes can -also be used to time-vary simulation parameters, e.g. the "fix deform" -command will change the simulation box size/shape and the "fix move" -command will change atom positions and velocities in prescribed -manners. +
Change or adapt one or more specific simulation attributes or settings +over time as a simulation runs. Pair potential and K-space and atom +attributes which can be varied by this fix are discussed below. Many +other fixes can also be used to time-vary simulation parameters, +e.g. the "fix deform" command will change the simulation box +size/shape and the "fix move" command will change atom positions and +velocities in a prescribed manner.
-IMPORTANT NOTE: Any settings changed by fix adapt are not reset to -their original values at the end of a simulation. They remain changed -to the final values they were set to at the end of the run. +
If N is specified as 0, the specified attributes are only changed +once, before the simulation begins. This is all that is needed if the +associated variables are not time-dependent. If N > 0, then changes +are made every N steps during the simulation, presumably with a +variable that is time-dependent.
+Depending on the value of the reset keyword, attributes changed by +this fix will or will not be reset back to their original values at +the end of a simulation. Even if reset is specified as yes, a +restart file written during a simulation will contain the modified +settings. +
+If the scale keyword is set to no, then the value the parameter is +set to will be whatever the variable generates. If the scale +keyword is set to yes, then the value of the altered parameter will +be the initial value of that parameter multiplied by whatever the +variable generates. I.e. the variable is now a "scale factor" applied +in (presumably) a time-varying fashion to the parameter. Internally, +the parameters themselves are actually altered; make sure you use the +reset yes option if you want the parameters to be restored to their +initial values after the run. +
+The pair keyword enables various parameters of potentials defined by the pair_style command to be changed, if the pair -style supports it. The pstyle argument is the name of the pair -style. If pair_style hybrid or hybrid/overlay is -used, pstyle should be a sub-style name. For example, pstyle -could be specified as "soft" or "lubricate". The pparam argument is -the name of the parameter to change. This is the current list of pair -styles and parameters that can be varied by this fix. See the doc -pages for individual pair styles for the meaning of these parameters. +style supports it. Note that the pair_style and +pair_coeff commands must be used in the usual manner +to specify these parameters initially; the fix adapt command simply +overrides the parameters. +
+The pstyle argument is the name of the pair style. If pair_style +hybrid or hybrid/overlay is used, pstyle should be +a sub-style name. For example, pstyle could be specified as "soft" +or "lubricate". The pparam argument is the name of the parameter to +change. This is the current list of pair styles and parameters that +can be varied by this fix. See the doc pages for individual pair +styles and their energy formulas for the meaning of these parameters:
| soft | a | global |
| lubricate | mu | type pairs + |
| born: a | b | c: type pairs:buck: a |
| c: type pairs:coul/cut: scale: type pairs:coul/debye: scale: type pairs:coul/long: scale: type pairs:lj/cut: epsilon: type pairs:lj/cut/opt: epsilon: type pairs:lubricate: mu: global:gauss: a: type pairs:soft: a: type pairs |
Some parameters are global settings for the pair style, e.g. the viscosity setting "mu" for pair_style lubricate. -Other parameters apply to pairs of atom types within the pair style, -e.g. the prefactor "a" for pair_style soft. If a -type pair parameter is specified, the I and J settings should be -specified to indicate which pair(s) to apply it to. Note that in all -cases, the pair_style and -pair_coeff commands must be used in the usual manner -to specify these parameters initially; the fix adapt command simply -overrides the parameters. +Other parameters apply to atom type pairs within the pair style, +e.g. the prefactor "a" for pair_style soft. +
+Note that for many of the potentials, the parameter that can be varied +is effectively a prefactor on the entire energy expression for the +potential, e.g. the lj/cut epsilon. The parameters listed as "scale" +are exactly that, since the energy expression for the +coul/cut potential (for example) has no labeled +prefactor in its formula. To apply an effective prefactor to some +potentials, multiple parameters need to be altered. For example, the +Buckingham potential needs both the A and C terms +altered together. To scale the Buckingham potential, you should thus +list the pair style twice, once for A and once for C. +
+If a type pair parameter is specified, the I and J settings should +be specified to indicate which type pairs to apply it to. If a global +parameter is specified, the I and J settings still need to be +specified, but are ignored.
Similar to the pair_coeff command, I and J can be specified in one of two ways. Explicit numeric values can be used for @@ -98,8 +147,11 @@ all types from 1 to N. A leading asterisk means all types from 1 to n (inclusive). Note that only type pairs with I <= J are considered; if asterisks imply type pairs where J < I, they are ignored.
-If a global parameter is specified, the I and J settings still -need to be specified, but are ignored. +
IMPROTANT NOTE: If pair_style hybrid or +hybrid/overlay is being used, then the pstyle will +be a sub-style name. You must specify I,J arguments that correspond +to type pair values defined (via the pair_coeff +command) for that sub-style.
The v_name argument for keyword pair is the name of an equal-style variable which will be evaluated each time @@ -121,6 +173,18 @@ linear fashion over the course of a simulation:
variable prefactor equal ramp(10,30) fix 1 all adapt 1 pair soft a * * v_prefactor+
The kspace keyword used the specified variable as a scale factor on +the energy, forces, virial calculated by whatever K-Space solver is +defined by the kspace_style command. If the +variable has a value of 1.0, then the solver is unaltered. +
+The kspace keyword works this way whether the scale keyword +is set to no or yes. +
+The atom keyword enables various atom properties to be changed. The aparam argument is the name of the parameter to change. This is the current list of atom parameters that can be varied by this fix: @@ -160,8 +224,12 @@ This fix is not invoked during energy minimization
Restrictions: none
-Related commands: none +
Related commands:
-Default: none +
+Default: +
+The option defaults are scale = no, reset = no.