Input Script
This section describes how an Aspherix® input script is formatted and the input script commands used to define an Aspherix® simulation.
Aspherix® input script
Aspherix® executes by reading commands from an input script (text file), one line at a time. When the input script ends, Aspherix® exits. Each command causes Aspherix® 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) Aspherix® does not read your entire input script and then performs 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.
(2) Some commands are only valid when they follow other commands. For example, you cannot insert particles into the computational domain without having defined beforehand the particle distribution that you want to insert. In the same way, it is not possible to define a particle distribution without having defined beforehand the particle types, or templates, that you want to have in the distribution.
(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. For example, the read command initializes the system by setting up the simulation box and assigning particles to processors. If default values are not desired, the enable_loadbalancing and boundary_conditions commands need to be used before the read command to tell Aspherix® how to map processors to the simulation box.
Many input script errors are detected by Aspherix® 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.
Parsing rules
Each non-blank line in the input script is treated as a command. Aspherix® 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 Aspherix®:
(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.
(2) All characters from the first “#” character onward are treated as comment and discarded. See an exception in (6). To comment out a multi-line command, it is necessary to put a leading “#” at the beginning of every line spanned by the 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”.
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. E.g.
print "Volume = $v"
print 'Volume = $v'
write_to_file string "${dt} ${fx1} ${y1} ${z1}" title "# particle positions" file part1_pos.tx
if "$*steps* > 1000" then quit
The quotes are removed when the single argument is stored internally. See the print, write_to_file or if 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).
Warning
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 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.
Input script structure
This section describes the structure of a typical Aspherix® input script. Note that the “examples” directory in the Aspherix® distribution contains many sample input scripts that can be used as a reference. One of these, the chute wear test case, is reported at the end of this section.
An Aspherix® input script typically has 4 parts:
Initialization
Particle definition and insertion
Settings
Simulation run
The last two parts can be repeated as many times as desired, i.e. run a simulation, change some settings, run some more, etc. Note that most of the commands reported below are optional and should be invoked only to trigger a non-default behaviour (e.g., the units command should be used only to set non-SI units). Each one of the four parts is now described in more detail.
Initialization
Set parameters that need to be defined before particles are created or read from a file.
The relevant commands are units, enable_loadbalancing, boundary_conditions, and particle_shape.
If force-field parameters appear in the files that will be read, these commands tell Aspherix® what kinds of force fields are being used, e.g., particle_contact_model and wall_contact_model.
Solid (e.g., walls) and non-solid (e.g., insertion faces) geometries can be defined via STL meshes or primitive walls.
Particle definition and insertion
There are three ways to define particles in Aspherix®. Read them in from a data or restart file via the read command, create particles on a lattice using the define_lattice and create_particles command, or (most commonly) inserting them via the insertion command. The latter can insert particles as a pack or as a stream into the computational domain. Before the insertion command can be used, a particle distribution is built up using one or more particle templates.
Settings
Once particles are defined, a variety of settings can be specified: simulation parameters, output options, etc.
Material parameters and force-field coefficients are set by these commands: materials, material_properties, material_interaction_properties.
Various simulation parameters are set by these commands: neighbor_list, group, simulation_timestep, region, etc.
Various computations can be specified for execution during a simulation using the calculate, compute, compute_modify, and variable commands.
Output options are set by the output_settings, write_to_file, status, and write_restart commands.
Run a simulation
A simulation is run using the simulate command.
An example of Aspherix® input script
This input script describes a simulation where particles drop onto a chute and wear its surface.
# define the particle shape
particle_shape sphere
# define the computational domain
simulation_domain low (-0.5, -0.2, -0.4) high (0.1, 0.2, 0.15)
# define the particle skin factor
neighbor_list skin_size 0.002
# define the material properties
materials {m1}
material_properties m1 youngsModulus 5e6 poissonsRatio 0.45 coefficientRestitution 0.3 coefficientFriction 0.5 k_finnie 1 density 2500
# define the particle-particle contact model
particle_contact_model normal hertz tangential history
# define the DEM time-step
simulation_timestep 1e-5
enable_gravity
# load the module for computing the surface wearing
mesh_module wear id wear_model model finnie
# load two meshes: the chute geometry and the insertion face
mesh id cad file meshes/simple_chute.stl material m1 mesh_modules {wear_model} solid yes
mesh id inface file meshes/insertion_face.stl solid no
# define the particle-wall contact model
wall_contact_model normal hertz tangential history
# define two particle templates and the particle distribution
particle_template id smallParticles material m1 radius 1.5e-3
particle_template id largeParticles material m1 radius 2.5e-3
particle_distribution id pdd1 templates {smallParticles, largeParticles} fractions {0.3, 0.7}
# insert a stream of particles into the domain through the insertion face
insertion mode stream particle_distribution pdd1 target_particle_count 6000 massrate 0.1 insert_every_time 0.01 all_in no velocity constant (0, 0, -1) insertion_face inface
# define the output time intervals
write_output_timestep 0.002
write_to_terminal_timestep 0.01
# run one simulation time step
simulate time 1e-5
# output the particle and mesh data to files
output_settings meshes {cad}
# run the simulation up to one second
simulate target_time 1