kipe.sampling module

Spatial sampling: bringing the model fields to the measurement locations.

A SpatialSampler evaluates the fields a measurement observes where the measurement is taken, giving the sampled state \(y\) that the measurement model (see kipe.measurements) compares with the data. The samplers here need only the field arrays and their own configuration; samplers that need the discretization (mesh, degrees of freedom) live with their backend, e.g., in kipe.fenicsx.sampling.

In parallel, each entry of the sampled vector is held by exactly one rank: a sampler knows the vector’s size over all ranks and, per rank, the global_indices of the entries it returns. The measurement’s data are read and written in the order of these positions, so they do not depend on the number of ranks.

To add a sampler: subclass SpatialSampler, set size and global_indices, implement sample(), add its options to kipe.options and a case to build_sampler().

class kipe.sampling.SpatialSampler[source]

Bases: ABC

Evaluates the model fields at the measurement locations.

size: int

Number of entries of the sampled vector, over all ranks.

global_indices: NDArray_i64

Positions of this rank’s entries in the sampled vector, in the order sample() returns them; each entry is held by exactly one rank.

abstractmethod sample(fields: Mapping[str, NDArray_f64]) → NDArray_f64[source]

Evaluate the model fields at the measurement locations.

Parameters:

fields – the state fields the measurement observes (its fields), rank-local

Returns:

this rank’s entries of the sampled state \(y\), at the positions global_indices; a new array, not a view of fields or of internal buffers

class kipe.sampling.ArraySampler(fields: list[str], state_spec: Mapping[str, FieldSpec], comm: mpi4py.MPI.Comm = mpi4py.MPI.COMM_WORLD)[source]

Bases: SpatialSampler

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

The fields must be replicated, i.e., held in full by every rank; rank 0 holds all entries of the sampled vector, the other ranks none.

Parameters:

  • fields – names of the observed fields, in the order of concatenation

  • state_spec – the forward solver’s state fields

  • comm – communicator of the run

Raises:

StudyFileError – if a field is distributed over the ranks; its entries would depend on the partition, which needs a sampler of the backend, e.g., fenicsx.mesh

sample(fields: Mapping[str, NDArray_f64]) → NDArray_f64[source]

Concatenate the observed fields, on rank 0.

Parameters:

fields – the observed state fields

Returns:

all entries of the fields, concatenated (a new array); empty on the other ranks

kipe.sampling.build_sampler(options: ArraySamplingOptions | MeshSamplingOptions | PointSamplingOptions, fields: list[str], solver: ForwardSolver, comm: mpi4py.MPI.Comm = mpi4py.MPI.COMM_WORLD) → SpatialSampler[source]

Construct the sampler given by the spatial_sampling options of a measurement.

Parameters:

  • options – spatial_sampling options of the measurement

  • fields – names of the fields the measurement observes

  • solver – the forward solver; backend samplers take what they need from it, e.g., the function spaces

  • comm – communicator of the run

Returns:

the spatial sampler

Raises:

StudyFileError – if a backend sampler is used but its backend is not installed