openghg_inversions.basis.covariance_products#

Labelled in-memory native-covariance products for retained scaling states.

This module is an eager numerical kernel. Callers supply a canonical native sensitivity H and basis prolongation U; basis operators own any source expansion. Their payloads may remain sparse or Dask-backed until the named projection boundary, where related arrays are materialized together. Custom restrictions are likewise materialized once and reused by all retained-state RHS blocks.

For native covariance B and retained restriction Pi, the kernel returns C_alpha = Pi B Pi.T, H U_*, H B Pi.T, and H B H.T (or its diagonal). Strategies return authoritative Pi; the kernel derives B Pi.T, C_alpha, and U_* = B Pi.T C_alpha^-1. The default strategy preserves bucket prolongation by deriving Pi_U = (U.T B^-1 U)^-1 U.T B^-1. The kernel trusts the covariance action’s real self-adjoint positive-definite semantics and compatible inverse rather than globally certifying a matrix-free operator. Durable artifact identity and persistence are intentionally deferred to the artifact-I/O layer.

class openghg_inversions.basis.covariance_products.NativeCovarianceProducts(restriction: DataArray, prolongation: DataArray, state_covariance: DataArray, effective_observation_operator: DataArray, observation_state_cross_covariance: DataArray, native_observation_covariance: DataArray, strategy: str, observation_covariance_view: Literal['dense', 'diagonal'])#

Bases: object

Labelled in-memory product blocks induced by one retained restriction.

Variables:

  • restriction (xarray.core.dataarray.DataArray) – Dimensionless Pi with dimensions (state_dim, *native_dims).

  • prolongation (xarray.core.dataarray.DataArray) – Derived dimensionless covariance-natural U_* with dimensions (*native_dims, state_dim).

  • state_covariance (xarray.core.dataarray.DataArray) – Positive-definite dimensionless C_alpha with distinct typed row/column state dimensions.

  • effective_observation_operator (xarray.core.dataarray.DataArray) – H U_* with dimensions (observation_dim, state_dim) and sensitivity units.

  • observation_state_cross_covariance (xarray.core.dataarray.DataArray) – H B Pi.T with dimensions (observation_dim, state_column_dim) and sensitivity units.

  • native_observation_covariance (xarray.core.dataarray.DataArray) – Dense positive-semidefinite (and possibly singular) H B H.T on distinct typed observation axes, or its nonnegative observation-axis diagonal. Units are squared sensitivity units.

  • strategy (str) – Identifier of the strategy that selected Pi.

  • observation_covariance_view (Literal['dense', 'diagonal']) – Whether the observation covariance field contains the dense matrix or its diagonal.

Notes

Freezing the dataclass prevents field reassignment, but the contained DataArrays remain mutable. Product attributes are construction-time snapshots, not live views of input attribute mappings.

effective_observation_operator: DataArray#
native_observation_covariance: DataArray#
observation_covariance_view: Literal['dense', 'diagonal']#
observation_state_cross_covariance: DataArray#
prolongation: DataArray#
restriction: DataArray#
state_covariance: DataArray#
strategy: str#
class openghg_inversions.basis.covariance_products.PreserveBucketProlongation(name: str = 'preserve_bucket_prolongation')#

Bases: object

Derive Pi_U so covariance-weighted prolongation equals U_bucket.

name: str#
projection(covariance: InvertibleNativeCovarianceAction, basis_prolongation: DataArray, *, native_dims: tuple[str, ...], state_dim: str) → RetainedProjection#

Construct the prior-precision-compatible restriction.

Parameters:

  • covariance – Invertible labelled action for native covariance B.

  • basis_prolongation – Eager canonical bucket prolongation U.

  • native_dims – Ordered native dimensions.

  • state_dim – Retained-state dimension.

Returns:

The authoritative bucket-compatible restriction Pi_U.

Raises:

ValueError – If U is invalid or lacks full column rank.

class openghg_inversions.basis.covariance_products.RetainedProjection(restriction: DataArray, strategy: str)#

Bases: object

A labelled retained restriction selected by one strategy.

Variables:

  • restriction (xarray.core.dataarray.DataArray) – Dimensionless Pi with dimensions (state_dim, *native_dims). The frozen dataclass does not freeze this mutable DataArray.

  • strategy (str) – Stable identifier for the scientific projection choice.

restriction: DataArray#
strategy: str#
class openghg_inversions.basis.covariance_products.RetainedProjectionStrategy(*args, **kwargs)#

Bases: Protocol

Extension seam for choosing authoritative retained coefficients.

projection(covariance: InvertibleNativeCovarianceAction, basis_prolongation: DataArray, *, native_dims: tuple[str, ...], state_dim: str) → RetainedProjection#

Return the authoritative labelled retained restriction Pi.

Parameters:

  • covariance – Labelled native covariance action.

  • basis_prolongation – Dimensionless basis U with dimensions (*native_dims, state_dim).

  • native_dims – Ordered native covariance dimensions.

  • state_dim – Retained-state dimension.

Returns:

A dimensionless restriction with dimensions (state_dim, *native_dims). The kernel derives B Pi.T, C_alpha, and U_* from it.

openghg_inversions.basis.covariance_products.project_native_covariance(*, covariance: InvertibleNativeCovarianceAction, basis_prolongation: DataArray, state_dim: str, native_sensitivity: DataArray, observation_dim: str, observation_covariance: Literal['dense', 'diagonal'] = 'dense', observation_batch_size: int = 64, strategy: RetainedProjectionStrategy | None = None) → NativeCovarianceProducts#

Compute coherent labelled native-covariance products eagerly.

Parameters:

  • covariance – Labelled native covariance action with a compatible solve.

  • basis_prolongation – Canonical labelled U from the basis-side native expansion boundary.

  • state_dim – Retained-state dimension shared by U and Pi.

  • native_sensitivity – Canonical labelled native sensitivity H.

  • observation_dim – Observation dimension in H.

  • observation_covariance – Return dense H B H.T or its diagonal.

  • observation_batch_size – Positive integral number of covariance right-hand sides per eager block.

  • strategy – Authoritative restriction choice; defaults to the bucket-preserving restriction.

Returns:

Frozen in-memory labelled product value object. Scaling covariance, restriction, and prolongation have units "1". Products linear in H inherit its units; observation covariance uses squared H units when supplied.

The kernel trusts the covariance action’s declared real, self-adjoint, positive-definite semantics. It does not globally certify a matrix-free B or revalidate products constructed here.

Raises:

ValueError – If labelled inputs cannot be exactly aligned, the batch size is not positive, or a required Cholesky factorization fails.