Adding User Templates

This section explains how to create a user-defined Calibration template. Additional information can be found in this tutorial.

Directory Setup

It is possible to add user templates to Aspherix® Calibration. The following is an outline of the procedure to do so.

First, it is necessary to supply the template directory to Aspherix® Calibration. This can be achieved in multiple ways:

via the command line switch -user-template-dir
by adding a setting userTemplateDir path/to/templates in dalilama.conf or a config file supplied via -user-config-file
in the Aspherix® Calibration input script through system_setting userTemplateDir path/to/templates

It is currently only possible to provide a single directory, however that directory can contain multiple simulation templates. The template directory is required to have the following structure:

userTemplateDir
  - Aspherix
    - asx_template1
    - asx_template2
    - ....
  - CFDEM
    - cfdem_template1
    - cfdem_template2
    - ...
  - Python
    - python_template1
    - python_template2
    - ...

and the templates can be used in calibrations by using the subdirectory name as template name, for example

calibration_case id asx asx_template1 type Aspherix [...]
calibration_case id py python_template2 type Python [...]

Warning

If a user provided template has the same template name as one that is already present in Aspherix® Calibration, Aspherix® Calibration will ignore the user provided template and load the template provided with the software.

General Structure for an Aspherix® Template

The calibration has two phases: initialization and simulation cycle. The former can be used to prepare a state, eg. in form of a restart file, for the latter to start. For Aspherix simulations, this usually means that two input scripts are necessary. The CFDEMcoupling case is more complex, and will be added to this document in the future. Furthermore, there are two shell scripts, usually named runInit.sh and runSimCycle.sh, which are used to run the two phases, provided runMode shellScript is used in the case.conf.

case.conf

The case.conf file for the new template needs to contain several settings, which are listed below:

setting name	meaning
scaleweight	scaling factor for the quality function; only relevant in case of multiple calibration cases
pairGranModel	Granular contact model
pairTangential	tangential model
pairCohesion	cohesion model
pairRollingFriction	rolling friction model
pairSurface	surface model (usually ‘default’)
dumpT	Dump interval in seconds
dump	0: no dump; 1: LAMMPS-style text dump; 2: vtk dump

In addition, any name/value combination provided in case.conf is available as variable in Aspherix, and can be overwritten from the input script using the parameter_overrides keyword of the calibration_case command. Setting any of the settings in case.conf to *undefined* (exact string) forces the user to provide a value for this setting in the input script.

Warning

Only settings present in case.conf can be overwritten in the input script. The attempt to add a nonexisting setting in parameter_overrides will result in an error.

Variable Includes

To get the variables from case.conf and others such as the DEM timestep into the input script, use the following commands:

include_foam_variables caseVariables
include_foam_variables ../../../temp/optimVariables

for the init script and

include_foam_variables caseVariables
include_foam_variables ../../optimVariables

for the run script.

Particle Distribution

The particle distribution is provided by Aspherix® Calibration, and written to the file aspherixPartDist.txt, which has to be included in the input scripts with the command

include aspherixPartDist.txt

The particle distribution fix for use in insertion commands has the id pdd1 and the particle material name is particle.

Quality Function

There are two methods to define a quality function for a user-defined template:

Use an already existing quality function

For the templates shipped with Aspherix® Calibration, a quality function is implemented. If your custom template only makes minor modifications (eg. changing a geometry) to one of the existing templates without changing the output it produces, then it makes sense to reuse that template’s quality function. To do so, add the line:
```
qualityFcnType [nameOfQualityFunction]
```
to your custom template’s case.conf. The name of the quality function is identical to the original template. So, to use the implemented quality function for staticAngleOfRepose, the line:
```
qualityFcnType staticAngleOfRepose
```
is required. The details of the implemented quality functions are not (yet) documented. However, their input requirements can be determined from the input scripts of the templates shipped with Aspherix® Calibration: simply check which output is generated from the cases, and recreate it in your custom template.
Create the quality function yourself.

This is the fallback option if no quality function is provided. A quality function can be computed either directly from the template input script, or through the use of external tools/scripts, such as pyhton or GNU octave. Regardless of how computation of the quality function is achieved, Aspherix® Calibration expects a file called Fun.txt. This file is expected to contain exactly one floating point number in plain text, which will be interpreted as quality function.

Note

If no quality function is set, Aspherix® Calibration will issue a warning that it defaults to reading Fun.txt. This is exactly what you want when creating your own quality function, and the warning can be ignored in that case.

Python

Since Aspherix® Calibration 6.1.0, it is possible to use python scripts as calibration templates. This is showcased in the example examples/calibration/Tutorials_public/pythonTemplate in your Aspherix® installation folder. The main procedure to add a template is very similar to adding an Aspherix® solver case. However, since a python script is not necessarily a full simulation, there are fewer restrictions.

case.conf

The case.conf file for the new template needs to contain several settings, which are listed below:

setting name	meaning
scaleweight	scaling factor for the quality function; only relevant in case of multiple calibration cases
initPythonScript	python script to be executed during the init phase
runPythonScript	python script to be executed during the run phase

Other settings can be added to configure the case. They are then available in the caseVariables file.

Variable Includes

The paths of the variable files are the same as for Aspherix® Solver. They just need to be parsed manually, for example with the following code, which returns a dictionary:

import re
def readFileToDict(fname):
    ret = {}
    with open(fname) as f:
        for line in f:
            m = re.match("([a-zA-Z0-9_]+) ([^;]+);", line);
            if m:
                ret[m.group(1)] = m.group(2)
    return ret;

# use as follows in the code:
caseVariables = readFileToDict("caseVariables")

Quality Function

Python templates always require a file Fun.txt to be written, eg. like the following:

# calculate quality function
qf = ...

# Apherix Calibration requires a file "Fun.txt" that contains a single number and nothing else                                                                                      with open("Fun.txt", "w") as f:
    f.write("{}".format(qf));