Add geothermal example (#15)

Add geothermal example from Mona Devos; shows how to implement external modellers. --------- Co-authored-by: Dieter Werthmüller <[email protected]> Co-authored-by: gabrielserrao <[email protected]>
tuda-geo · Dec 2, 2024 · e415794 · e415794
1 parent 5d4579a
commit e415794
Show file tree

Hide file tree

Showing 13 changed files with 713 additions and 98 deletions.
diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml
@@ -25,7 +25,7 @@ jobs:
       - name: Setup Python
         uses: actions/setup-python@v5
         with:
-          python-version: "3.11"
+          python-version: "3.12"
 
       - name: Install dependencies
         shell: bash -l {0}

diff --git a/.github/workflows/linux.yml b/.github/workflows/linux.yml
@@ -28,8 +28,25 @@ concurrency:
 jobs:
   test:
 
-    name: basic
-    runs-on: ubuntu-latest
+    name: ${{ matrix.case.os }} py${{ matrix.case.python-version }}
+    runs-on: ${{ matrix.case.os }}-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        case:
+          - python-version: "3.10"
+            os: ubuntu
+          - python-version: "3.11"
+            os: ubuntu
+          - python-version: "3.12"
+            os: ubuntu
+          - python-version: "3.12"
+            os: macos
+          - python-version: "3.12"
+            os: windows
+          - python-version: "3.13"
+            os: ubuntu
 
     steps:
 
@@ -53,13 +70,13 @@ jobs:
       - name: Setup Python
         uses: actions/setup-python@v5
         with:
-          python-version: "3.11"
+          python-version: ${{ matrix.case.python-version }}
 
       - name: Install dependencies
         shell: bash -l {0}
         run: |
           python -m pip install --upgrade pip
-          python -m pip install .[all]
+          python -m pip install .[tests]
 
       - name: Flake8
         shell: bash -l {0}
@@ -99,7 +116,7 @@ jobs:
       - name: Setup Python
         uses: actions/setup-python@v5
         with:
-          python-version: "3.11"
+          python-version: "3.12"
 
       - name: Install dependencies
         run: |

diff --git a/.gitignore b/.gitignore
@@ -1,16 +1,13 @@
 # Directories and file types
 __pycache__/
-*.nc
-*.pdf
-*.zip
 
 # Sphinx
 docs/_build/
 docs/api/resmda*
 docs/savefig/
 docs/gallery/*
-download/
 docs/sg_execution_times.rst
+examples/data/
 
 # Pytest and coverage related
 htmlcov

diff --git a/README.rst b/README.rst
@@ -1,8 +1,8 @@
-``resmda`` - Simple Reservoir Modeller with ESMDA
-=================================================
+``resmda`` - ES-MDA with a simple 2D reservoir modeller
+=======================================================
 
 A simple 2D reservoir simulator and a straight-forward implementation of the
-basic *Ensemble smoother with multiple data assimilation* (ESMDA) algorithm as
+basic *Ensemble smoother with multiple data assimilation* (ES-MDA) algorithm as
 presented by Emerick and Reynolds, 2013.
 
 - **Documentation:** https://tuda-geo.github.io/resmda

diff --git a/docs/conf.py b/docs/conf.py
@@ -6,19 +6,19 @@
 
 # Load extensions
 extensions = [
-    # 'sphinx.ext.autodoc',
-    'numpydoc',
-    'sphinx_design',
-    'sphinx.ext.intersphinx',
-    # 'sphinx.ext.autosummary',
-    'sphinx.ext.mathjax',
-    'sphinx.ext.viewcode',
-    'sphinx.ext.todo',
-    'sphinx_gallery.gen_gallery',
-    'sphinx_automodapi.automodapi',
-    'matplotlib.sphinxext.plot_directive',
-    'IPython.sphinxext.ipython_console_highlighting',
-    'IPython.sphinxext.ipython_directive',
+    # "sphinx.ext.autodoc",
+    "numpydoc",
+    "sphinx_design",
+    "sphinx.ext.intersphinx",
+    # "sphinx.ext.autosummary",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.todo",
+    "sphinx_gallery.gen_gallery",
+    "sphinx_automodapi.automodapi",
+    "matplotlib.sphinxext.plot_directive",
+    "IPython.sphinxext.ipython_console_highlighting",
+    "IPython.sphinxext.ipython_directive",
 ]
 autosummary_generate = True
 add_module_names = True
@@ -27,7 +27,7 @@
 # Numpydoc settings
 numpydoc_show_class_members = False
 # numfig = True
-# numfig_format = {'figure': 'Figure %s:'}
+# numfig_format = {"figure": "Figure %s:"}
 # Make numpydoc to generate plots for example sections
 numpydoc_use_plots = True
 
@@ -36,26 +36,26 @@
 
 # Sphinx gallery configuration
 sphinx_gallery_conf = {
-    'examples_dirs': ['../examples', ],
-    'gallery_dirs': ['gallery', ],
-    'capture_repr': ('_repr_html_', ),
+    "examples_dirs": ["../examples", ],
+    "gallery_dirs": ["gallery", ],
+    "capture_repr": ("_repr_html_", ),
     # Patter to search for example files
     "filename_pattern": r"\.py",
     # Sort gallery example by file name instead of number of lines (default)
     "within_subsection_order": "FileNameSortKey",
     # Remove the settings (e.g., sphinx_gallery_thumbnail_number)
-    'remove_config_comments': True,
+    "remove_config_comments": True,
     # Show memory
-    'show_memory': True,
+    "show_memory": True,
     # Custom first notebook cell
-    'first_notebook_cell': '%matplotlib widget',
+    "first_notebook_cell": "%matplotlib widget",
 }
 
 # https://github.com/sphinx-gallery/sphinx-gallery/pull/521/files
 # Remove matplotlib agg warnings from generated doc when using plt.show
 warnings.filterwarnings("ignore", category=UserWarning,
-                        message='Matplotlib is currently using agg, which is a'
-                                ' non-GUI backend, so cannot show the figure.')
+                        message="Matplotlib is currently using agg, which is a"
+                                " non-GUI backend, so cannot show the figure.")
 
 # Intersphinx configuration
 intersphinx_mapping = {
@@ -64,44 +64,44 @@
 }
 
 # ==== 2. General Settings ====
-description = "A simple 2D reservoir modeller plus ESMDA."
+description = "ES-MDA with a simple 2D reservoir modeller"
 
 # The templates path.
-# templates_path = ['_templates']
+# templates_path = ["_templates"]
 
 # The suffix(es) of source filenames.
-source_suffix = '.rst'
+source_suffix = ".rst"
 
 # The master toctree document.
-master_doc = 'index'
+master_doc = "index"
 
 # General information about the project.
-project = 'resmda'
-author = 'Dieter Werthmüller, Gabriel Serrao Seabra'
-copyright = f'2024-{time.strftime("%Y")}, {author}'
+project = "resmda"
+author = "D. Werthmüller, G. Serrao Seabra, F.C. Vossepoel"
+copyright = f"2024-{time.strftime('%Y')}, {author}"
 
 # |version| and |today| tags (|release|-tag is not used).
 version = __version__
 release = __version__
-today_fmt = '%d %B %Y'
+today_fmt = "%d %B %Y"
 
 # List of patterns to ignore, relative to source directory.
-exclude_patterns = ['_build', '../tests']
+exclude_patterns = ["_build", "../tests"]
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'friendly'
+pygments_style = "friendly"
 
 # ==== 3. HTML settings ====
-html_theme = 'pydata_sphinx_theme'
-html_static_path = ['_static']
-# html_logo = '_static/empymod-logo.svg'
-# html_favicon = '_static/favicon.ico'
+html_theme = "pydata_sphinx_theme"
+html_static_path = ["_static"]
+# html_logo = "_static/empymod-logo.svg"
+# html_favicon = "_static/favicon.ico"
 
 html_theme_options = {
     "logo": {
         "text": "resmda",
     },
-    'navigation_with_keys': True,
+    "navigation_with_keys": True,
     "github_url": "https://github.com/tuda-geo/resmda",
     # "use_edit_page_button": True,
 }
@@ -114,8 +114,8 @@
 }
 
 html_use_modindex = True
-html_file_suffix = '.html'
-htmlhelp_basename = 'resmda'
+html_file_suffix = ".html"
+htmlhelp_basename = "resmda"
 html_css_files = [
     "style.css",
     "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/" +

diff --git a/examples/basicreservoir.py b/examples/basicreservoir.py
@@ -1,6 +1,6 @@
 r"""
-2D Reservoir ESMDA example
-==========================
+2D Reservoir ES-MDA example
+===========================
 
 Ensemble Smoother Multiple Data Assimilation (ES-MDA) in Reservoir Simulation.
 
@@ -30,7 +30,7 @@
 perm_min = 0.5
 perm_max = 5.0
 
-# ESMDA parameters
+# ES-MDA parameters
 ne = 100                  # Number of ensembles
 dt = np.zeros(10)+0.0001  # Time steps (could be irregular, e.g., increasing!)
 time = np.r_[0, np.cumsum(dt)]
@@ -47,8 +47,8 @@
 
 
 ###############################################################################
-# Create permeability maps for ESMDA
-# ----------------------------------
+# Create permeability maps for ES-MDA
+# -----------------------------------
 #
 # We will create a set of permeability maps that will serve as our initial
 # guess (prior). These maps are generated using a Gaussian random field and are
@@ -109,8 +109,8 @@ def sim(x):
 
 
 ###############################################################################
-# ESMDA
-# -----
+# ES-MDA
+# ------
 
 
 def restrict_permeability(x):
@@ -134,7 +134,7 @@ def restrict_permeability(x):
 # Posterior Analysis
 # ------------------
 #
-# After running ESMDA, it's crucial to analyze the posterior ensemble of
+# After running ES-MDA, it's crucial to analyze the posterior ensemble of
 # models. Here, we visualize the first three realizations from both the prior
 # and posterior ensembles to see how the models have been updated.
 
@@ -153,7 +153,7 @@ def restrict_permeability(x):
 # Observing the monitored pressure at cell (1,1) for all realizations and the
 # reference case, we can see that the ensemble of models after the assimilation
 # steps (in blue) is closer to the reference case (in red) than the prior
-# ensemble (in gray). This indicates that the ESMDA method is effectively
+# ensemble (in gray). This indicates that the ES-MDA method is effectively
 # updating the models to better represent the observed data.
 
 

diff --git a/examples/fluvialreservoir.py b/examples/fluvialreservoir.py
@@ -1,12 +1,13 @@
 r"""
-2D Fluvial Reservoir ESMDA example
-==================================
+2D Fluvial Reservoir ES-MDA example
+===================================
 
-In contrast to the basic reservoir example
-:ref:`sphx_glr_gallery_basicreservoir.py`, where a single facies was used, this
-example uses fluvial models containing different facies. It also compares the
-use of ES-MDA with and without localization, as explained in the example
-:ref:`sphx_glr_gallery_localization.py`.
+This example uses fluvial models containing different facies.
+
+This in contrast to the basic reservoir example
+:ref:`sphx_glr_gallery_basicreservoir.py`, where a single facies was used. The
+example also compares the use of ES-MDA with and without localization, as
+explained in the example :ref:`sphx_glr_gallery_localization.py`.
 
 The fluvial models were generated with ``FLUVSIM`` through ``geomodpy``, for
 more information see towards the end of the example where the code is shown to
@@ -27,7 +28,6 @@
         conda install -c conda-forge pooch
 
 """
-import os
 import json
 
 import pooch
@@ -40,23 +40,22 @@
 # seed. For production, remove the seed!
 rng = np.random.default_rng(1513)
 
-# Adjust this path to a folder of your choice.
-data_path = os.path.join("..", "download", "")
-
 # sphinx_gallery_thumbnail_number = 3
 
 ###############################################################################
 # Load and plot the facies
 # ------------------------
 
-fname = "facies.npy"
-pooch.retrieve(
-    "https://raw.github.com/tuda-geo/data/2024-06-18/resmda/"+fname,
+folder = "data"
+ffacies = "facies.npy"
+finput = "facies.json"
+fpfacies = pooch.retrieve(
+    "https://raw.github.com/tuda-geo/data/2024-06-18/resmda/"+ffacies,
     "4bfe56c836bf17ca63453c37e5da91cb97bbef8cc6c08d605f70bd64fe7488b2",
-    fname=fname,
-    path=data_path,
+    fname=ffacies,
+    path=folder,
 )
-facies = np.load(data_path + fname)
+facies = np.load(fpfacies)
 ne, nx, ny = facies.shape
 
 # Define mean permeability per facies
@@ -363,13 +362,13 @@ def restrict_permeability(x):
 #         facies[i*nreal:(i+1)*nreal, ...] = realizations.astype("i4")
 #
 #
-#     # ==== Save the output ====
+#     # ==== Save the outputs ====
 #
 #     # Save the input parameters to FLUVSIM as a json.
 #     with open("facies.json", "w") as f:
 #         json.dump(all_params, f, indent=2)
 #     # Save the facies values as a compressed npy-file.
-#     np.save("facies", facies.squeeze(), allow_pickle=False)
+#     np.save("facies.npy", facies.squeeze(), allow_pickle=False)
 
 
 ###############################################################################
@@ -379,14 +378,13 @@ def restrict_permeability(x):
 # These are, just as the data themselves, online at
 # https://github.com/tuda-geo/data/resmda.
 
-fname = "facies.json"
-pooch.retrieve(
-    "https://raw.github.com/tuda-geo/data/2024-06-18/resmda/"+fname,
+fpinput = pooch.retrieve(
+    "https://raw.github.com/tuda-geo/data/2024-06-18/resmda/"+finput,
     "db2cb8a620775c68374c24a4fa811f6350381c7fc98a823b9571136d307540b4",
-    fname=fname,
-    path=data_path,
+    fname=finput,
+    path=folder,
 )
-with open(data_path + fname, "r") as f:
+with open(fpinput, "r") as f:
     print(json.dumps(json.load(f), indent=2))
 
 ###############################################################################