Getting Started

This section describes how to run Aspherix® Calibration, for both new and experienced users.

Running Aspherix® Calibration

The Aspherix® Calibration executable is called aspherix-calibration. A calibration setup defined in a file aspherix-calibration.casx is executed with the command

aspherix-calibration run -in aspherix-calibration.casx

Depending on which run mode is given in the input script, Aspherix® Calibration creates either a single subdirectory calibration/ or several subdirectories named calibration_param_name. In either case, the calibrated parameters are found in the file calibrated_params.txt in the directory where Aspherix® Calibration is executed. The input script is copied to current_aspherix_calibration.casx to allow for backup later.

If there are traces of a previous calibration, Aspherix® Calibration will issue an error message and stop. This is to prevent the user from overwriting results. To remove the old calibration, run

aspherix-calibration clean

This will remove all calibration* directories and move the results file to calibrated_params.bak. The file current_aspherix_calibration.casx is also moved to current_aspherix_calibration.casx.bak. An old logfile is moved to log_aspherix-calibration.txt.bak anyway. Alternatively, you can add the -force flag to your run command.

Note

By default, Aspherix® Calibration will use the Aspherix®Solver located in the installation folder (e.g. for Linux, ~/DCS-Computing/Aspherix-7.1/bin/aspherix). In certain circumstances, the user might need to change the path of the Aspherix® solver used by Aspherix® Calibration. In this case, the following configuration command should be used:

aspherix-calibration configure -aspherix-binary <arg0> -configuration <arg1>

where <arg0> denotes the path to the Aspherix® solver executable and <arg1> can be either user or system.

Alternatively, the new settings can be specified via the run command as follows:

run -in aspherix-calibration.casx -aspherix-binary <arg0> -configuration <arg1>

Each solution updates permanently the settings.

Command-line options

At run time, Aspherix® Calibration recognizes several command-line arguments.

  • run: runs a calibration. It must or can be followed by the arguments:

    • -in <arg>: speciefies the name of the input file for the run (mandatory argument).

    • -np <arg>: specifies the number of processors used for running in parallel each calibration case. Note that this argument has the precedence over the number of processors specified in input script via the NPROC.

    • -run-mode <arg>: overrides the run setting in the input script. The available modes are single and sequential.

    • -ncases <arg>: specifies the number of calibration cases to be run in parallel when -run-mode single. Each calibration case uses n_p processors (see -np argument); hence, the total number of processors that will be required is n_{tot} = n_p n_{cases}.

    • -restart: attempts to resume a previously aborted calibration run. It cannot be used together with -force. More information can be found in restart section.

    • -init-only: runs only the initialization step of all calibration cases.

    • -use-init : skips the initialization step and uses previously initialized simulation. More on the usage of these two switches can be found in restart section.

    • -backup-old: copies a preexisting calibration to a subfolder named “backup/<timestamp>”. It must be used together with the -force flag.

  • cluster_run: runs a calibration using a cluster queuing system. It must or can be followed by the arguments:

    • -in <arg>: speciefies the name of the input file for the run (mandatory argument)

    • -init: initializes the calibration and submits the first job to the queue

  • run and cluster_run can be followed by the arguments:

    • -force: force deletion of old calibration results. It is equivalent to running aspherix-calibration clean; aspherix-calibration run.

    • -user-template-dir <arg>: adds an additional directory for simulation templates. Only one template directory can be added, but this directory can contain multiple Aspherix® and/or CFDEM®coupling templates. See user templates for more details.

    • -var <arg>: creates a variable, just like the variable command. For example, to declare a string variable, use -var myVar string mvVarValue. A call to aspherix-calibration can contain multiple -var command line arguments.

    • -debug: write additional debug information to log_aspherix-calibration.txt.

    • -help: shows an help message and exits. It cannot be used together with another command.

    • -version: prints the version number and exits. It cannot be used together with another command.

  • configure: save to file the desired configuration and exists after doing so. It can be followed by the arguments:

    • -license-path <arg>: sets path to the license file.

    • -demo-password <arg>: sets password for a demo license.

    • -configuration <arg>: stores the configuration at user or system level; hence, <arg> can be user or system (mandatory argument).

    • -aspherix-binary <arg>: sets the path to the Aspherix® solver binary.

    • -mpi-binary <arg>: specifies the mpi executable (default: mpirun).

    • -mpi-arguments <arg0> ... <argN>: adds arguments for the mpi executable (default: –bind-to none).

    • Note: these arguments can also be used after run and cluster_run.

  • clean: removes old calibration results from current work directory.

  • -skip-qf-check true: allow calibrations that have the quality function defined in the Aspherix solver input scripts.

  • extract_templates: unzip the calibration templates contained in the file Aspherix-X.Y.Z/share/aspherix_calibration/templates/templates.zip into the folder Aspherix-X.Y.Z/share/aspherix_calibration/templates. In case the latter contains already the folders Aspherix and CFDEM, please append the argument -update to overwrite them.

Output

Aspherix® Calibration writes status output of the calibration to stdout, and to log_aspherix-calibration.txt. Simulation output is suppressed and written to log files located in calibration/workDir/workDir.x/path/to/case/. If a logfile exists on startup, it is moved to log._aspherix-calibration.txt.bak.

The current best parameter set is always written to the file calibrated_params.txt in the calibration root directory. Additionally, two files are written to calibration/results: qf_history.dat contains all parameter sets and the quality functions obtained with them, and conv.dat contains the “convergence” of the algorithm: whenever a quality function is found to be the current best, it is written to conv.dat.` For setups with more than one template, both files also contain the unscaled quality functions of each individual test.

Directory structure

The Aspherix® Calibration contents are located in the following subfolders of the Aspherix® installation directory:

  • bin/: contains the aspherix-calibration binary

  • share/aspherix_calibration/etc/: contains setting files for Aspherix® Calibration

  • share/aspherix_calibration/templates/: contains the calibration case templates

  • share/aspherix_calibration/scripts/: contains some additional scripts required to run the calibration

  • examples/calibration/: contains some tutorials, which partial documentation can be found here

  • documentation/calibration/: contains this documentation