This section describes how a SPPARKS input script is formatted and what commands are used to define a simulation.
3.1 SPPARKS input scriptSPPARKS executes by reading commands from a input script (text file), one line at a time. When the input script ends, SPPARKS exits. Each command causes SPPARKS 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) SPPARKS 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:
count ligand 10000 run 100 run 100
does something different than this sequence:
run 100 count ligand 10000 run 100
In the first case, the count of ligand molecules is set to 10000 before the first simulation and whatever the count becomes will be used as input for the second simulation. In the 2nd case, the default count of 0 is used for the 1st simulation and then the count is set to 10000 molecules before the second simulation.
(2) Some commands are only valid when they follow other commands. For example you cannot set the count of a molecular species until the add_species command has been used to define that species.
(3) Sometimes command B will use values that can be set by command A. This means command A must precede command B in the input script if it is to have the desired effect.
(4) Some commands are only used by a specific application(s).
Many input script errors are detected by SPPARKS and an ERROR or WARNING message is printed. This section gives more information on what errors mean. The documentation for each command lists restrictions on how the command can be used.
Each non-blank line in the input script is treated as a command. SPPARKS 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 SPPARKS:
(1) If the line ends with a "&" character (with no trailing whitespace), 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 are treated as comment and discarded.
(3) The line is searched repeatedly for $ characters which indicate variables that are replaced with a text string. 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 character immediately following the $. Thus ${myTemp} and $x refer to variable names "myTemp" and "x". See the variable command for details of how strings are assigned to variables and how they are substituted for in input scripts.
(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) Text with spaces can be enclosed in double quotes so it will be treated as a single argument. See the dump modify or fix print commands for examples. A '#' or '$' character that in text between double quotes will not be treated as a comment or substituted for as a variable.
This section describes the structure of a typical SPPARKS input script. The "examples" directory in the SPPARKS distribution contains sample input scripts; the corresponding problems are discussed in this section, and some are animated on the SPPARKS website.
A SPPARKS input script typically has 3 parts:
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 3 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) Choice of application, solver, sweep method
Use the app_style, solve_style, and sweep commands to setup the kind of simulation you wish to run. Note that sweeping is only relevant to applications that define a geometric lattice of event sites and only if you wish to perform rejection kinetic Monte Carlo updates.
(2) Settings
Parameters for a simulation can be defined by application-specific commands or by generic commands that are common to many kinds of applications. See the doc pages for individual applications for information on the former. Examples of the latter are the stats and temperature commands.
The diag_style command can also be used to setup various diagnostic computations to perform during a simulation.
(3) Run a simulation
A kinetic or Metropolis Monte Carlo simulation is performed using the run command.
This section lists all SPPARKS commands, grouped by category. The next section lists the same commands alphabetically. Note that some commands are only usable with certain applications. Also, some style options for some commands are part of specific SPPARKS packages, which means they cannot be used unless the package was included when SPPARKS was built. Not all packages are included in a default SPPARKS build. These dependencies are listed as Restrictions in the command's documentation.
Initialization commands:
app_style, create_box, create_sites, processors, read_sites, region, solve_style
Setting commands:
dimension, boundary, lattice, pair_coeff, pair_style, reset_time, sector, seed, sweep, set
Application-specific commands:
add_reaction, add_species, barrier, count, deposition, ecoord, inclusion, pin, temperature, volume
Output commands:
diag_style, dump, dump image, dump_modify, dump_one, stats, undump
Actions:
run,
Miscellaneous:
clear, echo, if, include, jump, label, log, next, print, shell, variable
This section lists all SPPARKS commands alphabetically, with a separate listing below of styles within certain commands. The previous section lists the same commands, grouped by category. Note that commands which are only usable with certain applications are listed in the next section.
Application-specific commands. These are commands defined only for use by one or more applications. See the command doc page for details. See the various app_style commands in the next section for a listing of all the commands defined for individual applications.
Application styles. See the app_style command for one-line descriptions of each style or click on the style itself for a full description:
Solve styles. See the solve_style command for one-line descriptions of each style or click on the style itself for a full description:
Pair styles. See the pair_style command for one-line descriptions of each style or click on the style itself for a full description:
Diagnostic styles. See the diag_style command for one-line descriptions of each style or click on the style itself for a full description: