forked from lijiext/lammps
271 lines
12 KiB
Plaintext
271 lines
12 KiB
Plaintext
.. index:: read_restart
|
|
|
|
read_restart command
|
|
====================
|
|
|
|
Syntax
|
|
""""""
|
|
|
|
.. parsed-literal::
|
|
|
|
read_restart file flag
|
|
|
|
* file = name of binary restart file to read in
|
|
* flag = remap (optional)
|
|
|
|
Examples
|
|
""""""""
|
|
|
|
.. parsed-literal::
|
|
|
|
read_restart save.10000
|
|
read_restart save.10000 remap
|
|
read_restart restart.*
|
|
read_restart restart.*.mpiio
|
|
read_restart poly.*.% remap
|
|
|
|
.. parsed-literal::
|
|
|
|
|
|
Description
|
|
"""""""""""
|
|
|
|
Read in a previously saved system configuration from a restart file.
|
|
This allows continuation of a previous run. Details about what
|
|
information is stored (and not stored) in a restart file is given
|
|
below. Basically this operation will re-create the simulation box
|
|
with all its atoms and their attributes as well as some related global
|
|
settings, at the point in time it was written to the restart file by a
|
|
previous simluation. The simulation box will be partitioned into a
|
|
regular 3d grid of rectangular bricks, one per processor, based on the
|
|
number of processors in the current simulation and the settings of the
|
|
:doc:`processors <processors>` command. The partitioning can later be
|
|
changed by the :doc:`balance <balance>` or :doc:`fix balance <fix_balance>` commands.
|
|
|
|
.. note::
|
|
|
|
Normally, restart files are written by the
|
|
:doc:`restart <restart>` or :doc:`write_restart <write_restart>` commands
|
|
so that all atoms in the restart file are inside the simulation box.
|
|
If this is not the case, the read_restart command will print an error
|
|
that atoms were "lost" when the file is read. This error should be
|
|
reported to the LAMMPS developers so the invalid writing of the
|
|
restart file can be fixed. If you still wish to use the restart file,
|
|
the optional *remap* flag can be appended to the read_restart command.
|
|
This should avoid the error, by explicitly remapping each atom back
|
|
into the simulation box, updating image flags for the atom
|
|
appropriately.
|
|
|
|
Restart files are saved in binary format to enable exact restarts,
|
|
meaning that the trajectories of a restarted run will precisely match
|
|
those produced by the original run had it continued on.
|
|
|
|
Several things can prevent exact restarts due to round-off effects, in
|
|
which case the trajectories in the 2 runs will slowly diverge. These
|
|
include running on a different number of processors or changing
|
|
certain settings such as those set by the :doc:`newton <newton>` or
|
|
:doc:`processors <processors>` commands. LAMMPS will issue a warning in
|
|
these cases.
|
|
|
|
Certain fixes will not restart exactly, though they should provide
|
|
statistically similar results. These include :doc:`fix shake <fix_shake>` and :doc:`fix langevin <fix_langevin>`.
|
|
|
|
Certain pair styles will not restart exactly, though they should
|
|
provide statistically similar results. This is because the forces
|
|
they compute depend on atom velocities, which are used at half-step
|
|
values every timestep when forces are computed. When a run restarts,
|
|
forces are initially evaluated with a full-step velocity, which is
|
|
different than if the run had continued. These pair styles include
|
|
:doc:`granular pair styles <pair_gran>`, :doc:`pair dpd <pair_dpd>`, and
|
|
:doc:`pair lubricate <pair_lubricate>`.
|
|
|
|
If a restarted run is immediately different than the run which
|
|
produced the restart file, it could be a LAMMPS bug, so consider
|
|
:ref:`reporting it <err_2>` if you think the behavior is
|
|
wrong.
|
|
|
|
Because restart files are binary, they may not be portable to other
|
|
machines. In this case, you can use the :ref:`-restart command-line switch <start_7>` to convert a restart file to a data
|
|
file.
|
|
|
|
Similar to how restart files are written (see the
|
|
:doc:`write_restart <write_restart>` and :doc:`restart <restart>`
|
|
commands), the restart filename can contain two wild-card characters.
|
|
If a "*" appears in the filename, the directory is searched for all
|
|
filenames that match the pattern where "*" is replaced with a timestep
|
|
value. The file with the largest timestep value is read in. Thus,
|
|
this effectively means, read the latest restart file. It's useful if
|
|
you want your script to continue a run from where it left off. See
|
|
the :doc:`run <run>` command and its "upto" option for how to specify
|
|
the run command so it doesn't need to be changed either.
|
|
|
|
If a "%" character appears in the restart filename, LAMMPS expects a
|
|
set of multiple files to exist. The :doc:`restart <restart>` and
|
|
:doc:`write_restart <write_restart>` commands explain how such sets are
|
|
created. Read_restart will first read a filename where "%" is
|
|
replaced by "base". This file tells LAMMPS how many processors
|
|
created the set and how many files are in it. Read_restart then reads
|
|
the additional files. For example, if the restart file was specified
|
|
as save.% when it was written, then read_restart reads the files
|
|
save.base, save.0, save.1, ... save.P-1, where P is the number of
|
|
processors that created the restart file.
|
|
|
|
Note that P could be the total number of processors in the previous
|
|
simulation, or some subset of those processors, if the *fileper* or
|
|
*nfile* options were used when the restart file was written; see the
|
|
:doc:`restart <restart>` and :doc:`write_restart <write_restart>` commands
|
|
for details. The processors in the current LAMMPS simulation share
|
|
the work of reading these files; each reads a roughly equal subset of
|
|
the files. The number of processors which created the set can be
|
|
different the number of processors in the current LAMMPS simulation.
|
|
This can be a fast mode of input on parallel machines that support
|
|
parallel I/O.
|
|
|
|
A restart file can also be read in parallel as one large binary file
|
|
via the MPI-IO library, assuming it was also written with MPI-IO.
|
|
MPI-IO is part of the MPI standard for versions 2.0 and above. Using
|
|
MPI-IO requires two steps. First, build LAMMPS with its MPIIO package
|
|
installed, e.g.
|
|
|
|
.. parsed-literal::
|
|
|
|
make yes-mpiio # installs the MPIIO package
|
|
make g++ # build LAMMPS for your platform
|
|
|
|
Second, use a restart filename which contains ".mpiio". Note that it
|
|
does not have to end in ".mpiio", just contain those characters.
|
|
Unlike MPI-IO dump files, a particular restart file must be both
|
|
written and read using MPI-IO.
|
|
|
|
|
|
----------
|
|
|
|
|
|
Here is the list of information included in a restart file, which
|
|
means these quantities do not need to be re-specified in the input
|
|
script that reads the restart file, though you can redefine many of
|
|
these settings after the restart file is read.
|
|
|
|
* :doc:`units <units>`
|
|
* :doc:`newton bond <newton>` (see discussion of newton command below)
|
|
* :doc:`atom style <atom_style>` and :doc:`atom_modify <atom_modify>` settings id, map, sort
|
|
* :doc:`comm style <comm_style>` and `comm_modify <comm_modify>`_ settings mode, cutoff, vel
|
|
* :doc:`timestep <timestep>`
|
|
* simulation box size and shape and :doc:`boundary <boundary>` settings
|
|
* atom :doc:`group <group>` definitions
|
|
* per-type atom settings such as `mass <mass.thml>`_
|
|
* per-atom attributes including their group assignments and molecular topology attributes (bonds, angles, etc)
|
|
* force field styles (:doc:`pair <pair_style>`, :doc:`bond <bond_style>`, :doc:`angle <angle_style>`, etc)
|
|
* force field coefficients (:doc:`pair <pair_coeff>`, :doc:`bond <bond_coeff>`, :doc:`angle <angle_coeff>`, etc) in some cases (see below)
|
|
* :doc:`pair_modify <pair_modify>` settings, except the compute option
|
|
* :doc:`special_bonds <special_bonds>` settings
|
|
|
|
Here is a list of information not stored in a restart file, which
|
|
means you must re-issue these commands in your input script, after
|
|
reading the restart file.
|
|
|
|
* :doc:`newton pair <newton>` (see discussion of newton command below)
|
|
* :doc:`fix <fix>` commands (see below)
|
|
* :doc:`compute <compute>` commands (see below)
|
|
* :doc:`variable <variable>` commands
|
|
* :doc:`region <region>` commands
|
|
* :doc:`neighbor list <neighbor>` criteria including :doc:`neigh_modify <neigh_modify>` settings
|
|
* :doc:`kspace_style <kspace_style>` and :doc:`kspace_modify <kspace_modify>` settings
|
|
* info for :doc:`thermodynamic <thermo_style>`, :doc:`dump <dump>`, or :doc:`restart <restart>` output
|
|
|
|
The :doc:`newton <newton>` command has two settings, one for pairwise
|
|
interactions, the other for bonded. Both settings are stored in the
|
|
restart file. For the bond setting, the value in the file will
|
|
overwrite the current value (at the time the read_restart command is
|
|
issued) and warn if the two values are not the same and the current
|
|
value is not the default. For the pair setting, the value in the file
|
|
will not overwrite the current value (so that you can override the
|
|
previous run's value), but a warning is issued if the two values are
|
|
not the same and the current value is not the default.
|
|
|
|
Note that some force field styles (pair, bond, angle, etc) do not
|
|
store their coefficient info in restart files. Typically these are
|
|
many-body or tabulated potentials which read their parameters from
|
|
separate files. In these cases you will need to re-specify the "pair
|
|
:doc:`pair_coeff <pair_coeff>`, :doc:`bond_coeff <bond_coeff>`, etc
|
|
commands in your restart input script. The doc pages for individual
|
|
force field styles mention if this is the case. This is also true of
|
|
:doc:`pair_style hybrid <pair_hybrid>` (bond hybrid, angle hybrid, etc)
|
|
commands; they do not store coefficient info.
|
|
|
|
As indicated in the above list, the :doc:`fixes <fix>` used for a
|
|
simulation are not stored in the restart file. This means the new
|
|
input script should specify all fixes it will use. However, note that
|
|
some fixes store an internal "state" which is written to the restart
|
|
file. This allows the fix to continue on with its calculations in a
|
|
restarted simulation. To re-enable such a fix, the fix command in the
|
|
new input script must use the same fix-ID and group-ID as was used in
|
|
the input script that wrote the restart file. If a match is found,
|
|
LAMMPS prints a message indicating that the fix is being re-enabled.
|
|
If no match is found before the first run or minimization is performed
|
|
by the new script, the "state" information for the saved fix is
|
|
discarded. See the doc pages for individual fixes for info on which
|
|
ones can be restarted in this manner.
|
|
|
|
Likewise, the :doc:`computes <fix>` used for a simulation are not stored
|
|
in the restart file. This means the new input script should specify
|
|
all computes it will use. However, some computes create a fix
|
|
internally to store "state" information that persists from timestep to
|
|
timestep. An example is the :doc:`compute msd <compute_msd>` command
|
|
which uses a fix to store a reference coordinate for each atom, so
|
|
that a displacement can be calculated at any later time. If the
|
|
compute command in the new input script uses the same compute-ID and
|
|
group-ID as was used in the input script that wrote the restart file,
|
|
then it will create the same fix in the restarted run. This means the
|
|
re-created fix will be re-enabled with the stored state information as
|
|
described in the previous paragraph, so that the compute can continue
|
|
its calculations in a consistent manner.
|
|
|
|
Some pair styles, like the :doc:`granular pair styles <pair_gran>`, also
|
|
use a fix to store "state" information that persists from timestep to
|
|
timestep. In the case of granular potentials, it is contact
|
|
information between pairs of touching particles. This info will also
|
|
be re-enabled in the restart script, assuming you re-use the same
|
|
granular pair style.
|
|
|
|
LAMMPS allows bond interactions (angle, etc) to be turned off or
|
|
deleted in various ways, which can affect how their info is stored in
|
|
a restart file.
|
|
|
|
If bonds (angles, etc) have been turned off by the :doc:`fix shake <fix_shake>` or :doc:`delete_bonds <delete_bonds>` command,
|
|
their info will be written to a restart file as if they are turned on.
|
|
This means they will need to be turned off again in a new run after
|
|
the restart file is read.
|
|
|
|
Bonds that are broken (e.g. by a bond-breaking potential) are written
|
|
to the restart file as broken bonds with a type of 0. Thus these
|
|
bonds will still be broken when the restart file is read.
|
|
|
|
Bonds that have been broken by the :doc:`fix bond/break <fix_bond_break>` command have disappeared from the
|
|
system. No information about these bonds is written to the restart
|
|
file.
|
|
|
|
|
|
----------
|
|
|
|
|
|
Restrictions
|
|
""""""""""""
|
|
|
|
|
|
To write and read restart files in parallel with MPI-IO, the MPIIO
|
|
package must be installed.
|
|
|
|
Related commands
|
|
""""""""""""""""
|
|
|
|
:doc:`read_data <read_data>`, :doc:`read_dump <read_dump>`,
|
|
:doc:`write_restart <write_restart>`, :doc:`restart <restart>`
|
|
|
|
**Default:** none
|
|
|
|
|
|
.. _lws: http://lammps.sandia.gov
|
|
.. _ld: Manual.html
|
|
.. _lc: Section_commands.html#comm
|