pygeoinf 1.0.9__py3-none-any.whl → 1.1.1__py3-none-any.whl

pygeoinf/inversion.py

@@ -1,5 +1,14 @@
 """
-Module containing the base class for inversion methods.
+Provides the abstract base class for all inversion algorithms.
+
+This module defines the `Inversion` class, which serves as a common
+foundation for various methods that solve an inverse problem. Its primary role
+is to maintain a reference to the `ForwardProblem` being solved, providing a
+consistent interface and convenient access to the problem's core components like
+the model space and data space.
+
+It also includes helper methods to assert preconditions required by different
+inversion techniques, such as the existence of a data error measure.
 """
 
 from __future__ import annotations
@@ -13,8 +22,10 @@ class Inversion:
     An abstract base class for inversion methods.
 
     This class provides a common structure for different inversion algorithms
-    (e.g., Bayesian, Least squares). Its primary role is to hold a reference to the
-    forward problem being solved and provide convenient access to its properties.
+    (e.g., Bayesian, Least Squares). Its main purpose is to hold a reference
+    to the forward problem being solved and provide convenient access to its
+    properties. Subclasses should inherit from this class to implement a
+    specific inversion technique.
     """
 
     def __init__(self, forward_problem: "LinearForwardProblem", /) -> None:
@@ -60,7 +71,8 @@ class Inversion:
         """
         Checks if the data error measure has an inverse covariance.
 
-        This is a precondition for methods that require the data precision matrix.
+        This is a precondition for methods that require the data precision
+        matrix (the inverse of the data error covariance).
 
         Raises:
             AttributeError: If no data error measure is set, or if the measure

pygeoinf/linear_bayesian.py

@@ -1,5 +1,23 @@
 """
-Module for solving inverse problems using Bayesian methods.
+Implements the Bayesian framework for solving linear inverse problems.
+
+This module treats the inverse problem from a statistical perspective, aiming to
+determine the full posterior probability distribution of the unknown model
+parameters, rather than a single best-fit solution.
+
+It assumes that the prior knowledge about the model and the statistics of the
+data errors can be described by Gaussian measures. For a linear forward problem,
+the resulting posterior distribution for the model is also Gaussian, allowing
+for an analytical solution.
+
+Key Classes
+-----------
+- `LinearBayesianInversion`: Computes the posterior Gaussian measure `p(u|d)`
+  for the model `u` given observed data `d`. This provides not only a mean
+  estimate for the model but also its uncertainty (covariance).
+- `LinearBayesianInference`: Extends the framework to compute the posterior
+  distribution for a derived property of the model, `p(B(u)|d)`, where `B` is
+  some linear operator.
 """
 
 from __future__ import annotations
@@ -12,22 +30,23 @@ from .gaussian_measure import GaussianMeasure
 from .forward_problem import LinearForwardProblem
 from .operators import LinearOperator
 from .linear_solvers import LinearSolver, IterativeLinearSolver
-from .hilbert_space import HilbertSpace, T_vec
+from .hilbert_space import HilbertSpace, Vector
 
 
 class LinearBayesianInversion(Inversion):
     """
     Solves a linear inverse problem using Bayesian methods.
 
-    This class applies to problems of the form `d = A(u) + e`, where the model
-    `u` and the error `e` are described by Gaussian distributions. It computes
-    the posterior probability distribution `p(u|d)` for the model parameters.
+    This class applies to problems of the form `d = A(u) + e`, where the prior
+    knowledge of the model `u` and the statistics of the error `e` are described
+    by Gaussian distributions. It computes the full posterior probability
+    distribution `p(u|d)` for the model parameters given an observation `d`.
     """
 
     def __init__(
         self,
-        forward_problem: "LinearForwardProblem",
-        model_prior_measure: "GaussianMeasure",
+        forward_problem: LinearForwardProblem,
+        model_prior_measure: GaussianMeasure,
         /,
     ) -> None:
         """
@@ -36,21 +55,22 @@ class LinearBayesianInversion(Inversion):
             model_prior_measure: The prior Gaussian measure on the model space.
         """
         super().__init__(forward_problem)
-        self._model_prior_measure: "GaussianMeasure" = model_prior_measure
+        self._model_prior_measure: GaussianMeasure = model_prior_measure
 
     @property
-    def model_prior_measure(self) -> "GaussianMeasure":
+    def model_prior_measure(self) -> GaussianMeasure:
         """The prior Gaussian measure on the model space."""
         return self._model_prior_measure
 
     @property
-    def normal_operator(self) -> "LinearOperator":
+    def normal_operator(self) -> LinearOperator:
         """
-        Returns the covariance of the prior predictive distribution.
+        Returns the covariance of the prior predictive distribution, `p(d)`.
 
-        This operator, `C_d = A * C_u * A^T + C_e`, represents the total
+        This operator, `C_d = A @ C_u @ A* + C_e`, represents the total
         expected covariance in the data space before any data is observed.
-        It is central to calculating the posterior distribution.
+        Its inverse is central to calculating the posterior distribution and is
+        often referred to as the Bayesian normal operator.
         """
         forward_operator = self.forward_problem.forward_operator
         prior_model_covariance = self.model_prior_measure.covariance
@@ -63,7 +83,7 @@ class LinearBayesianInversion(Inversion):
         else:
             return forward_operator @ prior_model_covariance @ forward_operator.adjoint
 
-    def data_prior_measure(self) -> "GaussianMeasure":
+    def data_prior_measure(self) -> GaussianMeasure:
         """
         Returns the prior predictive distribution on the data, `p(d)`.
 
@@ -87,17 +107,18 @@ class LinearBayesianInversion(Inversion):
 
     def model_posterior_measure(
         self,
-        data: "T_vec",
-        solver: "LinearSolver",
+        data: Vector,
+        solver: LinearSolver,
         /,
         *,
-        preconditioner: Optional["LinearOperator"] = None,
-    ) -> "GaussianMeasure":
+        preconditioner: Optional[LinearOperator] = None,
+    ) -> GaussianMeasure:
         """
         Returns the posterior Gaussian measure for the model, `p(u|d)`.
 
-        The posterior mean and covariance are computed analytically using the
-        standard formulas for linear-Gaussian models.
+        This measure represents our updated state of knowledge about the model
+        `u` after observing the data `d`. Its expectation is the most likely
+        model, and its covariance quantifies the remaining uncertainty.
 
         Args:
             data: The observed data vector.
@@ -148,19 +169,19 @@ class LinearBayesianInversion(Inversion):
 
 class LinearBayesianInference(LinearBayesianInversion):
     """
+    Performs Bayesian inference on a derived property of the model.
 
-    Performs Bayesian inference on a property of the model.
-
-    This class extends the Bayesian inversion framework to compute the posterior
-    distribution for a derived property `p = B(u)`, where `B` is a linear
-    operator acting on the model `u`.
+    While `LinearBayesianInversion` solves for the model `u` itself, this class
+    computes the posterior distribution for a property `p = B(u)`, where `B` is a
+    linear operator acting on the model `u`. This is useful for uncertainty
+    quantification of derived quantities (e.g., the average value of a field).
     """
 
     def __init__(
         self,
-        forward_problem: "LinearForwardProblem",
-        model_prior_measure: "GaussianMeasure",
-        property_operator: "LinearOperator",
+        forward_problem: LinearForwardProblem,
+        model_prior_measure: GaussianMeasure,
+        property_operator: LinearOperator,
         /,
     ) -> None:
         """
@@ -173,19 +194,19 @@ class LinearBayesianInference(LinearBayesianInversion):
         super().__init__(forward_problem, model_prior_measure)
         if property_operator.domain != self.forward_problem.model_space:
             raise ValueError("Property operator domain must match the model space.")
-        self._property_operator: "LinearOperator" = property_operator
+        self._property_operator: LinearOperator = property_operator
 
     @property
-    def property_space(self) -> "HilbertSpace":
+    def property_space(self) -> HilbertSpace:
         """The Hilbert space in which the property `p` resides."""
         return self._property_operator.codomain
 
     @property
-    def property_operator(self) -> "LinearOperator":
+    def property_operator(self) -> LinearOperator:
         """The linear operator `B` that defines the property."""
         return self._property_operator
 
-    def property_prior_measure(self) -> "GaussianMeasure":
+    def property_prior_measure(self) -> GaussianMeasure:
         """
         Returns the prior measure on the property space, `p(p)`.
 
@@ -196,12 +217,12 @@ class LinearBayesianInference(LinearBayesianInversion):
 
     def property_posterior_measure(
         self,
-        data: "T_vec",
-        solver: "LinearSolver",
+        data: Vector,
+        solver: LinearSolver,
         /,
         *,
-        preconditioner: Optional["LinearOperator"] = None,
-    ) -> "GaussianMeasure":
+        preconditioner: Optional[LinearOperator] = None,
+    ) -> GaussianMeasure:
         """
         Returns the posterior measure on the property space, `p(p|d)`.
 

pygeoinf/linear_forms.py

@@ -0,0 +1,169 @@
+"""
+Provides the `LinearForm` class to represent linear functionals.
+
+A linear form is a linear mapping from a vector in a Hilbert space to a
+scalar (a real number). This class provides a concrete representation for
+elements of the dual space of a `HilbertSpace`.
+
+A `LinearForm` can be thought of as a dual vector and is a fundamental component
+for defining inner products and adjoint operators within the library.
+"""
+
+from __future__ import annotations
+from typing import Callable, Optional, Any, TYPE_CHECKING
+
+import numpy as np
+
+# This block only runs for type checkers, not at runtime
+if TYPE_CHECKING:
+    from .hilbert_space import HilbertSpace, EuclideanSpace
+    from .operators import LinearOperator
+
+
+class LinearForm:
+    """
+    Represents a linear form, a functional that maps vectors to scalars.
+
+    A `LinearForm` is an element of a dual `HilbertSpace`. It is defined by its
+    action on vectors from its `domain` space. Internally, this action is
+    represented by a component vector, which when dotted with the component
+    vector of a primal space element, produces the scalar result.
+    """
+
+    def __init__(
+        self,
+        domain: HilbertSpace,
+        /,
+        *,
+        mapping: Optional[Callable[[Any], float]] = None,
+        components: Optional[np.ndarray] = None,
+    ) -> None:
+        """
+        Initializes the LinearForm.
+
+        A form can be defined either by its functional mapping or directly
+        by its component vector. If a mapping is provided without components,
+        the components will be computed by evaluating the mapping on the
+        basis vectors of the domain.
+
+        Args:
+            domain: The Hilbert space on which the form is defined.
+            mapping: A function `f(x)` defining the action of the form.
+            components: The component representation of the form.
+        """
+
+        self._domain: HilbertSpace = domain
+
+        if components is None:
+            if mapping is None:
+                raise AssertionError("Neither mapping nor components specified.")
+            self._compute_components(mapping)
+        else:
+            self._components: np.ndarray = components
+
+    @staticmethod
+    def from_linear_operator(operator: "LinearOperator") -> LinearForm:
+        """
+        Creates a LinearForm from an operator that maps to a 1D Euclidean space.
+        """
+        from .hilbert_space import EuclideanSpace
+
+        assert operator.codomain == EuclideanSpace(1)
+        return LinearForm(operator.domain, mapping=lambda x: operator(x)[0])
+
+    @property
+    def domain(self) -> HilbertSpace:
+        """The Hilbert space on which the form is defined."""
+        return self._domain
+
+    @property
+    def components(self) -> np.ndarray:
+        """
+        The component vector of the form.
+        """
+        return self._components
+
+    @property
+    def as_linear_operator(self) -> "LinearOperator":
+        """
+        Represents the linear form as a `LinearOperator`.
+
+        The resulting operator maps from the form's original domain to a
+        1-dimensional `EuclideanSpace`, where the single component of the output
+        is the scalar result of the form's action.
+        """
+        from .hilbert_space import EuclideanSpace
+        from .operators import LinearOperator
+
+        return LinearOperator(
+            self.domain,
+            EuclideanSpace(1),
+            lambda x: np.array([self(x)]),
+            dual_mapping=lambda y: y * self,
+        )
+
+    def copy(self) -> LinearForm:
+        """
+        Creates a deep copy of the linear form.
+        """
+        return LinearForm(self.domain, components=self.components.copy())
+
+    def __call__(self, x: Any) -> float:
+        """Applies the linear form to a vector."""
+        return np.dot(self._components, self.domain.to_components(x))
+
+    def __neg__(self) -> LinearForm:
+        """Returns the additive inverse of the form."""
+        return LinearForm(self.domain, components=-self._components)
+
+    def __mul__(self, a: float) -> LinearForm:
+        """Returns the product of the form and a scalar."""
+        return LinearForm(self.domain, components=a * self._components)
+
+    def __rmul__(self, a: float) -> LinearForm:
+        """Returns the product of the form and a scalar."""
+        return self * a
+
+    def __truediv__(self, a: float) -> LinearForm:
+        """Returns the division of the form by a scalar."""
+        return self * (1.0 / a)
+
+    def __add__(self, other: LinearForm) -> LinearForm:
+        """Returns the sum of this form and another."""
+        return LinearForm(self.domain, components=self.components + other.components)
+
+    def __sub__(self, other: LinearForm) -> LinearForm:
+        """Returns the difference between this form and another."""
+        return LinearForm(self.domain, components=self.components - other.components)
+
+    def __imul__(self, a: float) -> "LinearForm":
+        """
+        Performs in-place scalar multiplication: self *= a.
+        """
+        self._components *= a
+        return self
+
+    def __iadd__(self, other: "LinearForm") -> "LinearForm":
+        """
+        Performs in-place addition with another form: self += other.
+        """
+        if self.domain != other.domain:
+            raise ValueError("Linear forms must share the same domain for addition.")
+        self._components += other.components
+        return self
+
+    def __str__(self) -> str:
+        """Returns the string representation of the form's components."""
+        return self.components.__str__()
+
+    def _compute_components(self, mapping: Callable[[Any], float]):
+        """
+        Computes the component vector of the form.
+        """
+        self._components = np.zeros(self.domain.dim)
+        cx = np.zeros(self.domain.dim)
+        for i in range(self.domain.dim):
+            cx[i] = 1
+            x = self.domain.from_components(cx)
+            self._components[i] = mapping(x)
+            cx[i] = 0

pygeoinf/linear_optimisation.py

@@ -1,8 +1,21 @@
 """
-Module for solving inverse problems using optimisation methods.
-
-This module provides classes for finding solutions to inverse problems via
-regularized least-squares and minimum-norm criteria.
+Implements optimisation-based methods for solving linear inverse problems.
+
+This module provides classical, deterministic approaches to inversion that seek
+a single "best-fit" model. These methods are typically formulated as finding
+the model `u` that minimizes a cost functional.
+
+The primary goal is to find a stable solution to an ill-posed problem by
+incorporating regularization, which balances fitting the data with controlling
+the complexity or norm of the solution.
+
+Key Classes
+-----------
+- `LinearLeastSquaresInversion`: Solves the inverse problem by minimizing a
+  Tikhonov-regularized least-squares functional.
+- `LinearMinimumNormInversion`: Finds the model with the smallest norm that
+  fits the data to a statistically acceptable degree using the discrepancy
+  principle.
 """
 
 from __future__ import annotations
@@ -15,7 +28,7 @@ from .inversion import Inversion
 from .forward_problem import LinearForwardProblem
 from .operators import LinearOperator
 from .linear_solvers import LinearSolver, IterativeLinearSolver
-from .hilbert_space import T_vec
+from .hilbert_space import Vector
 
 
 class LinearLeastSquaresInversion(Inversion):
@@ -23,8 +36,9 @@ class LinearLeastSquaresInversion(Inversion):
     Solves a linear inverse problem using Tikhonov-regularized least-squares.
 
     This method finds the model `u` that minimizes the functional:
-    `J(u) = ||A(u) - d||^2 + alpha^2 * ||u||^2`
-    where the norms are appropriately weighted if a data error covariance is provided.
+    `J(u) = ||A(u) - d||² + α² * ||u||²`
+    where `α` is the damping parameter. If a data error covariance is provided,
+    the data misfit norm is appropriately weighted by the inverse covariance.
     """
 
     def __init__(self, forward_problem: "LinearForwardProblem", /) -> None:
@@ -41,19 +55,15 @@ class LinearLeastSquaresInversion(Inversion):
         """
         Returns the Tikhonov-regularized normal operator.
 
-        If a data error covariance `C_e` is provided, the operator is:
-        `N = A^T * C_e^-1 * A + alpha * I`
-        Otherwise, it is:
-        `N = A^T * A + alpha * I`
+        This operator, often written as `(A* @ W @ A + α*I)`, forms the left-hand
+        side of the normal equations that must be solved to find the least-squares
+        solution. `W` is the inverse data covariance (or identity).
 
         Args:
-            damping: The Tikhonov damping parameter, `alpha`. Must be non-negative.
+            damping: The Tikhonov damping parameter, `α`. Must be non-negative.
 
         Returns:
             The normal operator as a `LinearOperator`.
-
-        Raises:
-            ValueError: If the damping parameter is negative.
         """
         if damping < 0:
             raise ValueError("Damping parameter must be non-negative.")
@@ -111,7 +121,7 @@ class LinearLeastSquaresInversion(Inversion):
             )
 
             # This mapping is affine, not linear, if the error measure has a non-zero mean.
-            def mapping(data: "T_vec") -> "T_vec":
+            def mapping(data: "Vector") -> "Vector":
                 shifted_data = self.forward_problem.data_space.subtract(
                     data, self.forward_problem.data_error_measure.expectation
                 )
@@ -129,11 +139,12 @@ class LinearLeastSquaresInversion(Inversion):
 
 class LinearMinimumNormInversion(Inversion):
     """
-    Finds the minimum-norm solution to a linear inverse problem.
+    Finds a regularized solution using the discrepancy principle.
 
-    This method finds the model `u` with the smallest norm `||u||` that fits
-    the data `d` to a statistically acceptable level, as determined by a
-    chi-squared test.
+    This method automatically selects a Tikhonov damping parameter `α` such that
+    the resulting solution `u_α` fits the data to a statistically acceptable
+    level. It finds the model with the smallest norm `||u||` that satisfies
+    the target misfit, as determined by a chi-squared test.
     """
 
     def __init__(self, forward_problem: "LinearForwardProblem", /) -> None:
@@ -185,8 +196,8 @@ class LinearMinimumNormInversion(Inversion):
             lsq_inversion = LinearLeastSquaresInversion(self.forward_problem)
 
             def get_model_for_damping(
-                damping: float, data: "T_vec", model0: Optional["T_vec"] = None
-            ) -> tuple["T_vec", float]:
+                damping: float, data: "Vector", model0: Optional["Vector"] = None
+            ) -> tuple["Vector", float]:
                 """Computes the LS model and its chi-squared for a given damping."""
                 op = lsq_inversion.least_squares_operator(
                     damping, solver, preconditioner=preconditioner
@@ -195,7 +206,7 @@ class LinearMinimumNormInversion(Inversion):
                 chi_squared = self.forward_problem.chi_squared(model, data)
                 return model, chi_squared
 
-            def mapping(data: "T_vec") -> "T_vec":
+            def mapping(data: "Vector") -> "Vector":
                 """The non-linear mapping from data to the minimum-norm model."""
                 model = self.model_space.zero
                 chi_squared = self.forward_problem.chi_squared(model, data)