<HTML>
<CENTER><A HREF = "https://sparta.github.io">SPARTA WWW Site</A> - <A HREF = "Manual.html">SPARTA Documentation</A> - <A HREF = "Section_commands.html#comm">SPARTA Commands</A> 
</CENTER>






<HR>

<H3>run command 
</H3>
<P><B>Syntax:</B>
</P>
<PRE>run N keyword values ... 
</PRE>
<UL><LI>value = # of integer timesteps N 

<LI>zero or more keyword/value pairs may be appended 

<LI>keyword = <I>upto</I> or <I>start</I> or <I>stop</I> or <I>pre</I> or <I>post</I> or <I>every</I> 

<PRE>  <I>upto</I> value = none
  <I>start</I> value = N1
    N1 = timestep at which 1st run started
  <I>stop</I> value = N2
    N2 = timestep at which last run will end
  <I>pre</I> value = <I>no</I> or <I>yes</I>
  <I>post</I> value = <I>no</I> or <I>yes</I>
  <I>every</I> values = M c1 c2 ...
    M = break the run into M-timestep segments and invoke one or more commands between each segment
    c1,c2,...,cN = one or more SPARTA commands, each enclosed in quotes
    c1 = NULL means no command will be invoked 
</PRE>

</UL>
<P><B>Examples:</B>
</P>
<PRE>run 10000
run 1000000 upto
run 100 start 0 stop 1000
run 1000 pre no post yes
run 100000 start 0 stop 1000000 every 1000 "print 'Temp = $t'"
run 100000 every 1000 NULL 
</PRE>
<P><B>Description:</B>
</P>
<P>Run or continue a simulation for a specified number of timesteps.
</P>
<P>A value of N = 0 is acceptable; only the statistics of the system are
computed and printed without taking a timestep.
</P>
<P>The <I>upto</I> keyword means to perform a run starting at the current
timestep up to the specified timestep.  E.g. if the current timestep
is 10,000 and "run 100000 upto" is used, then an additional 90,000
timesteps will be run.  This can be useful for very long runs on a
machine that allocates chunks of time and terminate your job when time
is exceeded.  If you need to restart your script multiple times
(reading in the last restart file), you can keep restarting your
script with the same run command until the simulation finally
completes.
</P>
<P>The <I>start</I> or <I>stop</I> keywords can be used if multiple runs are being
performed and you want a <A HREF = "variable.html">variable</A> or <A HREF = "fix.html">fix</A>
command that changes some value over time (e.g. target temperature) to
make the change across the entire set of runs and not just a single
run.
</P>
<P>For example, consider these commands followed by 10 run commands:
</P>
<PRE>variable     myTemp equal ramp(300,500)
surf_collide 1 diffuse v_myTemp 0.5
run	     1000 start 0 stop 10000
run	     1000 start 0 stop 10000
...
run	     1000 start 0 stop 10000 
</PRE>
<P>The ramp() function in the <A HREF = "variable.html">variable</A> and its use in the
"surf_collide" command will ramp the target temperature from 300 to
500 during a run.  If the run commands did not have the start/stop
keywords (just "run 1000"), then the temperature would ramp from 300
to 500 during the 1000 steps of each run.  With the start/stop
keywords, the ramping takes place smoothly over the 10000 steps of all
the runs together.
</P>
<P>The <I>pre</I> and <I>post</I> keywords can be used to streamline the setup,
clean-up, and associated output to the screen that happens before and
after a run.  This can be useful if you wish to do many short runs in
succession (e.g. SPARTA is being called as a library which is doing
other computations between successive short SPARTA runs).
</P>
<P>By default (pre and post = yes), SPARTA zeroes statistical counts
before every run and initializes other <A HREF = "fix.html">fixes</A> and
<A HREF = "compute.html">computes</A> as needed.  And after every run it gathers and
prints timings statistics.  If a run is just a continuation of a
previous run (i.e. no settings are changed), the initial computation
is not necessary.  So if <I>pre</I> is specified as "no" then the initial
setup is skipped, except for printing statistical info.  Note that if
<I>pre</I> is set to "no" for the very 1st run SPARTA performs, then it is
overridden, since the initial setup computations must be done.
</P>
<P>IMPORTANT NOTE: If your input script changes settings between 2 runs
(e.g. adds a <A HREF = "fix.html">fix</A> or <A HREF = "compute.html">compute</A>), then the
initial setup must be performed.  SPARTA does not check for this, but
it would be an error to use the <I>pre no</I> option in this case.
</P>
<P>If <I>post</I> is specified as "no", the full timing and statistical output
is skipped; only a one-line summary timing is printed.
</P>
<P>The <I>every</I> keyword provides a means of breaking a SPARTA run into a
series of shorter runs.  Optionally, one or more SPARTA commands (c1,
c2, ..., cN) will be executed in between the short runs.  If used, the
<I>every</I> keyword must be the last keyword, since it has a variable
number of arguments.  Each of the trailing arguments is a single
SPARTA command, and each command should be enclosed in quotes, so that
the entire command will be treated as a single argument.  This will
also prevent any variables in the command from being evaluated until
it is executed multiple times during the run.  Note that if a command
itself needs one of its arguments quoted (e.g. the <A HREF = "print.html">print</A>
command), then you can use a combination of single and double quotes,
as in the example above or below.
</P>
<P>The <I>every</I> keyword is a means to avoid listing a long series of runs
and interleaving commands in your input script.  For example, a
<A HREF = "print.html">print</A> command could be invoked or a <A HREF = "fix.html">fix</A> could
be redefined, e.g. to reset a load balancing parameter.  Or this could
be useful for invoking a command you have added to SPARTA that wraps
some other code (e.g. as a library) to perform a computation
periodically during a long SPARTA run.  See <A HREF = "Section_modify.html">Section
8</A> of the manual for info about how to add new
commands to SPARTA.  See <A HREF = "Section_howto.html#howto_10">Section 6.7</A> of
the manual for ideas about how to couple SPARTA to other codes.
</P>
<P>With the <I>every</I> option, N total steps are simulated, in shorter runs
of M steps each.  After each M-length run, the specified commands are
invoked.  If only a single command is specified as NULL, then no
command is invoked.  Thus these lines:
</P>
<PRE>compute t temp
variable myT equal c_t
run 6000 every 2000 "print 'Temp = $<I>myT</I>'" 
</PRE>
<P>are the equivalent of:
</P>
<PRE>compute t temp
variable myT equal c_t
run 2000
print "Temp = $<I>myT</I>"
run 2000
print "Temp = $<I>myT</I>"
run 2000
print "Temp = $<I>myT</I>" 
</PRE>
<P>which does 3 runs of 2000 steps and prints the x-coordinate of a
particular atom between runs.  Note that the variable "$q" will
be evaluated afresh each time the print command is executed.
</P>
<P>Note that by using the line continuation character "&", the run every
command can be spread across many lines, though it is still a single
command:
</P>
<PRE>run 100000 every 1000 &
  "print 'Minimum value = $a'" &
  "print 'Maximum value = $b'" &
  "print 'Temp = $c'" 
</PRE>
<P>If the <I>pre</I> and <I>post</I> options are set to "no" when used with the
<I>every</I> keyword, then the 1st run will do the full setup and the last
run will print the full timing summary, but these operations will be
skipped for intermediate runs.
</P>
<P>If you want SPARTA to exit early during the middle of a run when a
condition is met, use <A HREF = "fix_halt.html">fix halt</A>.
</P>
<P><B>Restrictions:</B>
</P>
<P>The number of specified timesteps N must fit in a signed 32-bit
integer, so you are limited to slightly more than 2 billion steps
(2^31) in a single run.  However, you can perform successive runs to
run a simulation for any number of steps (ok, up to 2^63 steps).
</P>
<P><B>Related commands:</B>
</P>
<P><A HREF = "fix_halt.html">fix halt</A>
</P>
<P><B>Default:</B>
</P>
<P>The option defaults are start = the current timestep, stop = current
timestep + N, pre = yes, and post = yes.
</P>
</HTML>
