Set up cofi.utils and create Regularisation utilities

CHANGELOG.md

@@ -2,6 +2,13 @@
 
 <!--next-version-placeholder-->
 
+## v0.1.2.dev10 (NOT YET RELEASED)
+
+### CoFI Utils
+
+- [#65](https://github.com/inlab-geo/cofi/issues/54) Utility functions using findiff to generate the difference matrices
+
+
 ## v0.1.2.dev9 (13/09/2022)
 
 ### CoFI Core

docs/_templates/autosummary/class.rst

@@ -10,35 +10,33 @@
 
     .. rubric:: Reference Details
 
-.. ----
 
 {% for item in members %}
 {% if item in ['__call__'] %}
-.. automethod:: {{ objname }}.{{ item }}
+    .. automethod:: {{ objname }}.{{ item }}
+{% endif %}
+{% if "BaseRegularisation" in objname and item == '__add__' %}
+    .. automethod:: {{ objname }}.{{ item }}
 {% endif %}
 {% endfor %}
 
-.. :ref:`back to top <top_{{objname}}>`
 
-.. ----
 
 {% for item in methods %}
 
 {% if "BaseSolver" in objname and item == '__init__' %}
-.. automethod:: {{ objname }}.{{ item }}
+    .. automethod:: {{ objname }}.{{ item }}
 {% endif %}
 
 {% if item != '__init__' %}
-.. automethod:: {{ objname }}.{{ item }}
+    .. automethod:: {{ objname }}.{{ item }}
 {% endif %}
 {% endfor %}
 
-.. :ref:`back to top <top_{{objname}}>`
 
-----
 
 {% for item in attributes %}
-.. autoattribute:: {{ objname }}.{{ item }}
+    .. autoattribute:: {{ objname }}.{{ item }}
 {% endfor %}
 
 :ref:`back to top <top_{{objname}}>`
@@ -51,7 +49,7 @@
 
     .. rubric:: Reference Details
 
-.. automethod:: cofi.SamplingResult.to_arviz
+    .. automethod:: cofi.SamplingResult.to_arviz
 
 :ref:`back to top <top_{{objname}}>`
 {% endif %}

docs/api/index.rst

@@ -61,3 +61,15 @@ tools, simply create a subclass of :code:`BaseSolver` and implements :code:`__in
     :toctree: generated/
 
     cofi.solvers.BaseSolver
+
+
+CoFI Utils
+----------
+
+Module :mod:`cofi.utils` contains a set of helper classes and routines to enable
+easier problem definitions.
+
+.. autosummary::
+    :toctree: generated/
+
+    cofi.utils

docs/conf.py

@@ -91,6 +91,7 @@ def setup(app):
     "scipy": ("https://docs.scipy.org/doc/scipy/", None),
     "numpy": ("https://numpy.org/doc/stable/", None),
     "arviz": ("https://python.arviz.org/en/latest/", None),
+    "findiff": ("https://findiff.readthedocs.io/en/latest/", None),
 }
 
 # Disable including boostrap CSS for sphinx_panels since it's already included
@@ -156,6 +157,7 @@ def setup(app):
     "dollarmath",
     "html_image",
 ]
+nb_execution_mode = "cache"
 
 
 # -- Cutomised variables ------------------------------------------------------

docs/installation.rst

@@ -11,6 +11,7 @@ CoFI requires Python 3.6+, and the following dependencies:
 - scipy>=1.0.0
 - emcee>=3.1.0
 - arviz>=0.9.0
+- findiff>=0.7.0
 
 
 Virtual environment setup

envs/environment_dev.yml

@@ -48,3 +48,4 @@ dependencies:
     - watermark
     - sphinxcontrib-svg2pdfconverter==1.2.0
     - papermill
+    - findiff>=0.7.0

setup.py

@@ -2,6 +2,7 @@
 from io import StringIO
 import sys
 from pathlib import Path
+from setuptools import find_namespace_packages
 
 try:
     from skbuild import setup
@@ -54,8 +55,7 @@
     "License :: OSI Approved :: BSD License",
 ]
 PACKAGE_DIR = {"": "src"}
-# PACKAGES = find_packages("src")
-PACKAGES = ["cofi"]
+PACKAGES = find_namespace_packages(where='src')
 CMAKE_INSTALL_DIR = "src/cofi"
 CMAKE_ARGS=['-DSKBUILD=ON']
 PYTHON_REQUIRES = ">=3.6"
@@ -64,6 +64,7 @@
     "scipy>=1.0.0",
     "emcee>=3.1.0",
     "arviz>=0.9.0",
+    "findiff>=0.7.0",
 ]
 EXTRAS_REQUIRE = {
     "petsc": ["petsc4py>=3.16.0"],

src/cofi/base_problem.py

@@ -1195,7 +1195,7 @@ def set_model_shape(self, model_shape: Tuple):
                 np.reshape(self.initial_model, model_shape)
             except ValueError as err: 
                 raise DimensionMismatchError(
-                    entered_dimenion=model_shape, 
+                    entered_dimension=model_shape, 
                     entered_name="model shape", 
                     expected_dimension=self.initial_model.shape, 
                     expected_source="initial model"

src/cofi/exceptions.py

@@ -62,22 +62,23 @@ class DimensionMismatchError(CofiError, ValueError):
     def __init__(
         self, 
         *args, 
-        entered_dimenion: Tuple, 
+        entered_dimension: Tuple, 
         entered_name: str, 
         expected_dimension: Tuple, 
         expected_source: str,
     ) -> None:
         super().__init__(*args)
-        self._entered_dimension = entered_dimenion
+        self._entered_dimension = entered_dimension
         self._entered_name = entered_name 
         self._expected_dimension = expected_dimension
         self._expected_source = expected_source
 
     def __str__(self) -> str:
         super_msg = super().__str__()
-        msg = f"the {self._entered_name} you've provided {self._entered_dimension}" \
-              f" doesn't match and cannot be reshaped into the dimension you've set" \
-              f" for {self._expected_source} which is {self._expected_dimension}" 
+        msg = f"the {self._entered_name} you've provided (shape: " \
+              f"{self._entered_dimension}) doesn't match and cannot be reshaped " \
+              f"into the dimension you've set for {self._expected_source} which is " \
+              f"{self._expected_dimension}" 
         return self._form_str(super_msg, msg) 
 
 

src/cofi/utils/__init__.py

@@ -0,0 +1,13 @@
+"""Utility classes and functions (e.g. to generate regularisation terms and more)
+"""
+
+from .regularisation import (
+    BaseRegularisation,
+    QuadraticReg,
+)
+
+
+__all__ = [
+    "BaseRegularisation",
+    "QuadraticReg",
+]