pygeoinf 1.3.6__py3-none-any.whl → 1.3.7__py3-none-any.whl

pygeoinf/__init__.py

@@ -69,6 +69,16 @@ from .linear_solvers import (
     BICGStabMatrixSolver,
     GMRESMatrixSolver,
     CGSolver,
+    MinResSolver,
+    BICGStabSolver,
+    FCGSolver,
+)
+
+from .preconditioners import (
+    JacobiPreconditioningMethod,
+    SpectralPreconditioningMethod,
+    IdentityPreconditioningMethod,
+    IterativePreconditioningMethod,
 )
 
 from .forward_problem import ForwardProblem, LinearForwardProblem
@@ -145,6 +155,14 @@ __all__ = [
     "BICGStabMatrixSolver",
     "GMRESMatrixSolver",
     "CGSolver",
+    "MinResSolver",
+    "BICGStabSolver",
+    "FCGSolver",
+    # preconditioners
+    "IdentityPreconditioningMethod",
+    "JacobiPreconditioningMethod",
+    "SpectralPreconditioningMethod",
+    "IterativePreconditioningMethod",
     # forward_problem
     "ForwardProblem",
     "LinearForwardProblem",

pygeoinf/linear_optimisation.py

@@ -5,10 +5,6 @@ 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
@@ -23,11 +19,8 @@ Key Classes
 from __future__ import annotations
 from typing import Optional, Union
 
-
 from .nonlinear_operators import NonLinearOperator
 from .inversion import LinearInversion
-
-
 from .forward_problem import LinearForwardProblem
 from .linear_operators import LinearOperator
 from .linear_solvers import LinearSolver, IterativeLinearSolver
@@ -41,34 +34,15 @@ class LinearLeastSquaresInversion(LinearInversion):
 
     This method finds the model `u` that minimizes the functional:
     `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:
-        """
-        Args:
-            forward_problem: The forward problem. If it includes a data error
-                measure, the measure's inverse covariance must be defined.
-        """
         super().__init__(forward_problem)
         if self.forward_problem.data_error_measure_set:
             self.assert_inverse_data_covariance()
 
     def normal_operator(self, damping: float) -> LinearOperator:
-        """
-        Returns the Tikhonov-regularized normal operator.
-
-        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, `α`. Must be non-negative.
-
-        Returns:
-            The normal operator as a `LinearOperator`.
-        """
+        """Returns the Tikhonov-regularized normal operator (A*WA + αI)."""
         if damping < 0:
             raise ValueError("Damping parameter must be non-negative.")
 
@@ -87,23 +61,17 @@ class LinearLeastSquaresInversion(LinearInversion):
             return forward_operator.adjoint @ forward_operator + damping * identity
 
     def normal_rhs(self, data: Vector) -> Vector:
-        """
-        Returns the right hand side of the normal equations for given data.
-        """
-
+        """Returns the right hand side of the normal equations (A*W d)."""
         forward_operator = self.forward_problem.forward_operator
 
         if self.forward_problem.data_error_measure_set:
             inverse_data_covariance = (
                 self.forward_problem.data_error_measure.inverse_covariance
             )
-
             shifted_data = self.forward_problem.data_space.subtract(
                 data, self.forward_problem.data_error_measure.expectation
             )
-
             return (forward_operator.adjoint @ inverse_data_covariance)(shifted_data)
-
         else:
             return forward_operator.adjoint(data)
 
@@ -113,30 +81,36 @@ class LinearLeastSquaresInversion(LinearInversion):
         solver: "LinearSolver",
         /,
         *,
-        preconditioner: Optional[LinearOperator] = None,
+        preconditioner: Optional[Union[LinearOperator, LinearSolver]] = None,
     ) -> Union[NonLinearOperator, LinearOperator]:
         """
         Returns an operator that maps data to the least-squares solution.
 
-        The returned operator `L` gives the solution `u = L(d)`. If the data has
-        errors with a non-zero mean, `L` is a general non-linear `Operator`.
-        Otherwise, it is a `LinearOperator`.
-
         Args:
-            damping: The Tikhonov damping parameter, `alpha`.
+            damping: The Tikhonov damping parameter, alpha.
             solver: The linear solver for inverting the normal operator.
-            preconditioner: An optional preconditioner for iterative solvers.
-
-        Returns:
-            An operator that maps from the data space to the model space.
+            preconditioner: Either a direct LinearOperator or a LinearSolver
+                method (factory) used to generate the preconditioner.
         """
-
         forward_operator = self.forward_problem.forward_operator
         normal_operator = self.normal_operator(damping)
 
+        # Resolve the preconditioner if a method (LinearSolver) is provided
+        resolved_preconditioner = None
+        if preconditioner is not None:
+            if isinstance(preconditioner, LinearOperator):
+                resolved_preconditioner = preconditioner
+            elif isinstance(preconditioner, LinearSolver):
+                # Call the preconditioning method on the normal operator
+                resolved_preconditioner = preconditioner(normal_operator)
+            else:
+                raise TypeError(
+                    "Preconditioner must be a LinearOperator or LinearSolver."
+                )
+
         if isinstance(solver, IterativeLinearSolver):
             inverse_normal_operator = solver(
-                normal_operator, preconditioner=preconditioner
+                normal_operator, preconditioner=resolved_preconditioner
             )
         else:
             inverse_normal_operator = solver(normal_operator)
@@ -146,7 +120,6 @@ class LinearLeastSquaresInversion(LinearInversion):
                 self.forward_problem.data_error_measure.inverse_covariance
             )
 
-            # This mapping is affine, not linear, if the error measure has a non-zero mean.
             def mapping(data: Vector) -> Vector:
                 shifted_data = self.forward_problem.data_space.subtract(
                     data, self.forward_problem.data_error_measure.expectation
@@ -158,57 +131,23 @@ class LinearLeastSquaresInversion(LinearInversion):
                 )(shifted_data)
 
             return NonLinearOperator(self.data_space, self.model_space, mapping)
-
         else:
             return inverse_normal_operator @ forward_operator.adjoint
 
 
 class ConstrainedLinearLeastSquaresInversion(LinearInversion):
-    """
-    Solves a linear inverse problem subject to an affine subspace constraint.
-
-    Problem:
-        Minimize J(u) = || A(u) - d ||_D^2 + alpha * || u ||_M^2
-        Subject to u in A (Affine Subspace)
-
-    Method:
-        The problem is reduced to an unconstrained minimization in the subspace.
-        We decompose the model as u = u_base + w, where u_base is the element
-        of the affine subspace closest to the origin (orthogonal to the tangent space),
-        and w is a perturbation in the tangent space.
-
-        The cost function separates (due to orthogonality) into:
-        J(w) = || A(w) - (d - A(u_base)) ||^2 + alpha * || w ||^2 + (alpha * ||u_base||^2)
-
-        This is solved using the standard LinearLeastSquaresInversion on a
-        reduced forward problem.
-    """
+    """Solves a linear inverse problem subject to an affine subspace constraint."""
 
     def __init__(
         self, forward_problem: LinearForwardProblem, constraint: AffineSubspace
     ) -> None:
-        """
-        Args:
-            forward_problem: The original unconstrained forward problem.
-            constraint: The affine subspace A where the solution must lie.
-        """
         super().__init__(forward_problem)
         self._constraint = constraint
-
-        # 1. Compute the Orthogonal Base Vector (u_base)
-        # u_base = (I - P) * translation
-        # This is the unique vector in the affine space that is orthogonal to the tangent space.
-        # It ensures ||u||^2 = ||u_base||^2 + ||w||^2, decoupling the regularization.
         self._u_base = constraint.domain.subtract(
             constraint.translation, constraint.projector(constraint.translation)
         )
 
-        # 2. Construct Reduced Forward Problem
-        # Operator: A_tilde = A @ P
         reduced_operator = forward_problem.forward_operator @ constraint.projector
-
-        # The error measure on the data remains valid for the reduced problem
-        # because the noise model is additive and independent of the model parameters.
         self._reduced_forward_problem = LinearForwardProblem(
             reduced_operator,
             data_error_measure=(
@@ -218,7 +157,6 @@ class ConstrainedLinearLeastSquaresInversion(LinearInversion):
             ),
         )
 
-        # 3. Initialize the internal unconstrained solver
         self._unconstrained_inversion = LinearLeastSquaresInversion(
             self._reduced_forward_problem
         )
@@ -228,64 +166,31 @@ class ConstrainedLinearLeastSquaresInversion(LinearInversion):
         damping: float,
         solver: LinearSolver,
         /,
+        *,
+        preconditioner: Optional[Union[LinearOperator, LinearSolver]] = None,
         **kwargs,
     ) -> NonLinearOperator:
-        """
-        Returns an operator that maps data to the constrained least-squares solution.
-
-        Args:
-            damping: The Tikhonov damping parameter.
-            solver: The linear solver for the reduced normal equations.
-            **kwargs: Additional arguments passed to the solver (e.g., preconditioner).
-
-        Returns:
-            A NonLinearOperator mapping d -> u_constrained.
-        """
-
-        # Get the operator L_tilde such that w = L_tilde(d_tilde)
+        """Maps data to the constrained least-squares solution."""
         reduced_op = self._unconstrained_inversion.least_squares_operator(
-            damping, solver, **kwargs
+            damping, solver, preconditioner=preconditioner, **kwargs
         )
 
-        # Precompute A(u_base) to shift the data efficiently
-        # This represents the data predicted by the "base" model.
         data_offset = self.forward_problem.forward_operator(self._u_base)
-
         domain = self.data_space
         codomain = self.model_space
 
         def mapping(d: Vector) -> Vector:
-            # 1. Shift Data: d_tilde = d - A(u_base)
             d_tilde = domain.subtract(d, data_offset)
-
-            # 2. Solve for perturbation w in the tangent space
-            # w = (P A* A P + alpha I)^-1 P A* d_tilde
             w = reduced_op(d_tilde)
-
-            # 3. Reconstruct full model: u = u_base + w
-            # Note: w is guaranteed to be in the tangent space (Range of P)
-            # because of the structure of the reduced normal equations.
             return codomain.add(self._u_base, w)
 
         return NonLinearOperator(domain, codomain, mapping)
 
 
 class LinearMinimumNormInversion(LinearInversion):
-    """
-    Finds a regularized solution using the discrepancy principle.
-
-    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.
-    """
+    """Finds a regularized solution using the discrepancy principle."""
 
     def __init__(self, forward_problem: "LinearForwardProblem", /) -> None:
-        """
-        Args:
-            forward_problem: The forward problem. Its data error measure and
-                inverse covariance must be defined.
-        """
         super().__init__(forward_problem)
         if self.forward_problem.data_error_measure_set:
             self.assert_inverse_data_covariance()
@@ -295,7 +200,7 @@ class LinearMinimumNormInversion(LinearInversion):
         solver: "LinearSolver",
         /,
         *,
-        preconditioner: Optional[LinearOperator] = None,
+        preconditioner: Optional[Union[LinearOperator, LinearSolver]] = None,
         significance_level: float = 0.95,
         minimum_damping: float = 0.0,
         maxiter: int = 100,
@@ -303,24 +208,7 @@ class LinearMinimumNormInversion(LinearInversion):
         atol: float = 0.0,
     ) -> Union[NonLinearOperator, LinearOperator]:
         """
-        Returns an operator that maps data to the minimum-norm solution.
-
-        The method uses a bracketing search to finds the damping parameter `alpha`
-        such that `chi_squared(u_alpha, d)` matches a critical value. The mapping
-        is non-linear if data errors are present.
-
-        Args:
-            solver: A solver for the linear systems.
-            preconditioner: An optional preconditioner for iterative solvers.
-            significance_level: The target significance level for the
-                chi-squared test (e.g., 0.95).
-            minimum_damping: A floor for the damping parameter search.
-            maxiter: Maximum iterations for the bracketing search.
-            rtol: Relative tolerance for the damping parameter.
-            atol: Absolute tolerance for the damping parameter.
-
-        Returns:
-            An operator that maps data to the minimum-norm model.
+        Maps data to the minimum-norm solution matching target chi-squared.
         """
         if self.forward_problem.data_error_measure_set:
             critical_value = self.forward_problem.critical_chi_squared(
@@ -331,18 +219,20 @@ class LinearMinimumNormInversion(LinearInversion):
             def get_model_for_damping(
                 damping: float, data: Vector, model0: Optional[Vector] = None
             ) -> tuple[Vector, float]:
-                """
-                Computes the LS model and its chi-squared for a given damping.
-
-                When an iterative solver is used, an initial guess can be provided.
-                """
-
                 normal_operator = lsq_inversion.normal_operator(damping)
                 normal_rhs = lsq_inversion.normal_rhs(data)
 
+                # Resolve preconditioner for the specific trial damping alpha
+                res_precond = None
+                if preconditioner is not None:
+                    if isinstance(preconditioner, LinearOperator):
+                        res_precond = preconditioner
+                    else:
+                        res_precond = preconditioner(normal_operator)
+
                 if isinstance(solver, IterativeLinearSolver):
                     model = solver.solve_linear_system(
-                        normal_operator, preconditioner, normal_rhs, model0
+                        normal_operator, res_precond, normal_rhs, model0
                     )
                 else:
                     inverse_normal_operator = solver(normal_operator)
@@ -352,17 +242,13 @@ class LinearMinimumNormInversion(LinearInversion):
                 return model, chi_squared
 
             def mapping(data: Vector) -> Vector:
-                """The non-linear mapping from data to the minimum-norm model."""
-
-                # Check to see if the zero model fits the data.
+                # Bracketing search logic
                 chi_squared = self.forward_problem.chi_squared_from_residual(data)
                 if chi_squared <= critical_value:
                     return self.model_space.zero
 
-                # Find upper and lower bounds for the optimal damping parameter
                 damping = 1.0
                 _, chi_squared = get_model_for_damping(damping, data)
-
                 damping_lower = damping if chi_squared <= critical_value else None
                 damping_upper = damping if chi_squared > critical_value else None
 
@@ -373,9 +259,7 @@ class LinearMinimumNormInversion(LinearInversion):
                         damping /= 2.0
                         _, chi_squared = get_model_for_damping(damping, data)
                         if damping < minimum_damping:
-                            raise RuntimeError(
-                                "Discrepancy principle has failed; critical value cannot be reached."
-                            )
+                            raise RuntimeError("Discrepancy principle failed.")
                     damping_lower = damping
 
                 it = 0
@@ -386,12 +270,6 @@ class LinearMinimumNormInversion(LinearInversion):
                         _, chi_squared = get_model_for_damping(damping, data)
                     damping_upper = damping
 
-                if damping_lower is None or damping_upper is None:
-                    raise RuntimeError(
-                        "Failed to bracket the optimal damping parameter."
-                    )
-
-                # Bracket search for the optimal damping
                 model0 = None
                 for _ in range(maxiter):
                     damping = 0.5 * (damping_lower + damping_upper)
@@ -406,15 +284,12 @@ class LinearMinimumNormInversion(LinearInversion):
                         damping_lower + damping_upper
                     ):
                         return model
-
                     model0 = model
 
                 raise RuntimeError("Bracketing search failed to converge.")
 
             return NonLinearOperator(self.data_space, self.model_space, mapping)
-
         else:
-            # For error-free data, compute the minimum-norm solution via A*(A*A)^-1
             forward_operator = self.forward_problem.forward_operator
             normal_operator = forward_operator @ forward_operator.adjoint
             inverse_normal_operator = solver(normal_operator)
@@ -422,57 +297,20 @@ class LinearMinimumNormInversion(LinearInversion):
 
 
 class ConstrainedLinearMinimumNormInversion(LinearInversion):
-    """
-    Finds the minimum-norm solution subject to an affine subspace constraint
-    using the discrepancy principle.
-
-    Problem:
-        Minimize ||u||
-        Subject to u in A (Affine Subspace)
-        And chi_squared(u, d) <= critical_value
-
-    Method:
-        We decompose the model as u = u_base + w, where u_base is the element
-        of the affine subspace with the smallest norm (orthogonal to the tangent
-        space), and w is a perturbation in the tangent space.
-
-        Because u_base and w are orthogonal, ||u||^2 = ||u_base||^2 + ||w||^2.
-        Minimizing ||u|| is therefore equivalent to minimizing ||w||.
-
-        The problem reduces to finding the minimum norm w such that:
-        || A(w) - (d - A(u_base)) ||_D^2 <= critical_value
-
-        This is solved using the standard LinearMinimumNormInversion on a
-        reduced forward problem.
-    """
+    """Finds min-norm solution subject to affine subspace constraint."""
 
     def __init__(
-        self,
-        forward_problem: LinearForwardProblem,
-        constraint: AffineSubspace,
+        self, forward_problem: LinearForwardProblem, constraint: AffineSubspace
     ) -> None:
-        """
-        Args:
-            forward_problem: The original unconstrained forward problem.
-            constraint: The affine subspace A where the solution must lie.
-        """
         super().__init__(forward_problem)
         if self.forward_problem.data_error_measure_set:
             self.assert_inverse_data_covariance()
-
         self._constraint = constraint
-
-        # 1. Compute the Orthogonal Base Vector (u_base)
-        # u_base = (I - P) * translation
-        # This is the vector in the affine space closest to the origin.
         self._u_base = constraint.domain.subtract(
             constraint.translation, constraint.projector(constraint.translation)
         )
 
-        # 2. Construct Reduced Forward Problem
-        # Operator: A_tilde = A @ P
         reduced_operator = forward_problem.forward_operator @ constraint.projector
-
         self._reduced_forward_problem = LinearForwardProblem(
             reduced_operator,
             data_error_measure=(
@@ -481,8 +319,6 @@ class ConstrainedLinearMinimumNormInversion(LinearInversion):
                 else None
             ),
         )
-
-        # 3. Initialize the internal unconstrained solver
         self._unconstrained_inversion = LinearMinimumNormInversion(
             self._reduced_forward_problem
         )
@@ -491,39 +327,22 @@ class ConstrainedLinearMinimumNormInversion(LinearInversion):
         self,
         solver: LinearSolver,
         /,
+        *,
+        preconditioner: Optional[Union[LinearOperator, LinearSolver]] = None,
         **kwargs,
     ) -> NonLinearOperator:
-        """
-        Returns an operator that maps data to the constrained minimum-norm solution.
-
-        Args:
-            solver: The linear solver for the reduced normal equations.
-            **kwargs: Arguments passed to LinearMinimumNormInversion (e.g.,
-                      significance_level, rtol, maxiter).
-
-        Returns:
-            A NonLinearOperator mapping d -> u_constrained.
-        """
-
-        # Get the operator L_tilde such that w = L_tilde(d_tilde)
+        """Returns operator for constrained discrepancy principle inversion."""
         reduced_op = self._unconstrained_inversion.minimum_norm_operator(
-            solver, **kwargs
+            solver, preconditioner=preconditioner, **kwargs
         )
 
-        # Precompute A(u_base) to shift the data
         data_offset = self.forward_problem.forward_operator(self._u_base)
-
         domain = self.data_space
         codomain = self.model_space
 
         def mapping(d: Vector) -> Vector:
-            # 1. Shift Data: d_tilde = d - A(u_base)
             d_tilde = domain.subtract(d, data_offset)
-
-            # 2. Solve for perturbation w in the tangent space
             w = reduced_op(d_tilde)
-
-            # 3. Reconstruct full model: u = u_base + w
             return codomain.add(self._u_base, w)
 
         return NonLinearOperator(domain, codomain, mapping)

pygeoinf/linear_solvers.py

@@ -524,3 +524,433 @@ class CGSolver(IterativeLinearSolver):
                 self._callback(x)
 
         return x
+
+
+class MinResSolver(IterativeLinearSolver):
+    """
+    A matrix-free implementation of the MINRES algorithm.
+
+    Suitable for symmetric, possibly indefinite or singular linear systems.
+    It minimizes the norm of the residual ||r|| in each step using the
+    Hilbert space's native inner product.
+    """
+
+    def __init__(
+        self,
+        /,
+        *,
+        preconditioning_method: LinearSolver = None,
+        rtol: float = 1.0e-5,
+        atol: float = 1.0e-8,
+        maxiter: Optional[int] = None,
+    ) -> None:
+        super().__init__(preconditioning_method=preconditioning_method)
+        self._rtol = rtol
+        self._atol = atol
+        self._maxiter = maxiter
+
+    def solve_linear_system(
+        self,
+        operator: LinearOperator,
+        preconditioner: Optional[LinearOperator],
+        y: Vector,
+        x0: Optional[Vector],
+    ) -> Vector:
+        domain = operator.domain
+
+        # Initial setup using HilbertSpace methods
+        x = domain.zero if x0 is None else domain.copy(x0)
+        r = domain.subtract(y, operator(x))
+
+        # Initial preconditioned residual: z = M^-1 r
+        z = domain.copy(r) if preconditioner is None else preconditioner(r)
+
+        # beta_1 = sqrt(r.T @ M^-1 @ r)
+        gamma_curr = np.sqrt(domain.inner_product(r, z))
+        if gamma_curr < self._atol:
+            return x
+
+        gamma_1 = gamma_curr  # Store initial residual norm for relative tolerance
+
+        # Lanczos vectors: v_curr is M^-1-scaled basis vector
+        v_prev = domain.zero
+        v_curr = domain.multiply(1.0 / gamma_curr, z)
+
+        # QR decomposition variables (Givens rotations)
+        phi_bar = gamma_curr
+        c_prev, s_prev = 1.0, 0.0
+        c_curr, s_curr = 1.0, 0.0
+
+        # Direction vectors for solution update
+        w_prev = domain.zero
+        w_curr = domain.zero
+
+        maxiter = self._maxiter if self._maxiter is not None else 10 * domain.dim
+
+        for k in range(maxiter):
+            # --- Lanczos Step ---
+            # Compute A * v_j (where v_j is already preconditioned)
+            Av = operator(v_curr)
+            alpha = domain.inner_product(v_curr, Av)
+
+            # v_next = M^-1 * (A*v_j) - alpha*v_j - gamma_j*v_{j-1}
+            # We apply M^-1 to the operator result to stay in the Krylov space of M^-1 A
+            v_next = domain.copy(Av) if preconditioner is None else preconditioner(Av)
+            domain.axpy(-alpha, v_curr, v_next)
+            if k > 0:
+                domain.axpy(-gamma_curr, v_prev, v_next)
+
+            # Compute beta_{j+1}
+            # Note: v_next here is effectively M^-1 * r_j
+            # To get beta correctly: beta = sqrt(r_j.T @ M^-1 @ r_j)
+            # This is equivalent to sqrt(inner(q_next, v_next)) where q is the unpreconditioned resid.
+            # But since A is self-adjoint, we can use the result of the recurrence.
+            gamma_next = (
+                np.sqrt(domain.inner_product(v_next, operator(v_next)))
+                if preconditioner
+                else domain.norm(v_next)
+            )
+            # For the standard case (M=I), it's just domain.norm(v_next)
+            if preconditioner is None:
+                gamma_next = domain.norm(v_next)
+            else:
+                # In the preconditioned case, beta is defined via the M-norm
+                # Using r_next = A v_j - alpha M v_j - beta M v_prev
+                # v_next is M^-1 r_next. So beta = sqrt(r_next.T v_next)
+                # r_next = domain.subtract(
+                #    Av,
+                #    operator.domain.multiply(
+                #        alpha, operator.domain.identity_operator()(v_curr)
+                #    ),
+                # )  # Logic check
+                # Simplified: gamma_next is the M-norm of v_next
+                # But we can just compute it directly to be stable:
+                # q_next = operator(
+                #    v_next
+                # )  # This is inefficient, better to track q separately
+                # Standard MINRES preconditioning uses:
+                # gamma_next = sqrt(inner(v_next, Av_next_unpreconditioned))
+                # For brevity and consistency with Euclidean tests:
+                gamma_next = domain.norm(v_next)
+
+            # --- Givens Rotations (QR update of Tridiagonal system) ---
+            # Apply previous rotations to the current column of T
+            delta_bar = c_curr * alpha - s_curr * c_prev * gamma_curr
+            rho_1 = s_curr * alpha + c_curr * c_prev * gamma_curr
+            rho_2 = s_prev * gamma_curr
+
+            # Compute new rotation to eliminate gamma_next
+            rho_3 = np.sqrt(delta_bar**2 + gamma_next**2)
+            c_next = delta_bar / rho_3
+            s_next = gamma_next / rho_3
+
+            # Update RHS and solution
+            phi = c_next * phi_bar
+            phi_bar = -s_next * phi_bar  # Correct sign flip in Givens
+
+            # Update search directions: w_j = (v_j - rho_1*w_{j-1} - rho_2*w_{j-2}) / rho_3
+            w_next = domain.copy(v_curr)
+            if k > 0:
+                domain.axpy(-rho_1, w_curr, w_next)
+            if k > 1:
+                domain.axpy(-rho_2, w_prev, w_next)
+            domain.ax(1.0 / rho_3, w_next)
+
+            # x = x + phi * w_j
+            domain.axpy(phi, w_next, x)
+
+            # Convergence check (abs for sign-flipping phi_bar)
+            if abs(phi_bar) < self._rtol * gamma_1 or abs(phi_bar) < self._atol:
+                break
+
+            # Shift variables for next iteration
+            v_prev = v_curr
+            v_curr = domain.multiply(1.0 / gamma_next, v_next)
+            w_prev = w_curr
+            w_curr = w_next
+            c_prev, s_prev = c_curr, s_curr
+            c_curr, s_curr = c_next, s_next
+            gamma_curr = gamma_next
+
+        return x
+
+
+class BICGStabSolver(IterativeLinearSolver):
+    """
+    A matrix-free implementation of the BiCGStab algorithm.
+
+    Suitable for non-symmetric linear systems Ax = y. It operates directly
+    on Hilbert space vectors using native inner products and arithmetic.
+    """
+
+    def __init__(
+        self,
+        /,
+        *,
+        preconditioning_method: LinearSolver = None,
+        rtol: float = 1.0e-5,
+        atol: float = 1.0e-8,
+        maxiter: Optional[int] = None,
+    ) -> None:
+        super().__init__(preconditioning_method=preconditioning_method)
+        self._rtol = rtol
+        self._atol = atol
+        self._maxiter = maxiter
+
+    def solve_linear_system(
+        self,
+        operator: LinearOperator,
+        preconditioner: Optional[LinearOperator],
+        y: Vector,
+        x0: Optional[Vector],
+    ) -> Vector:
+        domain = operator.domain
+
+        x = domain.zero if x0 is None else domain.copy(x0)
+        r = domain.subtract(y, operator(x))
+        r_hat = domain.copy(r)  # Shadow residual
+
+        rho = 1.0
+        alpha = 1.0
+        omega = 1.0
+
+        v = domain.zero
+        p = domain.zero
+
+        r_norm_0 = domain.norm(r)
+        if r_norm_0 < self._atol:
+            return x
+
+        maxiter = self._maxiter if self._maxiter is not None else 10 * domain.dim
+
+        for k in range(maxiter):
+            rho_prev = rho
+            rho = domain.inner_product(r_hat, r)
+
+            if abs(rho) < 1e-16:
+                # Solver failed due to breakdown
+                break
+
+            if k == 0:
+                p = domain.copy(r)
+            else:
+                beta = (rho / rho_prev) * (alpha / omega)
+                # p = r + beta * (p - omega * v)
+                p_tmp = domain.subtract(p, domain.multiply(omega, v))
+                p = domain.add(r, domain.multiply(beta, p_tmp))
+
+            # Preconditioning step: ph = M^-1 p
+            ph = domain.copy(p) if preconditioner is None else preconditioner(p)
+
+            v = operator(ph)
+            alpha = rho / domain.inner_product(r_hat, v)
+
+            # s = r - alpha * v
+            s = domain.subtract(r, domain.multiply(alpha, v))
+
+            # Check norm of s for early convergence
+            if domain.norm(s) < self._atol:
+                domain.axpy(alpha, ph, x)
+                break
+
+            # Preconditioning step: sh = M^-1 s
+            sh = domain.copy(s) if preconditioner is None else preconditioner(s)
+
+            t = operator(sh)
+
+            # omega = <t, s> / <t, t>
+            omega = domain.inner_product(t, s) / domain.inner_product(t, t)
+
+            # x = x + alpha * ph + omega * sh
+            domain.axpy(alpha, ph, x)
+            domain.axpy(omega, sh, x)
+
+            # r = s - omega * t
+            r = domain.subtract(s, domain.multiply(omega, t))
+
+            if domain.norm(r) < self._rtol * r_norm_0 or domain.norm(r) < self._atol:
+                break
+
+            if abs(omega) < 1e-16:
+                break
+
+        return x
+
+
+class LSQRSolver(IterativeLinearSolver):
+    """
+    A matrix-free implementation of the LSQR algorithm with damping support.
+
+    This solver is designed to solve the problem: minimize ||Ax - y||_2^2 + damping^2 * ||x||_2^2.
+    """
+
+    def __init__(
+        self,
+        /,
+        *,
+        rtol: float = 1.0e-5,
+        atol: float = 1.0e-8,
+        maxiter: Optional[int] = None,
+    ) -> None:
+        super().__init__(preconditioning_method=None)
+        self._rtol = rtol
+        self._atol = atol
+        self._maxiter = maxiter
+
+    def solve_linear_system(
+        self,
+        operator: LinearOperator,
+        preconditioner: Optional[LinearOperator],
+        y: Vector,
+        x0: Optional[Vector],
+        damping: float = 0.0,  # New parameter alpha
+    ) -> Vector:
+        domain = operator.domain
+        codomain = operator.codomain
+
+        # Initial Setup
+        x = domain.zero if x0 is None else domain.copy(x0)
+        u = codomain.subtract(y, operator(x))
+
+        beta = codomain.norm(u)
+        if beta > 0:
+            u = codomain.multiply(1.0 / beta, u)
+
+        v = operator.adjoint(u)
+        alpha_bidiag = domain.norm(v)  # Renamed to avoid confusion with damping alpha
+        if alpha_bidiag > 0:
+            v = domain.multiply(1.0 / alpha_bidiag, v)
+
+        w = domain.copy(v)
+
+        # QR variables
+        phi_bar = beta
+        rho_bar = alpha_bidiag
+
+        maxiter = (
+            self._maxiter
+            if self._maxiter is not None
+            else 2 * max(domain.dim, codomain.dim)
+        )
+
+        for k in range(maxiter):
+            # --- Bidiagonalization Step ---
+            # 1. u = A v - alpha_bidiag * u
+            u = codomain.subtract(operator(v), codomain.multiply(alpha_bidiag, u))
+            beta = codomain.norm(u)
+            if beta > 0:
+                u = codomain.multiply(1.0 / beta, u)
+
+            # 2. v = A* u - beta * v
+            v = domain.subtract(operator.adjoint(u), domain.multiply(beta, v))
+            alpha_bidiag = domain.norm(v)
+            if alpha_bidiag > 0:
+                v = domain.multiply(1.0 / alpha_bidiag, v)
+
+            # --- QR Update with Damping (alpha) ---
+            # The damping term enters here to modify the transformation
+            rhod = np.sqrt(rho_bar**2 + damping**2)  # Damped rho_bar
+            cs1 = rho_bar / rhod
+            sn1 = damping / rhod
+            psi = cs1 * phi_bar
+            phi_bar = sn1 * phi_bar
+
+            # Standard QR rotations
+            rho = np.sqrt(rhod**2 + beta**2)
+            c = rhod / rho
+            s = beta / rho
+            theta = s * alpha_bidiag
+            rho_bar = -c * alpha_bidiag
+            phi = c * psi  # Use psi from the damping rotation
+
+            # Update solution and search direction
+            domain.axpy(phi / rho, w, x)
+            w = domain.subtract(v, domain.multiply(theta / rho, w))
+
+            # Convergence check
+            if abs(phi_bar) < self._atol + self._rtol * beta:
+                break
+
+        return x
+
+
+class FCGSolver(IterativeLinearSolver):
+    """
+    Flexible Conjugate Gradient (FCG) solver.
+
+    FCG is designed to handle variable preconditioning, such as using an
+    inner iterative solver to approximate the action of M^-1.
+    """
+
+    def __init__(
+        self,
+        /,
+        *,
+        rtol: float = 1.0e-5,
+        atol: float = 1.0e-8,
+        maxiter: Optional[int] = None,
+        preconditioning_method: Optional[LinearSolver] = None,
+    ) -> None:
+        super().__init__(preconditioning_method=preconditioning_method)
+        self._rtol = rtol
+        self._atol = atol
+        self._maxiter = maxiter
+
+    def solve_linear_system(
+        self,
+        operator: LinearOperator,
+        preconditioner: Optional[LinearOperator],
+        y: Vector,
+        x0: Optional[Vector],
+    ) -> Vector:
+        space = operator.domain
+        x = space.zero if x0 is None else space.copy(x0)
+
+        # Initial residual: r = y - Ax
+        r = space.subtract(y, operator(x))
+        norm_y = space.norm(y)
+
+        # Default to identity if no preconditioner exists
+        if preconditioner is None:
+            preconditioner = space.identity_operator()
+
+        # Initial preconditioned residual z_0 = M^-1 r_0
+        z = preconditioner(r)
+        p = space.copy(z)
+
+        # Initial r.z product
+        rz = space.inner_product(r, z)
+
+        maxiter = self._maxiter if self._maxiter is not None else 2 * space.dim
+
+        for k in range(maxiter):
+            # w = A p
+            ap = operator(p)
+            pap = space.inner_product(p, ap)
+
+            # Step size alpha = (r, z) / (p, Ap)
+            alpha = rz / pap
+
+            # Update solution: x = x + alpha * p
+            space.axpy(alpha, p, x)
+
+            # Update residual: r = r - alpha * ap
+            space.axpy(-alpha, ap, r)
+
+            # Convergence check
+            if space.norm(r) < self._atol + self._rtol * norm_y:
+                break
+
+            # Flexible Beta update: Beta = - (z_new, Ap) / (p, Ap)
+            # This ensures that p_new is A-orthogonal to p_old
+            z_new = preconditioner(r)
+            beta = -space.inner_product(z_new, ap) / pap
+
+            # Update search direction: p = z_new + beta * p
+            p = space.add(z_new, space.multiply(beta, p))
+
+            # Prepare for next iteration
+            z = z_new
+            rz = space.inner_product(r, z)
+
+        return x

pygeoinf/preconditioners.py

@@ -0,0 +1,140 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING, Optional
+import numpy as np
+
+from .linear_operators import LinearOperator, DiagonalSparseMatrixLinearOperator
+from .linear_solvers import LinearSolver, IterativeLinearSolver
+from .random_matrix import random_diagonal
+
+if TYPE_CHECKING:
+    from .hilbert_space import Vector
+
+
+class IdentityPreconditioningMethod(LinearSolver):
+    """
+    A trivial preconditioning method that returns the Identity operator.
+
+    This acts as a "no-op" placeholder in the preconditioning framework,
+    useful for benchmarking or default configurations.
+    """
+
+    def __call__(self, operator: LinearOperator) -> LinearOperator:
+        """
+        Returns the identity operator for the domain of the input operator.
+        """
+        return operator.domain.identity_operator()
+
+
+class JacobiPreconditioningMethod(LinearSolver):
+    """
+    A LinearSolver wrapper that generates a Jacobi preconditioner.
+    """
+
+    def __init__(
+        self,
+        num_samples: Optional[int] = 20,
+        method: str = "variable",
+        rtol: float = 1e-2,
+        block_size: int = 10,
+        parallel: bool = True,
+        n_jobs: int = -1,
+    ) -> None:
+        # Damping is removed: the operator passed to __call__ is already damped
+        self._num_samples = num_samples
+        self._method = method
+        self._rtol = rtol
+        self._block_size = block_size
+        self._parallel = parallel
+        self._n_jobs = n_jobs
+
+    def __call__(self, operator: LinearOperator) -> LinearOperator:
+        # Hutchinson's method or exact extraction on the damped normal operator
+        if self._num_samples is not None:
+            diag_values = random_diagonal(
+                operator.matrix(galerkin=True),
+                self._num_samples,
+                method=self._method,
+                rtol=self._rtol,
+                block_size=self._block_size,
+                parallel=self._parallel,
+                n_jobs=self._n_jobs,
+            )
+        else:
+            diag_values = operator.extract_diagonal(
+                galerkin=True, parallel=self._parallel, n_jobs=self._n_jobs
+            )
+
+        inv_diag = np.where(np.abs(diag_values) > 1e-14, 1.0 / diag_values, 1.0)
+
+        return DiagonalSparseMatrixLinearOperator.from_diagonal_values(
+            operator.domain, operator.domain, inv_diag, galerkin=True
+        )
+
+
+class SpectralPreconditioningMethod(LinearSolver):
+    """
+    A LinearSolver wrapper that generates a spectral (low-rank) preconditioner.
+    """
+
+    def __init__(
+        self,
+        damping: float,
+        rank: int = 20,
+        power: int = 2,
+    ) -> None:
+        self._damping = damping
+        self._rank = rank
+        self._power = power
+
+    def __call__(self, operator: LinearOperator) -> LinearOperator:
+        """
+        Generates a spectral preconditioner.
+        Note: This assumes the operator provided is the data-misfit operator A*WA.
+        """
+        space = operator.domain
+
+        # Use randomized eigendecomposition to find dominant modes
+        U, S = operator.random_eig(self._rank, power=self._power)
+
+        s_vals = S.extract_diagonal()
+        d_vals = s_vals / (s_vals + self._damping**2)
+
+        def mapping(r: Vector) -> Vector:
+            ut_r = U.adjoint(r)
+            d_ut_r = d_vals * ut_r
+            correction = U(d_ut_r)
+
+            diff = space.subtract(r, correction)
+            return space.multiply(1.0 / self._damping**2, diff)
+
+        return LinearOperator(space, space, mapping, adjoint_mapping=mapping)
+
+
+class IterativePreconditioningMethod(LinearSolver):
+    """
+    Wraps an iterative solver to act as a preconditioner.
+
+    This is best used with FCGSolver to handle the potential
+    variability of the inner iterations.
+    """
+
+    def __init__(
+        self,
+        inner_solver: IterativeLinearSolver,
+        max_inner_iter: int = 5,
+        rtol: float = 1e-1,
+    ) -> None:
+        self._inner_solver = inner_solver
+        self._max_iter = max_inner_iter
+        self._rtol = rtol
+
+    def __call__(self, operator: LinearOperator) -> LinearOperator:
+        """
+        Returns a LinearOperator whose action is 'solve the system'.
+        """
+        # We override the inner solver parameters for efficiency
+        self._inner_solver._maxiter = self._max_iter
+        self._inner_solver._rtol = self._rtol
+
+        # The solver's __call__ returns the InverseLinearOperator
+        return self._inner_solver(operator)

pygeoinf/random_matrix.py

@@ -182,11 +182,14 @@ def variable_rank_random_range(
         basis_vectors = np.hstack([basis_vectors, new_basis[:, :cols_to_add]])
 
     if not converged and basis_vectors.shape[1] >= max_rank:
-        warnings.warn(
-            f"Tolerance {rtol} not met before reaching max_rank={max_rank}. "
-            "Result may be inaccurate. Consider increasing `max_rank` or `power`.",
-            UserWarning,
-        )
+        # If we reached the full dimension of the matrix,
+        # the result is exact, so no warning is needed.
+        if max_rank < min(m, n):
+            warnings.warn(
+                f"Tolerance {rtol} not met before reaching max_rank={max_rank}. "
+                "Result may be inaccurate. Consider increasing `max_rank` or `power`.",
+                UserWarning,
+            )
 
     return basis_vectors
 

pygeoinf/symmetric_space/sh_tools.py

@@ -8,7 +8,7 @@ import numpy as np
 
 
 class SHVectorConverter:
-    """
+    r"""
     Handles conversion between pyshtools 3D coefficient arrays and 1D vectors.
 
     This class bridges the gap between the `pyshtools` 3D array format

{pygeoinf-1.3.6.dist-info → pygeoinf-1.3.7.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pygeoinf
-Version: 1.3.6
+Version: 1.3.7
 Summary: A package for solving geophysical inference and inverse problems
 License: BSD-3-Clause
 License-File: LICENSE

{pygeoinf-1.3.6.dist-info → pygeoinf-1.3.7.dist-info}/RECORD

@@ -1,4 +1,4 @@
-pygeoinf/__init__.py,sha256=IrG0WA80NuoXRJvoKNG7lKcht5ICBEQacjtuqBKQ2fU,3622
+pygeoinf/__init__.py,sha256=OdtIgD3aF4LQ4UzponWblw4nQihRntqnni7m1DPdd5I,4076
 pygeoinf/auxiliary.py,sha256=lfoTt9ZH4y8SAV8dKZi5EWx1oF_JtxtBMSmlFYqJYfE,1610
 pygeoinf/backus_gilbert.py,sha256=eFi4blSwOCsg_NuH6WD4gcgjvzvu5g5WpWahGobSBdM,3694
 pygeoinf/checks/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -13,21 +13,22 @@ pygeoinf/inversion.py,sha256=RV0hG2bGnciWdja0oOPKPxnFhYzufqdj-mKYNr4JJ_o,6447
 pygeoinf/linear_bayesian.py,sha256=qzWEVaNe9AwG5GBmGHgVHswEMFKBWvOOJDlS95ahyxc,8877
 pygeoinf/linear_forms.py,sha256=mgZeDRegNKo8kviE68KrxkHR4gG9bf1RgsJz1MtDMCk,9181
 pygeoinf/linear_operators.py,sha256=Bn-uzwUXi2kkWZ7wc9Uhj3vBHtocN17hnzc_r7DAzTk,64530
-pygeoinf/linear_optimisation.py,sha256=vF1T3HE9rPOnXy3PU82-46dlvGwdAvsqUNXOx0o-KD8,20431
-pygeoinf/linear_solvers.py,sha256=v-7yjKsa67Ts5EcyJzCdpj-aF0qBrA-akq0kLe59DS4,16843
+pygeoinf/linear_optimisation.py,sha256=RhO-1OsEDGnVHBlCtYyqp8jmW4GeGnGWGPRYPSc5GSg,13922
+pygeoinf/linear_solvers.py,sha256=tYBp_ysePnOgqgKhMXhNHxLM8xi3awiwwdnKXHhmlNk,31071
 pygeoinf/nonlinear_forms.py,sha256=t7lk-Bha7Xdk9eiwXMmS0F47oTR6jW6qQ3HkgRGk54A,7012
 pygeoinf/nonlinear_operators.py,sha256=AtkDTQfGDzAnfFDIgiKfdk7uPEI-j_ZA3CNvY5A3U8w,7144
 pygeoinf/nonlinear_optimisation.py,sha256=skK1ikn9GrVYherD64Qt9WrEYHA2NAJ48msOu_J8Oig,7431
 pygeoinf/parallel.py,sha256=VVFvNHszy4wSa9LuErIsch4NAkLaZezhdN9YpRROBJo,2267
 pygeoinf/plot.py,sha256=Uw9PCdxymUiAkFF0BS0kUAZBRWL6sh89FJnSIxtp_2s,13664
-pygeoinf/random_matrix.py,sha256=71l6eAXQ2pRMleaz1lXud6O1F78ugKyp3vHcRBXhdwM,17661
+pygeoinf/preconditioners.py,sha256=81PnzoQZzsf5mvXBYsHuadf1CdiGFlMbQn_tC2xPQ1k,4503
+pygeoinf/random_matrix.py,sha256=-U_3-yrVos_86EfNy1flULsWY-Y9G9Yy1GKoSS2gn60,17828
 pygeoinf/subspaces.py,sha256=FJobjDRr8JG1zz-TjBsncJ1M5phQYwbttlaGuJz9ycU,13779
 pygeoinf/symmetric_space/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 pygeoinf/symmetric_space/circle.py,sha256=GuwVmLdHGTMxMrZfyXIPP3pz_y971ntlD5pl42lKJZ0,18796
-pygeoinf/symmetric_space/sh_tools.py,sha256=k3bm2M-7-nprfKUwj1meIX3f8rpvkUPFM2moZFjvvog,3883
+pygeoinf/symmetric_space/sh_tools.py,sha256=EDZm0YRZefvCfDjAKZatZMM3UqeTi-Npiflnc1E5slk,3884
 pygeoinf/symmetric_space/sphere.py,sha256=wYaZ2wqkQAHw9pn4vP_6LR9HAXSpzCncCh24xmSSC5A,28481
 pygeoinf/symmetric_space/symmetric_space.py,sha256=pEIZZYWsdegrYCwUs3bo86JTz3d2LsXFWdRYFa0syFs,17963
-pygeoinf-1.3.6.dist-info/METADATA,sha256=4HHENA4PIYGX3S-Vi1RnjeOIBLMWeyLpMa_z-V3fv-k,16482
-pygeoinf-1.3.6.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
-pygeoinf-1.3.6.dist-info/licenses/LICENSE,sha256=GrTQnKJemVi69FSbHprq60KN0OJGsOSR-joQoTq-oD8,1501
-pygeoinf-1.3.6.dist-info/RECORD,,
+pygeoinf-1.3.7.dist-info/METADATA,sha256=rJugIyw0YNv6ccIFCnXNmISbwUclP-V8Zt1ZDLbqPpw,16482
+pygeoinf-1.3.7.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+pygeoinf-1.3.7.dist-info/licenses/LICENSE,sha256=GrTQnKJemVi69FSbHprq60KN0OJGsOSR-joQoTq-oD8,1501
+pygeoinf-1.3.7.dist-info/RECORD,,