kipe.measurements module

Measurements, and how predicted data are compared with them.

The observation operator compares a model state with a measurement in two steps: a spatial sampler (kipe.sampling) evaluates the observed fields at the measurement locations, giving \(y\); a MeasurementModel predicts the data from it, \(\hat{z} = M(y)\), and compares them with the measured data \(z\), giving the innovation \(\Gamma(z, \hat{z})\). Models act on arrays only, so they are the same for every backend. The ObservationOperator \(\mathcal{H} = M \circ S\) combines the two steps: it takes a model state to predicted data.

To add a model: subclass MeasurementModel, implement both methods, add its options to kipe.options and a case to build_model().

class kipe.measurements.MeasurementModel

Bases: ABC

Turns sampled model fields into predicted data and compares them with the measurement.

abstractmethod predict(y: NDArray_f64) → NDArray_f64

Predict the measured data from the sampled state, \(\hat{z} = M(y)\).

Parameters:

y – sampled state \(y\), as returned by kipe.sampling.SpatialSampler.sample()

Returns:

predicted data \(\hat{z}\), in the measurement space

abstractmethod innovation(z_hat: NDArray_f64, z: NDArray_f64) → NDArray_f64

Compare predicted and measured data, \(\Gamma(z, \hat{z})\).

Parameters:

• z_hat – predicted data \(\hat{z}\), as returned by predict()

• z – measured data at the current assimilation time, in the measurement space

Returns:

innovation, before weighting with the measurement noise

class kipe.measurements.DifferenceModel

Bases: MeasurementModel

The measured data are the sampled fields: \(\hat{z} = y\), and the innovation is \(\Gamma = z - \hat{z}\).

predict(y: NDArray_f64) → NDArray_f64

Return the sampled fields as predicted data.

Parameters:

y – sampled state

Returns:

y

innovation(z_hat: NDArray_f64, z: NDArray_f64) → NDArray_f64

Return measured minus predicted data.

Parameters:

• z_hat – predicted data

• z – measured data

Returns:

z - z_hat

kipe.measurements.build_model(options: DifferenceModelOptions) → MeasurementModel

Construct the measurement model given by the model options of a measurement.

Parameters:

options – model options of the measurement

Returns:

the measurement model

class kipe.measurements.ObservationOperator(fields: list[str], sampler: SpatialSampler, model: MeasurementModel)

Bases: object

The observation operator \(\mathcal{H} = M \circ S\) of a measurement.

Takes a model state \(\chi\) to predicted data \(\hat{z} = \mathcal{H}(\chi)\): the spatial sampler \(S\) evaluates the observed fields at the measurement locations, the measurement model \(M\) predicts the data from them.

fields: list[str]

Names of the observed state fields.

sampler: SpatialSampler

The spatial sampler \(S\).

model: MeasurementModel

The measurement model \(M\).

property size: int

Number of entries of the predicted data, over all ranks.

The models act entry by entry, so the predicted data have the sampler’s entries.

property global_indices: NDArray_i64

Positions of this rank’s entries in the measurement’s data, see kipe.sampling.SpatialSampler.global_indices.

kipe.measurements.build_observation_operator(name: str, options: MeasurementOptions, solver: ForwardSolver, comm: mpi4py.MPI.Comm = mpi4py.MPI.COMM_WORLD) → ObservationOperator

Construct the observation operator of a measurement.

Parameters:

• name – name of the measurement, for error messages

• options – the measurement options

• solver – the forward solver

• comm – communicator of the run

Returns:

the observation operator

Raises:

StudyFileError – if the measurement observes a field the solver does not have, or one its sampler cannot sample

class kipe.measurements.Measurement(name: str, operator: ObservationOperator, times: NDArray_f64, values: NDArray_f64, stddev: float)

Bases: object

A measurement: its data at all measurement times, and its observation operator.

Synthesis produces measurements, estimation consumes them.

name: str

Name of the measurement, for logs and error messages.

operator: ObservationOperator

The observation operator \(\mathcal{H}\), from a model state to predicted data.

times: NDArray_f64

The measurement times, shape (n,).

values: NDArray_f64

This rank’s entries of the measured data at each of the n times, at the positions operator.global_indices, shape (n, number of this rank's entries).

stddev: float

Standard deviation of the measurement noise, in the unit of the data.

kipe.measurements.measurement_times(times: list[float] | TimeRange) → NDArray_f64

Return the measurement times as an array.

Parameters:

times – the times of a measurement, a list or a range

Returns:

the times; for a range, from start up to and including stop (up to round-off)

kipe.measurements.read_numpy(path: str | Path) → tuple[NDArray_f64, NDArray_f64]

Read measurement data from a .npz file with the arrays times and values.

Parameters:

path – path to the .npz file

Returns:

• times, shape (n,)

• values, shape (n, m): m values at each of the n times

Raises:

StudyFileError – if the file cannot be read or does not hold the expected arrays

kipe.measurements.write_numpy(path: str | Path, times: NDArray_f64, values: NDArray_f64) → None

Write measurement data to a .npz file, creating its directory if needed.

Parameters:

• path – path to the .npz file

• times – the n measurement times, shape (n,)

• values – m values at each of the n times, shape (n, m)