pygeoinf 1.3.4__tar.gz → 1.3.5__tar.gz

{pygeoinf-1.3.4 → pygeoinf-1.3.5}/PKG-INFO

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

{pygeoinf-1.3.4 → pygeoinf-1.3.5}/pygeoinf/__init__.py

@@ -76,9 +76,14 @@ from .forward_problem import ForwardProblem, LinearForwardProblem
 from .linear_optimisation import (
     LinearLeastSquaresInversion,
     LinearMinimumNormInversion,
+    ConstrainedLinearLeastSquaresInversion,
+    ConstrainedLinearMinimumNormInversion,
 )
 
-from .linear_bayesian import LinearBayesianInversion, LinearBayesianInference
+from .linear_bayesian import (
+    LinearBayesianInversion,
+    ConstrainedLinearBayesianInversion,
+)
 
 from .backus_gilbert import HyperEllipsoid
 
@@ -87,6 +92,8 @@ from .nonlinear_optimisation import (
 )
 
 
+from .subspaces import OrthogonalProjector, AffineSubspace, LinearSubspace
+
 __all__ = [
     # random_matrix
     "fixed_rank_random_range",
@@ -144,11 +151,17 @@ __all__ = [
     # linear_optimisation
     "LinearLeastSquaresInversion",
     "LinearMinimumNormInversion",
+    "ConstrainedLinearLeastSquaresInversion",
+    "ConstrainedLinearMinimumNormInversion",
     # linear_bayesian
     "LinearBayesianInversion",
-    "LinearBayesianInference",
+    "ConstrainedLinearBayesianInversion",
     # backus_gilbert
     "HyperEllipsoid",
     # nonlinear_optimisation
     "ScipyUnconstrainedOptimiser",
+    # Subspaces
+    "OrthogonalProjector",
+    "AffineSubspace",
+    "LinearSubspace",
 ]

pygeoinf-1.3.5/pygeoinf/linear_bayesian.py

@@ -0,0 +1,303 @@
+"""
+Implements the Bayesian framework for solving linear inverse problems.
+
+This module treats the inverse problem from a statistical perspective, aiming to
+determine the full posterior probability distribution of the unknown model
+parameters, rather than a single best-fit solution.
+
+Key Classes
+-----------
+- `LinearBayesianInversion`: Computes the posterior Gaussian measure `p(u|d)`
+  for the model `u` given observed data `d`.
+- `LinearBayesianInference`: Extends the framework to compute the posterior
+  distribution for a derived property of the model.
+- `ConstrainedLinearBayesianInversion`: Solves the inverse problem subject to
+  a hard affine constraint `u in A`, interpreting it as conditioning the prior.
+"""
+
+from __future__ import annotations
+from typing import Optional
+
+from .inversion import LinearInversion
+from .gaussian_measure import GaussianMeasure
+from .forward_problem import LinearForwardProblem
+from .linear_operators import LinearOperator, NormalSumOperator
+from .linear_solvers import LinearSolver, IterativeLinearSolver
+from .hilbert_space import Vector
+from .subspaces import AffineSubspace
+
+
+class LinearBayesianInversion(LinearInversion):
+    """
+    Solves a linear inverse problem using Bayesian methods.
+
+    This class applies to problems of the form `d = A(u) + e`. It computes the
+    full posterior probability distribution `p(u|d)`.
+    """
+
+    def __init__(
+        self,
+        forward_problem: LinearForwardProblem,
+        model_prior_measure: GaussianMeasure,
+        /,
+    ) -> None:
+        super().__init__(forward_problem)
+        self._model_prior_measure: GaussianMeasure = model_prior_measure
+
+    @property
+    def model_prior_measure(self) -> GaussianMeasure:
+        """The prior Gaussian measure on the model space."""
+        return self._model_prior_measure
+
+    @property
+    def normal_operator(self) -> LinearOperator:
+        """
+        Returns the Bayesian Norm operator:
+
+        N = A Q A* + R
+
+        with A the forward operator (with A* its adjoint), Q the model
+        prior covariance, and R the data error covariance. For error-free
+        problems this operator is reduced to:
+
+        N = A Q A*
+
+        """
+        forward_operator = self.forward_problem.forward_operator
+        model_prior_covariance = self.model_prior_measure.covariance
+
+        if self.forward_problem.data_error_measure_set:
+            return (
+                forward_operator @ model_prior_covariance @ forward_operator.adjoint
+                + self.forward_problem.data_error_measure.covariance
+            )
+        else:
+            return NormalSumOperator(forward_operator, model_prior_covariance)
+
+    def kalman_operator(
+        self,
+        solver: LinearSolver,
+        /,
+        *,
+        preconditioner: Optional[LinearOperator] = None,
+    ):
+        """
+        Returns the Kalman gain operator for the problem:
+
+        K = Q A* Ni
+
+        where Q is the model prior covariance, A the forward operator
+        (with adjoint A*), and Ni is the inverse of the normal operator.
+
+        Args:
+            solver: A linear solver for inverting the normal operator.
+            preconditioner: An optional preconditioner for.
+
+        Returns:
+            A LinearOperator for the Kalman gain.
+        """
+
+        forward_operator = self.forward_problem.forward_operator
+        model_prior_covariance = self.model_prior_measure.covariance
+        normal_operator = self.normal_operator
+
+        if isinstance(solver, IterativeLinearSolver):
+            inverse_normal_operator = solver(
+                normal_operator, preconditioner=preconditioner
+            )
+        else:
+            inverse_normal_operator = solver(normal_operator)
+
+        return (
+            model_prior_covariance @ forward_operator.adjoint @ inverse_normal_operator
+        )
+
+    def model_posterior_measure(
+        self,
+        data: Vector,
+        solver: LinearSolver,
+        /,
+        *,
+        preconditioner: Optional[LinearOperator] = None,
+    ) -> GaussianMeasure:
+        """
+        Returns the posterior Gaussian measure for the model conditions on the data.
+
+        Args:
+            data: The observed data vector.
+            solver: A linear solver for inverting the normal operator C_d.
+            preconditioner: An optional preconditioner for C_d.
+        """
+        data_space = self.data_space
+        model_space = self.model_space
+        forward_operator = self.forward_problem.forward_operator
+        model_prior_covariance = self.model_prior_measure.covariance
+
+        kalman_gain = self.kalman_operator(solver, preconditioner=preconditioner)
+
+        # u_bar_post = u_bar + K (v - A u_bar - v_bar)
+        shifted_data = data_space.subtract(
+            data, forward_operator(self.model_prior_measure.expectation)
+        )
+        if self.forward_problem.data_error_measure_set:
+            shifted_data = data_space.subtract(
+                shifted_data, self.forward_problem.data_error_measure.expectation
+            )
+        mean_update = kalman_gain(shifted_data)
+        expectation = model_space.add(self.model_prior_measure.expectation, mean_update)
+
+        # Q_post = Q - K A Q
+        covariance = model_prior_covariance - (
+            kalman_gain @ forward_operator @ model_prior_covariance
+        )
+
+        # Add in a sampling method if that is possible.
+        can_sample_prior = self.model_prior_measure.sample_set
+        can_sample_noise = (
+            not self.forward_problem.data_error_measure_set
+            or self.forward_problem.data_error_measure.sample_set
+        )
+
+        if can_sample_prior and can_sample_noise:
+
+            if self.forward_problem.data_error_measure_set:
+                error_expectation = self.forward_problem.data_error_measure.expectation
+
+            def sample():
+                model_sample = self.model_prior_measure.sample()
+                prediction = forward_operator(model_sample)
+                data_residual = data_space.subtract(data, prediction)
+
+                if self.forward_problem.data_error_measure_set:
+                    noise_raw = self.forward_problem.data_error_measure.sample()
+                    epsilon = data_space.subtract(noise_raw, error_expectation)
+                    data_space.axpy(1.0, epsilon, data_residual)
+
+                correction = kalman_gain(data_residual)
+                return model_space.add(model_sample, correction)
+
+            return GaussianMeasure(
+                covariance=covariance, expectation=expectation, sample=sample
+            )
+        else:
+            return GaussianMeasure(covariance=covariance, expectation=expectation)
+
+
+class ConstrainedLinearBayesianInversion(LinearInversion):
+    """
+    Solves a linear inverse problem using Bayesian methods subject to an
+    affine subspace constraint `u in A`.
+
+    This interprets the constraint as conditioning the prior on the subspace.
+    The subspace must be defined by a linear equation B(u) = w.
+    """
+
+    def __init__(
+        self,
+        forward_problem: LinearForwardProblem,
+        model_prior_measure: GaussianMeasure,
+        constraint: AffineSubspace,
+        /,
+        *,
+        geometric: bool = False,
+    ) -> None:
+        """
+        Args:
+            forward_problem: The forward problem.
+            model_prior_measure: The unconstrained prior Gaussian measure.
+            constraint: The affine subspace A = {u | Bu = w}.
+            geometric: If True, uses orthogonal projection to enforce the constraint.
+                       If False (default), uses Bayesian conditioning.
+        """
+        super().__init__(forward_problem)
+        self._unconstrained_prior = model_prior_measure
+        self._constraint = constraint
+        self._geometric = geometric
+
+        if not constraint.has_constraint_equation:
+            raise ValueError(
+                "For Bayesian inversion, the subspace must be defined by a linear "
+                "equation (constraint operator). Use AffineSubspace.from_linear_equation."
+            )
+
+    def conditioned_prior_measure(
+        self,
+        solver: LinearSolver,
+        preconditioner: Optional[LinearOperator] = None,
+    ) -> GaussianMeasure:
+        """
+        Computes the prior measure conditioned on the constraint B(u) = w.
+
+        Args:
+            solver: Linear solver used to invert the normal operator, BQB*.
+            preconditioner: Optional preconditioner for the constraint solver.
+        """
+
+        constraint_op = self._constraint.constraint_operator
+        constraint_val = self._constraint.constraint_value
+
+        if self._geometric:
+            # --- Geometric Approach (Affine Mapping) ---
+            # Map: u -> P u + v
+            # P = I - B* (B B*)^-1 B
+            # v = B* (B B*)^-1 w
+
+            gram_operator = constraint_op @ constraint_op.adjoint
+
+            if isinstance(solver, IterativeLinearSolver):
+                inv_gram_operator = solver(gram_operator, preconditioner=preconditioner)
+            else:
+                inv_gram_operator = solver(gram_operator)
+
+            pseudo_inverse = constraint_op.adjoint @ inv_gram_operator
+            identity = self._unconstrained_prior.domain.identity_operator()
+            projector = identity - pseudo_inverse @ constraint_op
+            translation = pseudo_inverse(constraint_val)
+
+            return self._unconstrained_prior.affine_mapping(
+                operator=projector, translation=translation
+            )
+
+        else:
+            # --- Bayesian Approach (Statistical Conditioning) ---
+            # Treat the constraint as a noiseless observation: w = B(u)
+
+            constraint_problem = LinearForwardProblem(constraint_op)
+            constraint_inversion = LinearBayesianInversion(
+                constraint_problem, self._unconstrained_prior
+            )
+
+            return constraint_inversion.model_posterior_measure(
+                constraint_val, solver, preconditioner=preconditioner
+            )
+
+    def model_posterior_measure(
+        self,
+        data: Vector,
+        solver: LinearSolver,
+        constraint_solver: LinearSolver,
+        *,
+        preconditioner: Optional[LinearOperator] = None,
+        constraint_preconditioner: Optional[LinearOperator] = None,
+    ) -> GaussianMeasure:
+        """
+        Returns the posterior Gaussian measure for the model given the constraint and the data.
+
+        Args:
+            data: Observed data vector.
+            solver: Solver for the data update (inverts A C_cond A* + Ce).
+            constraint_solver: Solver for the prior conditioning (inverts B C_prior B*).
+            preconditioner: Preconditioner for the data update (acts on Data Space).
+            constraint_preconditioner: Preconditioner for the constraint update (acts on Property Space).
+        """
+        # 1. Condition Prior (Uses constraint_solver and constraint_preconditioner)
+        cond_prior = self.conditioned_prior_measure(
+            constraint_solver, preconditioner=constraint_preconditioner
+        )
+
+        # 2. Solve Bayesian Inverse Problem (Uses solver and preconditioner)
+        bayes_inv = LinearBayesianInversion(self.forward_problem, cond_prior)
+
+        return bayes_inv.model_posterior_measure(
+            data, solver, preconditioner=preconditioner
+        )

{pygeoinf-1.3.4 → pygeoinf-1.3.5}/pygeoinf/linear_optimisation.py

@@ -16,6 +16,8 @@ Key Classes
 - `LinearMinimumNormInversion`: Finds the model with the smallest norm that
   fits the data to a statistically acceptable degree using the discrepancy
   principle.
+- `ConstrainedLinearLeastSquaresInversion`: Solves a linear inverse problem
+  subject to an affine subspace constraint.
 """
 
 from __future__ import annotations
@@ -30,6 +32,7 @@ from .forward_problem import LinearForwardProblem
 from .linear_operators import LinearOperator
 from .linear_solvers import LinearSolver, IterativeLinearSolver
 from .hilbert_space import Vector
+from .subspaces import AffineSubspace
 
 
 class LinearLeastSquaresInversion(LinearInversion):
@@ -160,6 +163,113 @@ class LinearLeastSquaresInversion(LinearInversion):
             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.
+    """
+
+    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=(
+                forward_problem.data_error_measure
+                if forward_problem.data_error_measure_set
+                else None
+            ),
+        )
+
+        # 3. Initialize the internal unconstrained solver
+        self._unconstrained_inversion = LinearLeastSquaresInversion(
+            self._reduced_forward_problem
+        )
+
+    def least_squares_operator(
+        self,
+        damping: float,
+        solver: LinearSolver,
+        /,
+        **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)
+        reduced_op = self._unconstrained_inversion.least_squares_operator(
+            damping, solver, **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.
@@ -309,3 +419,111 @@ class LinearMinimumNormInversion(LinearInversion):
             normal_operator = forward_operator @ forward_operator.adjoint
             inverse_normal_operator = solver(normal_operator)
             return forward_operator.adjoint @ inverse_normal_operator
+
+
+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.
+    """
+
+    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)
+        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=(
+                forward_problem.data_error_measure
+                if forward_problem.data_error_measure_set
+                else None
+            ),
+        )
+
+        # 3. Initialize the internal unconstrained solver
+        self._unconstrained_inversion = LinearMinimumNormInversion(
+            self._reduced_forward_problem
+        )
+
+    def minimum_norm_operator(
+        self,
+        solver: LinearSolver,
+        /,
+        **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)
+        reduced_op = self._unconstrained_inversion.minimum_norm_operator(
+            solver, **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)