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 Errors 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, 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.

2. All characters from the first # character onward until a newline are treated as comment and discarded. See an exception in (6). 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 command 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.

4. The line is broken into “words” separated by whitespace (tabs, spaces). 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 double or single quotes. A long single argument enclosed in quotes can even span multiple lines if the & character is used, as described above. E.g.

   print "Volume = $v"
   print 'Volume = $v'
   variable a string "red green blue &
                      purple orange cyan"
   if "$steps > 1000" then quit
   

   The quotes are removed when the single argument is stored internally.

   See the dump modify format or print command, or if command 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 command or run every command), then the double and single quotes can be nested in the usual manner. See the doc pages for those commands for examples. Only one 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 Example problems, and animated on the SPARTA WWW Site.

A SPARTA input script typically has 4 parts:

1. Initialization
2. Problem definition
3. Settings
4. 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.

1. Initialization

   Set parameters that need to be defined before the simulation domain, particles, grid cells, and surfaces are defined.

   Relevant commands include dimension command units command, and seed command.

2. 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 between simulations using the adapt_grid command.

3. 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

4. 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, 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.

adapt_grid	balance_grid	boundary	bound_modify	clear	collide
collide_modify	compute	create_box	create_grid	create_particles	dimension
dump	dump image	dump_modify	dump movie	echo	fix
global	group	if	include	jump	label
log	mixture	move_surf	next	package	partition
print	quit	react	react_modify	read_grid	read_isurf
read_particles	read_restart	read_surf	region	remove_surf	reset_timestep
restart	run	scale_particles	seed	shell	species
stats	stats_modify	stats_style	suffix	surf_collide	surf_react
surf_modify	timestep	uncompute	undump	unfix	units
variable	write_grid	write_isurf	write_restart	write_surf

3.5.1. 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.

ablate	adapt (k)	ambipolar	ave/grid (k)	ave/histo (k)	ave/histo/weight (k)
ave/surf	ave/time	balance (k)	emit/face (k)	emit/face/file	emit/surf
grid/check (k)	move/surf (k)	print	vibmode

3.5.2. 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.

boundary (k)	count (k)	distsurf/grid (k)	eflux/grid (k)	fft/grid	grid (k)
isurf/grid	ke/particle (k)	lambda/grid (k)	pflux/grid (k)	property/grid (k)	react/boundary
react/surf	react/isurf/grid	reduce	sonine/grid (k)	surf (k)	thermal/grid (k)
temp (k)	tvib/grid

3.5.3. 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.

vss (k)

3.5.4. 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.

cll	diffuse (k)	impulsive
piston (k)	specular (k)	td
vanish (k)

3.5.5. Surface reaction styles

See the surf_react command for details of each style.

global

prob