read_restart command — LAMMPS 15 May 2015 version documentation

# read_restart command

## Syntax

    read_restart file flag

- file = name of binary restart file to read in
- flag = remap (optional)

## Examples

    read_restart save.10000
    read_restart save.10000 remap
    read_restart restart.*
    read_restart restart.*.mpiio
    read_restart poly.*.% remap

## 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 processors command. The partitioning can later be changed by the balance or fix balance commands.

Warning

Normally, restart files are written by the restart or 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 newton or 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 fix shake and 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 granular pair styles, pair dpd, and 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 reporting it 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 -restart command-line switch to convert a restart file to a data file.

Similar to how restart files are written (see the write_restart and 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 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 restart and 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 restart and 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.

    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.

A restart file stores the following information about a simulation: units, atom style and atom style related settings (id, map, sort), communication settings (mode, cutoff, vel), timestep, simulation box size and shape and boundary settings, group definitions, per-type atom settings such as mass, per-atom attributes including their group assignments and molecular topology attributes, force field styles and - in most cases - force field coefficients, and special_bonds settings. This means that commands for these quantities do not need to be re-specified in the input script that reads the restart file, though you can redefine settings after the restart file is read.

One exception is that some force 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; you may need to re-specify the pair style and pair coeff commands in your restart input script. The doc pages for individual pair styles mention if this is the case. This is also true of bond_style hybrid (and angle_style, dihedral_style, improper_style hybrid).

All settings made by the pair_modify command, such as the shift and tail settings, are stored in the restart file with the pair style. The one exception is the pair_modify compute setting is not stored, since it is typically only used for debugging purposes.

Information about kspace_style settings are not stored in the restart file. Hence if you wish to use an Ewald or PPPM solver, these commands must be re-issued after the restart file is read.

The list of fixes used for a simulation is not stored in the restart file. This means the new input script should specify all fixes it will use. 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.

Bond interactions (angle, etc) that have been turned off by the fix shake or delete_bonds command 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 fix bond/break command have disappeared from the system. No information about these bonds is written to the restart file.

Warning

No other information is stored in the restart file. This means that an input script that reads a restart file should specify settings for quantities like timestep size, thermodynamic, neighbor list criteria including settings made via the neigh_modify comand, dump file output, geometric regions, etc.

## Restrictions

To write and read restart files in parallel with MPI-IO, the MPIIO package must be installed.

## Related commands

read_data, read_dump, write_restart, restart

Default: none