openghg_inversions.source_covariance#

Compose labelled native covariance actions into independent source blocks.

The multisource covariance represented here is block diagonal by source. Each configured source owns a SeparableExponentialCovariance on the same labelled spatial grid, while amplitudes, correlation lengths, and optional class masks may differ by source. Applying or solving the composite action dispatches to each source block independently, preserves all labelled right-hand-side dimensions, and never constructs a dense cross-source matrix.

Source labels are non-empty strings whose insertion order defines the canonical block order. Input arrays must carry exactly those string labels in that order; values are not coerced between types. The leading native source dimension defaults to "native_source". This is intentionally distinct from the "source" level on OGI’s gathered retained-state MultiIndex because xarray cannot represent a dimension and a MultiIndex level with the same name in one prolongation array.

IndependentSourceCovariance can serialize its complete reproducible configuration, including typed class labels, to an xarray dataset. Restoration validates the schema, source labels, required variables, and spatial coordinate metadata before reconstructing the component actions.

Source dispatch intentionally uses eager per-source sel, component operator, and concat calls. A source-only apply_ufunc or source chunking is not equivalent: each component consumes the full labelled spatial grid and owns an explicit eager NumPy boundary, rather than acting pointwise along a source vector.

IndependentSourceCovariance is an ordinary slotted, identity-based action. It copies the source mapping once and exposes it through a read-only proxy; component actions and their borrowed coordinate properties are not copied on ordinary access.

class openghg_inversions.source_covariance.IndependentSourceCovariance(source_covariances: Mapping[str, SeparableExponentialCovariance], source_dim: str = 'native_source')#

Bases: object

Block-diagonal native covariance over an ordered source mapping.

Parameters:

  • source_covariances – Non-empty insertion-ordered mapping from source labels to separable spatial covariance actions on the same grid.

  • source_dim – Explicit native source dimension. It should not collide with a level name on the retained state MultiIndex.

Raises:

  • TypeError – If a source block is not a SeparableExponentialCovariance or the source mapping cannot be copied.

  • ValueError – If the mapping is empty, source labels or source_dim are invalid, or block spatial dimensions or grids differ.

Notes

The source mapping and source-dimension properties are read-only. Changed configuration requires explicit reconstruction.

apply(rhs: DataArray) → DataArray#

Apply independent source covariance blocks to labelled RHS arrays.

Parameters:

rhs – Array containing the exact source and spatial native labels; all other right-hand-side dimensions are preserved.

Returns:

Blockwise B rhs in the original dimension order.

Raises:

  • TypeError – If rhs is not an xarray data array.

  • ValueError – If source or spatial dimensions, coordinates, labels, or numerical values are missing or invalid.

classmethod from_dataset(dataset: Dataset) → IndependentSourceCovariance#

Restore source blocks from to_dataset() output.

Parameters:

dataset – Versioned independent-source covariance dataset.

Returns:

Reconstructed source-block covariance action with class-label values, name, and JSON-compatible attributes restored.

Raises:

ValueError – If schema metadata, source or spatial coordinates, or required variables are absent or invalid, or encoded metadata cannot be decoded.

property native_dims: tuple[str, ...]#

Return the source dimension followed by common spatial dimensions.

Returns:

Native dimensions in vectorisation order.

schema = 'openghg_inversions.independent_source_covariance'#
schema_version = 1#
solve(rhs: DataArray) → DataArray#

Solve independent source covariance blocks for labelled RHS arrays.

Parameters:

rhs – Array containing the exact source and spatial native labels; all other right-hand-side dimensions are preserved.

Returns:

Blockwise B^-1 rhs in the original dimension order.

Raises:

  • TypeError – If rhs is not an xarray data array.

  • ValueError – If source or spatial dimensions, coordinates, labels, or numerical values are missing or invalid.

  • numpy.linalg.LinAlgError – If a class-blocked component solve does not converge.

property source_covariances: Mapping[str, SeparableExponentialCovariance]#

Return the read-only source-to-covariance mapping.

property source_dim: str#

Return the read-only native source dimension name.

property source_labels: tuple[str, ...]#

Return configured source labels in canonical insertion order.

Returns:

Source labels defining the block order.

to_dataset() → Dataset#

Serialize source order and reproducible component configuration.

Returns:

Versioned dataset containing source-specific covariance parameters, independent eager copies of the common spatial coordinates, and any encoded class labels. The returned dataset may be mutated without changing component actions.

Raises:

TypeError – If a class label or class-label attribute cannot be represented by the tagged JSON encoding.