Configuration Reference#

The abaci configuration file stores information about the project such as user subroutine and abaqus job file locations. There is typically one configuration file per user-subroutine per project.

Note

By default, abaci will look for a configuration file named abaci.toml in the current directory. Use the --config argument to specify an alternative, see Common Flags.

Configuration File Format#

The abaci configuration file uses the human-readable TOML format:

  • Lines beginning with an octothorp # are ignored

  • Configuration parameters are written in key = value format

  • Values can be:

    • numbers, e.g. pi = 3.141

    • strings denoted by quotes, e.g. name = 'test'

    • arrays of values denoted by square brackets, e.g. tags = ['test','default']

  • Parameters can optionally be grouped under unique sections denoted by square brackets, e.g. [section-name]

  • Non-unique (repeatable) sections form arrays and are denoted with double square brackets, e.g. [[job]]

See also

See https://toml.io for the full TOML specification.

Top-level fields#

Example:

name = 'project-name'
user-sub-file = 'usersub.f90'
output = 'scratch'
test-mod-dir = 'test'

name#

string, optional

Specifies the name of the project to uniquely identify it when used as a dependency for another abaci project.

Note

The name field is mandatory if the project is to be used as a dependency, otherwise it can be omitted.

user-sub-file#

string, mandatory

Specifies the filename of the abaqus user subroutine to compile.

  • The filename is relative to the folder containing the configuration file

output#

string, optional

Specifies the name of the directory into which compilation and job folders will be placed.

  • The output directory is either:

    • a relative path, relative to the current working directory or;

    • an absolute path

  • If omitted, the default output directory is a subdirectory called scratch in the current working directory

  • The output folder is created if it does not exist

test-mod-dir#

string, optional

Specifies the name of the directory in which test module files are stored.

  • The directory is relative to the folder containing the configuration file

  • If omitted, the default test module directory is test

See also

See the unit tests guide for how to structure and write unit tests for your Abaqus user subroutine.

Use the test subcommand to compile and run these test subroutines.

abq-flags#

string or [string,…], optional

String or list of strings specifying additional flags to pass to Abaqus when launching a job.

  • This top-level option applies to all jobs in the config file unless it has been overridden in the specification of the job

Jobs list#

Array of optional subsections that predefine specific abaqus jobs to run.

Example:

[[job]]
job-file = 'my-abaqus-job.inp'
name = 'job1'
tags = ['test','three_elem']
abq-flags = 'domains'
include = ['job1_extra_inputs.inp']
mp-mode = 'threads'
post-process = '{PY} {ROOT}/scripts/postprocess.py {ODB}'
cluster.mem-per-cpu = '8000M'
cluster.time = '1-00:00:00'

job-file#

string, mandatory

Specifies the path to the abaqus job file (*.inp).

  • Job file path is specified relative to the folder containing the configuration file

name#

string, optional

An unique name to reference this job in the job-spec at the command line.

tags#

string or [string,…], optional

An list of non-unique tags to reference groups of jobs in the job-spec at the command line.

abq-flags#

string or [string,…], optional

String or list of strings specifying additional flags to pass to Abaqus when launching a job.

  • This option overrides the top-level default for this job only

  • Use the top-level abq-flags option to set the default for all jobs

include#

string or [string,…], optional

An list of additional files to copy to the job folder before launching the job.

  • Include file paths are specified relative to the folder containing the configuration file

Note

Abaci will automatically detect and copy .inp files in the same folder as the job file - use the include field to specify other files that also need to be copied to the job folder for running the job.

mp-mode#

string, optional

An optional field taking the value of either 'threads' (default), 'mpi' or 'disable' to indicate the parallel mode to execute in abaqus (corresponds to the -mp_mode command line flag).

If mp-mode is 'disable', then the abaci command line option for multiple processors will be ignored for this job, it will always run in serial.

cluster.#

subsection, optional

Override the default options for submitting this job to a cluster via SLURM.

See cluster options below for more information on the cluster option fields.

See also

See the How-to guide for more information on how to setup and submit jobs to a SLURM cluster.

post-process#

string or [string,…], optional

An optional field specifying one or more post-processing commands to run once the job has completed.

Specify multiple commands as a list ( e.g. ['command_1.sh', 'command_2.sh']) where each command is run sequentially in order.

The field takes the form of a command to execute and allows certain variables to be used:

  • {PY} will be substituted with the correct abaqus python command

  • {ROOT} will be substituted with the path to the directory containing the abaci.toml configuration file; this allows you to specify the path to your postprocessing script relative to the repository root

  • {ODB} will be substituted with the path to the output database (.odb) file for this job

  • {DIR} will be substituted with the path to the output directory for this job

  • {JOB} will be substituted with the name of the job (without any extensions or paths)

  • {REF} will be substituted with the path to the check.reference file

  • {NAME} will be substituted with the job name file

See also

See the Post-processing Guide for more information on how to set up post-processing commands.

Note

You can run and rerun post-processing commands for completed jobs using the command abaci post <job-dir> where <job-dir> is the output directory for the abaci job that has completed.

check.#

subsection, optional

An optional group for detailing regression checks.

Example:

[[job]]
job-file = 'job.inp'
check.reference = 'reference-output.pkl'
check.steps = ['Step-1']
check.fields = ['SDV1','SDV2']
check.frames = 'last'
check.elements = 'all'

check.reference#

string, mandatory

Specifies the reference file to compare output against. This is a binary Python pickle file that contains data from a previous reference run. If the file does not exist, then it is created using the current run.

The following special variables can be used in this field:

  • {NCPU} will be substituted with the number of CPUs used to run the job

Note

It is recommended to include {NCPU} in check.reference when performing regression checks on multicore jobs due to unavoidable variations that occur between results produced with different numbers of CPUs

check.steps#

[string,…], mandatory

List of strings specifying Abaqus job steps for which to check output.

check.fields#

[string,…], mandatory

List of strings specifying Abaqus output field variables to check.

check.frames#

strings or [int,…], optional

Either a list of frame indices for which to perform checks or 'all' or 'last'.

If not specified, then 'last' is the default.

Compile section#

subsection, optional

An optional subsection that details compilation settings.

Example:

[compile]
fflags.windows = ''
fflags.linux = ''
cflags.windows = ''
cflags.linux = ''
lflags.windows = ''
lflags.linux = ''
compiletime-checks = false
include = ['extra-source.f90']
sources = ['cpp_functions.cpp']

fflags.windows / fflags.linux#

string or [string,…], optional

Extra compilation flags to pass to the fortran compiler.

  • Flags specified here are appended to the Abaqus defaults

cflags.windows / cflags.linux#

string or [string,…], optional

Extra compilation flags to pass to the c/c++ compiler (auxilliary sources only).

See also

See the how-to guide for more information on how to include C and C++ source files with your Abaqus user subroutines.

lflags.windows / lflags.linux#

string or [string,…], optional

Extra link flags to pass to the shared library linker.

  • Flags specified here are appended to the Abaqus defaults

opt-host#

boolean, optional

Whether to compile with host-specific optimisations (default: false). Disable if distributable binaries are required.

Note

Host-specific optimisations may provide additional speedup, however there are some known incompatibilities with using host-specific optimisation from newer Intel compilers due to how Abaqus vendors fixed versions of Intel shared libraries

See Intel Compiler Developer Guide: xHost for more information.

compiletime-checks#

boolean, optional

Whether to always perform strict compile-time checks.

See Intel Fortran Compiler Developer Guide: warn for more information on compile-time checks.

include#

string or [string,…], optional

String or list of strings specifying additional files that are included (with #include) in the user subroutine file.

Note

Abaci will automatically detect Fortran source files in the same directory as your main user subroutine file as include files - use the include field to specify source files in other folders that need to be included into your user subroutine.

  • Included file paths are specified relative to the folder containing the configuration file

  • File globbing is supported, e.g.: include = 'include/*.f'

  • Sources specified here are automatically made available to other projects that use your project as an Abaci dependency

sources#

string or [string,…], optional

String or list of strings specifying additional c/c++ source files that are to be compiled and linked with the main user subroutine file.

  • Included file paths are specified relative to the folder containing the configuration file

  • File globbing is supported, e.g.: sources = 'src/*.cpp'

  • Sources specified here are automatically compiled with other projects that use your project as an Abaci dependency

See also

See the how-to guide for more information on how to include C and C++ source files with your Abaqus user subroutines.

Cluster section#

subsection, optional

An optional subsection that details default values for submitting jobs to a cluster via SLURM.

Options specified in this section can be overridden on a per-job basis by providing them within each job table or by running the submit command interactively (--interactive).

Note

The multiprocessing mode (mp_mode) is specified separately on a per-job basis using the mp-mode job field.

Example:

[cluster]
account = 'aero01234'
time = '0-01:00:00'
nodes = 1
tasks-per-node = 14
cpus-per-task = 1
mem-per-cpu = '4000m'
email = 'ab12345@bristol.ac.uk'

See also

See the How-to guide for more information on how to setup and submit jobs to a SLURM cluster.

account#

string, optional

Specifies the project account code under which to submit the job.

If not specified, no account code is supplied to SLURM.

time#

string, optional

Specifies the maximum time limit to request for the job. Format: days-hours:minutes:seconds.

If not specified, default is 1 hour if not specified.

partition#

string, optional

Specifies the cluster partitiion to which to submit the job.

If not specified, default is to let SLURM choose the most appropriate partitiion.

nodes#

integer, optional

Specifies the number of nodes to request for the job. This option is only valid if mp-mode is 'mpi', otherwise it is ignored and set to 1.

If not specified, default is 1.

tasks-per-node#

integer, optional

Specifies the number of separate tasks to allocate per node for the job.

This option is only valid if mp-mode is 'mpi', otherwise it is ignored and set to 1.

If not specified, default is 1.

cpus-per-task#

integer, optional

Specifies the number of processors to allocate per task for the job.

This option is only valid if mp-mode is 'threads', otherwise it is ignored and set to 1.

mem-per-cpu#

string, optional

Specifies the amount of memory to request per CPU/task for theh job.

If not specified, default is '4000M' (4000 MB).

email#

string, optional

Specifies an email address to which to send job termination notifications.

If not specified, default is for no email notifications.

Dependency list#

subsection, optional

Array of optional subsections that specify third-party repositories from which to include additional source files.

Example:

[[dependency]]
name = 'demo-dependency'
git = 'git@github.com:BristolCompositesInstitute/demo-dep.git'
version = '<commit|tag>'

Note

The dependency must have an abaci.toml file in the repository root that specifies a project name and the include field in the [compile] subsection.

name#

string, mandatory

The name of the dependency used to uniquely identify it and organise its source files.

Caution

The name field must match the top-level name field in the corresponding abaci.toml file in the dependency repository.

To include source files from a dependency into your Fortran source, prefix the source file path with the dependency name, e.g.:

#include '<dependency-name>/source-file.f'

Hint

To view a list of available source files to include, run abaci show sources at the command line.

git#

string, mandatory

The remote url to the upstream git repository from which to fetch the dependency.

version#

string, mandatory

A commit hash or tag specifying the exact version to fetch from the upstream repository.

Note: Abaci will automatically refetch the dependency if this field changes.

Caution

It is possible to specify a branch name for version, however this is not recommended since the dependency is not ‘pinned’ to a specific snapshot; this can cause sudden breaking changes and prevents other users of your code from reproducing your configuration. If you specify a branch, then abaci will fetch the latest changes from the branch everytime it is run.