pygeoinf 1.2.3__py3-none-any.whl → 1.2.5__py3-none-any.whl

pygeoinf/__init__.py

@@ -1,3 +1,7 @@
+"""
+Unified imports for the package.
+"""
+
 from .random_matrix import (
     fixed_rank_random_range,
     variable_rank_random_range,
@@ -71,6 +75,8 @@ from .linear_optimisation import (
 
 from .linear_bayesian import LinearBayesianInversion, LinearBayesianInference
 
+from .backus_gilbert import HyperEllipsoid
+
 from .nonlinear_optimisation import (
     ScipyUnconstrainedOptimiser,
 )

pygeoinf/backus_gilbert.py

@@ -2,10 +2,15 @@
 Module for Backus-Gilbert like methods for solving inference problems. To be done...
 """
 
+from __future__ import annotations
+
 from .hilbert_space import HilbertSpace, Vector
 from .linear_operators import LinearOperator
 from .nonlinear_forms import NonLinearForm
 
+from .forward_problem import LinearForwardProblem
+from .inversion import LinearInference
+
 
 class HyperEllipsoid:
     """

pygeoinf/checks/hilbert_space.py

@@ -0,0 +1,183 @@
+import numpy as np
+
+
+class HilbertSpaceAxiomChecks:
+    """
+    A mixin class providing a self-checking mechanism for Hilbert space axioms.
+
+    When inherited by a HilbertSpace subclass, it provides the `.check()` method
+    to run a suite of randomized tests, ensuring the implementation is valid.
+    """
+
+    def _check_vector_space_axioms(self, x, y, a):
+        """Checks axioms related to vector addition and scalar multiplication."""
+        # (x + y) - y == x
+        sum_vec = self.add(x, y)
+        res_vec = self.subtract(sum_vec, y)
+        if not np.allclose(self.to_components(x), self.to_components(res_vec)):
+            raise AssertionError("Axiom failed: (x + y) - y != x")
+
+        # a*(x+y) == a*x + a*y
+        lhs = self.multiply(a, self.add(x, y))
+        rhs = self.add(self.multiply(a, x), self.multiply(a, y))
+        if not np.allclose(self.to_components(lhs), self.to_components(rhs)):
+            raise AssertionError("Axiom failed: a*(x+y) != a*x + a*y")
+
+        # x + 0 = x
+        zero_vec = self.zero
+        res_vec = self.add(x, zero_vec)
+        if not np.allclose(self.to_components(x), self.to_components(res_vec)):
+            raise AssertionError("Axiom failed: x + 0 != x")
+
+    def _check_inner_product_axioms(self, x, y, z, a, b):
+        """Checks axioms related to the inner product and norm."""
+        # Linearity: <ax+by, z> = a<x,z> + b<y,z>
+        lhs = self.inner_product(self.add(self.multiply(a, x), self.multiply(b, y)), z)
+        rhs = a * self.inner_product(x, z) + b * self.inner_product(y, z)
+        if not np.isclose(lhs, rhs):
+            raise AssertionError("Axiom failed: Inner product linearity")
+
+        # Symmetry: <x, y> == <y, x>
+        if not np.isclose(self.inner_product(x, y), self.inner_product(y, x)):
+            raise AssertionError("Axiom failed: Inner product symmetry")
+
+        # Triangle Inequality: ||x + y|| <= ||x|| + ||y||
+        norm_sum = self.norm(self.add(x, y))
+        if not norm_sum <= self.norm(x) + self.norm(y):
+            raise AssertionError("Axiom failed: Triangle inequality")
+
+    def _check_mapping_identities(self, x):
+        """Checks that component and dual mappings are self-consistent."""
+        # from_components(to_components(x)) == x
+        components = self.to_components(x)
+        reconstructed_x = self.from_components(components)
+        if not np.allclose(components, self.to_components(reconstructed_x)):
+            raise AssertionError("Axiom failed: Component mapping round-trip")
+
+        # from_dual(to_dual(x)) == x
+        x_dual = self.to_dual(x)
+        reconstructed_x = self.from_dual(x_dual)
+        if not np.allclose(self.to_components(x), self.to_components(reconstructed_x)):
+            raise AssertionError("Axiom failed: Dual mapping round-trip")
+
+    def _check_inplace_operations(self, x, y, a):
+        """Checks the in-place operations `ax` and `axpy`."""
+        # Test ax: y := a*x
+        x_copy = self.copy(x)
+        expected_ax = self.multiply(a, x)
+        self.ax(a, x_copy)
+        if not np.allclose(self.to_components(expected_ax), self.to_components(x_copy)):
+            raise AssertionError("Axiom failed: In-place operation ax")
+
+        # Test axpy: y := a*x + y
+        y_copy = self.copy(y)
+        expected_axpy = self.add(self.multiply(a, x), y)
+        self.axpy(a, x, y_copy)
+        if not np.allclose(
+            self.to_components(expected_axpy), self.to_components(y_copy)
+        ):
+            raise AssertionError("Axiom failed: In-place operation axpy")
+
+    def _check_copy(self, x):
+        """Checks that the copy method creates a deep, independent copy."""
+        x_copy = self.copy(x)
+
+        # The copy should have the same value but be a different object
+        if x is x_copy:
+            raise AssertionError("Axiom failed: copy() returned the same object.")
+        if not np.allclose(self.to_components(x), self.to_components(x_copy)):
+            raise AssertionError("Axiom failed: copy() did not preserve values.")
+
+        # Modify the copy and ensure the original is unchanged
+        self.ax(2.0, x_copy)
+        if np.allclose(self.to_components(x), self.to_components(x_copy)):
+            raise AssertionError("Axiom failed: copy() is not a deep copy.")
+
+    def _check_gram_schmidt(self):
+        """Checks the Gram-Schmidt orthonormalization process."""
+        # Create a list of linearly independent vectors
+        vectors = [self.random() for _ in range(min(self.dim, 5))]
+        if not vectors:
+            return  # Skip if dimension is 0
+
+        try:
+            orthonormal_vectors = self.gram_schmidt(vectors)
+        except ValueError as e:
+            # This can happen if the random vectors are not linearly independent
+            print(f"Skipping Gram-Schmidt check due to non-independent vectors: {e}")
+            return
+
+        # Check for orthonormality
+        for i, v1 in enumerate(orthonormal_vectors):
+            for j, v2 in enumerate(orthonormal_vectors):
+                inner_product = self.inner_product(v1, v2)
+                if i == j:
+                    if not np.isclose(inner_product, 1.0):
+                        raise AssertionError(
+                            "Axiom failed: Gram-Schmidt vector norm is not 1."
+                        )
+                else:
+                    if not np.isclose(inner_product, 0.0):
+                        raise AssertionError(
+                            "Axiom failed: Gram-Schmidt vectors are not orthogonal."
+                        )
+
+    def _check_basis_and_expectation(self):
+        """Checks the basis_vector and sample_expectation methods."""
+        if self.dim == 0:
+            return  # Skip for zero-dimensional spaces
+
+        # Check basis vectors
+        for i in range(self.dim):
+            basis_vector = self.basis_vector(i)
+            components = self.to_components(basis_vector)
+            expected_components = np.zeros(self.dim)
+            expected_components[i] = 1.0
+            if not np.allclose(components, expected_components):
+                raise AssertionError(
+                    "Axiom failed: basis_vector has incorrect components."
+                )
+
+        # Check sample expectation
+        vectors = [self.random() for _ in range(5)]
+        mean_vec = self.sample_expectation(vectors)
+
+        mean_comps = np.mean([self.to_components(v) for v in vectors], axis=0)
+        if not np.allclose(self.to_components(mean_vec), mean_comps):
+            raise AssertionError("Axiom failed: sample_expectation is incorrect.")
+
+    def check(self, n_checks: int = 10) -> None:
+        """
+        Runs a suite of randomized checks to verify the Hilbert space axioms.
+
+        This method performs `n_checks` iterations, generating new random
+        vectors and scalars for each one. It provides an "interactive" way
+        to validate any concrete HilbertSpace implementation.
+
+        Args:
+            n_checks: The number of randomized trials to run.
+
+        Raises:
+            AssertionError: If any of the underlying axiom checks fail.
+        """
+        print(
+            f"\nRunning {n_checks} randomized axiom checks for {self.__class__.__name__}... (and some one-off checks)"
+        )
+
+        # These checks only need to be run once
+        self._check_gram_schmidt()
+        self._check_basis_and_expectation()
+
+        for _ in range(n_checks):
+            # Generate fresh random data for each trial
+            x, y, z = self.random(), self.random(), self.random()
+            a, b = np.random.randn(), np.random.randn()
+
+            # Run all checks
+            self._check_vector_space_axioms(x, y, a)
+            self._check_inner_product_axioms(x, y, z, a, b)
+            self._check_mapping_identities(x)
+            self._check_inplace_operations(x, y, a)
+            self._check_copy(x)
+
+        print(f"✅ All {n_checks} Hilbert space axiom checks passed successfully.")

pygeoinf/checks/linear_operators.py

@@ -0,0 +1,124 @@
+"""
+Provides a self-checking mechanism for LinearOperator implementations.
+"""
+
+from __future__ import annotations
+from typing import TYPE_CHECKING
+import numpy as np
+
+# Import the base checks from the sibling module
+from .nonlinear_operators import NonLinearOperatorAxiomChecks
+
+
+if TYPE_CHECKING:
+    from ..hilbert_space import Vector
+
+
+class LinearOperatorAxiomChecks(NonLinearOperatorAxiomChecks):
+    """
+    A mixin for checking the properties of a LinearOperator.
+
+    Inherits the derivative check from NonLinearOperatorAxiomChecks and adds
+    checks for linearity and the adjoint identity.
+    """
+
+    def _check_linearity(self, x: Vector, y: Vector, a: float, b: float):
+        """Verifies the linearity property: L(ax + by) = a*L(x) + b*L(y)"""
+        ax_plus_by = self.domain.add(
+            self.domain.multiply(a, x), self.domain.multiply(b, y)
+        )
+        lhs = self(ax_plus_by)
+
+        aLx = self.codomain.multiply(a, self(x))
+        bLy = self.codomain.multiply(b, self(y))
+        rhs = self.codomain.add(aLx, bLy)
+
+        # Compare the results in the codomain
+        diff_norm = self.codomain.norm(self.codomain.subtract(lhs, rhs))
+        rhs_norm = self.codomain.norm(rhs)
+        relative_error = diff_norm / (rhs_norm + 1e-12)
+
+        if relative_error > 1e-9:
+            raise AssertionError(
+                f"Linearity check failed: L(ax+by) != aL(x)+bL(y). Relative error: {relative_error:.2e}"
+            )
+
+    def _check_adjoint_definition(self, x: Vector, y: Vector):
+        """Verifies the adjoint identity: <L(x), y> = <x, L*(y)>"""
+        lhs = self.codomain.inner_product(self(x), y)
+        rhs = self.domain.inner_product(x, self.adjoint(y))
+
+        if not np.isclose(lhs, rhs):
+            raise AssertionError(
+                f"Adjoint definition failed: <L(x),y> = {lhs:.4e}, but <x,L*(y)> = {rhs:.4e}"
+            )
+
+    def _check_algebraic_identities(self, op1, op2, x, y, a):
+        """
+        Verifies the algebraic properties of the adjoint and dual operators.
+        Requires a second compatible operator (op2).
+        """
+        # --- Adjoint Identities ---
+        # (A+B)* = A* + B*
+        op_sum_adj = (op1 + op2).adjoint
+        adj_sum = op1.adjoint + op2.adjoint
+        diff = op1.domain.subtract(op_sum_adj(y), adj_sum(y))
+        if op1.domain.norm(diff) > 1e-9:
+            raise AssertionError("Axiom failed: (A+B)* != A* + B*")
+
+        # (a*A)* = a*A*
+        op_scaled_adj = (a * op1).adjoint
+        adj_scaled = a * op1.adjoint
+        diff = op1.domain.subtract(op_scaled_adj(y), adj_scaled(y))
+        if op1.domain.norm(diff) > 1e-9:
+            raise AssertionError("Axiom failed: (a*A)* != a*A*")
+
+        # (A*)* = A
+        op_adj_adj = op1.adjoint.adjoint
+        diff = op1.codomain.subtract(op_adj_adj(x), op1(x))
+        if op1.codomain.norm(diff) > 1e-9:
+            raise AssertionError("Axiom failed: (A*)* != A")
+
+        # (A@B)* = B*@A*
+        if op1.domain == op2.codomain:
+            op_comp_adj = (op1 @ op2).adjoint
+            adj_comp = op2.adjoint @ op1.adjoint
+            diff = op2.domain.subtract(op_comp_adj(y), adj_comp(y))
+            if op2.domain.norm(diff) > 1e-9:
+                raise AssertionError("Axiom failed: (A@B)* != B*@A*")
+
+        # --- Dual Identities ---
+        # (A+B)' = A' + B'
+        op_sum_dual = (op1 + op2).dual
+        dual_sum = op1.dual + op2.dual
+        y_dual = op1.codomain.to_dual(y)
+        # The result of applying a dual operator is a LinearForm, which supports subtraction
+        diff_dual = op_sum_dual(y_dual) - dual_sum(y_dual)
+        if op1.domain.dual.norm(diff_dual) > 1e-9:
+            raise AssertionError("Axiom failed: (A+B)' != A' + B'")
+
+    def check(self, n_checks: int = 5, op2=None) -> None:
+        """
+        Runs all checks for the LinearOperator, including non-linear checks
+        and algebraic identities.
+        """
+        # First, run the parent (non-linear) checks from the base class
+        super().check(n_checks, op2=op2)
+
+        # Now, run the linear-specific checks
+        print(
+            f"Running {n_checks} additional randomized checks for linearity and adjoints..."
+        )
+        for _ in range(n_checks):
+            x1 = self.domain.random()
+            x2 = self.domain.random()
+            y = self.codomain.random()
+            a, b = np.random.randn(), np.random.randn()
+
+            self._check_linearity(x1, x2, a, b)
+            self._check_adjoint_definition(x1, y)
+
+            if op2:
+                self._check_algebraic_identities(self, op2, x1, y, a)
+
+        print(f"✅ All {n_checks} linear operator checks passed successfully.")

pygeoinf/checks/nonlinear_operators.py

@@ -0,0 +1,154 @@
+"""
+Provides a self-checking mechanism for NonLinearOperator implementations.
+"""
+
+from __future__ import annotations
+from typing import TYPE_CHECKING
+import numpy as np
+
+if TYPE_CHECKING:
+    from ..linear_operators import LinearOperator
+
+
+class NonLinearOperatorAxiomChecks:
+    """A mixin for checking the properties of a NonLinearOperator."""
+
+    def _check_derivative_finite_difference(self, x, v, h=1e-7):
+        """
+        Verifies the derivative using the finite difference formula:
+        D[F](x) @ v  ≈  (F(x + h*v) - F(x)) / h
+        """
+        from ..linear_operators import LinearOperator
+
+        derivative_op = self.derivative(x)
+
+        # 1. Check that the derivative is a valid LinearOperator
+        if not isinstance(derivative_op, LinearOperator):
+            raise AssertionError("The derivative must be a valid LinearOperator.")
+        if not (
+            derivative_op.domain == self.domain
+            and derivative_op.codomain == self.codomain
+        ):
+            raise AssertionError("The derivative has a mismatched domain or codomain.")
+
+        # 2. Calculate the analytical derivative's action on a random vector v
+        analytic_result = derivative_op(v)
+
+        # 3. Calculate the numerical approximation using the finite difference formula
+        x_plus_hv = self.domain.add(x, self.domain.multiply(h, v))
+        fx_plus_hv = self(x_plus_hv)
+        fx = self(x)
+        finite_diff_result = self.codomain.multiply(
+            1 / h, self.codomain.subtract(fx_plus_hv, fx)
+        )
+
+        # 4. Compare the analytical and numerical results
+        diff_norm = self.codomain.norm(
+            self.codomain.subtract(analytic_result, finite_diff_result)
+        )
+        analytic_norm = self.codomain.norm(analytic_result)
+        relative_error = diff_norm / (analytic_norm + 1e-12)
+
+        if relative_error > 1e-4:
+            raise AssertionError(
+                f"Finite difference check failed. Relative error: {relative_error:.2e}"
+            )
+
+    def _check_add_derivative(self, op1, op2, x, v):
+        """Verifies the sum rule for derivatives: (F+G)' = F' + G'"""
+        if not (op1.has_derivative and op2.has_derivative):
+            return  # Skip if derivatives aren't defined
+
+        # Derivative of the sum of operators
+        sum_op = op1 + op2
+        derivative_of_sum = sum_op.derivative(x)
+
+        # Sum of the individual derivatives
+        sum_of_derivatives = op1.derivative(x) + op2.derivative(x)
+
+        # Compare their action on a random vector
+        res1 = derivative_of_sum(v)
+        res2 = sum_of_derivatives(v)
+
+        diff_norm = self.codomain.norm(self.codomain.subtract(res1, res2))
+        if diff_norm > 1e-9:
+            raise AssertionError("Axiom failed: Derivative of sum is incorrect.")
+
+    def _check_scalar_mul_derivative(self, op, x, v, a):
+        """Verifies the scalar multiple rule: (a*F)' = a*F'"""
+        if not op.has_derivative:
+            return
+
+        # Derivative of the scaled operator
+        scaled_op = a * op
+        derivative_of_scaled = scaled_op.derivative(x)
+
+        # Scaled original derivative
+        scaled_derivative = a * op.derivative(x)
+
+        # Compare their action
+        res1 = derivative_of_scaled(v)
+        res2 = scaled_derivative(v)
+
+        diff_norm = self.codomain.norm(self.codomain.subtract(res1, res2))
+        if diff_norm > 1e-9:
+            raise AssertionError(
+                "Axiom failed: Derivative of scalar multiple is incorrect."
+            )
+
+    def _check_matmul_derivative(self, op1, op2, x, v):
+        """Verifies the chain rule for derivatives: (F o G)'(x) = F'(G(x)) @ G'(x)"""
+        if not (op1.has_derivative and op2.has_derivative):
+            return
+        if op1.domain != op2.codomain:
+            return  # Skip if not composable
+
+        # Derivative of the composed operator
+        composed_op = op1 @ op2
+        derivative_of_composed = composed_op.derivative(x)
+
+        # Apply the chain rule manually
+        gx = op2(x)
+        chain_rule_derivative = op1.derivative(gx) @ op2.derivative(x)
+
+        # Compare their action
+        res1 = derivative_of_composed(v)
+        res2 = chain_rule_derivative(v)
+
+        diff_norm = op1.codomain.norm(op1.codomain.subtract(res1, res2))
+        if diff_norm > 1e-9:
+            raise AssertionError(
+                "Axiom failed: Chain rule for derivatives is incorrect."
+            )
+
+    def check(self, n_checks: int = 5, op2=None) -> None:
+        """
+        Runs randomized checks to validate the operator's derivative and
+        its algebraic properties.
+
+        Args:
+            n_checks: The number of randomized trials to perform.
+            op2: An optional second operator for testing algebraic rules.
+        """
+        print(
+            f"\nRunning {n_checks} randomized checks for {self.__class__.__name__}..."
+        )
+        for _ in range(n_checks):
+            x = self.domain.random()
+            v = self.domain.random()
+            a = np.random.randn()
+
+            # Ensure the direction vector 'v' is not a zero vector
+            if self.domain.norm(v) < 1e-12:
+                v = self.domain.random()
+
+            # Original check
+            self._check_derivative_finite_difference(x, v)
+
+            # New algebraic checks
+            self._check_scalar_mul_derivative(self, x, v, a)
+            if op2:
+                self._check_add_derivative(self, op2, x, v)
+                self._check_matmul_derivative(self, op2, x, v)
+
+        print(f"✅ All {n_checks} non-linear operator checks passed successfully.")

pygeoinf/forward_problem.py

@@ -237,6 +237,27 @@ class LinearForwardProblem(ForwardProblem):
         """
         return chi2.ppf(significance_level, self.data_space.dim)
 
+    def chi_squared_from_residual(self, residual: Vector) -> float:
+        """
+        Calculates the chi-squared statistic from a residual vector.
+
+        Args:
+            residual: The residual vector.
+
+        Returns:
+            The chi-squared statistic.
+        """
+        if self.data_error_measure_set:
+            residual = self.data_space.subtract(
+                residual, self.data_error_measure.expectation
+            )
+            inverse_data_covariance = self.data_error_measure.inverse_covariance
+            return self.data_space.inner_product(
+                inverse_data_covariance(residual), residual
+            )
+        else:
+            return self.data_space.squared_norm(residual)
+
     def chi_squared(self, model: Vector, data: Vector) -> float:
         """
         Calculates the chi-squared statistic for a given model and data.
@@ -256,19 +277,7 @@ class LinearForwardProblem(ForwardProblem):
         """
 
         residual = self.data_space.subtract(data, self.forward_operator(model))
-
-        if self.data_error_measure_set:
-            # Center the residual with respect to the error measure's mean
-            residual = self.data_space.subtract(
-                residual, self.data_error_measure.expectation
-            )
-            inverse_data_covariance = self.data_error_measure.inverse_covariance
-            return self.data_space.inner_product(
-                inverse_data_covariance(residual), residual
-            )
-        else:
-            # Fallback to the squared L2 norm of the residual
-            return self.data_space.squared_norm(residual)
+        return self.chi_squared_from_residual(residual)
 
     def chi_squared_test(
         self, significance_level: float, model: Vector, data: Vector

pygeoinf/hilbert_space.py

@@ -36,6 +36,8 @@ from typing import (
 
 import numpy as np
 
+from .checks.hilbert_space import HilbertSpaceAxiomChecks
+
 # This block only runs for type checkers, not at runtime
 if TYPE_CHECKING:
     from .linear_operators import LinearOperator
@@ -45,7 +47,7 @@ if TYPE_CHECKING:
 Vector = TypeVar("Vector")
 
 
-class HilbertSpace(ABC):
+class HilbertSpace(ABC, HilbertSpaceAxiomChecks):
     """
     An abstract base class for real Hilbert spaces.
 

pygeoinf/inversion.py

@@ -126,6 +126,10 @@ class Inference(Inversion):
                 relationship between model parameters and data.
             property_operator: A mapping takes elements of the model space to
                 property vector of interest.
+
+        Raises:
+            ValueError: If the domain of the property operator is
+                not equal to the model space.
         """
 
         super().__init__(forward_problem)
@@ -166,6 +170,10 @@ class LinearInference(Inference):
                 relationship between model parameters and data.
             property_operator: A linear mapping takes elements of the model space to
                 property vector of interest.
+
+        Raises:
+            ValueError: If the domain of the property operator is
+                not equal to the model space.
         """
 
         if not isinstance(forward_problem, LinearForwardProblem):

pygeoinf/linear_operators.py

@@ -36,13 +36,15 @@ from .random_matrix import (
 
 from .parallel import parallel_compute_dense_matrix_from_scipy_op
 
+from .checks.linear_operators import LinearOperatorAxiomChecks
+
 # This block only runs for type checkers, not at runtime
 if TYPE_CHECKING:
     from .hilbert_space import HilbertSpace, EuclideanSpace
     from .linear_forms import LinearForm
 
 
-class LinearOperator(NonLinearOperator):
+class LinearOperator(NonLinearOperator, LinearOperatorAxiomChecks):
     """A linear operator between two Hilbert spaces.
 
     This class represents a linear map `L(x) = Ax` and provides rich

pygeoinf/linear_optimisation.py

@@ -21,6 +21,7 @@ Key Classes
 from __future__ import annotations
 from typing import Optional, Union
 
+
 from .nonlinear_operators import NonLinearOperator
 from .inversion import LinearInversion
 
@@ -82,6 +83,27 @@ class LinearLeastSquaresInversion(LinearInversion):
         else:
             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.
+        """
+
+        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)
+
     def least_squares_operator(
         self,
         damping: float,
@@ -105,6 +127,7 @@ class LinearLeastSquaresInversion(LinearInversion):
         Returns:
             An operator that maps from the data space to the model space.
         """
+
         forward_operator = self.forward_problem.forward_operator
         normal_operator = self.normal_operator(damping)
 
@@ -198,20 +221,33 @@ 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."""
-                op = lsq_inversion.least_squares_operator(
-                    damping, solver, preconditioner=preconditioner
-                )
-                model = op(data)
+                """
+                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)
+
+                if isinstance(solver, IterativeLinearSolver):
+                    model = solver.solve_linear_system(
+                        normal_operator, preconditioner, normal_rhs, model0
+                    )
+                else:
+                    inverse_normal_operator = solver(normal_operator)
+                    model = inverse_normal_operator(normal_rhs)
+
                 chi_squared = self.forward_problem.chi_squared(model, data)
                 return model, chi_squared
 
             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)
+
+                # Check to see if the zero model fits the data.
+                chi_squared = self.forward_problem.chi_squared_from_residual(data)
                 if chi_squared <= critical_value:
-                    return model
+                    return self.model_space.zero
 
                 # Find upper and lower bounds for the optimal damping parameter
                 damping = 1.0
@@ -246,9 +282,10 @@ class LinearMinimumNormInversion(LinearInversion):
                     )
 
                 # Bracket search for the optimal damping
+                model0 = None
                 for _ in range(maxiter):
                     damping = 0.5 * (damping_lower + damping_upper)
-                    model, chi_squared = get_model_for_damping(damping, data)
+                    model, chi_squared = get_model_for_damping(damping, data, model0)
 
                     if chi_squared < critical_value:
                         damping_lower = damping
@@ -260,6 +297,8 @@ class LinearMinimumNormInversion(LinearInversion):
                     ):
                         return model
 
+                    model0 = model
+
                 raise RuntimeError("Bracketing search failed to converge.")
 
             return NonLinearOperator(self.data_space, self.model_space, mapping)

pygeoinf/linear_solvers.py

@@ -463,7 +463,7 @@ class CGSolver(IterativeLinearSolver):
 
         num = domain.inner_product(r, z)
 
-        for _ in range(maxiter):
+        for i in range(maxiter):
             # Check for convergence
             if domain.squared_norm(r) <= tol_sq:
                 break

pygeoinf/nonlinear_operators.py

@@ -11,13 +11,16 @@ from __future__ import annotations
 from typing import Callable, Optional, Any, TYPE_CHECKING
 
 
+from .checks.nonlinear_operators import NonLinearOperatorAxiomChecks
+
+
 # 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:
+class NonLinearOperator(NonLinearOperatorAxiomChecks):
     """
     Represents a general non-linear operator that maps vectors to vectors.
 

pygeoinf/nonlinear_optimisation.py

@@ -17,6 +17,13 @@ from .nonlinear_forms import NonLinearForm
 class ScipyUnconstrainedOptimiser:
     """
     A wrapper for scipy.optimize.minimize that adapts a NonLinearForm.
+
+    Note on derivative-free methods:
+    Internal testing has shown that the 'Nelder-Mead' solver can be unreliable
+    for some problems, failing to converge to the correct minimum while still
+    reporting success. The 'Powell' method appears to be more robust. Users
+    should exercise caution and verify results when using derivative-free
+    methods.
     """
 
     _HESSIAN_METHODS = {
@@ -168,7 +175,7 @@ def line_search(
     # terms of the components of the derivative (i.e., an element
     # of the dual space) and not the gradient, this meaning that
     # the standard Euclidean pairing with the components on the
-    #  descent direction will yield the correct slope.
+    # descent direction will yield the correct slope.
     def myfprime(c: np.ndarray) -> np.ndarray:
         x = domain.from_components(c)
         g = form.derivative(x)

pygeoinf/symmetric_space/sphere.py

@@ -225,6 +225,9 @@ class SphereHelper:
         map_extent: Optional[List[float]] = None,
         gridlines: bool = True,
         symmetric: bool = False,
+        contour_lines: bool = False,
+        contour_lines_kwargs: Optional[dict] = None,
+        num_levels: int = 10,
         **kwargs,
     ) -> Tuple[Figure, "GeoAxes", Any]:
         """
@@ -241,6 +244,11 @@ class SphereHelper:
             map_extent: A list `[lon_min, lon_max, lat_min, lat_max]` to set map bounds.
             gridlines: If True, draws latitude/longitude gridlines.
             symmetric: If True, centers the color scale symmetrically around zero.
+            contour_lines: If True, overlays contour lines on the plot.
+            contour_lines_kwargs: A dictionary of keyword arguments for styling the
+                contour lines (e.g., {'colors': 'k', 'linewidths': 0.5})
+            num_levels: The number of levels to generate automatically if `levels`
+                is not provided directly.
             **kwargs: Additional keyword arguments forwarded to the plotting function
                 (`ax.contourf` or `ax.pcolormesh`).
 
@@ -269,9 +277,17 @@ class SphereHelper:
             kwargs.setdefault("vmin", -data_max)
             kwargs.setdefault("vmax", data_max)
 
-        levels = kwargs.pop("levels", 10)
+        if "levels" in kwargs:
+            levels = kwargs.pop("levels")
+        else:
+            vmin = kwargs.get("vmin", np.nanmin(u.data))
+            vmax = kwargs.get("vmax", np.nanmax(u.data))
+            levels = np.linspace(vmin, vmax, num_levels)
+
         im: Any
         if contour:
+            kwargs.pop("vmin", None)
+            kwargs.pop("vmax", None)
             im = ax.contourf(
                 lons,
                 lats,
@@ -285,6 +301,20 @@ class SphereHelper:
                 lons, lats, u.data, transform=ccrs.PlateCarree(), **kwargs
             )
 
+        if contour_lines:
+            cl_kwargs = contour_lines_kwargs if contour_lines_kwargs is not None else {}
+            cl_kwargs.setdefault("colors", "k")
+            cl_kwargs.setdefault("linewidths", 0.5)
+
+            ax.contour(
+                lons,
+                lats,
+                u.data,
+                transform=ccrs.PlateCarree(),
+                levels=levels,
+                **cl_kwargs,
+            )
+
         if gridlines:
             lat_interval = kwargs.pop("lat_interval", 30)
             lon_interval = kwargs.pop("lon_interval", 30)

{pygeoinf-1.2.3.dist-info → pygeoinf-1.2.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: pygeoinf
-Version: 1.2.3
+Version: 1.2.5
 Summary: A package for solving geophysical inference and inverse problems
 License: BSD-3-Clause
 Author: David Al-Attar and Dan Heathcote
@@ -16,7 +16,7 @@ Requires-Dist: matplotlib (>=3.0.0)
 Requires-Dist: numpy (>=1.26.0)
 Requires-Dist: pyqt6 (>=6.0.0)
 Requires-Dist: pyshtools (>=4.0.0)
-Requires-Dist: scipy (>=1.0.0)
+Requires-Dist: scipy (>=1.16.1)
 Description-Content-Type: text/markdown
 
 # pygeoinf: A Python Library for Geophysical Inference
@@ -233,7 +233,7 @@ plt.show()
 
 The output of the above script will look similar to the following figure:
 
-![Example of Bayesian Inference on a Circle](figures/fig1.png)
+![Example of Bayesian Inference on a Circle](docs/source/figures/fig1.png)
 
 ## Dependencies
 

pygeoinf-1.2.5.dist-info/RECORD

@@ -0,0 +1,28 @@
+pygeoinf/__init__.py,sha256=r5dumZhCLtuk9I-YXFDKnXB8t1gzjmgmjazkbqrZQpQ,1505
+pygeoinf/backus_gilbert.py,sha256=vpIWvryUIy6pHWhT9A4bVB3A9MuTll1MyN9U8zmVI5c,3783
+pygeoinf/checks/hilbert_space.py,sha256=Kr7PcOGrNIISezty0FBj5uXavIHC91yjCp2FVGNlHeE,7931
+pygeoinf/checks/linear_operators.py,sha256=RkmtAW6e5Zr6EuhX6GAt_pI0IWu2WZ-CrfjSBN_7dsU,4664
+pygeoinf/checks/nonlinear_operators.py,sha256=Rn9LTftyw5eGU3akx6xYNUJVGvX9J6gyTEXVFgLfYqs,5601
+pygeoinf/direct_sum.py,sha256=1RHPJI_PoEvSRH9AmjX-v88IkSW4uT2rPSt5pmZQEZY,19377
+pygeoinf/forward_problem.py,sha256=NnqWp7iMfkhHa9d-jBHzYHClaAfhKmO5D058AcJLLYg,10724
+pygeoinf/gaussian_measure.py,sha256=EOUyBYT-K9u2ZD_uwPXDv17BJHk-L0RM55jfIR-DmXY,24020
+pygeoinf/hilbert_space.py,sha256=0NCCG-OOHysdXYEFUs1wtJhGgOnuKvjZCZg8NJZO-DA,25331
+pygeoinf/inversion.py,sha256=RV0hG2bGnciWdja0oOPKPxnFhYzufqdj-mKYNr4JJ_o,6447
+pygeoinf/linear_bayesian.py,sha256=L1cJkeHtba4fPXZ8CmiLRBtuG2fmzG228M_iEar-iP8,9643
+pygeoinf/linear_forms.py,sha256=sgynBvlQ35CaH12PKU2vWPHh9ikrmQbD5IASCUQtlbw,9197
+pygeoinf/linear_operators.py,sha256=p03t2Azvdd4gakJws-myYDYDthyEskylsg6wODKbzJk,36424
+pygeoinf/linear_optimisation.py,sha256=UbSr6AOPpR2sRYoN1Pvv24-Zu7_XlJk1zE1IhQu83hg,12428
+pygeoinf/linear_solvers.py,sha256=mPhPiWKW82WHul_tfc0Xf-Y0GRtZQcPxfwEsWXh9G6M,15706
+pygeoinf/nonlinear_forms.py,sha256=eQudA-HfedbURvRmzVvU8HfNCxHTuWUpdDoWe_KlA4Y,7067
+pygeoinf/nonlinear_operators.py,sha256=X4_UMV1Rn4MqorjfN4P_UTckzCb4Gy1XceR3Ix8G4F8,7170
+pygeoinf/nonlinear_optimisation.py,sha256=skK1ikn9GrVYherD64Qt9WrEYHA2NAJ48msOu_J8Oig,7431
+pygeoinf/parallel.py,sha256=VVFvNHszy4wSa9LuErIsch4NAkLaZezhdN9YpRROBJo,2267
+pygeoinf/random_matrix.py,sha256=afEUFuoVbkFobhC9Jy9SuGb4Yib-fn3pQyiWUqXrA-8,13629
+pygeoinf/symmetric_space/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pygeoinf/symmetric_space/circle.py,sha256=7Bz9BfSkbDnoz5-HFwTsAQE4a09jUapBePwoCK0xYWw,18007
+pygeoinf/symmetric_space/sphere.py,sha256=5elw48I8A2i5EuRyYnm4craVp-ZB2_bBy9QQ15GytxE,23144
+pygeoinf/symmetric_space/symmetric_space.py,sha256=Q3KtfCtHO0_8LjsdKtH-5WVhRQurt5Bdk4yx1D2F5YY,17977
+pygeoinf-1.2.5.dist-info/LICENSE,sha256=GrTQnKJemVi69FSbHprq60KN0OJGsOSR-joQoTq-oD8,1501
+pygeoinf-1.2.5.dist-info/METADATA,sha256=MzCodk83iQ3UmX4sM3UbQP5F0wWEsCxp3WwimgbZolU,15376
+pygeoinf-1.2.5.dist-info/WHEEL,sha256=IYZQI976HJqqOpQU6PHkJ8fb3tMNBFjg-Cn-pwAbaFM,88
+pygeoinf-1.2.5.dist-info/RECORD,,

pygeoinf-1.2.3.dist-info/RECORD

@@ -1,29 +0,0 @@
-pygeoinf/__init__.py,sha256=LG49pW8RUK-NxO0KSEHNVG_tBClUK5GFLtjvNLDRnjE,1419
-pygeoinf/backus_gilbert.py,sha256=bXJ0JKh49elNKLm5cGJj_RBh0oXcH3hpR7U-QUFHj8M,3657
-pygeoinf/direct_sum.py,sha256=1RHPJI_PoEvSRH9AmjX-v88IkSW4uT2rPSt5pmZQEZY,19377
-pygeoinf/forward_problem.py,sha256=iQsTQ4CV4XAqWd48EzhA82NMySGJSQ0_PaEtfG40agw,10529
-pygeoinf/gaussian_measure.py,sha256=EOUyBYT-K9u2ZD_uwPXDv17BJHk-L0RM55jfIR-DmXY,24020
-pygeoinf/hilbert_space.py,sha256=StS2AoTnOFTrh3XRyZ6K9lhQDqJijDaJGMC8RRagoTQ,25247
-pygeoinf/inversion.py,sha256=3FiujTK4PDBPjS0aYdo02nHQjsVFL4GDqv4gvg2YilA,6189
-pygeoinf/linear_bayesian.py,sha256=L1cJkeHtba4fPXZ8CmiLRBtuG2fmzG228M_iEar-iP8,9643
-pygeoinf/linear_forms.py,sha256=sgynBvlQ35CaH12PKU2vWPHh9ikrmQbD5IASCUQtlbw,9197
-pygeoinf/linear_operators.py,sha256=ha6QHKHVBd_MLMNmk8zAoqm_yDM2dClb8C6p13jo7Ik,36333
-pygeoinf/linear_optimisation.py,sha256=sO155SkGg5H1RR-jmULru7R4vlCPjUce--6Z52l3Pks,11147
-pygeoinf/linear_solvers.py,sha256=fPcr4f2mhSK34cHdRXk9LsonQJ_gLhXQYwCYA4O6Jv4,15706
-pygeoinf/nonlinear_forms.py,sha256=eQudA-HfedbURvRmzVvU8HfNCxHTuWUpdDoWe_KlA4Y,7067
-pygeoinf/nonlinear_operators.py,sha256=1FvimPwMxt0h1qOvTTjGabm-2ctDO4bT71LLro-7t68,7069
-pygeoinf/nonlinear_optimisation.py,sha256=xcIJX6Uw6HuJ3OySGXm3cDQ-BVgIVi3jjtOpIHNq8ks,7074
-pygeoinf/parallel.py,sha256=VVFvNHszy4wSa9LuErIsch4NAkLaZezhdN9YpRROBJo,2267
-pygeoinf/random_matrix.py,sha256=afEUFuoVbkFobhC9Jy9SuGb4Yib-fn3pQyiWUqXrA-8,13629
-pygeoinf/symmetric_space/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pygeoinf/symmetric_space/__pycache__/__init__.cpython-311.pyc,sha256=mNBD912BewlTTEf1AutjuLwFyZzl76XX9PRCC1sH9D8,174
-pygeoinf/symmetric_space/__pycache__/circle.cpython-311.pyc,sha256=Gi7nJQmhng8bXAjOa-TmJLES--96jyJLh_H_VImyV_Y,27071
-pygeoinf/symmetric_space/__pycache__/sphere.cpython-311.pyc,sha256=sjTM71d-B70lMNjU-dinEQFY-QmVGFFdaiuVzemka5Y,32232
-pygeoinf/symmetric_space/__pycache__/symmetric_space.cpython-311.pyc,sha256=msPMApzg25Z4Dg9smh9983sf7e3om26fQE4rlgGVGck,25610
-pygeoinf/symmetric_space/circle.py,sha256=7Bz9BfSkbDnoz5-HFwTsAQE4a09jUapBePwoCK0xYWw,18007
-pygeoinf/symmetric_space/sphere.py,sha256=poasBQEXV5WNSA9LBuCY2lsxv79aV90jKP13FSoQUmU,21950
-pygeoinf/symmetric_space/symmetric_space.py,sha256=Q3KtfCtHO0_8LjsdKtH-5WVhRQurt5Bdk4yx1D2F5YY,17977
-pygeoinf-1.2.3.dist-info/LICENSE,sha256=GrTQnKJemVi69FSbHprq60KN0OJGsOSR-joQoTq-oD8,1501
-pygeoinf-1.2.3.dist-info/METADATA,sha256=zo3zrrAmpM1Swy2TycZrbRb3sfWmOsnyuvj1x8aelmw,15363
-pygeoinf-1.2.3.dist-info/WHEEL,sha256=IYZQI976HJqqOpQU6PHkJ8fb3tMNBFjg-Cn-pwAbaFM,88
-pygeoinf-1.2.3.dist-info/RECORD,,