Parameter Tree
Reference Keysβ
A parameter tree is a collection of keyβvalue pairs that may be grouped by
sections. We call it a tree because sections may contain also other sections.
Here, we follow the DUNE
ini file convention to refer to
sections and keywords. In addition, keywords between angle brackets (i.e.
<key>
) are references to multiple user-defined keywords of the same kind.
[grid]
β
The grid is entred by a GMSH file and should be formed by triangles and rectangles in 2D or tetraedra and hexahedra in 3D. It must define physical groups, each referring to a different compartment. Each physical group can only be formed the same collection of geometric types.
Key | Type | Description |
---|---|---|
dimension | integer | The dimension of the grid |
file | path | GMSH v2 file directory absolute or relative to the executable |
initial_level | integer | The refinement level to start the simulation with |
The GMSH file should not contain the $PhysicalGroup
section at the
beginning of the file (this is a known bug in the dune-grid
GMSH reader).
[model]
β
This section is the one that contains most of the aspects for simulation.
Key | Type | Description |
---|---|---|
order | integer | Finite Element polynomial order. if order==0 FV else CG |
[data] | subsection | List of input files |
[writer] | subsection | Options for vtk writer |
[time_stepping] | subsection | Options for time-stepping |
[compartment] | subsection | List of compartmentes to simulate |
[<comp_k>] | subsection | Options for equations per each compartment |
Whenever a compartment is coposed by cubes (2D) or hexahedra (3D), then such compartment is modeled using Finite Volumes. These compartments are suitable to model membranes processes.
The subsection [<comp_k>]
is a placeholder for the name of all
compartment given in [compartment]
. See [model.compartment]
subsection for
more information.
[model.data]
β
This section will contain all the input files for the initial conditions of the model.
Key | Type | Description |
---|---|---|
<data_name> | path | 16-bit grayscale TIFF file |
See Input Data section for more information about usage.
[model.output]
β
The model output is controlled by the following parameters:
Key | Type | Description |
---|---|---|
file_path | string | Name used to output VTK files |
[model.time_stepping]
β
This section sets the settings for the evolution in time of the forward model.
Key | Type | Description |
---|---|---|
rk_method | rk_id | Runge-Kutta method |
begin | float | Initial time of the forward simulation |
end | float | Final time of the forward simulation |
initial_step | float | Time step at the beginning of the simulation |
min_step | float | Maximum time step allowed |
max_step | float | Minimum time step allowed |
decrease_factor | float | Time step decrease factor when time step fails |
increase_factor | float | Time step increase factor when time step succeeds |
[newton] | subsection | Parameters for the Newton method at each timestep |
The possible rk_id
s can be found at the end of this document.
[model.newton]
β
Key | Type | Description |
---|---|---|
reduction | float | Threshold for termination, relative to first linear defect |
absolute_limit | float | Threshold for termination, absolute to linear defect |
min_linear_reduction | float | The linear reduction will be determined as minimum of this and the one needed to achieve second order newton convergence |
fixed_linear_reduction | bool | Whenever true , the linear reduction rate will always be fixed to min_linear_reduction |
max_iterations | integer | Maximum number of linear searches allowed |
reassemble_threshold | float | If the reduction drops below this the linear operator is reassembled to ensure convergence |
keep_matrix | bool | Whether the jacobian matrix should be kept across time steps |
force_iteration | bool | Enforce first iteration even if required reduction is achieved |
[linear_search] | subsection | Parameters for linear search |
[model.newton.linear_search]
β
Key | Type | Description |
---|---|---|
strategy | string | noLineSearch or hackbuschReusken or hackbuschReuskenAcceptBest |
max_iterations | integer | Maximum iterations on Hackbusch-Reusken linear search |
damping_factor | float | Damping factor for Hackbusch-Reusken linear search |
[model.compartment]
β
The compartment section is filled with key=value
pairs that assign a physical
group id (value
) to an compartment name (key
).
Key | Type | Description |
---|---|---|
<comp_k> | integer | Physical group id assigned to <comp_k> subdomain |
Each compartment id maps to a physical group in the gmsh identifiers.
Although the gmsh format allows you to name such physical groups.
Notice that dune-copasi
uses 0-based
indices while gmsh
uses 1-based indices. In other words,
<gmsh_physical_group> = <dune_copasi_compartment> + 1
.
Let's say that there is two physical groups in our gmsh file
and we are going to name them as nucleus
and cytoplasm
compartments:
[model.compartments]
# nucleus corresponds to the physical group 1 in the gmsh file
nucleus = 0
# cytoplasm corresponds to the physical group 2 in the gmsh file
cytoplasm = 1
# They then become available as new compartment subsections
[model.nucleus]
# Parameters for the nucleus compartment
[model.cytoplasm]
# Parameters for the nucleus compartment
[model.<comp_k>]
β
Each compartment will define its own initial conditions,
its diffusion-reaction system, etc. A set of variables is be assigned to each
compartment. The amount variables may be different on each compartment, but
the same namings must be used on all the [model.<comp_k>]
subsections.
Key | Type | Description |
---|---|---|
[initial] | subsection | List of variables and their initial conditions |
[diffusion] | subsection | List of variables and their diffusion coefficient |
[reaction] | subsection | List of variables and their reaction networks |
[boundary] | subsection | Definition of boundary fluxes on this <comp_k> |
[model.<comp_k>.initial]
β
The initial
subsection allows the initialization for each of the variables.
Expressions in this section may contain Input Data functions.
Key | Type | Description |
---|---|---|
<var> | math_expr | Math expression to initialize variable <var> |
[model.<comp_k>.diffusion]
β
The diffusion
subsection defines the self-diffusion coefficient associated
with each variable.
Key | Type | Description |
---|---|---|
<var> | math_expr | Diffusion math expression assigned to <var> |
[model.<comp_k>.reaction]
β
This subsection defines the reaction network associated with each variable.
Key | Type | Description |
---|---|---|
<var> | math_expr | Reaction network expression assigned to <var> |
[jacobian] | subsection | Jacobian expressions for compartment reaction networks |
Variables (<var>
s) in this section differ from other math expressions in that
all variables names on this <comp_k>
are available to form the
expression.
The variables u
and v
are available to each other for a subsection
[model.nucleus.reaction]
[model.nucleus.reaction]
u = u*v
v = u*v
[model.<comp_k>.reaction.jacobian]
β
This subsection lists the
jacobian matrix
entries for the reaction
section. It must follow the syntax of
d<var_i>__d<var_j>
, which reads as the partial derivative of <var_i>
with
respect to <var_j>
.
Key | Type | Description |
---|---|---|
d<var_i>__d<var_j> | math_expr | Reaction network jacobian entries |
Similar to [model.<comp_k>.reaction]
, math expressions here allow all
compartmenet variables to be used.
The section [model.nucleus]
for a Gray-Scott model with F=0.0420 and
k=0.0610 may look like
this:
[model.nucleus.initial]
u = 0.5
v = (x>0) && (x<0.5) && (y>0.) && (y<0.5) ? 1 : 0
[model.nucleus.diffusion]
u = 2e-5
v = 2e-5/2
[model.nucleus.reaction]
u = -u*v^2+0.0420*(1-u)
v = u*v^2-(0.0420+0.0610)*v
[model.nucleus.reaction.jacobian]
du__du = -v^2-0.0420
du__dv = -2*u*v
dv__du = v^2
dv__dv = 2*u*v-(0.0420+0.0610)
[model.<comp_k>.boundary]
β
The boundary section encapsulates the information for the transmmission conditios
. It contains subsections for every other compartment
<comp_l>
making reference to the membrane defined by , where
<comp_k>
corresponds to the interior -th domain and <comp_l>
to the exterior -th domain .
Key | Type | Description |
---|---|---|
[<comp_l>.outflow] | subsection | Outflow for membranes between <comp_k> and <comp_l> |
[model.<comp_k>.boundary.<comp_l>.outflow]
β
This section contains the transmmission condition for each
variable, <var_i>
in <comp_k>
.
Key | Type | Description |
---|---|---|
<var_i> | math_expr | Transmission condition for <var_i> |
[jacobian] | subsection | Outflow jacobian entries |
The math expressions in this subsection are allowed to use all variables from
both <comp_k>
and <comp_l>
compartments. Because they may have the same
name, the parser distinguish them by assigin a _i
(inside) sufix for variables
in <comp_k>
and _o
(outside) for variables in <comp_l>
. Additionally,
their normal gradients,