From e9ad4a85eec877b95d1c8da1179694b158a4d433 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Dieter=20Werthm=C3=BCller?= <mail@werthmuller.org>
Date: Wed, 12 Jun 2024 17:31:30 +0200
Subject: [PATCH] Spelling etc

---
 .gitignore                   |  2 ++
 docs/manual/about.rst        | 40 +++++++++++++++++++-----------------
 docs/manual/installation.rst |  6 ++++--
 3 files changed, 27 insertions(+), 21 deletions(-)

diff --git a/.gitignore b/.gitignore
index a53eba5..e4bc802 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,5 +1,7 @@
 # Directories and file types
 __pycache__/
+*.nc
+*.pdf
 
 # Sphinx
 docs/_build/
diff --git a/docs/manual/about.rst b/docs/manual/about.rst
index e501e7a..acd611d 100644
--- a/docs/manual/about.rst
+++ b/docs/manual/about.rst
@@ -13,9 +13,12 @@ ES-MDA
 In the following an introduction to the ES-MDA (Ensemble Smoother with Multiple
 Data Assimilation) algorithm following [EmRe13]_:
 
-In history-matching problems, it is common to only consider the
-parameter-estimation problem (neglecting model uncertainties). In that case,
-the analyzed vector of model parameters :math:`m^a` is given by
+In history-matching problems, it is common to consider solely the
+parameter-estimation problem and thereby neglecting model uncertainties. Thus,
+unlike EnKF, the parameters and states are always consistent (Thulin et al.,
+2007). This fact helps to explain the better data matches obtained by ES-MDA
+compared to EnKF. The analyzed vector of model parameters :math:`m^a` is given
+in that case by
 
 .. math::
     m_j^a = m_j^f + C_\text{MD}^f \left(C_\text{DD}^f + \alpha C_\text{D}
@@ -25,24 +28,25 @@ for ensembles :math:`j=1, 2, \dots, N_e`. Here,
 
 - :math:`^a`: analysis;
 - :math:`^f`: forecast;
-- :math:`m^f`: prior vector of model parameters;
-- :math:`d^f`: vector of predicted data;
+- :math:`m^f`: prior vector of model parameters (:math:`N_m`);
 - :math:`C_\text{MD}^f`: cross-covariance matrix between :math:`m^f` and
-  :math:`d^f`;
-- :math:`C_\text{DD}^f`: :math:`N_d \times N_d` auto-covariance matrix of
-  predicted data;
-- :math:`d_\text{obs}`: :math:`N_d`-dimensional vector of observed data;
-- :math:`d_\text{uc} = d_\text{obs} + \sqrt{\alpha}C_\text{D}^{1/2} z_d, \ z_d
-  \sim \mathcal{N}(0, I_{N_d})`;
-- :math:`C_\text{D}`: :math:`N_d \times N_d` covariance matrix of observed data
-  measurement errors;
-- :math:`\alpha`: ES-MDA coefficient.
+  :math:`d^f` (:math:`N_m \times N_d`);
+- :math:`C_\text{DD}^f`:  auto-covariance matrix of predicted data
+  (:math:`N_d \times N_d`);
+- :math:`C_\text{D}`: covariance matrix of observed data measurement errors
+  (:math:`N_d \times N_d`);
+- :math:`\alpha`: ES-MDA coefficient;
+- :math:`d_\text{uc}` : vector of perturbed data, obtained from the
+  vector of observed data, :math:`d_\text{obs}` (:math:`N_d`);
+- :math:`d^f`: vector of predicted data (:math:`N_d`).
 
 The prior vector of model parameters, :math:`m^f_j`, can in reality be
 :math:`j` possible models :math:`m^f` given from an analyst (e.g., the
 geologist). In theoretical tests, these are usually created by perturbing the
 prior :math:`m^f` by, e.g., adding random Gaussian noise.
 
+The ES-MDA algorithm follows [EmRe13]_:
+
 1. Choose the number of data assimilations, :math:`N_a`, and the coefficients
    :math:`\alpha_i` for :math:`i = 1, \dots, N_a`.
 2. For :math:`i = 1` to :math:`N_a`:
@@ -73,13 +77,11 @@ method. In this case, we start assimilating data with a large value of
 :math:`\alpha`, which reduces the magnitude of the initial updates; then, we
 gradually decrease :math:`\alpha`.
 
-For ES-MDA, we only consider the parameter-estimation problem. Thus, unlike EnKF, the parameters and states are always consistent (Thulin et al., 2007). This fact helps to explain the better data matches obtained by ES-MDA compared to EnKF.
-
 
 Reservoir Model
 ---------------
 
 The implemented small 2D Reservoir Simulator was created by following the
-course **AESM304A - Flow and Simulation of Subsurface processes** at Delft
-University of Technology (TUD); this particular part was taught by Dr. D.V.
-Voskov, https://orcid.org/0000-0002-5399-1755.
+course material of **AESM304A - Flow and Simulation of Subsurface processes**
+at Delft University of Technology (TUD); this particular part was taught by Dr.
+D.V. Voskov, https://orcid.org/0000-0002-5399-1755.
diff --git a/docs/manual/installation.rst b/docs/manual/installation.rst
index 2c002e4..3d5e40a 100644
--- a/docs/manual/installation.rst
+++ b/docs/manual/installation.rst
@@ -1,16 +1,18 @@
 Installation
 ============
 
-You can install the latest release of resmda simply via ``pip``:
+You can install the latest release of resmda simply via ``pip``
 
 .. code-block:: console
 
    pip install resmda
 
-or clone the repository and run within the command
+or clone the repository and install it manually with
 
 .. code-block:: console
 
+   git clone git@github.com:tuda-geo/resmda
+   cd resmda
    make install
 
 to get the latest version.