doc/src/restart.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 restart command :h3
  10
  11 [Syntax:]
  12
  13 restart 0
  14 restart N root keyword value ...
  15 restart N file1 file2 keyword value ... :pre
  16
  17 N = write a restart file every this many timesteps :ulb,l
  18 N can be a variable (see below) :l
  19 root = filename to which timestep # is appended :l
  20 file1,file2 = two full filenames, toggle between them when writing file :l
  21 zero or more keyword/value pairs may be appended :l
  22 keyword = {fileper} or {nfile} :l
  23   {fileper} arg = Np
  24     Np = write one file for every this many processors
  25   {nfile} arg = Nf
  26     Nf = write this many files, one from each of Nf processors :pre
  27 :ule
  28
  29 [Examples:]
  30
  31 restart 0
  32 restart 1000 poly.restart
  33 restart 1000 poly.restart.mpiio
  34 restart 1000 restart.*.equil
  35 restart 10000 poly.%.1 poly.%.2 nfile 10
  36 restart v_mystep poly.restart :pre
  37
  38 [Description:]
  39
  40 Write out a binary restart file with the current state of the
  41 simulation every so many timesteps, in either or both of two modes, as
  42 a run proceeds.  A value of 0 means do not write out any restart
  43 files.  The two modes are as follows.  If one filename is specified, a
  44 series of filenames will be created which include the timestep in the
  45 filename.  If two filenames are specified, only 2 restart files will
  46 be created, with those names.  LAMMPS will toggle between the 2 names
  47 as it writes successive restart files.
  48
  49 Note that you can specify the restart command twice, once with a
  50 single filename and once with two filenames.  This would allow you,
  51 for example, to write out archival restart files every 100000 steps
  52 using a single filenname, and more frequent temporary restart files
  53 every 1000 steps, using two filenames.  Using restart 0 will turn off
  54 both modes of output.
  55
  56 Similar to "dump"_dump.html files, the restart filename(s) can contain
  57 two wild-card characters.
  58
  59 If a "*" appears in the single filename, it is replaced with the
  60 current timestep value.  This is only recognized when a single
  61 filename is used (not when toggling back and forth).  Thus, the 3rd
  62 example above creates restart files as follows: restart.1000.equil,
  63 restart.2000.equil, etc.  If a single filename is used with no "*",
  64 then the timestep value is appended.  E.g. the 2nd example above
  65 creates restart files as follows: poly.restart.1000,
  66 poly.restart.2000, etc.
  67
  68 If a "%" character appears in the restart filename(s), then one file
  69 is written for each processor and the "%" character is replaced with
  70 the processor ID from 0 to P-1.  An additional file with the "%"
  71 replaced by "base" is also written, which contains global information.
  72 For example, the files written on step 1000 for filename restart.%
  73 would be restart.base.1000, restart.0.1000, restart.1.1000, ...,
  74 restart.P-1.1000.  This creates smaller files and can be a fast mode
  75 of output and subsequent input on parallel machines that support
  76 parallel I/O.  The optional {fileper} and {nfile} keywords discussed
  77 below can alter the number of files written.
  78
  79 The restart file can also be written in parallel as one large binary
  80 file via the MPI-IO library, which is part of the MPI standard for
  81 versions 2.0 and above.  Using MPI-IO requires two steps.  First,
  82 build LAMMPS with its MPIIO package installed, e.g.
  83
  84 make yes-mpiio    # installs the MPIIO package
  85 make mpi          # build LAMMPS for your platform :pre
  86
  87 Second, use a restart filename which contains ".mpiio".  Note that it
  88 does not have to end in ".mpiio", just contain those characters.
  89 Unlike MPI-IO dump files, a particular restart file must be both
  90 written and read using MPI-IO.
  91
  92 Restart files are written on timesteps that are a multiple of N but
  93 not on the first timestep of a run or minimization.  You can use the
  94 "write_restart"_write_restart.html command to write a restart file
  95 before a run begins.  A restart file is not written on the last
  96 timestep of a run unless it is a multiple of N.  A restart file is
  97 written on the last timestep of a minimization if N > 0 and the
  98 minimization converges.
  99
 100 Instead of a numeric value, N can be specifed as an "equal-style
 101 variable"_variable.html, which should be specified as v_name, where
 102 name is the variable name.  In this case, the variable is evaluated at
 103 the beginning of a run to determine the next timestep at which a
 104 restart file will be written out.  On that timestep, the variable will
 105 be evaluated again to determine the next timestep, etc.  Thus the
 106 variable should return timestep values.  See the stagger() and
 107 logfreq() and stride() math functions for "equal-style
 108 variables"_variable.html, as examples of useful functions to use in
 109 this context.  Other similar math functions could easily be added as
 110 options for "equal-style variables"_variable.html.
 111
 112 For example, the following commands will write restart files
 113 every step from 1100 to 1200, and could be useful for debugging
 114 a simulation where something goes wrong at step 1163:
 115
 116 variable       s equal stride(1100,1200,1)
 117 restart        v_s tmp.restart :pre
 118
 119 :line
 120
 121 See the "read_restart"_read_restart.html command for information about
 122 what is stored in a restart file.
 123
 124 Restart files can be read by a "read_restart"_read_restart.html
 125 command to restart a simulation from a particular state.  Because the
 126 file is binary (to enable exact restarts), it may not be readable on
 127 another machine.  In this case, you can use the "-r command-line
 128 switch"_Section_start.html#start_7 to convert a restart file to a data
 129 file.
 130
 131 NOTE: Although the purpose of restart files is to enable restarting a
 132 simulation from where it left off, not all information about a
 133 simulation is stored in the file.  For example, the list of fixes that
 134 were specified during the initial run is not stored, which means the
 135 new input script must specify any fixes you want to use.  Even when
 136 restart information is stored in the file, as it is for some fixes,
 137 commands may need to be re-specified in the new input script, in order
 138 to re-use that information.  See the "read_restart"_read_restart.html
 139 command for information about what is stored in a restart file.
 140
 141 :line
 142
 143 The optional {nfile} or {fileper} keywords can be used in conjunction
 144 with the "%" wildcard character in the specified restart file name(s).
 145 As explained above, the "%" character causes the restart file to be
 146 written in pieces, one piece for each of P processors.  By default P =
 147 the number of processors the simulation is running on.  The {nfile} or
 148 {fileper} keyword can be used to set P to a smaller value, which can
 149 be more efficient when running on a large number of processors.
 150
 151 The {nfile} keyword sets P to the specified Nf value.  For example, if
 152 Nf = 4, and the simulation is running on 100 processors, 4 files will
 153 be written, by processors 0,25,50,75.  Each will collect information
 154 from itself and the next 24 processors and write it to a restart file.
 155
 156 For the {fileper} keyword, the specified value of Np means write one
 157 file for every Np processors.  For example, if Np = 4, every 4th
 158 processor (0,4,8,12,etc) will collect information from itself and the
 159 next 3 processors and write it to a restart file.
 160
 161 :line
 162
 163 [Restrictions:]
 164
 165 To write and read restart files in parallel with MPI-IO, the MPIIO
 166 package must be installed.
 167
 168 [Related commands:]
 169
 170 "write_restart"_write_restart.html, "read_restart"_read_restart.html
 171
 172 [Default:]
 173
 174 restart 0 :pre