Input Script

This section describes how an Aspherix® Calibration input script is formatted and the input script commands used to define a calibration workflow.

Parsing rules 

Aspherix® Calibration calibration setups are described using an input script in text format, which usually named aspherix-calibration.casx (note, the file extension casx is not a requirement).

Parsing rules for an input script are very similar to those of Aspherix®. A command consists of a command_name, a command_id, and multiple keyword-value groups in the form

command_name command_id keyword_1 value_1 keyword_2 value_2 ...

The number of spaces or tabs between the components of a command does not matter, neither does leading or trailing whitespace. The order of the keywords is usually irrelevant (documented if otherwise).

Aspherix® Calibration expects a single command per line. Everything after the # character is ignored. A line can be continued using the & character.

this is a command # with a comment

this is a command & # with a comment
    and multiple lines

these are &

two separate commands

Note that a blank or commented line ends the current command. So, if in the following command you do not want to set bar, commenting it out will not cause the following lines to be added to the command.

some command &
    foo 1 &
    # bar 3.14 &
    baz 42 &
    asdf 'yyz'

is equivalent to the two commands

some command foo 1
baz 42 asdf 'yyz'

In order to treat the above like it still is a single command, use the following:

some command &
    foo 1 &
    &# bar 3.14 &
    baz 42 &
    asdf 'yyz'

which will translate into

some command foo 1 baz 42 asdf 'yyz'

Variables 

Aspherix® Calibration supports the definition of string variables. To define a variable, use

variable varName string varString

Variable names can only contain letters, numbers and the underscore, and need to start with a letter. Currently, variables can only store strings without whitespace. Note that a string can also be a number, so a variable can be used to set a parameter on various places throughout the input script, e.g.,

variable normal_contact_model string hertz
variable density string 2500
variable young string 1e8

The value of a variable can be accessed by enclosing the variable name in curly brakets and preposing the dollar symbol, e.g.,

param_fixed Y_p type scalar value ${young}

Given a certain command including variables, comments and line continuations, the following operations are performed before its execution:

comments are removed
lines are patched together
the variable values are replaced
the command is executed

Currently, it is not possible to redefine variables. Aspherix® Calibration will throw an error if a variable name is used twice.

Multiple variables can also be specified using -var command-line arguments:

aspherix-calibration run -in aspherix-calibration.casx -var density string 2500 -var young string 1e8

Material parameters 

Material parameters can be either fixed or subject to calibration. The former are given by the param_fixed command, while the latter are defined via param_calibration command. Furthermore, param_tracking can be set up to track another parameter in a calibration. Any material parameter can be used as either fixed or calibration parameter. The common material parameters required by a calibration template can be found here, while more specific ones can be found in the template individual documentations.

`param_fixed` command

This command defines a material parameter that is kept constant throughout the calibration run. A fixed parameter is defined as

param_fixed param_name value param_value type param_type

where param_name is the name of the parameter, param_value is its value, type is a keyword and param_type has to be set to scalar, as for the moment is only possible to specify scalar parameters.

`param_calibration` command

This command defines a material parameter that changes value during optimization. An initial, a minimum and a maximum value need to be specified. A calibration parameter is defined as

param_calibration param_name type param_type min min_value max max_value init init_value

where min, max and init are keywords, and min_value, max_value and init_value are corresponding values. It is required that min_value < init_value < max_value. param_type can be either linear or log. The former varies the parameter linearly during optimization, while the latter uses a logarithmic scaling. This is useful if max_value is several orders of magnitude larger than min_value.

Note

The init parameter is only used during the initialization stage of a calibration (eg. particle insertion, bed creation - depending on the template). The paramter value for the first iteration is already chosen by the optimizer, and cannot be controlled by the user.

`param_tracking` command

This command defines a material parameter that tracks a param_calibration. This is useful to reduce the dimensionality of a calibration, eg. to keep the sliding and rolling friction coefficient the same if both are independent target parameters.

Warning

Do not use param_tracking as target_param in your calibration_case!

param_tracking param_name reference ref_param_name [factor factor_val] [offset offset_val] [poly a_0 a_1 ... a_n]

The value of a param_tracking is always computed from its reference parameter ref_param_name. In the simplest case, the values are identical:

param_calibration calib type linear min 0 max 1 init 0.5
param_tracking track reference calib

The value can also be changed via the factor, offset and poly keywords:

factor multiplies the reference value by a constant factor
offset adds a fixed value to the reference value
poly computes the value of the tracking parameter as a polynomial $a_0 + a_1 x + a_2 x^2 + \ldots$ . Coefficients are given in ascending order, and the degree of the polynomial is limited to 20.

Below are examples for these three options. Note that either offset and factor or poly can be used.

# calib*100
param_tracking track1 reference calib factor 100
# calib+3
param_tracking track1 reference calib offset 3
# 100*calib+3
param_tracking track1 reference calib offset 3 factor 100
# 3*calib^2 + 2*calib + 1
param_tracking track1 reference calib poly 1 2 3

System settings 

`system_settings` command

All settings given in dalilama.conf for running Aspherix® Calibration in cluster mode can be overridden using the following command

system_setting setting_name setting_value

where setting_name and setting_value are the name and value of the setting to be overridden, e.g.,

system_setting maxConcurrentEval 2

Case setup 

`particle_template` command

The particle_template command allows to define a particle template.

particle_template template-ID shape template-shape [other kw/value pairs depending on template-shape]

template-ID = ID assigned to the particle template
template-shape = shape of the particles. Currently implemented: sphere and multisphere

shape `sphere`

defines a spherical particle template

additional keyword/value combinations:

radius = radius of the spherical particle in m

example:

particle_template mySphere shape sphere radius 0.02

shape `multisphere`

defines a multisphere particle template

additional keyword/value combinations:

file = path to the multisphere definition file
scale = scale factor for the template - must be > 0

If the path to the multisphere file is given as a relative path, it is assumed to be relative to the directory aspherix-calibration is executed in. The format for the multisphere definition file is described here

example:

particle_template multi shape multisphere file my_ms.txt scale 0.01

`particle_distribution` command

defines a particle distribution to be used in calibrations.

particle_distribution dist-ID templates [template-IDs] mass_fractions [mass-fractions]

dist-ID = user-assigned name for the particle distribution
template-IDs = IDs of one or multiple particle_template command commands
mass-fractions = mass fractios for each of the particle templates pased to this command

This command defines a particle distribution to be used in the calibration simulations. The distribution is created from the templates, which are combined according to the mass fractions given in the command. Obviously, this implies that the number of particle templates and mass fractions need to be equal.

Warning

when the new style of the particle_distribution command is used, a parameter (either param_fixed command or param_calibration command) with ID rho_p needs to be defined. This is used as the particle density, for example

param_fixed rho_p type scalar value 7200
param_calibration rho_p type linear init 1300 min 1000 max 2000

Warning

current restrictions:

for particle shape multisphere, only one template can be used
templates of shapes multisphere and sphere cannot be mixed.

example:

particle_distribution p templates p1 mass_fractions 1

`particle_distribution` command (legacy)

Warning

This particle_distribution command structure is deprecated, please use the new combination of particle_template and particle_distribution.

This is the legacy version of the particle_distribution command. It sets the particle density and the particle size distribution to be used for the simulation. The command syntax reads as follows:

particle_distribution dist-ID density rho radius r1 r2 ... rM mass_fraction mf1 mf2 ... mfM

dist-ID = user-assigned name for the command call
density = obligatory keyword
rho = density of the particle material
radius = obligatory keyword
r1 r2 … rN = M radii of the size distribution
mass_fraction = obligatory keyword
mf1 mf2 ... mfN = M mass fraction of the size distribution

Here follows an example of command usage:

particle_distribution p density 2500 radius 0.001 0.002 0.003 mass_fraction 0.1 0.2 0.7

This command defines a particle mixture consisting for 10% of its mass of particles with radius 0.001 m, for 20% of particles with radius 0.002 m, and for 70% of particles with radius 0.003 m. The density is equal for all three components. If the mass fractions do not add up to one, the distribution is normalized so that the sum is equal to one.

`calibration_case` command

A simulation case is defined via the calibration_case command using the following syntax:

calibration_case case-ID template template-ID type case_type target_param par1 par2 ... parN measfile filename dem_timestep ts_value parameter_overrides keyword value

case-ID = user-assigned name for the command call (it needs to be unique across all the calibration_case commands)
template = obligatory keyword
template-ID = name of a calibration template
type = obligatory keyword
case_type = either Aspherix or CFDEM
target_param = obligatory keyword
par1 par2 … parN = a space-separated list of target parameters. These are varied during the optimization run
measfile = obligatory keyword
filename = path to a file containing the experimental reference values. The content of this file depends on the chosen calibration template
dem_timestep = optional keyword
dem_timestep = value of DEM timestep - overrides default value computed by Aspherix® Calibration.
parameter_overrides = optional keyword
keyword value = name and value of template parameters that need to be overwritten. Multiple name/value pairs can be appended

Here follows an example of command usage:

calibration_case test1 template inclinedWall type Aspherix target_param c_rollFrict_pw  &
    measfile measurements/dummy.txt parameter_overrides                                 &
    targetAngle 22 nParticles 2000 dumpT 0.1

note that nParticles, dumpT and targetAngle are parameters defined in the template inclinedWall (see Standard parameters and inclinedWall template) and their default values are 30, 1000 and 0.01. By using the keyword parameter_overrides, it is possible to set them to arbitrary values.

Note

Calibration cases will be executed in lexical order of their IDs.

Run settings 

`run` command

An input script has to contain a single run command

run run_type

where run_type can be

single : run a single calibration where all target parameters are calibrated in one multidimensional calibration
sequential : one run per target parameter; each run will use the calibrated values for already calibrated values, and the value provided as init for the parameters not yet calibrated.

The run mode specified in the input script can be overridden using the command-line argument -run-mode (see command-line arguments for more information).

Let us consider the following example:

[...]

calibration_case a template inclinedWall type Aspherix target_param c_rollFrict_pw          &
    measfile measurements/dummy.txt parameter_overrides [...]

calibration_case b template staticAngleOfRepose type Aspherix target_param c_rollFrict_pp   &
    measfile measurements/staticAngleOfRepose.txt parameter_overrides [...]

calibration_case c template shearCellSchulzePeriodic type Aspherix target_param c_frict_pp  &
    measfile measurements/ultimateShear.txt parameter_overrides [...]

run sequential

In this case, the three calibrations are performed in sequence and the order is prescribed by the ID of the case (i.e., a, b and c). After the calibration case a is over, the calibrated parameter c_rollFrict_pw is used for running the second calibration case b. The last calibration case to be run, c, uses as input the calibrated values of c_rollFrict_pw and c_rollFrict_pp. The order in which the calibration cases are run might change the result, as in general a calibration case might be sensitive to different target parameters (e.g., the static angle of repose depends on the particle-particle rolling friction and, although to a less extent, on the particle-particle static friction). By setting the run command to single, the three cases are merged into a single multidimensional calibration, which can be run in parallel by specifing -ncases 3 as command-line argument.

Warning

with run sequential, it is not possible to

use calibration_case with multiple target parameters
use multiple calibration_case targeting the same parameters

Aspherix® Calibration will issue an error message in either case.

`optimizer_setting` command

The behaviour of the optimizer of Aspherix® Calibration can be controlled through the optimizer_setting command

optimizer_setting keyword value

where keyword can be

maxFunctionEval : expects an integer as value. Sets a soft limit for the number of simulation iterations performed during an optimization. Default value: 100. Due to some internal mechanisms of the optimizing algorithm, the number defined here can be slightly exceeded.
maxSplitPerDim : expects an integer as value. Sets a maximum depth for the optimization algorithm. During optimization, the parameter space is split recursively in all dimensions to find the best parameter set. Default value: 4 (equivalent to a variation of 1.2% of the parameter range). Decrease to only scan the parameter space. Increase when using large parameter spaces with log scaling.

Input Script

Parsing rules

Variables

Material parameters

param_fixed command

param_calibration command

param_tracking command

System settings

system_settings command

Case setup

particle_template command

shape sphere

shape multisphere

particle_distribution command

particle_distribution command (legacy)

calibration_case command

Run settings

run command

optimizer_setting command

Parsing rules 

Variables 

Material parameters 

`param_fixed` command

`param_calibration` command

`param_tracking` command

System settings 

`system_settings` command

Case setup 

`particle_template` command

shape `sphere`

shape `multisphere`

`particle_distribution` command

`particle_distribution` command (legacy)

`calibration_case` command

Run settings 

`run` command

`optimizer_setting` command