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

pygeoinf/linear_optimisation.py

@@ -21,17 +21,17 @@ Key Classes
 from __future__ import annotations
 from typing import Optional, Union
 
-from .operators import Operator
-from .inversion import Inversion
+from .nonlinear_operators import NonLinearOperator
+from .inversion import LinearInversion
 
 
 from .forward_problem import LinearForwardProblem
-from .operators import LinearOperator
+from .linear_operators import LinearOperator
 from .linear_solvers import LinearSolver, IterativeLinearSolver
 from .hilbert_space import Vector
 
 
-class LinearLeastSquaresInversion(Inversion):
+class LinearLeastSquaresInversion(LinearInversion):
     """
     Solves a linear inverse problem using Tikhonov-regularized least-squares.
 
@@ -89,7 +89,7 @@ class LinearLeastSquaresInversion(Inversion):
         /,
         *,
         preconditioner: Optional[LinearOperator] = None,
-    ) -> Union[Operator, LinearOperator]:
+    ) -> Union[NonLinearOperator, LinearOperator]:
         """
         Returns an operator that maps data to the least-squares solution.
 
@@ -131,13 +131,13 @@ class LinearLeastSquaresInversion(Inversion):
                     @ inverse_data_covariance
                 )(shifted_data)
 
-            return Operator(self.data_space, self.model_space, mapping)
+            return NonLinearOperator(self.data_space, self.model_space, mapping)
 
         else:
             return inverse_normal_operator @ forward_operator.adjoint
 
 
-class LinearMinimumNormInversion(Inversion):
+class LinearMinimumNormInversion(LinearInversion):
     """
     Finds a regularized solution using the discrepancy principle.
 
@@ -168,7 +168,7 @@ class LinearMinimumNormInversion(Inversion):
         maxiter: int = 100,
         rtol: float = 1.0e-6,
         atol: float = 0.0,
-    ) -> Union[Operator, LinearOperator]:
+    ) -> Union[NonLinearOperator, LinearOperator]:
         """
         Returns an operator that maps data to the minimum-norm solution.
 
@@ -262,7 +262,7 @@ class LinearMinimumNormInversion(Inversion):
 
                 raise RuntimeError("Bracketing search failed to converge.")
 
-            return Operator(self.data_space, self.model_space, mapping)
+            return NonLinearOperator(self.data_space, self.model_space, mapping)
 
         else:
             # For error-free data, compute the minimum-norm solution via A*(A*A)^-1

pygeoinf/linear_solvers.py

@@ -24,15 +24,10 @@ from typing import Callable, Optional, Dict, Any
 
 import numpy as np
 from scipy.sparse.linalg import LinearOperator as ScipyLinOp
-from scipy.linalg import (
-    cho_factor,
-    cho_solve,
-    lu_factor,
-    lu_solve,
-)
+from scipy.linalg import cho_factor, cho_solve, lu_factor, lu_solve, eigh
 from scipy.sparse.linalg import gmres, bicgstab, cg, bicg
 
-from .operators import LinearOperator
+from .linear_operators import LinearOperator
 from .hilbert_space import Vector
 
 
@@ -167,6 +162,78 @@ class CholeskySolver(DirectLinearSolver):
         )
 
 
+class EigenSolver(DirectLinearSolver):
+    """
+    A direct linear solver based on the eigendecomposition of a symmetric operator.
+
+    This solver is robust for symmetric operators that may be singular or
+    numerically ill-conditioned. In such cases, it computes a pseudo-inverse by
+    regularizing the eigenvalues, treating those close to zero (relative to the largest
+    eigenvalue) as exactly zero.
+    """
+
+    def __init__(
+        self,
+        /,
+        *,
+        galerkin: bool = False,
+        parallel: bool = False,
+        n_jobs: int = -1,
+        rtol: float = 1e-12,
+    ) -> None:
+        """
+        Args:
+            galerkin (bool): If True, the Galerkin matrix representation is used.
+            parallel (bool): If True, parallel computation is used.
+            n_jobs (int): Number of parallel jobs.
+            rtol (float): Relative tolerance for treating eigenvalues as zero.
+                An eigenvalue `s` is treated as zero if
+                `abs(s) < rtol * max(abs(eigenvalues))`.
+        """
+        super().__init__(galerkin=galerkin, parallel=parallel, n_jobs=n_jobs)
+        self._rtol = rtol
+
+    def __call__(self, operator: LinearOperator) -> LinearOperator:
+        """
+        Computes the pseudo-inverse of a self-adjoint LinearOperator.
+        """
+        assert operator.is_automorphism
+
+        matrix = operator.matrix(
+            dense=True,
+            galerkin=self._galerkin,
+            parallel=self._parallel,
+            n_jobs=self._n_jobs,
+        )
+
+        eigenvalues, eigenvectors = eigh(matrix)
+
+        max_abs_eigenvalue = np.max(np.abs(eigenvalues))
+        if max_abs_eigenvalue > 0:
+            threshold = self._rtol * max_abs_eigenvalue
+        else:
+            threshold = 0
+
+        inv_eigenvalues = np.where(
+            np.abs(eigenvalues) > threshold,
+            np.reciprocal(eigenvalues),
+            0.0,
+        )
+
+        def matvec(cy: np.ndarray) -> np.ndarray:
+            z = eigenvectors.T @ cy
+            w = inv_eigenvalues * z
+            return eigenvectors @ w
+
+        inverse_matrix = ScipyLinOp(
+            (operator.domain.dim, operator.codomain.dim), matvec=matvec, rmatvec=matvec
+        )
+
+        return LinearOperator.from_matrix(
+            operator.domain, operator.domain, inverse_matrix, galerkin=self._galerkin
+        )
+
+
 class IterativeLinearSolver(LinearSolver):
     """
     An abstract base class for iterative linear solvers.

pygeoinf/nonlinear_forms.py

@@ -0,0 +1,226 @@
+"""
+Provides the `NonLinearForm` base class to represent non-linear functionals.
+
+A non-linear form, or functional, is a mapping from a vector in a Hilbert
+space to a scalar. This class provides a foundational structure for these
+functionals, equipping them with algebraic operations and an interface for
+derivatives like gradients and Hessians.
+"""
+
+from __future__ import annotations
+from typing import Callable, Optional, Any, TYPE_CHECKING
+
+
+# This block only runs for type checkers, not at runtime
+if TYPE_CHECKING:
+    from .hilbert_space import HilbertSpace, Vector
+    from .linear_forms import LinearForm
+    from .linear_operators import LinearOperator
+    from .nonlinear_operators import NonLinearOperator
+
+
+class NonLinearForm:
+    """
+    Represents a general non-linear functional that maps vectors to scalars.
+
+    This class serves as the foundation for all forms. It defines the basic
+    callable interface `form(x)` and overloads arithmetic operators (`+`, `-`, `*`)
+    to create new forms. It also provides an optional framework for specifying
+    a form's gradient and Hessian.
+    """
+
+    def __init__(
+        self,
+        domain: HilbertSpace,
+        mapping: Callable[[Vector], float],
+        /,
+        *,
+        gradient: Optional[Callable[[Vector], Vector]] = None,
+        hessian: Optional[Callable[[Vector], LinearOperator]] = None,
+    ) -> None:
+        """
+        Initializes the NonLinearForm.
+
+        Args:
+            domain: The Hilbert space on which the form is defined.
+            mapping: The function `f(x)` that defines the action of the form.
+            gradient: An optional function that computes the gradient of the form.
+            hessian: An optional function that computes the Hessian of the form.
+        """
+
+        self._domain: HilbertSpace = domain
+        self._mapping = mapping
+        self._gradient = gradient
+        self._hessian = hessian
+
+    @property
+    def domain(self) -> HilbertSpace:
+        """The Hilbert space on which the form is defined."""
+        return self._domain
+
+    @property
+    def has_gradient(self) -> bool:
+        """True if the form has a gradient."""
+        return self._gradient is not None
+
+    @property
+    def has_hessian(self) -> bool:
+        """True if the form has a Hessian."""
+        return self._hessian is not None
+
+    def __call__(self, x: Any) -> float:
+        """Applies the linear form to a vector."""
+        return self._mapping(x)
+
+    def gradient(self, x: Any) -> Vector:
+        """
+        Computes the gradient of the form at a given point.
+
+        Args:
+            x: The vector at which to evaluate the gradient.
+
+        Returns:
+            The gradient of the form as a vector in the domain space.
+
+        Raises:
+            NotImplementedError: If a gradient function was not provided
+                during initialization.
+        """
+        if self._gradient is None:
+            raise NotImplementedError("Gradient not implemented for this form.")
+        return self._gradient(x)
+
+    def derivative(self, x: Vector) -> LinearForm:
+        """
+        Computes the derivative of the form at a given point.
+
+        Args:
+            x: The vector at which to evaluate the derivative.
+
+        Returns:
+            The derivative of the form as a `LinearForm`.
+
+        Raises:
+            NotImplementedError: If a gradient function was not provided
+                during initialization.
+        """
+        return self.domain.to_dual(self.gradient(x))
+
+    def hessian(self, x: Any) -> LinearOperator:
+        """
+        Computes the Hessian of the form at a given point.
+
+        Args:
+            x: The vector at which to evaluate the Hessian.
+
+        Returns:
+            The Hessian of the form as a LinearOperator mapping the domain to itself.
+
+        Raises:
+            NotImplementedError: If a Hessian function was not provided
+                during initialization.
+        """
+        if self._hessian is None:
+            raise NotImplementedError("Hessian not implemented for this form.")
+        return self._hessian(x)
+
+    def __neg__(self) -> NonLinearForm:
+        """Returns the additive inverse of the form."""
+
+        if self._gradient is None:
+            gradient = None
+        else:
+
+            def gradient(x: Vector) -> Vector:
+                return self.domain.negative(self.gradient(x))
+
+        if self._hessian is None:
+            hessian = None
+        else:
+
+            def hessian(x: Vector) -> LinearOperator:
+                return -self.hessian(x)
+
+        return NonLinearForm(
+            self.domain, lambda x: -self(x), gradient=gradient, hessian=hessian
+        )
+
+    def __mul__(self, a: float) -> NonLinearForm:
+        """Returns the product of the form and a scalar."""
+
+        if self._gradient is None:
+            gradient = None
+        else:
+
+            def gradient(x: Vector) -> Vector:
+                return self.domain.multiply(a, self.gradient(x))
+
+        if self._hessian is None:
+            hessian = None
+        else:
+
+            def hessian(x: Vector) -> LinearOperator:
+                return a * self.hessian(x)
+
+        return NonLinearForm(
+            self.domain,
+            lambda x: a * self(x),
+            gradient=gradient,
+            hessian=hessian,
+        )
+
+    def __rmul__(self, a: float) -> NonLinearForm:
+        """Returns the product of the form and a scalar."""
+        return self * a
+
+    def __truediv__(self, a: float) -> NonLinearForm:
+        """Returns the division of the form by a scalar."""
+        return self * (1.0 / a)
+
+    def __add__(self, other: NonLinearForm) -> NonLinearForm:
+        """Returns the sum of this form and another."""
+
+        if self._gradient is None or other._gradient is None:
+            gradient = None
+        else:
+
+            def gradient(x: Vector) -> Vector:
+                return self.domain.add(self.gradient(x), other.gradient(x))
+
+        if self._hessian is None or other._hessian is None:
+            hessian = None
+        else:
+
+            def hessian(x: Vector) -> LinearOperator:
+                return self.hessian(x) + other.hessian(x)
+
+        return NonLinearForm(
+            self.domain,
+            lambda x: self(x) + other(x),
+            gradient=gradient,
+            hessian=hessian,
+        )
+
+    def __sub__(self, other: NonLinearForm) -> NonLinearForm:
+        """Returns the difference between this form and another."""
+
+        if self._gradient is None or other._gradient is None:
+            gradient = None
+        else:
+
+            def gradient(x: Vector) -> Vector:
+                return self.domain.subtract(self.gradient(x), other.gradient(x))
+
+        if self._hessian is None or other._hessian is None:
+            hessian = None
+        else:
+
+            def hessian(x: Vector) -> LinearOperator:
+                return self.hessian(x) - other.hessian(x)
+
+        return NonLinearForm(
+            self.domain,
+            lambda x: self(x) - other(x),
+            gradient=gradient,
+            hessian=hessian,
+        )

pygeoinf/nonlinear_operators.py

@@ -0,0 +1,216 @@
+"""
+Provides the `NonLinearOperator` base class for mappings between Hilbert spaces.
+
+A non-linear operator is a general mapping `F(x)` from a vector `x` in a
+domain Hilbert space to a vector `y` in a codomain Hilbert space. This class
+provides a foundational structure for these mappings, equipping them with
+algebraic operations and an interface for the Frécher derivative.
+"""
+
+from __future__ import annotations
+from typing import Callable, Optional, Any, TYPE_CHECKING
+
+
+# This block only runs for type checkers, not at runtime
+if TYPE_CHECKING:
+    from .hilbert_space import HilbertSpace, EuclideanSpace, Vector
+    from .linear_operators import LinearOperator
+
+
+class NonLinearOperator:
+    """
+    Represents a general non-linear operator that maps vectors to vectors.
+
+    This class provides a functional representation for an operator `F(x)`,
+    and includes an interface for its Fréchet derivative, F'(x), which is the
+    linear operator that best approximates F at a given point x. It serves
+    as the base class for the more specialized `LinearOperator`.
+    """
+
+    def __init__(
+        self,
+        domain: HilbertSpace,
+        codomain: HilbertSpace,
+        mapping: Callable[[Vector], Any],
+        /,
+        *,
+        derivative: Callable[[Vector], LinearOperator] = None,
+    ) -> None:
+        """Initializes the NonLinearOperator.
+
+        Args:
+            domain: The Hilbert space from which the operator maps.
+            codomain: The Hilbert space to which the operator maps.
+            mapping: The function `F(x)` that defines the mapping.
+            derivative: An optional function that takes a vector `x` and
+                returns the Fréchet derivative (a `LinearOperator`) at
+                that point.
+        """
+        self._domain: HilbertSpace = domain
+        self._codomain: HilbertSpace = codomain
+        self._mapping: Callable[[Any], Any] = mapping
+        self._derivative: Callable[[Any], LinearOperator] = derivative
+
+    @property
+    def domain(self) -> HilbertSpace:
+        """The domain of the operator."""
+        return self._domain
+
+    @property
+    def codomain(self) -> HilbertSpace:
+        """The codomain of the operator."""
+        return self._codomain
+
+    @property
+    def is_automorphism(self) -> bool:
+        """True if the operator maps a space into itself."""
+        return self.domain == self.codomain
+
+    @property
+    def is_square(self) -> bool:
+        """True if the operator's domain and codomain have the same dimension."""
+        return self.domain.dim == self.codomain.dim
+
+    @property
+    def has_derivative(self) -> bool:
+        """
+        Returns true if the operators derivative is implemented.
+        """
+        return self._derivative is not None
+
+    def __call__(self, x: Any) -> Any:
+        """Applies the operator's mapping to a vector."""
+        return self._mapping(x)
+
+    def derivative(self, x: Vector) -> LinearOperator:
+        """Computes the Fréchet derivative of the operator at a given point.
+
+        The Fréchet derivative is the linear operator that best approximates
+        the non-linear operator in the neighborhood of the point `x`.
+
+        Args:
+            x: The point at which to compute the derivative.
+
+        Returns:
+            The derivative as a `LinearOperator`.
+
+        Raises:
+            NotImplementedError: If a derivative function was not provided.
+        """
+        if self._derivative is None:
+            raise NotImplementedError("Derivative not implemented")
+        return self._derivative(x)
+
+    def __neg__(self) -> NonLinearOperator:
+        domain = self.domain
+        codomain = self.codomain
+
+        def mapping(x: Any) -> Any:
+            return codomain.negative(self(x))
+
+        if self._derivative is not None:
+
+            def derivative(x: Vector) -> LinearOperator:
+                return -self.derivative(x)
+
+        else:
+            derivative = None
+
+        return NonLinearOperator(domain, codomain, mapping, derivative=derivative)
+
+    def __mul__(self, a: float) -> NonLinearOperator:
+        domain = self.domain
+        codomain = self.codomain
+
+        def mapping(x: Any) -> Any:
+            return codomain.multiply(a, self(x))
+
+        if self._derivative is not None:
+
+            def derivative(x: Vector) -> LinearOperator:
+                return a * self.derivative(x)
+
+        else:
+            derivative = None
+
+        return NonLinearOperator(domain, codomain, mapping, derivative=derivative)
+
+    def __rmul__(self, a: float) -> NonLinearOperator:
+        return self * a
+
+    def __truediv__(self, a: float) -> NonLinearOperator:
+        return self * (1.0 / a)
+
+    def __add__(self, other: NonLinearOperator) -> NonLinearOperator:
+
+        if not isinstance(other, NonLinearOperator):
+            raise TypeError("Operand must be a NonLinearOperator")
+
+        domain = self.domain
+        codomain = self.codomain
+
+        def mapping(x: Any) -> Any:
+            return codomain.add(self(x), other(x))
+
+        if self._derivative is not None and other._derivative is not None:
+
+            def derivative(x: Vector) -> LinearOperator:
+                return self.derivative(x) + other.derivative(x)
+
+        else:
+            derivative = None
+
+        return NonLinearOperator(domain, codomain, mapping, derivative=derivative)
+
+    def __sub__(self, other: NonLinearOperator) -> NonLinearOperator:
+
+        if not isinstance(other, NonLinearOperator):
+            raise TypeError("Operand must be a NonLinearOperator")
+
+        domain = self.domain
+        codomain = self.codomain
+
+        def mapping(x: Any) -> Any:
+            return codomain.subtract(self(x), other(x))
+
+        if self._derivative is not None and other._derivative is not None:
+
+            def derivative(x: Vector) -> LinearOperator:
+                return self.derivative(x) - other.derivative(x)
+
+        else:
+            derivative = None
+
+        return NonLinearOperator(domain, codomain, mapping, derivative=derivative)
+
+    def __matmul__(self, other: NonLinearOperator) -> NonLinearOperator:
+        """Composes this operator with another: `(self @ other)(x) = self(other(x))`.
+
+        The derivative of the composed operator is computed using the chain rule:
+        `(F o G)'(x) = F'(G(x)) @ G'(x)`.
+
+        Args:
+            other: The operator to apply before this one.
+
+        Returns:
+            A new `NonLinearOperator` representing the composition.
+        """
+
+        if not isinstance(other, NonLinearOperator):
+            raise TypeError("Operand must be a NonLinearOperator")
+
+        domain = other.domain
+        codomain = self.codomain
+
+        def mapping(x: Any) -> Any:
+            return self(other(x))
+
+        if self._derivative is not None and other._derivative is not None:
+
+            def derivative(x: Vector) -> LinearOperator:
+                return self.derivative(other(x)) @ other.derivative(x)
+
+        else:
+            derivative = None
+
+        return NonLinearOperator(domain, codomain, mapping, derivative=derivative)