fix halt command

Syntax

fix ID group-ID halt N attribute operator avalue keyword value ...

• ID, group-ID are documented in fix command

• halt = style name of this fix command

• N = check halt condition every N steps

• attribute = bondmax or tlimit or v_name

  bondmax = length of longest bond in the system (in length units)
  tlimit = elapsed CPU time (in seconds)
  diskfree = free disk space (in MBytes)
  v_name = name of equal-style variable

• operator = “<” or “<=” or “>” or “>=” or “==” or “!=” or “|^”

• avalue = numeric value to compare attribute to

• zero or more keyword/value pairs may be appended

• keyword = error or message or path

  error value = hard or soft or continue
  message value = yes or no
  path value = path to check for free space (may be in quotes)

Examples

fix 10 all halt 1 bondmax > 1.5
fix 10 all halt 10 v_myCheck != 0 error soft
fix 10 all halt 100 diskfree < 100000.0 path "dump storage/."

Description

Check a condition every N steps during a simulation run. N must be >=1. If the condition is met, exit the run. In this context a “run” can be dynamics or minimization iterations, as specified by the run or minimize command.

The specified group-ID is ignored by this fix.

The specified attribute can be one of the options listed above, namely bondmax, tlimit, diskfree, or an equal-style variable referenced as v_name, where “name” is the name of a variable that has been defined previously in the input script.

The bondmax attribute will loop over all bonds in the system, compute their current lengths, and set attribute to the longest bond distance.

The tlimit attribute queries the elapsed CPU time (in seconds) since the current run began, and sets attribute to that value. This is an alternative way to limit the length of a simulation run, similar to the timer timeout command. There are two differences in using this method versus the timer command option. The first is that the clock starts at the beginning of the current run (not when the timer or fix command is specified), so that any setup time for the run is not included in the elapsed time. The second is that the timer invocation and syncing across all processors (via MPI_Allreduce) is not performed once every N steps by this command. Instead it is performed (typically) only a small number of times and the elapsed times are used to predict when the end-of-the-run will be. Both of these attributes can be useful when performing benchmark calculations for a desired length of time with minimal overhead. For example, if a run is performing 1000s of timesteps/sec, the overhead for syncing the timer frequently across a large number of processors may be non-negligible.

The diskfree attribute will check for available disk space (in MBytes) on supported operating systems. By default it will check the file system of the current working directory. This can be changed with the optional path keyword, which will take the path to a file or folder on the file system to be checked as argument. This path must be given with single or double quotes, if it contains blanks or other special characters (like $).

Equal-style variables evaluate to a numeric value. See the variable command for a description. They calculate formulas which can involve mathematical operations, atom properties, group properties, thermodynamic properties, global values calculated by a compute or fix, or references to other variables. Thus they are a very general means of computing some attribute of the current system. For example, the following “bondmax” variable will calculate the same quantity as the hstyle = bondmax option.

compute         bdist all bond/local dist
compute         bmax all reduce max c_bdist
variable        bondmax equal c_bmax

Thus these two versions of a fix halt command will do the same thing:

fix 10 all halt 1 bondmax > 1.5
fix 10 all halt 1 v_bondmax > 1.5

The version with “bondmax” will just run somewhat faster, due to less overhead in computing bond lengths and not storing them in a separate compute.

A variable can be used to implement a large variety of conditions, including to stop when a specific file exists. Example:

variable exit equal is_file(EXIT)
fix 10 all halt 100 v_exit != 0 error soft

Will stop the current run command when a file EXIT is created in the current working directory. The condition can be cleared by removing the file through the shell command.

The choice of operators listed above are the usual comparison operators. The XOR operation (exclusive or) is also included as “|^”. In this context, XOR means that if either the attribute or avalue is 0.0 and the other is non-zero, then the result is “true”. Otherwise it is “false”.

The specified avalue must be a numeric value.

---

The optional error keyword determines how the current run is halted. If its value is hard, then LAMMPS will stop with an error message.

If its value is soft, LAMMPS will exit the current run, but continue to execute subsequent commands in the input script. However, additional run or minimize commands will be skipped. For example, this allows a script to output the current state of the system, e.g. via a write_dump or write_restart command.

If its value is continue, the behavior is the same as for soft, except subsequent run or minimize commands are executed. This allows your script to remedy the condition that triggered the halt, if necessary. Note that you may wish use the unfix command on the fix halt ID, so that the same condition is not immediately triggered in a subsequent run.

The optional message keyword determines whether a message is printed to the screen and logfile when the halt condition is triggered. If message is set to yes, a one line message with the values that triggered the halt is printed. If message is set to no, no message is printed; the run simply exits. The latter may be desirable for post-processing tools that extract thermodynamic information from log files.

Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix. No global or per-atom quantities are stored by this fix for access by various output commands. No parameter of this fix can be used with the start/stop keywords of the run command.

Restrictions

The diskfree attribute is currently only supported on Linux, MacOSX, and BSD.

Related commands

variable

Default

The option defaults are error = hard, message = yes, and path = “.”.