3. Commands
This section describes how a SPARTA input script is formatted and what commands are used to define a SPARTA simulation.
3.1. SPARTA input script
SPARTA executes by reading commands from a input script (text file), one line at a time. When the input script ends, SPARTA exits. Each command causes SPARTA to take some action. It may set an internal variable, read in a file, or run a simulation. Most commands have default settings, which means you only need to use the command if you wish to change the default.
In many cases, the ordering of commands in an input script is not important. However the following rules apply:
(1) SPARTA does not read your entire input script and then perform a simulation with all the settings. Rather, the input script is read one line at a time and each command takes effect when it is read. Thus this sequence of commands:
timestep 0.5
run 100
run 100
does something different than this sequence:
run 100
timestep 0.5
run 100
In the first case, the specified timestep (0.5 secs) is used for two simulations of 100 timesteps each. In the 2nd case, the default timestep (1.0 sec is used for the 1st 100 step simulation and a 0.5 fmsec timestep is used for the 2nd one.
(2) Some commands are only valid when they follow other commands. For example you cannot define the grid overlaying the simulation box until the box itself has been defined. Likewise you cannot read in triangulated surfaces until a grid has been defined to store them.
Many input script errors are detected by SPARTA and an ERROR or WARNING message is printed. Section 12 gives more information on what errors mean. The documentation for each command lists restrictions on how the command can be used.
3.2. Parsing rules
Each non-blank line in the input script is treated as a command. SPARTA commands are case sensitive. Command names are lower-case, as are specified command arguments. Upper case letters may be used in file names or user-chosen ID strings.
Here is how each line in the input script is parsed by SPARTA:
(1) If the last printable character on the line is a “&” character (with no surrounding quotes), the command is assumed to continue on the next line. The next line is concatenated to the previous line by removing the “&” character and newline. This allows long commands to be continued across two or more lines.
Note
that a comment after a trailing “&” character will prevent the command from continuing on the next line. Also note that for multi-line commands a single leading “#” will comment out the entire command.
(3) The line is searched repeatedly for $ characters, which indicate variables that are replaced with a text string. See an exception in (6).
If the $ is followed by curly brackets, then the variable name is the text inside the curly brackets. If no curly brackets follow the $, then the variable name is the single character immediately following the $. Thus ${myTemp} and $x refer to variable names “myTemp” and “x”.
How the variable is converted to a text string depends on what style of variable it is; see the variable doc page for details. It can be a variable that stores multiple text strings, and return one of them. The returned text string can be multiple “words” (space separated) which will then be interpreted as multiple arguments in the input command. The variable can also store a numeric formula which will be evaluated and its numeric result returned as a string.
As a special case, if the $ is followed by parenthesis, then the text inside the parenthesis is treated as an “immediate” variable and evaluated as an equal-style variable. This is a way to use numeric formulas in an input script without having to assign them to variable names. For example, these 3 input script lines:
variable X equal (xlo+xhi)/2+sqrt(v_area)
region 1 block $X 2 INF INF EDGE EDGE
variable X delete
can be replaced by
region 1 block $((xlo+xhi)/2+sqrt(v_area)) 2 INF INF EDGE EDGE
so that you do not have to define (or discard) a temporary variable X.
Note
that neither the curly-bracket or immediate form of variables can contain nested $ characters for other variables to substitute for. Thus you cannot do this:
variable a equal 2
variable b2 equal 4
print "B2 = $\{b$a\}"
Nor can you specify this $($x-1.0) for an immediate variable, but you could use $(v_x-1.0), since the latter is valid syntax for an equal-style variable.
See the variable command for more details of how strings are assigned to variables and evaluated, and how they can be used in input script commands.
Note
that words can thus contain letters, digits, underscores, or punctuation characters.
(5) The first word is the command name. All successive words in the line are arguments.
(6) If you want text with spaces to be treated as a single argument, it can be enclosed in either single (’) or double (”) or triple quotes (“””). A long single argument enclosed in single or double quotes can span multiple lines if the “&” character is used, as described above. When the lines are concatenated together by SPARTA (and the “&” characters and line breaks removed), the combined text will become a single line. If you want multiple lines of an argument to retain their line breaks, the text can be enclosed in triple quotes, in which case “&” characters are not needed and do not function as line continuation character.
For example:
print “Volume = $v” print ‘Volume = $v’ print “”” System volume = $v System temperature = $t “”” variable a string “red green blue &
purple orange cyan”
if “$*steps* > 1000” then quit
In each of these cases, the single, double, or triple quotes are removed and the enclosed text stored internally as a single argument.
See the dump modify format, print, if, or python commands for examples.
A “#” or “$” character that is between quotes will not be treated as a comment indicator in (2) or substituted for as a variable in (3).
Important
If the argument is itself a command that requires a quoted argument (e.g. using a print command as part of an if or run every command), then single, double, or triple quotes can be nested in the usual manner. See the doc pages for those commands for examples. Only one of level of nesting is allowed, but that should be sufficient for most use cases.
3.3. Input script structure
This section describes the structure of a typical SPARTA input script. The “examples” directory in the SPARTA distribution contains sample input scripts; the corresponding problems are discussed in Section 5, and animated on the SPARTA WWW Site.
A SPARTA input script typically has 4 parts:
Initialization
Problem definition
Settings
Run a simulation
The last 2 parts can be repeated as many times as desired. I.e. run a simulation, change some settings, run some more, etc. Each of the 4 parts is now described in more detail. Remember that almost all the commands need only be used if a non-default value is desired.
Initialization
Set parameters that need to be defined before the simulation domain, particles, grid cells, and surfaces are defined.
Relevant commands include dimension, units, and seed.
Problem definition
These items must be defined before running a SPARTA calculation, and typically in this order:
create_box for the simulation box
create_grid or read_grid for grid cells
read_surf or read_isurf for surfaces
species for particle species properties
create_particles for particles
The first two are required. Surfaces are optional. Particles are also optional in the setup stage, since they can be added as the simulation runs.
The system can also be load-balanced after the grid and/or particles are defined in the setup stage using the balance_grid command. The grid can also be adapted before or betwee simulations using the adapt_grid command.
Settings
Once the problem geometry, grid cells, surfaces, and particles are defined, a variety of settings can be specified, which include simulation parameters, output options, etc.
Commands that do this include
global timestep collide for a collision model react for a chemisty model fix for boundary conditions, time-averaging, load-balancing, etc compute for diagnostic computations stats_style for screen output dump for snapshots of particle, grid, and surface info dump image for on-the-fly images of the simulation
Run a simulation
A simulation is run using the run command.
3.4. Commands listed by category
This section lists many SPARTA commands, grouped by category. The next section lists all commands alphabetically.
Initialization:
dimension, package, seed, suffix, units
Problem definition:
boundary, bound_modify, create_box, create_grid, create_particles, mixture, read_grid, read_isurf, read_particles, read_surf, read_restart, species,
Settings:
collide, collide_modify, compute, fix, global, react, react_modify, region, surf_collide, surf_modify, surf_react, timestep, uncompute, unfix
Output:
dump, dump_image, dump_modify, restart, stats, stats_modify, stats_style, undump, write_grid, write_isurf, write_surf, write_restart
Actions:
adapt_grid, balance_grid, run, scale_particles
Miscellaneous:
clear, echo, if, include, jump, label, log, next, partition, print, python, quit, shell, variable
3.5. Individual commands
This section lists all SPARTA commands alphabetically, with a separate listing below of styles within certain commands. The previous section lists many of the same commands, grouped by category.
3.6. Fix styles
See the fix command for one-line descriptions of each style or click on the style itself for a full description. Some of the styles have accelerated versions, which can be used if SPARTA is built with the appropriate accelerated package. This is indicated by additional letters in parenthesis: k = KOKKOS.
3.7. Compute styles
See the compute command for one-line descriptions of each style or click on the style itself for a full description. Some of the styles have accelerated versions, which can be used if SPARTA is built with the appropriate accelerated package. This is indicated by additional letters in parenthesis: k = KOKKOS.
3.8. Collide styles
See the collide command for details of each style. Some of the styles have accelerated versions, which can be used if SPARTA is built with the appropriate accelerated package. This is indicated by additional letters in parenthesis: k = KOKKOS.
3.9. Surface collide styles
See the surf_collide command for details of each style. Some of the styles have accelerated versions, which can be used if SPARTA is built with the appropriate accelerated package. This is indicated by additional letters in parenthesis: k = KOKKOS.
3.10. Surface reaction styles
See the surf_react command for details of each style. Some of the styles have accelerated versions, which can be used if SPARTA is built with the appropriate accelerated package. This is indicated by additional letters in parenthesis: k = KOKKOS.