Skip to main content
Version: v2.1.0

List of Options

CLI Usage

This documentation page is intended for the Command Line Interface (CLI). If you're new to DuneCopasi, we recommend starting with our Tutorials.

The simulator may be configured by passing a collection of key=value pair that change the behavior of the solver. These options may be passed via a configuration file with the DUNE ini file convention or by the command line --{key}={value}. Note that command line arguments take precedence over the config file parameters.

Superfluous keys

Unknown keys will be ignored: This means that typos will silently be passed through the configuration options without any error!

Value Types

The value on the key=value pair may be of different kinds. The following is list of possible accepted types

TypeDescription
stringSequence of characters terminated an end of line
floatDecimal number in floating point representation
integerInteger number
booltrue or false
enumEnumeration with a named set of identifiers
pathString that represent filesystem paths absolute or relative to the program
math-exprMath Expression
function-exprFunction Math Expression

Examples

config.ini
key = I am a good looking string
# this next line is not part of the string

Key Options

Search bar

Here you will find a comprehensive list of all the available options for running DuneCopasi simulations. This guide serves as a reference and isn't intended to be read sequentially. To find specific features or keywords within these options, use the search bar located at the top right of the website.

Placeholders

Whenever a key in this documentation contains curly braces {...} it means that it is a placeholder for a user defined key.

Example

The option compartments.domain.expression means that the {cmp} placeholder in compartments.{cmp}.expression is being replaced with the domain keyword and is a valid option.

Multiple keys
  • Whenever a key in this documentation contains square brackets [...] it means that any of the options expanded by the contents separated by | is a valid option.
Example

The option model.time_[begin|end] means that both model.time_begin and model.time_end are valid options.

Below you can find an expandable list of the keys that may be used in the solver:

Configuration Options

Compartment definition with name {cmp} as a sub-domain of the grid

compartments.{cmp}.[expression|parser_type]

Compartments represent one sub-domain within the grid where the model scalar fields have support. There must be at least one non-empty compartment.

Expression that defines a compartment in terms of a function evaluated on grid elements

expression
Type
math-expr

If the expression evaluates to a value different than zero in the center of a grid entity, such entity is assigned to the compartment {cmp} For example, an the expression compartments.top.expression="position_y > 0.5" defines a compartment {cmp} with name top that is only defined for the top half of an squared grid. If the grid was read from a gmsh file (i.e., grid.path=path/to/gmsh/file), the parser will additionally know the gmsh_id for each of entity. For example, an expression of the form compartments.gmsh_domain.expression = (gmsh_id == 2) will be a compartment with name gmsh_domain with entities that have a gmsh id equal to 2.

Parser type of the compartment expression

parser_type
Type
enum
Default
<see '--parser-default' option>

Parameters to read or define a grid

grid.[dimension|path|cells|extensions|origin|refinement_level|axis_names]

Reads or defines a grid. If a file is not provided with the path option, an structured grid will be automatically generated with a given origin, extensions, and cells.

Dimension of the simulation

dimension
Type
integer
Default
<deduced from `grid.extensions` if define, otherwise 2>

Path to a Gmsh file containing a grid

path
Type
path

Reads gmsh format v2.0 and constructs the grid with it. Additionally, the token gmsh_id will be added to the math parsers for each entity of the grid. It will contain the physical id in the gmsh file.

Numbers of cells per dimension direction

cells
Type
integer-list
Default
<one-per-dimension (e.g., '1 1 1' in 3D)>

This option can only be used if no grid.path=/path/to/grid was given

Extensions of an squared domain

extensions
Type
float-list
Default
1 1

This option can only be used if no grid.path=/path/to/grid was given

Position of the origin of an squared domain

origin
Type
float-list
Default
<caresian-origin (e.g., '0. 0. 0.' in 3D)>

This option can only be used if no grid.path=/path/to/grid was given

Number of global refinements to make to the initial grid

refinement_level
Type
integer
Default
0

Names given to the axis of the grid

axis_names
Type
string-list
Default
"x y z"

These names are used to identify the cartesian components of several parameters in the program (e.g. position_x, model.scalar_field.{var}.velocity.z.initial.expression, etc). Through the rest of the documentation, they are assumed to be the default ones.

Sets up a token {dtkn} in the dune-copasi parsers that holds cell data loaded from a file

grid.cell_data.{dtkn}.[type|path]

The cell data file needs to provide the values of the entities to which the values needs to be assigned. The first entry in the file should contain the total number of cells to assign data to. The subsequent entries should contain the data, starting with the grid_cell_id, followed by the n floatss and terminating with a end of line character:

  • 'scalar': n := 1
  • 'vector': n := grid.dimension
  • 'tensor': n := grid.dimension * grid.dimension

Lines starting with # are not read. A simple example for a 'scalar' case is:

# this line is ignored
2
50 +0.5
51 -0.5

This example would assign the values +0.5 and -0.5 to the cells 50 and 51 respectively for the coarsest entities of the grid. Note that the indexation of the entities starts with 0, whereas file formats like gmsh start their indices with 1.

type
Type
enum

Sets token {dtkn} as a scalar double.

'scalar'

Sets token {dtkn} as a vector double. (Not implemented - WIP).

'vector'

Sets token {dtkn} as a tensor double. (Not implemented - WIP).

'tensor'

The path of the file containing values for {dtkn} for the entities values

path
Type
path

General options of the model

model.[order|is_linear|parser_type]

Whether the problem is linear

is_linear
Type
bool
Default
false

Polynomail order of the finite elements

order
Type
integer
Default
1

Default underlying parser for dune-copasi models

parser_type
Type
enum
Default
<see '--parser-default' option>

Whenever a model.* option doesn't define its own parser, this one is selected

General options for the jacobian of the model

model.jacobian.[type|epsilon]

Evaluation type of the jacobian

type
Type
enum
Default
analytical

This option specifies how to generate the assembled operator that is applied on linear systems. If the type is 'analytical', each entry is constructed from the 'model.scalar_field.{var}.jacobian.{dvar}' configuration options.

Jacobians are computed from analyicial expressions provided within the configuration options

'analytical'

In this case, the sparsity pattern is inferred from the 'model.scalar_field.{var}.jacobian.{dvar}' configuration options and its value corresponds to the evaluation of these expressions.

Jacobians are computed numerically from the primary expressions provided within the configuration options

'numeric'

In this case, the sparsity pattern is inferred from the 'model.scalar_field.{var}.jacobian.{dvar}' configuration options and its value corresponds a forward euler evaluation of the 'model.scalar_field.{var}' expressions. Notice that the 'jacobian' configuration options may not be evaluated at all (e.g. 'no_value' is a valid expression) but they still need to be present, otherwise, the pattern will not be created correctly and the numerical evaluation will yield an invalid access error.

The discretization step to evaluate jacobians with a numerical type

epsilon
Type
float
Default
1e-7

Options for the execution policy on the assembly of residuals and jacobians

model.assembly.[type|partition.type|partition.patches|partition.coloring]

Type of execution policy

type
Type
enum
Default
'concurrent'

The assembly of residuals/jacobians is sequenced one after the other

'sequential'

The assembly of residuals/jacobians is made concurrently

'concurrent'

Type of partition of the grid entities. Only used if model.assembly.partition.type=concurrent

partition.type
Type
enum
Default
<'METIS' if found, otherwise 'Simple'>

Partition the grid patches using METIS library

'METIS'

Partition the grid patches by naively splitting the grid iterator

'Simple'

Number of patches to partition the grid

partition.patches
Type
integer
Default
<cells / 40>

Whether to use a coloring for a synchronization free assembly

partition.coloring
Type
enum
Default
'None'

No Coloring and use local basis lock to sincronize accumulation to residuals/jacobians

'None'

Use DSatur algorithm to find patches free of synchronization requirements

'DSatur'

Control data layout of the matrices and vectors. Note that this affects the allowed solvers

model.blocked_layout.[compartments|scalar_fields]
Type
bool

To visualize the resulting layout of a matrix use the model.time_step_operator.linear_solver.layout.writer.svg.path option.

Expression options for the deformation of the domain (Experimental)`

model.domain.deformation.[x|y|z].[expression|parser_type]

The domain deformation expressions may depend on any number of variables {var} from the 'scalar_field' section and only works when using numerical jacobians. Depending on a variable {var} makes the problem non-linear and makes every {var} in 'scalar_field' depend on the variables {var} used here. In practice, this means that the jacobian of every sub-section in scalar_field.{var} needs to also explicitly show the dependency on the variables used here. The differential equations on the scalar section are posed on the deformed domain and conserved over time via the Reynolds Transport Theorem. The latter means that the equations are in their conservative form.

expression
Type
math-expr
parser_type
Type
enum
Default
<see '--parser-default' option>

Expression options for the jacobian wrt variable {wrt} of the scalar field equation in variable {var}

model.scalar_field.{var}.[reaction|storage|velocity.[x|y|z]|outflow.{cmp}].jacobian.{wrt}.[expression|parser_type]
expression
Type
math-expr
parser_type
Type
enum
Default
<see '--parser-default' option>

Expression options for the scalar field equation in variable {var}

model.scalar_field.{var}.[reaction|storage|velocity.[x|y|z]|outflow.{cmp}|initial].[expression|parser_type]

Math expression for the reaction part for equation on variable {var}

reaction.expression
Type
math-expr

Math expression for the storage part on the temporal derivative for equation on variable {var}

storage.expression
Type
math-expr

Math expression for the convection part for equation on variable {var}

velocity.[x|y|z].expression
Type
math-expr

Math expression for the outflow condition w.r.t compartment {cmp} for equation on variable {var}

outflow.{cmp}.expression
Type
math-expr

Math expression for the initial condition for equation on variable {var}

initial.expression
Type
math-expr
[reaction|storage|velocity.[x|y|z]|outflow.{cmp}|initial].parser_type
Type
enum
Default
<see '--parser-default' option>

Compartment name {cmp} where the scalar field {var} is has support

model.scalar_field.{var}.compartment
Type
string

Constraints expressions for {var} on boundary, skeleton and volume degrees of freedom

model.scalar_field.{var}.constrain.[boundary|skeleton|volume].[expression|parser_type]

When the expression evaluates to no_value the degree of freedom will be left unconstrained and left to be solved. Otherwise, the resulting value on the expression will be set as a constrain and the degree of freedom won't be modified when the system is solved. When this option not set, the all the degrees of freedom for {var} will automatically be unconstrained. The boundary degrees of freedom refer to the coefficients bound to the boundary of the entire grid (i.e., not necessarily the compartment boundary). Warning: Time dependent constraints are currently unsupported.

expression
Type
math-expr
parser_type
Type
enum
Default
<see '--parser-default' option>

Selects the kind of cross diffusion jacobian of the variable {drwt} diffusing into variable {var}

model.scalar_field.{var}.cross_diffusion.{dwrt}.jacobian.type
Type
enum
Default
'scalar'
'scalar'

The cross diffusion jacobian is an scalar and it must be set with the model.scalar_field.{var}.cross_diffusion.{dwrt}.jacobian.{wrt}.[expression|parser_type] options.

'tensor'

The cross diffusion jacobian is a tensor and it must be set with the model.scalar_field.{var}.cross_diffusion.{dwrt}.jacobian.[xx|xy|xz|yx|yy|yz|zx|zy|zz].{wrt}.[expression|parser_type] options where each sub-section xx|xy|xz|yx|yy|yz|zx|zy|zz has its own expression and parser_type definition.

Options for the cross diffusion jacobian wrt variable {wrt} of the variable {drwt} diffusing into variable {var}

model.scalar_field.{var}.cross_diffusion.{dwrt}.jacobian[.xx|.xy|.xz|.yx|.yy|.yz|.zx|.zy|.zz].{wrt}.[expression|parser_type]
expression
Type
math-expr
parser_type
Type
enum
Default
<see '--parser-default' option>

Selects the kind of cross diffusion of the variable {drwt} diffusing into variable {var}

model.scalar_field.{var}.cross_diffusion.{dwrt}.type
Type
enum
Default
'scalar'
'scalar'

The cross diffusion is an scalar and it must be set with the model.scalar_field.{var}.cross_diffusion.{dwrt}.[expression|parser_type] options.

'tensor'

The cross diffusion is a tensor and it must be set with the model.scalar_field.{var}.cross_diffusion.{dwrt}.[xx|xy|xz|yx|yy|yz|zx|zy|zz].[expression|parser_type] options where each sub-section xx|xy|xz|yx|yy|yz|zx|zy|zz has its own expression and parser_type definition.

Expression options for the cross diffusion of the variable {drwt} diffusing into variable {var}

model.scalar_field.{var}.cross_diffusion.{dwrt}[.xx|.xy|.xz|.yx|.yy|.yz|.zx|.zy|.zz].[expression|parser_type]
expression
Type
math-expr
parser_type
Type
enum
Default
<see '--parser-default' option>

Options of the linear solver

model.time_step_operator.linear_solver.[type|verbosity|matrix_free|restart]

Type of the linear solver

type
Type
enum
Default
<first found from 'UMFPack', 'SuperLU', and 'BiCGSTAB'>
'RestartedGMRes'
'CG'
'BiCGSTAB'
'UMFPack'
'SuperLU'

Number of iterations before the Gram-Schmidt orthognialization is restarted

restart
Type
integer

This option can only be used together with type=RestartedGMRes

Whether to perform computations with matrix-free methods in the linear solver

matrix_free
Type
bool
Default
false

In general, the matrix-free version will require less memory but will take more computation time to calculate the jacobian application. Additionally, it is not compatible with direct solvers.

Convergence condition options for the linear solver

model.time_step_operator.linear_solver.convergence_condition.[relative_tolerance|iteration_range]

Minimum relative tolerance (defect₀/defectᵢ) to accept convergence

relative_tolerance
Type
float
Default
1e-4

Iteration range [min_it, max_it] allowed to assert convergence

iteration_range
Type
integer-pair
Default
"1, 500"

Path to write svg layout of the matrix

model.time_step_operator.linear_solver.layout.writer.svg.path
Type
path

Writes a svg file with the matrix layout of the jacobian of the system in the current directory.

There are a number of parameters that affect the resulting layout:

  • The model.blocked_layout.[compartments|scalar_fields]=<bool> options affect the hierarchal structure of the matrix.
  • The number of scalar fields in model.scalar_field.{var}.* and the compartment {cmp} where the belong (i.e., model.scalar_field.{var}.compartment={cmp}) affacts the position of the matrix entries.
  • The grid connectivity affects the position of the matrix entries.
  • The jacobian options of the reaction operator (i.e. model.scalar_field.{var}.reaction.jacobian.{wrt}.expression) affects the appearance of many entries in the matrix.

To visualize the results of this option use your web browser, GIMP, Inkscape, Affinity Designer or another vector graphics editor.

This option will only have effect when the a matrix is created, (e.g., matrix-free computation won't write any file).

Options of the non-linear solver

model.time_step_operator.nonlinear_solver.[norm|linearization_threshold|dx_inverse_fixed_tolerance|dx_inverse_min_relative_tolerance]

Type of norm to evaluate the resuldual

norm
Type
enum
Default
'l_2'
'l_2'
'l_inf'
'l_1'

Threshold to trigger linearization of the jacobian

linearization_threshold
Type
float
Default
0.0

Whenever the defect rate (defectᵢ/defectᵢ₋₁) between iterations is lower than this threshold, the system is linearized at a new linearization once again. Notice that the default behavior linearizes on every newton iteration.

Whether jacobian inverse relative reduction is fixed between newton iterations

dx_inverse_fixed_tolerance
Type
bool
Default
false

The newton method may have a better guess for a relative reduction for the jacobian inverse correction at each iteration. If this is set to false, the newton application will modify the convergence_condition.relative_tolerance on the jacobian inverse solver property before each iteration of the newton method

Minimum relative reduction of the jacobian inverse solver

dx_inverse_min_relative_tolerance
Type
float
Default
0.1

Convergence condition options for the non-linear solver

model.time_step_operator.nonlinear_solver.convergence_condition.[relative_tolerance|absolute_tolerance|iteration_range]

Minimum relative tolerance (defect₀/defectᵢ) to accept convergence

relative_tolerance
Type
float
Default
1e-8

Minimum absolute tolerance (defectᵢ) to accept convergence

absolute_tolerance
Type
float

Note that the absence of an absolute tolerance might be hurtful for convergence since good initial guesses will have very hard time to converge with the relative tolerance

Iteration range [min_it, max_it] allowed to assert convergence

iteration_range
Type
integer-pair
Default
"0, 45"

Initial and final time the simulation

model.time_step_operator.time_[begin|end]
Type
float
time_begin
Default
0.
time_end
Default
1.

Time-step settings of the simulation

model.time_step_operator.time_step_[initial|increase_factor|decrease_factor|max|min]

Initial time step when starting the simulation

time_step_initial
Type
float
Default
0.1

In case of time-step success, the subsequent time-step will be increased by this factor

time_step_increase_factor
Type
float
Default
1.1

In case of time-step failure, the subsequent time-step will be decreased by this factor

time_step_decrease_factor
Type
float
Default
0.5

Maximum time-step that the simulation is allowed to make

time_step_max
Type
float

Minimum time-step that the simulation is allowed to make

time_step_min
Type
float

Type of the time-stepping scheme for the operator

model.time_step_operator.type
Type
enum
Default
'Alexander2'
'ExplicitEuler'
'ImplicitEuler'
'Heun'
'Shu3'
'RungeKutta4'
'Alexander2'
'Alexander3'
'FractionalStepTheta'

Define an evaluation/reduction/transformation algorithm on grid functions

model.transform_reduce.{key}.[evaluation|reduction|transformation|error|warn].[expression|parser_type]

The token {key} defines the context for a generic reduction algorithm over grid functions. In general, this allows to evaluate a pointwise function over the whole grid

   # set initial value from options
   value := initial.value
   for entity in grid:
     for [pos, weight] in quadrature(entity):
       # contextual evaluation to the current quadrature position
       quad_eval := evaluation.expression() 
       # apply reduction to new and old value
       value = reduction.expression(quad_eval, value) 
   # apply final transformation to last reduced value
   value = transformation.expression(value) 

Finally, the warn and error expressions allow to control whether the final value must be reported as an error or a warning.

Pointwise math expression to evaluate. Its context includes values defined in the scalar_field sections

evaluation.expression
Type
math-expr

This expression additionally defines the keyword integration_order with the quadrature factor to weight integrals

Reduce the successive value after the every evaluation

reduction.expression
Type
function-expr

Function expression with exactly 2 arguments:

  1. New value: Contextual evaluation of evaluation.expression
  2. Old value: previous result of reduction.expression or initial.value

Transform the final value after the last reduction

transformation.expression
Type
function-expr

Function expression with exactly 1 argument:

  1. Old value: Value after a reduction over all of the quadrature points

If expression evaluates different than 0, an error is thrown

error.expression
Type
function-expr

Function expression with exactly 1 argument:

  1. Final value: Value after a transformation

If expression evaluates different than 0, an warning is thrown

warn.expression
Type
function-expr

Function expression with exactly 1 argument:

  1. Final value: Value after a transformation

Define the initial value and quietness of an evaluation/reduction/transformation algorithm on grid functions

model.transform_reduce.{key}.[initial.value|quiet]

Initial value of the evaluation/reduction/transformation algorithm for the token {key}

initial.value
Type
float
Default
0.

Skip printing results of {key} unless a warning or error occur

quiet
Type
bool
Default
false

If not empty, path to write VTK results

model.writer.vtk.path
Type
path

Writes a set vtu files with the scalar field solution of the problem in the file system under {prefix}-{cmp} directory for each {cmp} compartment. Additionally, a compendium of all timesteps for each compartment is written in a pvd file on the same directory. The resulting vtu and pvd files can be opened by ParaView or VisiIt to visualize their results.

Sets up a token {tkn} in the dune-copasi parsers

parser_context.{tkn}.[type|expression|parser_type|domain|range|value|path|interpolate|seed]

Type of token {tkn} within the dune-copasi parsers

type
Type
enum

Sets token {tkn} as a constant float. Options: parser_context.{tkn}.value

'constant'

Sets token {tkn} as an inline function. Options: parser_context.{tkn}.[expression|interpolate|interpolation.[...]]

'function'

Sets token {tkn} as a 2D function with the contents of a tiff file. Options: parser_context.{tkn}.path

'tiff'

Reads an image file with tiff format and makes it available as a 2D function expression with the {tkn} token. Images with grayscale values of 8, 16, 32, and 64 bits are supported.

Sets token {tkn} as a 1D interpolation function. Options: parser_context.{tkn}.[domain|range]

'interpolation'

Sets token {tkn} as a random field function. Options: parser_context.{tkn}.[seed|grid|...]

'random_field'

Value of the token {tkn} as a float

value
Type
float

This option can only be used together with parser_context.{tkn}.type=constat

function

Expression of an inline function for the token {tkn}

expression
Type
math-expr

The expression must start with a comma serparated list of arguments followed by a colon which splits the function arguments from the function definition. For example: parser_context.pow2.expression="x: x^2" defines a function that may be called as pow2(1.) in the context of parsed expressions. Note that inline functions know other contexts defined in the parser (e.g., random_field, constant, interpolation, etc.), except other inline functions. Thus, inline functions are not recursive nor composable with other inline functions. This option can only be used together with parser_context.{tkn}.type=function.

Whether 1D functions should be interpolated

interpolate
Type
bool
Default
false

If a function is expensive to evaluate, this option will help to reduce the cost by automatically interpolating the function on a given domain.

Domain of values to be interpolated for token {tkn}

domain
Type
float-list

For example, the options parser_context.f.domain="0 1 2" and parser_context.f.range=".5 .1 .3" will define an interpolated function f: domain -> range within the parser. This option can only be used together with parser_context.{tkn}.type=interpolation

Range of values to be interpolated for token {tkn}

range
Type
float-list

The number of arguments in the list must be the same as for parser_context.{tkn}.range This option can only be used together with parser_context.{tkn}.type=interpolation

Underlying parser for inlined function of the token {tkn}

parser_type
Type
enum
Default
<see '--parser-default' option>

This option can only be used together with parser_context.{tkn}.type=function

File path of a TIFF image to set token {tkn} as a 2D function

path
Type
path

This option can only be used together with parser_context.{tkn}.type=tiff

Seed to be used in the pseudorandom number field generator

seed
Type
integer

This option can only be used together with parser_context.{tkn}.type=random_field

Parameters to define a structured grid of the random field in token {tkn}

parser_context.{tkn}.grid.[cells|extensions|refinement_level]

Numbers of cells per dimension direction

cells
Type
integer-list

Extensions of an squared domain

extensions
Type
float-list

Number of global refinements to make to the initial grid

refinement_level
Type
integer
Default
0

Parameters to generate the random field in token {tkn}

parser_context.{tkn}.{parafields-key}={parafields-value}

When the token {tkn} is a 'random_field' type, all parameters {parafields-key}={parafields-value} under the parser_context.{tkn} subsection will be forwarded to the parafields-core engine.

Interpolation options for the context function {tkn}

parser_context.{tkn}.interpolation.[domain.{arg}|intervals|out_of_bounds]

Domain interval for the function argument {arg} where the interpolation needs to be made

domain.{arg}
Type
float-pair

Number of sub-divisions to split the interpolation scheme. Default: 1000

intervals
Type
integer
Default
1000

Type of behavior when function is evaluated out of the defined domain bounds

out_of_bounds
Type
enum
Default
'error'

Throw an error when function {tkn} is evaluated outside of domain.{arg}

'error'

Clamps the arguments of the function {tkn} to be evaluated inside of domain.{arg}

'clamp'

Path to write VTK file of random_field contexts

parser_context.{tkn}.writer.vtk.path
Type
path

Writes a vtu file with the contents of the generated random field in the filesystem with the {tkn} keyword as a base name. This option can only be used together with parser_context.{tkn}.type=random_field. The resulting vtu files can be opened by ParaView or VisiIt to visualize their results.

Selects default underlying parser for the parser_context sub-sections

parser_context.parser_type
Type
enum
Default
<see '--parser-default' option>

Whenever an parser_context.* option doesn't define its own parser, this one is selected.

File path to store the trace of the program

trace.path
Type
path

Writes a trace file with the timing information of the simulation on the current directory. To visualize the trace, use Perfetto Trace Viewer. Only available if binary is built with Perfetto.