cofi 0.1.3.dev2__tar.gz → 0.2.0__tar.gz

{cofi-0.1.3.dev2/src/cofi.egg-info → cofi-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cofi
-Version: 0.1.3.dev2
+Version: 0.2.0
 Summary: Common Framework for Inference
 Author: InLab, CoFI development team
 Keywords: inversion,inference,python package,geoscience,geophysics
@@ -24,7 +24,6 @@ License-File: LICENCE
 
 # <img src="https://raw.githubusercontent.com/inlab-geo/cofi/main/docs/source/_static/latte_art_cropped.png" width="5%" style="vertical-align:bottom"/> CoFI (Common Framework for Inference)
 
-
 [![PyPI version](https://img.shields.io/pypi/v/cofi?logo=pypi&style=flat-square&color=cae9ff&labelColor=f8f9fa)](https://pypi.org/project/cofi/)
 [![Conda Version](https://img.shields.io/conda/vn/conda-forge/cofi.svg?logo=condaforge&style=flat-square&color=cce3de&labelColor=f8f9fa&logoColor=344e41)](https://anaconda.org/conda-forge/cofi)
 [![Documentation Status](https://img.shields.io/readthedocs/cofi?logo=readthedocs&style=flat-square&color=fed9b7&labelColor=f8f9fa&logoColor=eaac8b)](https://cofi.readthedocs.io/en/latest/?badge=latest)
@@ -32,6 +31,9 @@ License-File: LICENCE
 [![Slack](https://img.shields.io/badge/Slack-InLab_community-4A154B?logo=slack&style=flat-square&color=cdb4db&labelColor=f8f9fa&logoColor=9c89b8)](https://join.slack.com/t/inlab-community/shared_invite/zt-1ejny069z-v5ZyvP2tDjBR42OAu~TkHg)
 <!-- [![Wheels](https://img.shields.io/pypi/wheel/cofi)](https://pypi.org/project/cofi/) -->
 
+> Related repositories by [InLab](https://inlab.edu.au/community/):
+> - [CoFI Examples](https://github.com/inlab-geo/cofi-examples)
+> - [Espresso](https://github.com/inlab-geo/espresso)
 
 ## Introduction
 
@@ -39,8 +41,7 @@ CoFI (Common Framework for Inference) is an open source initiative for interfaci
 
 With a mission to bridge the gap between the domain expertise and the inference expertise, CoFI provides an interface across a wide range of inference algorithms from different sources, underpinned by a rich set of domain relevant [examples](https://cofi.readthedocs.io/en/latest/examples/generated/index.html).
 
-> This project and [documentation](https://cofi.readthedocs.io/en/latest/) are under initial development stage. Please feel free to contact us for feedback or issues!
-
+Read [the documentation](https://cofi.readthedocs.io/en/latest/), and let us know your feedback or any issues!
 
 ## Installation
 

{cofi-0.1.3.dev2 → cofi-0.2.0}/README.md

@@ -2,7 +2,6 @@
 
 # <img src="https://raw.githubusercontent.com/inlab-geo/cofi/main/docs/source/_static/latte_art_cropped.png" width="5%" style="vertical-align:bottom"/> CoFI (Common Framework for Inference)
 
-
 [![PyPI version](https://img.shields.io/pypi/v/cofi?logo=pypi&style=flat-square&color=cae9ff&labelColor=f8f9fa)](https://pypi.org/project/cofi/)
 [![Conda Version](https://img.shields.io/conda/vn/conda-forge/cofi.svg?logo=condaforge&style=flat-square&color=cce3de&labelColor=f8f9fa&logoColor=344e41)](https://anaconda.org/conda-forge/cofi)
 [![Documentation Status](https://img.shields.io/readthedocs/cofi?logo=readthedocs&style=flat-square&color=fed9b7&labelColor=f8f9fa&logoColor=eaac8b)](https://cofi.readthedocs.io/en/latest/?badge=latest)
@@ -10,6 +9,9 @@
 [![Slack](https://img.shields.io/badge/Slack-InLab_community-4A154B?logo=slack&style=flat-square&color=cdb4db&labelColor=f8f9fa&logoColor=9c89b8)](https://join.slack.com/t/inlab-community/shared_invite/zt-1ejny069z-v5ZyvP2tDjBR42OAu~TkHg)
 <!-- [![Wheels](https://img.shields.io/pypi/wheel/cofi)](https://pypi.org/project/cofi/) -->
 
+> Related repositories by [InLab](https://inlab.edu.au/community/):
+> - [CoFI Examples](https://github.com/inlab-geo/cofi-examples)
+> - [Espresso](https://github.com/inlab-geo/espresso)
 
 ## Introduction
 
@@ -17,8 +19,7 @@ CoFI (Common Framework for Inference) is an open source initiative for interfaci
 
 With a mission to bridge the gap between the domain expertise and the inference expertise, CoFI provides an interface across a wide range of inference algorithms from different sources, underpinned by a rich set of domain relevant [examples](https://cofi.readthedocs.io/en/latest/examples/generated/index.html).
 
-> This project and [documentation](https://cofi.readthedocs.io/en/latest/) are under initial development stage. Please feel free to contact us for feedback or issues!
-
+Read [the documentation](https://cofi.readthedocs.io/en/latest/), and let us know your feedback or any issues!
 
 ## Installation
 

{cofi-0.1.3.dev2 → cofi-0.2.0}/src/cofi/_base_problem.py

@@ -5,6 +5,7 @@ import json
 
 import numpy as np
 
+from .utils import BaseRegularization
 from ._exceptions import (
     DimensionMismatchError,
     InvalidOptionError,
@@ -197,7 +198,6 @@ class BaseProblem:
         BaseProblem.data_misfit
         BaseProblem.regularization
         BaseProblem.regularization_matrix
-        BaseProblem.regularization_factor
         BaseProblem.forward
         BaseProblem.name
         BaseProblem.data
@@ -230,7 +230,6 @@ class BaseProblem:
         "data_misfit",
         "regularization",
         "regularization_matrix",
-        "regularization_factor",
         "forward",
         "data",
         "data_covariance",
@@ -968,8 +967,7 @@ class BaseProblem:
 
     def set_regularization(
         self,
-        regularization: Union[str, Callable[[np.ndarray], Number]],
-        regularization_factor: Number = 1,
+        regularization: Union[Callable[[np.ndarray], Number], BaseRegularization],
         regularization_matrix: Union[
             np.ndarray, Callable[[np.ndarray], np.ndarray]
         ] = None,
@@ -989,11 +987,6 @@ class BaseProblem:
         regularization : str or (function - np.ndarray -> Number)
             either a string from pre-built functions above, or a regularization function that
             matches :meth:`regularization` in signature.
-        regularization_factor : Number, optional
-            the regularization factor (lamda) that adjusts the ratio of the regularization
-            term over the data misfit, by default 1. If ``regularization`` and ``data_misfit``
-            are set but ``objective`` isn't, then we will generate ``objective`` function as
-            following: :math:`\text{objective}(model)=\text{data_misfit}(model)+\text{factor}\times\text{regularization}(model)`
         regularization_matrix : np.ndarray or (function - np.ndarray -> np.ndarray)
             a matrix of shape ``(model_size, model_size)``, or a function that takes in
             a model and calculates the (weighting) matrix.
@@ -1010,11 +1003,6 @@ class BaseProblem:
         kwargs : dict, optional
             extra dict of keyword arguments for regularization function
 
-        Raises
-        ------
-        InvalidOptionError
-            when you've passed in a string not in our supported regularization list
-
         Examples
         --------
 
@@ -1023,87 +1011,41 @@ class BaseProblem:
         >>> from cofi import BaseProblem
         >>> inv_problem = BaseProblem()
 
-        1. Example with an L1 norm
-
-        >>> inv_problem.set_regularization(1)
-        >>> inv_problem.regularization([1,1])
-        2
-
-        2. Example with an inf norm
-
-        >>> inv_problem.set_regularization("inf")
-        >>> inv_problem.regularization([1,1])
-        1
-
-        3. Example with a custom regularization function
+        1. Example with a custom regularization function
 
         >>> inv_problem.set_regularization(lambda x: sum(x))
         >>> inv_problem.regularization([1,1])
         2
 
-        4. Example with an L2 norm and regularization factor of 0.5 (by default 1)
+        2. Example with a custom regularization + a regularization matrix
 
-        >>> inv_problem.set_regularization(2, 0.5)
+        >>> inv_problem.set_regularization(lambda x: np.sum(x**2), np.eye(3))
         >>> inv_problem.regularization([1,1])
-        0.7071067811865476
-
-        5. Example with a regularization matrix
-
-        >>> inv_problem.set_regularization(2, 0.5, np.array([[2,0], [0,1]]))
-        >>> inv_problem.regularization([1,1])
-        1.118033988749895
+        2
         """
-        # preprocess regularization_matrix
-        if np.ndim(regularization_matrix) != 0:
+        # preprocess regularization_matrix if there is one
+        _reg_matrix = None
+        if regularization_matrix is not None:
+            _reg_matrix = regularization_matrix
+        elif isinstance(regularization, BaseRegularization) and hasattr(
+            regularization, "matrix"
+        ):
+            _reg_matrix = regularization.matrix
+        # wrap regularization_matrix as a function
+        if _reg_matrix is not None and np.ndim(_reg_matrix) != 0:
             self.regularization_matrix = _FunctionWrapper(
-                "regularization_matrix", _matrix_to_func, args=[regularization_matrix]
+                "regularization_matrix", _matrix_to_func, args=[_reg_matrix]
             )
-        elif callable(regularization_matrix):
+        elif _reg_matrix is not None and callable(_reg_matrix):
             self.regularization_matrix = _FunctionWrapper(
-                "regularization_matrix", regularization_matrix
+                "regularization_matrix", _reg_matrix
             )
         else:
             self.regularization_matrix = None
-        # preprocess regularization function without lambda
-        if isinstance(regularization, (Number, str)) or not regularization:
-            order = regularization
-            if (
-                isinstance(order, str)
-                and order not in ["fro", "nuc", "inf", "-inf"]
-                or isinstance(order, Number)
-                and order < 0
-            ):
-                raise InvalidOptionError(
-                    name="regularization order",
-                    invalid_option=order,
-                    valid_options=(
-                        "[None, 'fro', 'nuc', numpy.inf, -numpy.inf] or any positive"
-                        " number"
-                    ),
-                )
-            elif isinstance(order, str) and order in ["inf", "-inf"]:
-                order = float(order)
-            _reg = _FunctionWrapper(
-                "regularization_none_lamda", np.linalg.norm, args=[order]
-            )
-        else:
-            _reg = _FunctionWrapper(
-                "regularization_none_lamda", regularization, args, kwargs
-            )
-        # wrapper function that calculates: lambda * raw regularization value
-        self._regularization_factor = regularization_factor
-        if self.regularization_matrix is None:
-            self.regularization = _FunctionWrapper(
-                "regularization",
-                _regularization_with_lamda,
-                args=[_reg, regularization_factor],
-            )
-        else:
-            self.regularization = _FunctionWrapper(
-                "regularization",
-                _regularization_with_lamda_n_matrix,
-                args=[_reg, regularization_factor, self.regularization_matrix],
-            )
+        # process regularization function
+        self.regularization = _FunctionWrapper(
+            "regularization", regularization, args, kwargs
+        )
         # update some autogenerated functions (as usual)
         self._update_autogen("regularization")
 
@@ -1444,24 +1386,6 @@ class BaseProblem:
             return self._blobs_dtype
         raise NotDefinedError(needs="blobs name and type")
 
-    @property
-    def regularization_factor(self) -> Number:
-        r"""regularization factor (lambda) that adjusts weights of the regularization
-        term
-
-        Raises
-        ------
-        NotDefinedError
-            when this property has not been defined (by
-            :meth:`set_regularization`
-        """
-        if (
-            hasattr(self, "_regularization_factor")
-            and self._regularization_factor is not None
-        ):
-            return self._regularization_factor
-        raise NotDefinedError(needs="regularization_factor (lamda)")
-
     @property
     def bounds(self):
         r"""TODO: document me!
@@ -1597,11 +1521,6 @@ class BaseProblem:
         r"""indicates whether :meth:`blobs_dtype` has been defined"""
         return self._check_property_defined("blobs_dtype")
 
-    @property
-    def regularization_factor_defined(self) -> bool:
-        r"""indicates whether :meth:`regularization_factor` has been defined"""
-        return self._check_property_defined("regularization_factor")
-
     @property
     def bounds_defined(self) -> bool:
         r"""indicates whether :meth:`bounds` has been defined"""
@@ -1718,12 +1637,12 @@ class BaseProblem:
             if self.data_covariance_inv_defined:
                 if _is_diag(self.data_covariance_inv):
                     weighted_res = np.diag(self.data_covariance_inv) * res
-                    return np.sum(np.square(weighted_res))
+                    return res @ weighted_res
                 else:
                     return res.T @ self.data_covariance_inv @ res
             elif self.data_covariance_defined and _is_diag(self.data_covariance):
                 weighted_res = res / np.diag(self.data_covariance)
-                return np.sum(np.square(weighted_res))
+                return res @ weighted_res
             else:
                 return np.sum(np.square(res))
         except Exception as exception:
@@ -1895,14 +1814,6 @@ def _jacobian_times_vector_from_jcb(model, vector, jacobian):
         ) from exception
 
 
-def _regularization_with_lamda(model, reg_func, lamda):
-    return lamda * reg_func(model)
-
-
-def _regularization_with_lamda_n_matrix(model, reg_func, lamda, reg_matrix_func):
-    return lamda * reg_func(reg_matrix_func(model) @ model)
-
-
 def _matrix_to_func(_, matrix):
     return matrix
 

cofi-0.2.0/src/cofi/_version.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

{cofi-0.1.3.dev2 → cofi-0.2.0}/src/cofi/tools/_base_inference_tool.py

@@ -310,8 +310,10 @@ def error_handler(when, context):
                 return func(*args, **kwargs)
             except Exception as e:
                 raise CofiError(
-                    f"error ocurred {when} ({context}). Check exception details "
-                    "from message above.",
+                    (
+                        f"error ocurred {when} ({context}). Check exception details "
+                        "from message above."
+                    ),
                 ) from e
 
         return wrapped_func

{cofi-0.1.3.dev2 → cofi-0.2.0}/src/cofi/tools/_scipy_lstsq.py

@@ -119,7 +119,6 @@ class ScipyLstSq(BaseInferenceTool):
         )
         # get lamda and L matrix if needed
         if self._params["with_tikhonov"]:
-            self._lamda = inv_problem.regularization_factor
             if inv_problem.regularization_matrix_defined:
                 try:
                     _L = inv_problem.regularization_matrix(dummy_model)
@@ -133,7 +132,7 @@ class ScipyLstSq(BaseInferenceTool):
                 self._components_used.append("regularization_matrix")
             else:
                 self._LtL = np.identity(self._G.shape[1])
-            self._a += self._lamda * self._LtL
+            self._a += self._LtL
 
     def __call__(self) -> dict:
         res_p, residual, rank, singular_vals = self._call_lstsq()

{cofi-0.1.3.dev2 → cofi-0.2.0}/src/cofi/tools/_scipy_opt_min.py

@@ -6,20 +6,20 @@ from . import BaseInferenceTool, error_handler
 # Official documentation for scipy.optimize.minimize
 # https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.minimize.html
 
-# 'jac' is only for:
+# 'jac' will be used when choosing the following methods:
 # CG, BFGS, Newton-CG, L-BFGS-B, TNC, SLSQP, dogleg, trust-ncg, trust-krylov, trust-exact
 # and trust-constr
 
-# 'hess' is only for:
+# 'hess' will be used when choosing the following methods:
 # Newton-CG, dogleg, trust-ncg, trust-krylov, trust-exact and trust-constr
 
-# 'hessp' is only for:
+# 'hessp' will be used when choosing the following methods:
 # Newton-CG, trust-ncg, trust-krylov, trust-constr
 
-# 'bounds' is only for:
+# 'bounds' will be used when choosing the following methods:
 # Nelder-Mead, L-BFGS-B, TNC, SLSQP, Powell, and trust-constr
 
-# 'constraints' is only for:
+# 'constraints' will be used when choosing the following methods:
 # COBYLA, SLSQP and trust-constr
 
 # other arguments include: tol, options, callback

cofi-0.2.0/src/cofi/utils/__init__.py

@@ -0,0 +1,26 @@
+r"""Utility classes and functions (e.g. to generate regularization terms and more)
+
+The class inheritance of regularization classes:
+
+.. mermaid::
+
+    graph TD;
+    BaseRegularization --> LpNormRegularization;
+    LpNormRegularization --> QuadraticReg;
+    BaseRegularization --> ModelCovariance;
+    ModelCovariance --> GaussianPrior;
+
+"""
+
+from ._reg_base import BaseRegularization
+from ._reg_lp_norm import LpNormRegularization, QuadraticReg
+from ._reg_model_cov import ModelCovariance, GaussianPrior
+
+
+__all__ = [
+    "BaseRegularization",
+    "LpNormRegularization",
+    "QuadraticReg",
+    "ModelCovariance",
+    "GaussianPrior",
+]

cofi-0.2.0/src/cofi/utils/_reg_base.py

@@ -0,0 +1,214 @@
+from abc import abstractmethod, ABCMeta
+from numbers import Number
+from functools import reduce
+import numpy as np
+
+from .._exceptions import DimensionMismatchError
+
+
+class BaseRegularization(metaclass=ABCMeta):
+    r"""Base class for a regularization term
+
+    Check :class:`QuadraticReg` for a concrete example.
+
+    .. rubric:: Basic interface
+
+    The basic properties / methods for a regularization term in ``cofi.utils``
+    include the following:
+
+    .. autosummary::
+        BaseRegularization.model_size
+        BaseRegularization.reg
+        BaseRegularization.gradient
+        BaseRegularization.hessian
+        BaseRegularization.__call__
+
+    .. rubric:: Adding two terms
+
+    Two instances of ``BaseRegularization`` can also be added together using the ``+``
+    operator:
+
+    .. autosummary::
+        BaseRegularization.__add__
+
+    """
+
+    def __init__(
+        self,
+    ):
+        pass
+
+    @property
+    @abstractmethod
+    def model_shape(self) -> tuple:
+        """the shape of models that current regularization function accepts"""
+        raise NotImplementedError
+
+    @property
+    def model_size(self) -> Number:
+        """the number of unknowns that current regularization function accepts"""
+        return reduce(lambda a, b: a * b, np.array(self.model_shape), 1)
+
+    def __call__(self, model: np.ndarray) -> Number:
+        r"""a class instance itself can also be called as a function
+
+        It works exactly the same as :meth:`reg`.
+
+        In other words, the following two usages are exactly the same::
+
+        >>> my_reg = QuadraticReg(factor=1, model_size=3)
+        >>> my_reg_value = my_reg(np.array([1,2,3]))            # usage 1
+        >>> my_reg_value = my_reg.reg(np.array([1,2,3]))        # usage 2
+        """
+        return self.reg(model)
+
+    @abstractmethod
+    def reg(self, model: np.ndarray) -> Number:
+        """the regularization function value given a model to evaluate"""
+        raise NotImplementedError
+
+    @abstractmethod
+    def gradient(self, model: np.ndarray) -> np.ndarray:
+        """the gradient of regularization function with respect to model given a model
+
+        The usual size for the gradient is :math:`(M,)` where :math:`M` is the number
+        of model parameters
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def hessian(self, model: np.ndarray) -> np.ndarray:
+        """the hessian of regularization function with respect to model given a model
+
+        The usual size for the Hessian is :math:`(M,M)` where :math:`M` is the number
+        of model parameters
+        """
+        raise NotImplementedError
+
+    def __add__(self, other_reg):
+        r"""Adds two regularization terms
+
+        Parameters
+        ----------
+        other_reg : BaseRegularization
+            the second argument of "+" operator; must also be a
+            :class:`BaseRegularization` instance
+
+        Returns
+        -------
+        BaseRegularization
+            a regularization term ``resRegularization`` such that:
+
+            - :math:`\text{resRegularization.reg}(m)=\text{self.reg}(m)+\text{other_reg.reg}(m)`
+            - :math:`\text{resRegularization.gradient}(m)=\text{self.gradient}(m)+\text{other_reg.gradient}(m)`
+            - :math:`\text{resRegularization.hessian}(m)=\text{self.hessian}(m)+\text{other_reg.hessian}(m)`
+
+        Raises
+        ------
+        TypeError
+            when the ``other_reg`` is not a regularization term generated by CoFI Utils
+        DimensionMismatchError
+            when the ``other_reg`` doesn't accept model_size that matches the one of
+            ``self``
+
+        Examples
+        --------
+
+        >>> from cofi import BaseProblem
+        >>> from cofi.utils import QuadraticReg
+        >>> reg1 = QuadraticReg(model_shape=(3,), weighting_matrix="damping")
+        >>> reg2 = QuadraticReg(model_shape=(3,), weighting_matrix="smoothing")
+        >>> my_problem = BaseProblem()
+        >>> my_problem.set_regularization(reg1 + reg2)
+
+        """
+        if not isinstance(other_reg, BaseRegularization):
+            raise TypeError(
+                f"unsupported operand type(s) for +: '{self.__class__.__name__}' "
+                f"and '{other_reg.__class__.__name__}"
+            )
+        if self.model_size != other_reg.model_size:
+            raise DimensionMismatchError(
+                entered_name="the second regularization term",
+                entered_dimension=other_reg.model_size,
+                expected_source="the first regularization term",
+                expected_dimension=self.model_size,
+            )
+        tmp_model_shape = self.model_shape
+        tmp_reg = self.reg
+        tmp_grad = self.gradient
+        tmp_hess = self.hessian
+
+        class CompositeRegularization(BaseRegularization):
+            @property
+            def model_shape(self):
+                return tmp_model_shape
+
+            def reg(self, model):
+                return tmp_reg(model) + other_reg(model)
+
+            def gradient(self, model):
+                return tmp_grad(model) + other_reg.gradient(model)
+
+            def hessian(self, model):
+                return tmp_hess(model) + other_reg.hessian(model)
+
+        return CompositeRegularization()
+
+    def __rmul__(self, coefficient):
+        r"""Multiply a regularization term with a constant number
+
+        Parameters
+        ----------
+        coefficient : Number
+            the first argument of "*" operator; must be a Number
+
+        Returns
+        -------
+        BaseRegularization
+            a regularization term ``resRegularization`` such that:
+
+            - :math:`\text{resRegularization.reg}(m)=\text{coefficient}\times\text{self.reg}(m)`
+            - :math:`\text{resRegularization.gradient}(m)=\text{coefficient}\times\text{self.gradient}(m)`
+            - :math:`\text{resRegularization.hessian}(m)=\text{coefficient}\times\text{self.hessian}(m)`
+
+        Raises
+        ------
+        TypeError
+            when the ``coefficient`` is not of a python Number type
+
+        Examples
+        --------
+
+        >>> from cofi import BaseProblem
+        >>> from cofi.utils import QuadraticReg
+        >>> reg = QuadraticReg(model_shape=(3,), weighting_matrix="damping")
+        >>> my_problem = BaseProblem()
+        >>> my_problem.set_regularization(10 * reg)
+
+        """
+        if not isinstance(coefficient, Number):
+            raise TypeError(
+                f"unsupported operand type(s) for *: '{coefficient.__class__.__name__}'"
+                f" and '{self.__class__.__name__}"
+            )
+        tmp_model_shape = self.model_shape
+        tmp_reg = self.reg
+        tmp_grad = self.gradient
+        tmp_hess = self.hessian
+
+        class CompositeRegularization(BaseRegularization):
+            @property
+            def model_shape(self):
+                return tmp_model_shape
+
+            def reg(self, model):
+                return coefficient * tmp_reg(model)
+
+            def gradient(self, model):
+                return coefficient * tmp_grad(model)
+
+            def hessian(self, model):
+                return coefficient * tmp_hess(model)
+
+        return CompositeRegularization()