pygeoinf 1.2.0__py3-none-any.whl → 1.2.2__py3-none-any.whl

pygeoinf/inversion.py

@@ -13,22 +13,25 @@ inversion techniques, such as the existence of a data error measure.
 
 from __future__ import annotations
 
-from .forward_problem import LinearForwardProblem
+
 from .hilbert_space import HilbertSpace
+from .nonlinear_operators import NonLinearOperator
+from .linear_operators import LinearOperator
+from .forward_problem import LinearForwardProblem, ForwardProblem
 
 
 class Inversion:
     """
-    An abstract base class for inversion methods.
+    A base class for inversion methods.
 
-    This class provides a common structure for different inversion algorithms
+    This class provides a common structure for different inversion and inference algorithms
     (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.
+    specific inversion algorithm.
     """
 
-    def __init__(self, forward_problem: "LinearForwardProblem", /) -> None:
+    def __init__(self, forward_problem: ForwardProblem, /) -> None:
         """
         Initializes the Inversion class.
 
@@ -36,20 +39,20 @@ class Inversion:
             forward_problem: An instance of a forward problem that defines the
                 relationship between model parameters and data.
         """
-        self._forward_problem: "LinearForwardProblem" = forward_problem
+        self._forward_problem: ForwardProblem = forward_problem
 
     @property
-    def forward_problem(self) -> "LinearForwardProblem":
+    def forward_problem(self) -> ForwardProblem:
         """The forward problem associated with this inversion."""
         return self._forward_problem
 
     @property
-    def model_space(self) -> "HilbertSpace":
+    def model_space(self) -> HilbertSpace:
         """The model space (domain) of the forward problem."""
         return self.forward_problem.model_space
 
     @property
-    def data_space(self) -> "HilbertSpace":
+    def data_space(self) -> HilbertSpace:
         """The data space (codomain) of the forward problem."""
         return self.forward_problem.data_space
 
@@ -83,3 +86,92 @@ class Inversion:
             raise AttributeError(
                 "An inverse data covariance (precision) operator is required for this inversion method."
             )
+
+
+class LinearInversion(Inversion):
+    """
+    An abstract base class for linear inversion algorithms.
+    """
+
+    def __init__(self, forward_problem: LinearForwardProblem, /) -> None:
+        """
+        Initializes the LinearInversion class.
+
+        Args:
+            forward_problem: An instance of a linear forward problem.
+        """
+        if not isinstance(forward_problem, LinearForwardProblem):
+            raise ValueError("Forward problem must be a LinearForwardProblem.")
+        super().__init__(forward_problem)
+
+
+class Inference(Inversion):
+    """
+    A base class for inference algorithms. These methods inherit common functionality from
+    the inversion base class, but need not themselves derive from a specific inversion scheme.
+
+    Within an inference problem, the aim is to estimate some property of the unknown model,
+    and hence a property operator mapping from the model to a property space must be
+    specified.
+    """
+
+    def __init__(
+        self, forward_problem: ForwardProblem, property_operator: NonLinearOperator
+    ) -> None:
+        """
+        Initializes the Inference class.
+
+        Args:
+            forward_problem: An instance of a forward problem that defines the
+                relationship between model parameters and data.
+            property_operator: A mapping takes elements of the model space to
+                property vector of interest.
+        """
+
+        super().__init__(forward_problem)
+
+        if property_operator.domain != self.model_space:
+            raise ValueError("Property operator incompatible with model space")
+
+        self._property_operator = property_operator
+
+    @property
+    def property_operator(self) -> NonLinearOperator:
+        """
+        Returns the property operator.
+        """
+        return self._property_operator
+
+    @property
+    def property_space(self) -> HilbertSpace:
+        """
+        Returns the property space.
+        """
+        return self.property_operator.codomain
+
+
+class LinearInference(Inference):
+    """
+    A base class for linear inference algorithms.
+    """
+
+    def __init__(
+        self, forward_problem: LinearForwardProblem, property_operator: LinearOperator
+    ) -> None:
+        """
+        Initializes the LinearInference class.
+
+        Args:
+            forward_problem: An instance of a linear forward problem that defines the
+                relationship between model parameters and data.
+            property_operator: A linear mapping takes elements of the model space to
+                property vector of interest.
+        """
+
+        if not isinstance(forward_problem, LinearForwardProblem):
+            raise ValueError("Forward problem must be linear")
+
+        if not isinstance(property_operator, LinearOperator):
+            raise ValueError("Property mapping must be linear")
+
+        super().__init__(forward_problem, property_operator)

pygeoinf/linear_bayesian.py

@@ -23,17 +23,17 @@ Key Classes
 from __future__ import annotations
 from typing import Optional
 
-from .inversion import Inversion
+from .inversion import LinearInversion
 from .gaussian_measure import GaussianMeasure
 
 
 from .forward_problem import LinearForwardProblem
-from .operators import LinearOperator
+from .linear_operators import LinearOperator
 from .linear_solvers import LinearSolver, IterativeLinearSolver
 from .hilbert_space import HilbertSpace, Vector
 
 
-class LinearBayesianInversion(Inversion):
+class LinearBayesianInversion(LinearInversion):
     """
     Solves a linear inverse problem using Bayesian methods.
 

pygeoinf/linear_forms.py

@@ -1,33 +1,36 @@
 """
-Provides the `LinearForm` class to represent linear functionals.
+Provides the `LinearForm` class for representing 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.
+scalar. This class provides a concrete, component-based representation for
+elements of the dual space of a `HilbertSpace`. It inherits from `NonLinearForm`,
+specializing it for the linear case.
 """
 
 from __future__ import annotations
 from typing import Callable, Optional, Any, TYPE_CHECKING
 
+from joblib import Parallel, delayed
+
 import numpy as np
 
+from .nonlinear_forms import NonLinearForm
+
 # This block only runs for type checkers, not at runtime
 if TYPE_CHECKING:
-    from .hilbert_space import HilbertSpace, EuclideanSpace
-    from .operators import LinearOperator
+    from .hilbert_space import HilbertSpace, EuclideanSpace, Vector
+    from .linear_operators import LinearOperator
 
 
-class LinearForm:
+class LinearForm(NonLinearForm):
     """
-    Represents a linear form, a functional that maps vectors to scalars.
+    Represents a linear form as an efficient, component-based functional.
 
-    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.
+    A `LinearForm` is an element of a dual `HilbertSpace` and is defined by its
+    action on vectors from its `domain`. Internally, this action is represented
+    by a component vector. This class provides optimized arithmetic operations
+    and correctly defines the gradient (a constant vector) and the Hessian
+    (the zero operator) for any linear functional.
     """
 
     def __init__(
@@ -35,29 +38,49 @@ class LinearForm:
         domain: HilbertSpace,
         /,
         *,
-        mapping: Optional[Callable[[Any], float]] = None,
         components: Optional[np.ndarray] = None,
+        mapping: Optional[Callable[[Vector], float]] = None,
+        parallel: bool = False,
+        n_jobs: int = -1,
     ) -> None:
         """
-        Initializes the LinearForm.
+        Initializes the LinearForm from a mapping or component vector.
+
+        A form must be defined by exactly one of two methods:
+        1.  **components**: The explicit component vector representing the form.
+        2.  **mapping**: A function `f(x)` that defines the form's action.
+            The components will be automatically computed from this mapping.
 
-        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.
+            mapping: The functional mapping `f(x)`. Used if `components` is None.
+            parallel: Whether to use parallel computing components from the mapping.
+            n_jobs: The number of jobs to use for parallel computing.
+
+        Raises:
+            AssertionError: If neither or both `mapping` and `components`
+                are specified.
+
+        Notes:
+            Parallel options only relevant if the form is defined by a mapping.
+
+            If both `components` and `mapping` are specified, `components`
+            will take precedence.
         """
 
-        self._domain: HilbertSpace = domain
+        super().__init__(
+            domain,
+            self._mapping_impl,
+            gradient=self._gradient_impl,
+            hessian=self._hessian_impl,
+        )
 
         if components is None:
             if mapping is None:
                 raise AssertionError("Neither mapping nor components specified.")
-            self._compute_components(mapping)
+            self._compute_components(mapping, parallel, n_jobs)
         else:
             self._components: np.ndarray = components
 
@@ -93,7 +116,7 @@ class LinearForm:
         is the scalar result of the form's action.
         """
         from .hilbert_space import EuclideanSpace
-        from .operators import LinearOperator
+        from .linear_operators import LinearOperator
 
         return LinearOperator(
             self.domain,
@@ -108,10 +131,6 @@ class LinearForm:
         """
         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)
@@ -128,13 +147,47 @@ class 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 __add__(self, other: NonLinearForm | LinearForm) -> NonLinearForm | LinearForm:
+        """
+        Returns the sum of this form and another.
+
+        If `other` is also a `LinearForm`, this performs an optimized,
+        component-wise addition. Otherwise, it delegates to the general
+        implementation in the `NonLinearForm` base class.
+
+        Args:
+            other: The form to add to this one.
+
+        Returns:
+            A `LinearForm` if adding two `LinearForm`s, otherwise a `NonLinearForm`.
+        """
+        if isinstance(other, LinearForm):
+            return LinearForm(
+                self.domain, components=self.components + other.components
+            )
+        else:
+            return super().__add__(other)
+
+    def __sub__(self, other: NonLinearForm | LinearForm) -> NonLinearForm | LinearForm:
+        """
+        Returns the difference of this form and another.
+
+        If `other` is also a `LinearForm`, this performs an optimized,
+        component-wise subtraction. Otherwise, it delegates to the general
+        implementation in the `NonLinearForm` base class.
+
+        Args:
+            other: The form to subtract from this one.
 
-    def __sub__(self, other: LinearForm) -> LinearForm:
-        """Returns the difference between this form and another."""
-        return LinearForm(self.domain, components=self.components - other.components)
+        Returns:
+            A `LinearForm` if subtracting two `LinearForm`s, otherwise a `NonLinearForm`.
+        """
+        if isinstance(other, LinearForm):
+            return LinearForm(
+                self.domain, components=self.components - other.components
+            )
+        else:
+            return super().__sub__(other)
 
     def __imul__(self, a: float) -> "LinearForm":
         """
@@ -156,14 +209,55 @@ class LinearForm:
         """Returns the string representation of the form's components."""
         return self.components.__str__()
 
-    def _compute_components(self, mapping: Callable[[Any], float]):
+    def _compute_components(
+        self,
+        mapping: Callable[[Any], float],
+        parallel: bool,
+        n_jobs: Optional[int],
+    ):
+        """Computes the component vector of the form, with an optional parallel backend."""
+        if not parallel:
+            self._components = np.zeros(self.domain.dim)
+            cx = np.zeros(self.domain.dim)
+            for i in range(self.domain.dim):
+                cx[i] = 1.0
+                x = self.domain.from_components(cx)
+                self._components[i] = mapping(x)
+                cx[i] = 0.0
+        else:
+
+            def compute_one_component(i: int) -> float:
+                """
+                Computes a single component for a given basis vector index.
+                This function is sent to each parallel worker.
+                """
+
+                # cx = np.zeros(self.domain.dim)
+                # cx[i] = 1.0
+                # x = self.domain.from_components(cx)
+                x = self.domain.basis_vector(i)
+                return mapping(x)
+
+            # Run the helper function in parallel for each dimension
+            results = Parallel(n_jobs=n_jobs)(
+                delayed(compute_one_component)(i) for i in range(self.domain.dim)
+            )
+            self._components = np.array(results)
+
+    def _mapping_impl(self, x: Vector) -> float:
+        """
+        Maps a vector to its scalar value.
+        """
+        return np.dot(self.components, self.domain.to_components(x))
+
+    def _gradient_impl(self, _: Vector) -> Vector:
+        """
+        Computes the gradient of the form at a point.
+        """
+        return self.domain.from_dual(self)
+
+    def _hessian_impl(self, _: Vector) -> LinearOperator:
         """
-        Computes the component vector of the form.
+        Computes the Hessian of the form at a point.
         """
-        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
+        return self.domain.zero_operator()