doc/src/fix_halt.txt

   1 "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c
   2
   3 :link(lws,http://lammps.sandia.gov)
   4 :link(ld,Manual.html)
   5 :link(lc,Section_commands.html#comm)
   6
   7 :line
   8
   9 fix halt command :h3
  10
  11 [Syntax:]
  12
  13 fix ID group-ID halt N attribute operator avalue keyword value ... :pre
  14
  15 ID, group-ID are documented in "fix"_fix.html command :ulb,l
  16 halt = style name of this fix command :l
  17 N = check halt condition every N steps :l
  18 attribute = hstyle or v_name :l
  19   hstyle = {bondmax}
  20   v_name = name of "equal-style variable"_variable.html :pre
  21 operator = "<" or "<=" or ">" or ">=" or "==" or "!=" or "|^" :l
  22 avalue = numeric value to compare attribute to :l
  23 string = text string to print with optional variable names :l
  24 zero or more keyword/value pairs may be appended :l
  25 keyword = {error} :l
  26   {error} value = {hard} or {soft} or {continue} :pre
  27 :ule
  28
  29 [Examples:]
  30
  31 fix 10 all halt 1 bondmax > 1.5
  32 fix 10 all print 10 v_myCheck != 0 error soft :pre
  33
  34 [Description:]
  35
  36 Check a condition every N steps during a simulation run.  N must be >=
  37 1.  If the condition is met, exit the run immediately.  In this
  38 context a "run" can be dynamics or minimization iterations, as
  39 specified by the "run"_run.html or "minimize"_minimize.html command.
  40
  41 The specified group-ID is ignored by this fix.
  42
  43 The specified {attribute} can be one of the {hstyle} options listed
  44 above, or an "equal-style variable"_variable.html referenced as
  45 {v_name}, where "name" is the name of a variable that has been defined
  46 previously in the input script.
  47
  48 The only {hstyle} option currently implemented is {bondmax}.  This
  49 will loop over all bonds in the system, compute their current
  50 lengths, and set {attribute} to the longest bond distance.
  51
  52 Equal-style variables evaluate to a numeric value.  See the
  53 "variable"_variable.html command for a description.  They calculate
  54 formulas which can involve mathematical operations, atom properties,
  55 group properties, thermodynamic properties, global values calculated
  56 by a "compute"_compute.html or "fix"_fix.html, or references to other
  57 "variables"_variable.html.  Thus they are a very general means of
  58 computing some attribute of the current system.  For example, the
  59 following "bondmax" variable will calculate the same quantity as the
  60 hstyle = bondmax option.
  61
  62 compute         bdist all bond/local dist
  63 compute         bmax all reduce max c_bdist
  64 variable        bondmax equal c_bmax :pre
  65
  66 Thus these two versions of a fix halt command will do the same thing:
  67
  68 fix 10 all halt 1 bondmax > 1.5
  69 fix 10 all halt 1 v_bondmax > 1.5 :pre
  70
  71 The version with "bondmax" will just run somewhat faster, due to less
  72 overhead in computing bond lengths and not storing them in a separate
  73 compute.
  74
  75 The choice of operators listed above are the usual comparison
  76 operators.  The XOR operation (exclusive or) is also included as "|^".
  77 In this context, XOR means that if either the attribute or avalue is
  78 0.0 and the other is non-zero, then the result is "true".  Otherwise
  79 it is "false".
  80
  81 The specified {avalue} must be a numeric value.
  82
  83 :line
  84
  85 The optional {error} keyword determines how the current run is halted.
  86 If its value is {hard}, then LAMMPS will stop with an error message.
  87
  88 If its value is {soft}, LAMMPS will exit the current run, but continue
  89 to execute subsequent commands in the input script.  However,
  90 additional "run"_run.html or "minimize"_minimize.html commands will be
  91 skipped.  For example, this allows a script to output the current
  92 state of the system, e.g. via a "write_dump"_write_dump.html or
  93 "write_restart"_write_restart.html command.
  94
  95 If its value is {continue}, the behavior is the same as for {soft},
  96 except subsequent subsequent "run"_run.html or
  97 "minimize"_minimize.html commands are executed.  This allows your
  98 script to remedy the condition that triggered the halt, if necessary.
  99 Note that you may wish use the "unfix"_unfix.html command on the fix
 100 halt ID, so that the same condition is not immediately triggered in a
 101 subsequent run.
 102
 103 [Restart, fix_modify, output, run start/stop, minimize info:]
 104
 105 No information about this fix is written to "binary restart
 106 files"_restart.html.  None of the "fix_modify"_fix_modify.html options
 107 are relevant to this fix.  No global or per-atom quantities are stored
 108 by this fix for access by various "output
 109 commands"_Section_howto.html#howto_15.  No parameter of this fix can
 110 be used with the {start/stop} keywords of the "run"_run.html command.
 111 This fix is not invoked during "energy minimization"_minimize.html.
 112
 113 [Restrictions:] none
 114
 115 [Related commands:]
 116
 117 "variable"_variable.html
 118
 119 [Default:]
 120
 121 The option defaults are error = hard.