fips.problem#
Core inversion classes and functions.
- This module provides core classes and utilities for formulating and solving inverse problems, including:
Abstract base classes for inversion estimators.
Registry for estimator implementations.
Forward operator and covariance matrix wrappers with index-aware functionality.
Utilities for convolving state vectors with forward operators.
The InverseProblem class, which orchestrates the alignment of data, prior information, error covariances, and the solution process.
Classes
|
Inverse problem class for estimating model states from observations. |
- class fips.problem.InverseProblem(estimator, obs, prior, forward_operator, prior_error, modeldata_mismatch, constant=None, state_index=None, estimator_kwargs=None, coord_decimals=6)[source]#
Inverse problem class for estimating model states from observations.
Represents a statistical inverse problem for estimating model states from observed data using Bayesian inference and linear forward operators.
An inverse problem seeks to infer unknown model parameters (the “state”) from observed data, given prior knowledge and a mathematical relationship (the forward operator) that links the state to the observations. This class provides a flexible interface for formulating and solving such problems using various estimators.
- Parameters:
estimator (str or type[Estimator]) – The estimator to use for solving the inverse problem. Can be the name of a registered estimator or an Estimator class.
obs (pd.Series) – Observed data as a pandas Series, indexed by observation dimensions.
prior (pd.Series) – Prior estimate of the model state as a pandas Series, indexed by state dimensions.
forward_operator (ForwardOperator or pd.DataFrame) – Linear operator mapping model state to observations. Can be a ForwardOperator instance or a pandas DataFrame with appropriate indices and columns.
prior_error (CovarianceMatrix) – Covariance matrix representing uncertainty in the prior state estimate.
modeldata_mismatch (CovarianceMatrix) – Covariance matrix representing uncertainty in the observed data (model-data mismatch).
constant (float or pd.Series or None, optional) – Optional constant term added to the forward model output. If not provided, defaults to zero.
state_index (pd.Index or None, optional) – Index for the state variables. If None, uses the index from the prior.
estimator_kwargs (dict, optional) – Additional keyword arguments to pass to the estimator.
coord_decimals (int, optional) – Number of decimal places to round coordinate values for alignment (default is 6).
- Raises:
TypeError – If input types are incorrect.
ValueError – If input data dimensions are incompatible or indices do not align.
- obs_index#
Index of the observations used in the problem.
- Type:
pd.Index
- state_index#
Index of the state variables used in the problem.
- Type:
pd.Index
- posterior#
Posterior mean estimate of the model state.
- Type:
pd.Series
- posterior_error#
Posterior error covariance matrix.
- Type:
- posterior_obs#
Posterior mean estimate of the observations.
- Type:
pd.Series
- prior_obs#
Prior mean estimate of the observations.
- Type:
pd.Series
- xr#
Xarray interface for accessing inversion results as xarray DataArrays.
- Type:
InverseProblem._XR
- solve() dict[str, pd.Series | CovarianceMatrix | pd.Series][source]#
Solves the inverse problem and returns a dictionary with posterior state, posterior error covariance, and posterior observation estimates.
Notes
This class is designed for linear inverse problems with Gaussian error models, commonly encountered in geosciences, remote sensing, and other fields where model parameters are inferred from indirect measurements. It supports flexible input formats and provides robust alignment and validation of input data.
- __init__(estimator, obs, prior, forward_operator, prior_error, modeldata_mismatch, constant=None, state_index=None, estimator_kwargs=None, coord_decimals=6)[source]#
Initialize the InverseProblem.
- Parameters:
estimator (str or type[Estimator]) – Estimator class or its name as a string.
obs (pd.Series) – Observed data.
prior (pd.Series) – Prior model state estimate.
forward_operator (pd.DataFrame) – Forward operator matrix.
prior_error (CovarianceMatrix) – Prior error covariance matrix.
modeldata_mismatch (CovarianceMatrix) – Model-data mismatch covariance matrix.
constant (float or pd.Series, optional) – Constant data, defaults to 0.0.
state_index (pd.Index, optional) – Index for the state variables.
estimator_kwargs (dict, optional) – Additional keyword arguments for the estimator.
obs_aggregation (optional) – Observation aggregation method.
coord_decimals (int, optional) – Number of decimal places for rounding coordinates.
- Raises:
TypeError – If any of the inputs are of the wrong type.
ValueError – If there are issues with the input data (e.g., incompatible dimensions).
- solve()[source]#
Solve the inversion problem using the configured estimator.
- Returns:
A dictionary containing the posterior estimates: - ‘posterior’: Pandas series with the posterior mean model estimate. - ‘posterior_error’: Covariance object with the posterior error covariance matrix. - ‘posterior_obs’: Pandas series with the posterior observation estimates.
- Return type:
- property posterior: Series#
Posterior state estimate.
- Returns:
Pandas series with the posterior mean model estimate.
- Return type:
pd.Series
- property posterior_obs: Series#
Posterior observation estimates.
- Returns:
Pandas series with the posterior observation estimates.
- Return type:
pd.Series
- property posterior_error: SymmetricMatrix#
Posterior error covariance matrix.
- Returns:
CovarianceMatrix instance with the posterior error covariance matrix.
- Return type: