List of Options
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.
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
| Type | Description |
|---|---|
string | Sequence of characters terminated an end of line |
float | Decimal number in floating point representation |
integer | Integer number |
bool | true or false |
enum | Enumeration with a named set of identifiers |
path | String that represent filesystem paths absolute or relative to the program |
math-expr | Math Expression |
function-expr | Function Math Expression |
Examples
- String
- Float
- Integer
- Bool
- Enum
- Path
- Math Expr
- Func Expr
key = I am a good looking string
# this next line is not part of the string
key_a = 1e-2
key_b = 0.1
key = 1
key_a = true
key_b = false
# e.g. named set of identifiers: ['l_1', 'l_2', 'l_inf']
key_a = l_1
key_b = l_2
key_c = l_inf
key_d = l_3
# error: not known 'l_3' in enum
# absolute path
key_a = /path/to/directory/
# relative path
key_a = path/to/directory/
# math expression using contextual 'pi', 'position_x', and 'position_y' tokens
key = pi*sin(position_x)*sin(position_y)
# function math expression using 'a' and 'b' arguments of a function named 'key'
key = a, b: sin(a)*sin(b)
Key Options
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.
Whenever a key in this documentation contains curly braces {...} it means that it is a placeholder for a user defined key.
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.
- 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.
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
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
enum <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
integer <deduced from `grid.extensions` if define, otherwise 2>Path to a Gmsh file containing a grid
path
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
integer-list <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
float-list 1 1This option can only be used if no grid.path=/path/to/grid was given
Position of the origin of an squared domain
origin
float-list <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
integer 0Names given to the axis of the grid
axis_names
string-list "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
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
path General options of the model
model.[order|is_linear|parser_type]
Whether the problem is linear
is_linear
bool falsePolynomail order of the finite elements
order
integer 1Default underlying parser for dune-copasi models
parser_type
enum <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
enum analyticalThis 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
float 1e-7Options 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
enum '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
enum <'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
integer <cells / 40>Whether to use a coloring for a synchronization free assembly
partition.coloring
enum '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]
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
math-expr parser_type
enum <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
math-expr parser_type
enum <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
math-expr Math expression for the storage part on the temporal derivative for equation on variable {var}
storage.expression
math-expr Math expression for the convection part for equation on variable {var}
velocity.[x|y|z].expression
math-expr Math expression for the outflow condition w.r.t compartment {cmp} for equation on variable {var}
outflow.{cmp}.expression
math-expr Math expression for the initial condition for equation on variable {var}
initial.expression
math-expr [reaction|storage|velocity.[x|y|z]|outflow.{cmp}|initial].parser_type
enum <see '--parser-default' option>Compartment name {cmp} where the scalar field {var} is has support
model.scalar_field.{var}.compartment
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
math-expr parser_type
enum <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
enum '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
math-expr parser_type
enum <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
enum '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
math-expr parser_type
enum <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
enum <first found from 'UMFPack', 'SuperLU', and 'BiCGSTAB'>'RestartedGMRes'
'CG'
'BiCGSTAB'
'UMFPack'
'SuperLU'
Number of iterations before the Gram-Schmidt orthognialization is restarted
restart
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
bool falseIn 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
float 1e-4Iteration range [min_it, max_it] allowed to assert convergence
iteration_range
integer-pair "1, 500"Path to write svg layout of the matrix
model.time_step_operator.linear_solver.layout.writer.svg.path
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
enum 'l_2''l_2'
'l_inf'
'l_1'
Threshold to trigger linearization of the jacobian
linearization_threshold
float 0.0Whenever 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
bool falseThe 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
float 0.1Convergence 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
float 1e-8Minimum absolute tolerance (defectᵢ) to accept convergence
absolute_tolerance
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
integer-pair "0, 45"Initial and final time the simulation
model.time_step_operator.time_[begin|end]
float time_begin
0.time_end
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
float 0.1In case of time-step success, the subsequent time-step will be increased by this factor
time_step_increase_factor
float 1.1In case of time-step failure, the subsequent time-step will be decreased by this factor
time_step_decrease_factor
float 0.5Maximum time-step that the simulation is allowed to make
time_step_max
float Minimum time-step that the simulation is allowed to make
time_step_min
float Type of the time-stepping scheme for the operator
model.time_step_operator.type
enum '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
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
function-expr Function expression with exactly 2 arguments:
- New value: Contextual evaluation of
evaluation.expression - Old value: previous result of
reduction.expressionorinitial.value
Transform the final value after the last reduction
transformation.expression
function-expr Function expression with exactly 1 argument:
- Old value: Value after a reduction over all of the quadrature points
If expression evaluates different than 0, an error is thrown
error.expression
function-expr Function expression with exactly 1 argument:
- Final value: Value after a transformation
If expression evaluates different than 0, an warning is thrown
warn.expression
function-expr Function expression with exactly 1 argument:
- 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
float 0.Skip printing results of {key} unless a warning or error occur
quiet
bool falseIf not empty, path to write VTK results
model.writer.vtk.path
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
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
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
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
bool falseIf 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
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
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
enum <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
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
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
integer-list Extensions of an squared domain
extensions
float-list Number of global refinements to make to the initial grid
refinement_level
integer 0Parameters 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}
float-pair Number of sub-divisions to split the interpolation scheme. Default: 1000
intervals
integer 1000Type of behavior when function is evaluated out of the defined domain bounds
out_of_bounds
enum '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
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
enum <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
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.