pyesmda 0.4.3
Python Ensemble Smoother with Multiple Data Assimilation.
License: MIT license
Requires Python: <4,>=3.7
Keywords: esmda,es-mda,inversion,inverse problem,parameter estimation,stochastic-optimization,ensemble smoother

=======
pyESMDA
=======


.. image:: https://img.shields.io/badge/License-MIT license-blue.svg
    :target: https://gitlab.com/antoinecollet5/pyesmda/-/blob/master/LICENSE

.. image:: https://img.shields.io/badge/dynamic/json?color=green&label=gitlab%20stars&query=%24.star_count&url=https%3A%2F%2Fgitlab.com%2Fapi%2Fv4%2Fprojects%2F31672379
    :target: https://img.shields.io/badge/dynamic/json?color=green&label=gitlab%20stars&query=%24.star_count&url=https%3A%2F%2Fgitlab.com%2Fapi%2Fv4%2Fprojects%2F31672379`
    :alt: Stars

.. image:: https://img.shields.io/pypi/pyversions/pyesmda.svg
    :target: https://pypi.org/pypi/pyesmda
    :alt: Python

.. image:: https://img.shields.io/pypi/v/pyesmda.svg
    :target: https://pypi.org/pypi/pyesmda
    :alt: PyPI

.. image:: https://pepy.tech/badge/pyesmda
    :target: https://pepy.tech/project/pyesmda
    :alt: Downoads

.. image:: https://gitlab.com/antoinecollet5/pyesmda/badges/master/pipeline.svg
    :target: https://gitlab.com/antoinecollet5/pyesmda/pipelines/
    :alt: Build Status

.. image:: https://readthedocs.org/projects/pyesmda/badge/?version=latest
    :target: https://pyesmda.readthedocs.io/en/latest/?badge=latest
    :alt: Documentation Status

.. image:: https://gitlab.com/antoinecollet5/pyesmda/badges/master/coverage.svg
    :target: https://gitlab.com/antoinecollet5/pyesmda/pipelines/
    :alt: Coverage

.. image:: https://app.codacy.com/project/badge/Grade/bc4d1a8a1f574273a053a32d44931c00
    :target: https://www.codacy.com/gl/antoinecollet5/pyesmda/dashboard?utm_source=gitlab.com&amp;utm_medium=referral&amp;utm_content=antoinecollet5/pyesmda&amp;utm_campaign=Badge_Grade
    :alt: codacy

.. image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit
   :target: https://github.com/pre-commit/pre-commit
   :alt: pre-commit

.. image:: https://img.shields.io/badge/code%20style-black-000000.svg?style=flat
    :target: https://github.com/psf/black
    :alt: Black

.. image:: https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat
    :target: https://timothycrosley.github.io/isort
    :alt: isort

.. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.7425670.svg
   :target: https://doi.org/10.5281/zenodo.7425670
   :alt: DOI

Python Ensemble Smoother with Multiple Data Assimilation

**pyesmda** is an open-source, pure python, and object-oriented library that provides
a user friendly implementation of one of the most popular ensemble based method
for parameters estimation and data assimilation: the Ensemble Smoother with
Multiple Data Assimilation (ES-MDA) algorithm, introduced by Emerick and Reynolds [1-2].

Thanks to its simple formulation, ES-MDA of Emerick and Reynolds (2012) is perhaps the
most used iterative form of the ensemble smoother in geoscience applications.

* Free software: MIT license
* Documentation: https://pyesmda.readthedocs.io.

How to Cite
-----------

**Software/Code citation for pyESMDA:**

Antoine Collet. (2023). pyESMDA - Python Ensemble Smoother with Multiple Data Assimilation (v0.4.3). Zenodo. https://doi.org/10.5281/zenodo.7425670


References
----------

* [1] Emerick, A. A. and A. C. Reynolds, Ensemble smoother with multiple
  data assimilation, Computers & Geosciences, 2012.
* [2] Emerick, A. A. and A. C. Reynolds. (2013). History-Matching
  Production and Seismic Data in a Real Field Case Using the Ensemble
  Smoother With Multiple Data Assimilation. Society of Petroleum
  Engineers - SPE Reservoir Simulation Symposium
  1.    2. 10.2118/163675-MS.

==============
Changelog
==============

0.4.3 (2023-08-03)
------------------

* `!PR39 <https://gitlab.com/antoinecollet5/pyesmda/-/merge_requests/39>`_ ENH: introduce abstraction through a base class and remove some code duplication (see solve methods) and remove some conflicts around the inflation parameters.
  ESMDA-RS now supports local update (**batch_size** and **is_parallel_analyse_step**) and initial inflation of the ensemble (**cov_mm_inflation_factor**). The keyword `seed` has been replaced by a more flexible `random_state`, that accepts
  **np.random.RandomState** and **Generator** in addition to classic seeds. In ESMDA-RS, the **std_m_prior** is no longer mandatory and can be omitted. In that case,
  the initial adjusted parameter variance is estimated from the ensemble.

0.4.2 (2023-08-02)
------------------

* `!PR36 <https://gitlab.com/antoinecollet5/pyesmda/-/merge_requests/36>`_ ENH: add some correlation functions.
* Also add new hooks in pre-commit.

0.4.1 (2023-07-31)
------------------

* `!PR33 <https://gitlab.com/antoinecollet5/pyesmda/-/merge_requests/33>`_ FIX: the covariance inflation is now applied before the forecast step.

0.4.0 (2023-06-28)
------------------

* `!PR30 <https://gitlab.com/antoinecollet5/pyesmda/-/merge_requests/30>`_ ENH: Allow to perform the analyse step by batches of gridblocks and avoid the
  construction on large (N, M) correlation matrices. Three new parameters have been introduced - **batch_size**: Number of parameters that are assimilated at once. This option is
  available to overcome memory limitations when the number of updated parameters is large. In that case, the size of the covariance matrices tends to explode
  and the update step must be performed by chunks of parameters.
  **is_parallel_analyse_step**: Whether to use parallel computing for the analyse step if the number of batch is above one. The default is True.
  **n_batches**: Number of batches required during the update step.
  It also introduces the support for sparse matrices for correlation matrices and observation covariance matrix.
* `!PR29 <https://gitlab.com/antoinecollet5/pyesmda/-/merge_requests/29>`_ ENH: Add a function to get the ensemble variance. Convinient to compute the uncertainty a posteriori without the full covariance matrix approximation.
* STYLE: Format with updated version of black.

0.3.3 (2022-12-12)
------------------

* `!PR27 <https://gitlab.com/antoinecollet5/pyesmda/-/merge_requests/27>`_ STYLE: Add a DOI number from zenodo and correct typos.

0.3.2 (2022-10-07)
------------------

* `!PR21 <https://gitlab.com/antoinecollet5/pyesmda/-/merge_requests/21>`_ FIX: design - some static methods should be moved to a utils.py file.

0.3.1 (2022-08-12)
------------------

* `!PR20 <https://gitlab.com/antoinecollet5/pyesmda/-/merge_requests/20>`_ Fix ESMDA-RS documentation and change the
  **cov_m_prior** input parameter to its diagonal **std_m_prior** to be consistent with the implementation and be less memory consuming.

0.3.0 (2022-08-12)
------------------

* `!PR15 <https://gitlab.com/antoinecollet5/pyesmda/-/merge_requests/15>`_ Implement ESMDA-RS (restricted step) which provides
  an automatic estimation of the inflation parameter and determines when to stop (number of assimilations) on the fly.
* `!PR14 <https://gitlab.com/antoinecollet5/pyesmda/-/merge_requests/14>`_ Add keyword **is_forecast_for_last_assimilation** to choose whether to
  compute the predictions for the ensemble obtained at the last assimilation step. The default is True.
* `!PR13 <https://gitlab.com/antoinecollet5/pyesmda/-/merge_requests/13>`_ Implementation: Faster analyse step by avoiding matrix inversion.
* `!PR12 <https://gitlab.com/antoinecollet5/pyesmda/-/merge_requests/12>`_ Add a seed parameter for the random
  number generation **seed** in the prediction perturbation step.
  To avoid confusion , **cov_d** has been renamed **cov_obs**.
* `!PR11 <https://gitlab.com/antoinecollet5/pyesmda/-/merge_requests/11>`_ Implement the covariance localization. Introduces the
  correlation matrices **dd_correlation_matrix** and **md_correlation_matrix**.
  To avoid confusion , **cov_d** has been renamed **cov_obs**.
* `!PR10 <https://gitlab.com/antoinecollet5/pyesmda/-/merge_requests/10>`_ Implement the parameters auto-covariance inflation.
  Add the estimation of the parameters auto-covariance matrix. The parameter **alpha** becomes **cov_obs_inflation_factors**.


0.2.0 (2022-07-23)
------------------

* `!PR6 <https://gitlab.com/antoinecollet5/pyesmda/-/merge_requests/6>`_ The parameter **stdev_d** becomes **cov_d**.
* `!PR5 <https://gitlab.com/antoinecollet5/pyesmda/-/merge_requests/5>`_ The parameter **n_assimilation** becomes **n_assimilations**.
* `!PR4 <https://gitlab.com/antoinecollet5/pyesmda/-/merge_requests/4>`_ The parameter **stdev_m** is removed.
* `!PR3 <https://gitlab.com/antoinecollet5/pyesmda/-/merge_requests/3>`_ Type hints are now used in the library.
* `!PR2 <https://gitlab.com/antoinecollet5/pyesmda/-/merge_requests/2>`_ Add the possibility to save the history of m and d. This introduces a new knew
  keyword (boolean) for the constructor **save_ensembles_history**.
  Note that the **m_mean** attribute is depreciated and two new attributes are
  introduced: **m_history**, **d_history** respectively to access the successive
  parameter and predictions ensemble.


0.1.0 (2021-11-28)
------------------


* First release on PyPI.

MIT License

Copyright (c) 2021, Antoine Collet

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.