209 lines
8.3 KiB
ReStructuredText
209 lines
8.3 KiB
ReStructuredText
.. index:: fix halt
|
|
|
|
fix halt command
|
|
================
|
|
|
|
Syntax
|
|
""""""
|
|
|
|
.. code-block:: LAMMPS
|
|
|
|
fix ID group-ID halt N attribute operator avalue keyword value ...
|
|
|
|
* ID, group-ID are documented in :doc:`fix <fix>` command
|
|
* halt = style name of this fix command
|
|
* N = check halt condition every N steps
|
|
* attribute = *bondmax* or *tlimit* or v_name
|
|
|
|
.. parsed-literal::
|
|
|
|
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 :doc:`equal-style variable <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* or *universe*
|
|
|
|
.. parsed-literal::
|
|
|
|
*error* value = *hard* or *soft* or *continue*
|
|
*message* value = *yes* or *no*
|
|
*path* value = path to check for free space (may be in quotes)
|
|
*universe* value = *yes* or *no*
|
|
|
|
|
|
Examples
|
|
""""""""
|
|
|
|
.. code-block:: LAMMPS
|
|
|
|
fix 10 all halt 1 bondmax > 1.5
|
|
fix 10 all halt 10 v_myCheck != 0 error soft message no
|
|
fix 10 all halt 100 diskfree < 100000.0 path "dump storage/."
|
|
fix 2 all halt 100 v_curtime > ${maxtime} universe yes
|
|
|
|
|
|
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 :doc:`run
|
|
<run>` or :doc:`minimize <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 :doc:`equal-style variable
|
|
<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 :doc:`timer <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
|
|
:doc:`variable <variable>` command for a description. They calculate
|
|
formulas which can involve mathematical operations, atom properties,
|
|
group properties, thermodynamic properties, global values calculated
|
|
by a :doc:`compute <compute>` or :doc:`fix <fix>`, or references to other
|
|
:doc:`variables <variable>`. 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.
|
|
|
|
.. code-block:: LAMMPS
|
|
|
|
compute bdist all bond/local dist
|
|
compute bmax all reduce max c_bdist inputs local
|
|
variable bondmax equal c_bmax
|
|
|
|
Thus these two versions of a fix halt command will do the same thing:
|
|
|
|
.. code-block:: LAMMPS
|
|
|
|
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:
|
|
|
|
.. code-block:: LAMMPS
|
|
|
|
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 :doc:`shell <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
|
|
:doc:`run <run>` or :doc:`minimize <minimize>` commands will be skipped.
|
|
For example, this allows a script to output the current state of the
|
|
system, e.g. via a :doc:`write_dump <write_dump>` or :doc:`write_restart
|
|
<write_restart>` command. To re-enable regular runs after *fix halt*
|
|
stopped a run, you need to issue a :doc:`timer timeout unlimited
|
|
<timer>` command.
|
|
|
|
If its value is *continue*, the behavior is the same as for *soft*,
|
|
except subsequent :doc:`run <run>` or :doc:`minimize <minimize>` commands
|
|
are executed. This allows your script to remedy the condition that
|
|
triggered the halt, if necessary. This is the equivalent of stopping
|
|
with *error soft* and followed by :doc:`timer timeout unlimited
|
|
<timer>` command. This can have undesired consequences, when a
|
|
:doc:`run command <run>` uses the *every* keyword, so using *error soft*
|
|
and resetting the timer manually may be the preferred option.
|
|
|
|
You may wish use the :doc:`unfix <unfix>` command on the *fix halt* ID
|
|
before starting a subsequent run, so that the same condition is not
|
|
immediately triggered again.
|
|
|
|
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.
|
|
|
|
.. versionadded:: 2Apr2025
|
|
|
|
The optional *universe* keyword determines whether the halt request
|
|
should be synchronized across the partitions of a :doc:`multi-partition
|
|
run <Run_options>`. If *universe* is set to yes, fix halt will check if
|
|
there is a specific message received from any of the other partitions
|
|
requesting to stop the run on this partition as well. Consequently, if
|
|
fix halt determines to halt the simulation, the fix will send messages
|
|
to all other partitions so they stop their runs, too.
|
|
|
|
Restart, fix_modify, output, run start/stop, minimize info
|
|
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
|
|
|
|
No information about this fix is written to :doc:`binary restart files
|
|
<restart>`. None of the :doc:`fix_modify <fix_modify>` options are
|
|
relevant to this fix. No global or per-atom quantities are stored by
|
|
this fix for access by various :doc:`output commands <Howto_output>`.
|
|
No parameter of this fix can be used with the *start/stop* keywords of
|
|
the :doc:`run <run>` command.
|
|
|
|
Restrictions
|
|
""""""""""""
|
|
The *diskfree* attribute is currently only supported on Linux, macOS, and \*BSD.
|
|
|
|
Related commands
|
|
""""""""""""""""
|
|
|
|
:doc:`variable <variable>`
|
|
|
|
Default
|
|
"""""""
|
|
|
|
The option defaults are error = soft, message = yes, path = ".", and universe = no.
|