pyesmda.ESMDA

class pyesmda.ESMDA(obs: ndarray[Any, dtype[float64]], m_init: ndarray[Any, dtype[float64]], cov_d: ndarray[Any, dtype[float64]], forward_model: Callable[[...], ndarray[Any, dtype[float64]]], forward_model_args: Sequence[Any] = (), forward_model_kwargs: Optional[Dict[str, Any]] = None, n_assimilations: int = 4, alpha: Optional[Sequence[float]] = None, m_bounds: Optional[ndarray[Any, dtype[float64]]] = None, save_ensembles_history: bool = False)

Bases: object

Ensemble Smoother with Multiple Data Assimilations.

Implement the ES-MDA as proposed by Emerick, A. A. and A. C. Reynolds [Emerick and Reynolds, 2013, Emerick and Reynolds, 2013].

Attributes

• d_dim (int) – Number of observation values \(N_{obs}\), and consequently of predicted values.

• obs (npt.NDArray[np.float64]) – Obsevrations vector with dimensions (\(N_{obs}\)).

• cov_d (npt.NDArray[np.float64]) – Covariance matrix of observed data measurement errors with dimensions (\(N_{obs}\), \(N_{obs}\)).

• d_obs_uc (npt.NDArray[np.float64]) – Vectors of pertubed observations with dimension (\(N_{e}\), \(N_{obs}\)).

• d_pred (npt.NDArray[np.float64]) – Vectors of predicted values (one for each ensemble member) with dimensions (\(N_{e}\), \(N_{obs}\)).

• d_history (List[npt.NDArray[np.float64]]) – List of vectors of predicted values obtained at each assimilation step.

• m_prior – Vectors of parameter values (one vector for each ensemble member) used in the last assimilation step. Dimensions are (\(N_{e}\), \(N_{m}\)).

• m_bounds (npt.NDArray[np.float64]) – Lower and upper bounds for the \(N_{m}\) parameter values. Expected dimensions are (\(N_{m}\), 2) with lower bounds on the first column and upper on the second one.

• m_history (List[npt.NDArray[np.float64]]) – List of successive m_prior.

• cov_md (npt.NDArray[np.float64]) – Cross-covariance matrix between the forecast state vector and predicted data. Dimensions are (\(N_{m}, N_{obs}\))

• cov_dd (npt.NDArray[np.float64]) – Autocovariance matrix of predicted data. Dimensions are (\(N_{obs}, N_{obs}\))

• forward_model (callable) – Function calling the non-linear observation model (forward model) for all ensemble members and returning the predicted data for each ensemble member.

• forward_model_args (Tuple[Any]) – Additional args for the callable forward_model.

• forward_model_kwargs (Dict[str, Any]) – Additional kwargs for the callable forward_model.

• n_assimilations (int) – Number of data assimilations (\(N_{a}\)).

• alpha (List[float]) – List of multiplication factor used to inflate the covariance matrix of the measurement errors. Dimensions

• save_ensembles_history (bool) – Whether to save the history predictions and parameters over the assimilations.

__init__(obs: ndarray[Any, dtype[float64]], m_init: ndarray[Any, dtype[float64]], cov_d: ndarray[Any, dtype[float64]], forward_model: Callable[[...], ndarray[Any, dtype[float64]]], forward_model_args: Sequence[Any] = (), forward_model_kwargs: Optional[Dict[str, Any]] = None, n_assimilations: int = 4, alpha: Optional[Sequence[float]] = None, m_bounds: Optional[ndarray[Any, dtype[float64]]] = None, save_ensembles_history: bool = False) → None

Construct the instance.

Parameters

• obs (npt.NDArray[np.float64]) – Obsevrations vector with dimension \(N_{obs}\).

• m_init (npt.NDArray[np.float64]) – Initial ensemble of parameters vector with dimensions (\(N_{e}\), \(N_{m}\)).

• cov_d (npt.NDArray[np.float64]) – Covariance matrix of observed data measurement errors with dimensions (\(N_{obs}\), \(N_{obs}\)).

• forward_model (callable) – Function calling the non-linear observation model (forward model) for all ensemble members and returning the predicted data for each ensemble member.

• forward_model_args (Optional[Tuple[Any]]) – Additional args for the callable forward_model. The default is None.

• forward_model_kwargs (Optional[Dict[str, Any]]) – Additional kwargs for the callable forward_model. The default is None.

• n_assimilations (int, optional) – Number of data assimilations (\(N_{a}\)). The default is 4.

• alpha (Optional[Sequence[float]]) – Multiplication factor used to inflate the covariance matrix of the measurement errors. The default is None.

• m_bounds (Optional[npt.NDArray[np.float64]], optional) – Lower and upper bounds for the \(N_{m}\) parameter values. Expected dimensions are (\(N_{m}\), 2) with lower bounds on the first column and upper on the second one. The default is None.

• save_ensembles_history (bool, optional) – Whether to save the history predictions and parameters over the assimilations. The default is False.

Public methods summary

__init__(obs, m_init, cov_d, forward_model)	Construct the instance.
solve()	Solve the optimization problem with ES-MDA algorithm.

Methods definition

__annotations__ = {'__slots__': typing.List[str]}

__class__

alias of type

__delattr__(name, /)

Implement delattr(self, name).

__dir__()

Default dir() implementation.

__eq__(value, /)

Return self==value.

__format__(format_spec, /)

Default object formatter.

__ge__(value, /)

Return self>=value.

__getattribute__(name, /)

Return getattr(self, name).

__gt__(value, /)

Return self>value.

__hash__()

Return hash(self).

__init_subclass__()

This method is called when a class is subclassed.

The default implementation does nothing. It may be overridden to extend subclasses.

__le__(value, /)

Return self<=value.

__lt__(value, /)

Return self<value.

__ne__(value, /)

Return self!=value.

__new__(**kwargs)

__reduce__()

Helper for pickle.

__reduce_ex__(protocol, /)

Helper for pickle.

__repr__()

Return repr(self).

__setattr__(name, value, /)

Implement setattr(self, name, value).

__sizeof__()

Size of object in memory, in bytes.

__slots__: List[str] = ['obs', '_cov_d', 'd_obs_uc', 'd_pred', 'd_history', 'm_prior', '_m_bounds', 'm_history', 'cov_md', 'cov_dd', 'forward_model', 'forward_model_args', 'forward_model_kwargs', '_n_assimilations', '_alpha', 'save_ensembles_history']

__str__()

Return str(self).

__subclasshook__()

Abstract classes can override this to customize issubclass().

This is invoked early on by abc.ABCMeta.__subclasscheck__(). It should return True, False or NotImplemented. If it returns NotImplemented, the normal algorithm is used. Otherwise, it overrides the normal algorithm (and the outcome is cached).

_alpha

_analyse(assimilation_iteration: int) → None

Analysis step of the ES-MDA.

Update the vector of model parameters using

\[m^{l+1}_{j} = m^{l}_{j} + C^{l}_{MD}\left(C^{l}_{DD}+\alpha_{l+1} C_{D}\right)^{-1} \left(d^{l}_{uc,j} - d^{l}_{j} \right), \textrm{for } j=1,2,...,N_{e}.\]

_approximate_covariance_matrices() → None

Calculate Average and Covariance MD and Covariance DD.

The covariance matrices \(C^{l}_{MD}\) and \(C^{l}_{DD}\) are approximated from the ensemble in the standard way of EnKF [Evensen, 2007, Aanonsen et al., 2009].

_cov_d

_forecast() → None

Forecast step of ES-MDA.

Run the forward model from time zero until the end of the historical period from time zero until the end of the historical period to compute the vector of predicted data

\[d^{l}_{j}=g\left(m^{l}_{j}\right),\textrm{for }j=1,2,...,N_{e},\]

where \(g(·)\) denotes the nonlinear observation model, i.e., \(d^{l}_{j}\) is the \(N_{d}\)-dimensional vector of predicted data obtained by running the forward model reservoir simulation with the model parameters given by the vector \(m^{l}_{j}\) from time zero. Note that we use \(N_{d}\) to denote the total number of measurements in the entire history.

_m_bounds

_n_assimilations

_pertrub(assimilation_iteration: int) → None

Perturbation of the observation vector step of ES-MDA.

Perturb the vector of observations

\[d^{l}_{uc,j} = d_{obs} + \sqrt{\alpha_{l+1}}C_{D}^{1/2}Z_{d}, \textrm{for } j=1,2,...,N_{e},\]

where \(Z_{d} \sim \mathcal{N}(O, I_{N_{d}})\).

property alpha: Union[List[float], ndarray[Any, dtype[float64]]]

Get the alpha coefficients used by ES-MDA.

Single and multiple data assimilation are equivalent for the linear-Gaussian case as long as the factor \(\alpha_{l}\) used to inflate the covariance matrix of the measurement errors satisfy the following condition:

\[\sum_{l=1}^{N_{a}} \frac{1}{\alpha_{l}} = 1\]

In practise, \(\alpha_{l} = N_{a}\) is a good choice [Emerick and Reynolds, 2013].

property cov_d: ndarray[Any, dtype[float64]]

Get the observation errors covariance matrix.

cov_dd: npt.NDArray[np.float64]

cov_md: npt.NDArray[np.float64]

property d_dim: int

Return the number of forecast data.

d_history: list[npt.NDArray[np.float64]]

d_obs_uc: npt.NDArray[np.float64]

d_pred: npt.NDArray[np.float64]

forward_model: Callable

forward_model_args: Sequence[Any]

forward_model_kwargs: Dict[str, Any]

property m_bounds: ndarray[Any, dtype[float64]]

Get the parameter errors covariance matrix.

property m_dim: int

Return the length of the parameters vector.

m_history: list[npt.NDArray[np.float64]]

m_prior: npt.NDArray[np.float64]

property n_assimilations: int

Return the number of assimilations to perfom.

property n_ensemble: int

Return the number of ensemble members.

obs: npt.NDArray[np.float64]

save_ensembles_history: bool

solve() → None

Solve the optimization problem with ES-MDA algorithm.