Study file reference

All keys of a study file: first as an overview, a commented study file, then section by section, each key with its type, its default (or whether it is required) and what it does. <name> stands for a name you choose, e.g., of a measurement. Running a study and Measurements explain how the keys work together.

This page is generated from the study file’s options (kipe.options), so it describes exactly what kipe accepts. Unknown keys are an error.

Overview

output:                                 # required
  path: <string>                        # required
  log_level: info                       # debug | info | warning | error

forward_solver:                         # required
  factory: <string>                     # required
  arguments: <mapping>                  # optional

parameters:
  reparameterization: <log | multiplicative | additive> # required
  select:                               # required
    <name>:                             # a parameter of the solver
      initial: <number>                 # optional
      relative_stddev: <number > 0>     # optional
      stddev: <number > 0>              # optional
      reparameterization: <log | multiplicative | additive> # optional

measurements:
  <name>:                               # a name you choose
    fields: <list of strings (at least 1)> # required
    data:                               # required
      type: numpy
      path: <string>                    # required
    noise:                              # required
      stddev: <number > 0>              # required
      seed: <integer ≥ 0>               # optional
    times: <list of numbers or {start, stop, step}> # optional
    spatial_sampling:                   # one of, by type
      type: array                       # the default
      # or:
      # type: fenicsx.mesh
      # mesh: <string>                  # required
      # mesh_name: mesh
      # element: P1                     # P1 | DG0
      # projection: <list of numbers (at least 1) or surface_normal> # optional
      # padding: 0.0
      # or:
      # type: fenicsx.points
      # points: <list of lists of numbers (at least 1)> # required
    model:
      type: difference

synthesis:
  truth:                                # one of, by type
    type: run                           # the default
    # or:
    # type: checkpoints
    # path: <string>                    # required
  noise:
    <name>:                             # one of the measurements
      stddev: <number ≥ 0>              # required
  realizations: 1

estimation:
  sigma_points: simplex                 # simplex | canonical | unique
  iterations: 1

output

Output location and logging.

key	type	default	description
path	string	required	Directory for all results. Subcommands write into subdirectories.
log_level	debug | info | warning | error	info	Minimum level of the log messages kipe writes.

forward_solver

Construction of the forward solver.

key	type	default	description
factory	string	required	Import path of the factory, "module:name", e.g., "kipe.examples.fitzhugh_nagumo:Solver".
arguments	mapping	optional	Keyword arguments passed to the factory, as given (no path resolution).

parameters

Estimated parameters.

key	type	default	description
reparameterization	log | multiplicative | additive	required	How the estimated parameter \(\theta\) relates to the physical value \(\phi\), relative to the initial estimate \(\phi_0\). Default for all parameters in select, each can override it. Available reparameterizations: log: \(\phi = \phi_0 2^\theta\), starting at \(\theta = 0\), with a relative_stddev. Keeps \(\phi\) positive; the initial estimate must be positive. multiplicative: \(\phi = \phi_0 \theta\), starting at \(\theta = 1\), with a relative_stddev. The initial estimate must not be zero; \(\phi\) can change sign. additive: \(\phi = \phi_0 + \theta\), starting at \(\theta = 0\), with an absolute stddev. \(\theta\) is the deviation from the initial estimate, in the parameter’s physical unit. Accepts any initial estimate, including zero.
select	mapping: name → section, see below	required	Estimated parameters: parameter name -> initial estimate and uncertainty. All other parameters keep their nominal values.

parameters.select

Estimated parameters: parameter name -> initial estimate and uncertainty. All other parameters keep their nominal values.

Each parameters.select.<name>, where <name> is a parameter of the solver:

key	type	default	description
initial	number	optional	Initial estimate (prior mean), as physical value. The solver’s nominal value if not given.
relative_stddev	number > 0	optional	Standard deviation relative to initial, e.g., 0.3 for 30%. For log and multiplicative. Converted to the standard deviation of \(\theta\), to first order around initial: \(\sigma_\theta\) = relative_stddev / ln 2 for log, \(\sigma_\theta\) = relative_stddev for multiplicative. So both give the same prior as long as relative_stddev is small. For large values they differ: log keeps the parameter positive, at the price of an asymmetric distribution. kipe list-parameters shows the resulting 1σ range.
stddev	number > 0	optional	Absolute standard deviation, in the parameter’s physical unit. For additive.
reparameterization	log | multiplicative | additive	optional	Overrides the section’s reparameterization for this parameter.

measurements

Measurements: name -> measurement. The names appear in logs, output and errors.

Each measurements.<name>, where <name> is a name you choose:

key	type	default	description
fields	list of strings (at least 1)	required	State fields the measurement observes.
data	section, see below	required	Where the measured data are: read by estimation, written by synthesis.
noise	section, see below	required	Measurement noise.
times	list of numbers or {start, stop, step}, see below	optional	Measurement times: a list or a range. Required by synthesis (the times to generate); for estimation a selection from the times in the data, all if not given.
spatial_sampling	one of, by type: array, fenicsx.mesh, fenicsx.points, see below	optional	How the observed fields are brought to the measurement locations; the kind is selected by type, array by default.
model	section, see below	optional	How predicted data are computed from the sampled fields and compared with the data.

measurements.<name>.data

Where the measured data are: read by estimation, written by synthesis.

key	type	default	description
type	numpy	required	Data format.
path	string	required	Path to the .npz file. With several noise realizations (synthesis.realizations), it contains the placeholder {realization}, e.g., "data/r{realization}/u.npz" or "data/u_{realization:02d}.npz": each realization has its own file. In quotes, since YAML reads braces in {type: ..., path: ...} as a mapping.

measurements.<name>.noise

Measurement noise.

key	type	default	description
stddev	number > 0	required	Standard deviation of the noise, in the unit of the data.
seed	integer ≥ 0	optional	Seed of the noise added by synthesis (required there, unless it adds none, see synthesis.noise). The noise of the k-th time of the measurement is drawn from numpy.random.default_rng([seed, k]), so it does not depend on the other times. Measurements must have different seeds.

measurements.<name>.times

Measurement times: a list or a range. Required by synthesis (the times to generate); for estimation a selection from the times in the data, all if not given.

key	type	default	description
start	number	required	First time.
stop	number	required	Last time, included (up to round-off).
step	number > 0	required	Distance between successive times.

measurements.<name>.spatial_sampling

How the observed fields are brought to the measurement locations; the kind is selected by type, array by default.

type: array (the default)

Sample all entries of the observed fields, concatenated in the order of fields.

type: fenicsx.mesh

Interpolate the observed field onto a measurement mesh (FEniCSx backend).

The field must be a distributed field whose function space the forward solver provides (kipe.fenicsx.forward_solver.SupportsFunctionSpaces). The measurement mesh need not match the solver’s mesh. The data are in the order of the mesh file: by vertex for P1, by cell for DG0, independent of the number of ranks; for a vector field without projection, the components of each vertex or cell one after another.

key	type	default	description
mesh	string	required	Path to the measurement mesh, an XDMF file.
mesh_name	string	mesh	Name of the mesh in the XDMF file (its grid): mesh as dolfinx writes it; meshio writes Grid.
element	P1 | DG0	P1	Finite element on the measurement mesh: vertex values (P1) or cell values (DG0).
projection	list of numbers (at least 1) or surface_normal	optional	What is measured of a vector field; all components if not given. A direction, e.g., [0, 0, 1] for the z component (normalized by kipe), or surface_normal: the component along the cell normal of a surface mesh (needs element: DG0, one normal per cell). The normal’s orientation follows the order of each cell’s vertices in the mesh file, as ufl.CellNormal: the right-hand rule for triangles in 3D, the tangent rotated by +90° for lines in 2D; it is outward only if the mesh’s cells are oriented that way.
padding	number ≥ 0	0.0	Distance, in mesh units, by which a measurement point may lie outside the solver’s mesh, e.g., where a surface mesh cuts slightly across the solver’s boundary. Such a point takes the value of the field in the nearest cell, extrapolated; a point farther out is an error.

type: fenicsx.points

Evaluate the observed field at given points (FEniCSx backend).

The field must be a distributed field whose function space the forward solver provides (kipe.fenicsx.forward_solver.SupportsFunctionSpaces). The data are in the order of points; for a vector field, the components of each point one after another.

key	type	default	description
points	list of lists of numbers (at least 1)	required	Coordinates of the measurement points, one list per point, e.g., [[0.5, 0.5], [0.2, 0.8]] in 2D. Each point must lie in the solver’s mesh.

measurements.<name>.model

How predicted data are computed from the sampled fields and compared with the data.

key	type	default	description
type	difference	difference	Kind of measurement model.

synthesis

Generation of synthetic measurement data.

key	type	default	description
truth	one of, by type: run, checkpoints, see below	optional	Source of the true state the data are generated from: a run of the forward solver, or its checkpoints.
noise	mapping: name → section, see below	optional	Noise synthesis adds to the data of the listed measurements (measurement name -> noise), instead of their noise.stddev, which estimation assumes: for noise-free data (stddev: 0) or studies with misspecified noise. Measurements not listed get their noise.stddev.
realizations	integer > 0	1	Number of noise realizations, e.g., for the statistics of the estimates over the noise. Synthesis computes the true state once and writes the data of realizations \(r = 0, \dots, n - 1\), each to the data.path of the measurements with {realization} replaced by \(r\); kipe estimation --realization r estimates from one of them. Realization 0 has the noise of a study without realizations.

synthesis.truth

Source of the true state the data are generated from: a run of the forward solver, or its checkpoints.

type: run (the default)

Generate the data by running the forward solver with its nominal parameters.

type: checkpoints

Generate the data from the checkpoints of an earlier run of the forward solver.

The solver reads the true states at the measurement times from the checkpoints at path; it needs kipe.forward_solver.SupportsCheckpoints. The run may differ from the model of the forward_solver section (e.g., in its time step or parameters), as long as the solver can read its checkpoints into the model’s state.

key	type	default	description
path	string	required	Location of the checkpoints, as the solver understands it (e.g., the output directory of the run).

synthesis.noise

Noise synthesis adds to the data of the listed measurements (measurement name -> noise), instead of their noise.stddev, which estimation assumes: for noise-free data (stddev: 0) or studies with misspecified noise. Measurements not listed get their noise.stddev.

Each synthesis.noise.<name>, where <name> is one of the measurements:

key	type	default	description
stddev	number ≥ 0	required	Standard deviation of the noise, in the unit of the data; 0 for noise-free data.

estimation

Parameter estimation.

key	type	default	description
sigma_points	simplex | canonical | unique	simplex	Sigma-point stencil, the pattern along which the estimates are perturbed. Each sigma point costs one forward run per measurement time: simplex: \(p + 1\) sigma points, the cheapest. canonical: \(2p\) sigma points, \(\pm\) along each parameter. unique: one sigma point at the estimate, no spread: no correction. A sanity check of the whole pipeline (with the true parameters, the innovations are pure noise).
iterations	integer ≥ 1	1	Number of passes over the measurements. Each pass after the first starts from the previous estimate, with the initial uncertainty.