pygeoinf 1.3.5__tar.gz → 1.3.6__tar.gz

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

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

{pygeoinf-1.3.5 → pygeoinf-1.3.6}/pygeoinf/linear_bayesian.py

@@ -9,10 +9,8 @@ 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.
+  an affine constraint `u in A`.
 """
 
 from __future__ import annotations
@@ -41,6 +39,11 @@ class LinearBayesianInversion(LinearInversion):
         model_prior_measure: GaussianMeasure,
         /,
     ) -> None:
+        """
+        Args:
+            forward_problem: The forward problem linking the model to the data.
+            model_prior_measure: The prior Gaussian measure on the model space.
+        """
         super().__init__(forward_problem)
         self._model_prior_measure: GaussianMeasure = model_prior_measure
 
@@ -52,16 +55,7 @@ class LinearBayesianInversion(LinearInversion):
     @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*
-
+        Returns the Bayesian Normal operator: N = A Q A* + R.
         """
         forward_operator = self.forward_problem.forward_operator
         model_prior_covariance = self.model_prior_measure.covariance
@@ -80,23 +74,10 @@ class LinearBayesianInversion(LinearInversion):
         /,
         *,
         preconditioner: Optional[LinearOperator] = None,
-    ):
+    ) -> LinearOperator:
         """
-        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.
+        Returns the Kalman gain operator K = Q A* N^-1.
         """
-
         forward_operator = self.forward_problem.forward_operator
         model_prior_covariance = self.model_prior_measure.covariance
         normal_operator = self.normal_operator
@@ -121,37 +102,45 @@ class LinearBayesianInversion(LinearInversion):
         preconditioner: Optional[LinearOperator] = None,
     ) -> GaussianMeasure:
         """
-        Returns the posterior Gaussian measure for the model conditions on the data.
+        Returns the posterior Gaussian measure p(u|d).
 
         Args:
             data: The observed data vector.
-            solver: A linear solver for inverting the normal operator C_d.
-            preconditioner: An optional preconditioner for C_d.
+            solver: A linear solver for inverting the normal operator.
+            preconditioner: An optional preconditioner.
         """
         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
 
+        # 1. Compute Kalman Gain
         kalman_gain = self.kalman_operator(solver, preconditioner=preconditioner)
 
-        # u_bar_post = u_bar + K (v - A u_bar - v_bar)
+        # 2. Compute Posterior Mean
+        # Shift data: d - A(mu_u)
         shifted_data = data_space.subtract(
             data, forward_operator(self.model_prior_measure.expectation)
         )
+
+        # Shift for noise mean: d - A(mu_u) - mu_e
         if self.forward_problem.data_error_measure_set:
-            shifted_data = data_space.subtract(
-                shifted_data, self.forward_problem.data_error_measure.expectation
-            )
+            error_expectation = self.forward_problem.data_error_measure.expectation
+            shifted_data = data_space.subtract(shifted_data, error_expectation)
+        else:
+            error_expectation = data_space.zero
+
         mean_update = kalman_gain(shifted_data)
         expectation = model_space.add(self.model_prior_measure.expectation, mean_update)
 
-        # Q_post = Q - K A Q
+        # 3. Compute Posterior Covariance (Implicitly)
+        # C_post = C_u - K A C_u
         covariance = model_prior_covariance - (
             kalman_gain @ forward_operator @ model_prior_covariance
         )
 
-        # Add in a sampling method if that is possible.
+        # 4. Set up Posterior Sampling
+        # Logic: Can sample if prior is samplable AND (noise is absent OR samplable)
         can_sample_prior = self.model_prior_measure.sample_set
         can_sample_noise = (
             not self.forward_problem.data_error_measure_set
@@ -160,19 +149,21 @@ class LinearBayesianInversion(LinearInversion):
 
         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():
+                # a. Sample Prior
                 model_sample = self.model_prior_measure.sample()
+
+                # b. Calculate Residual
                 prediction = forward_operator(model_sample)
                 data_residual = data_space.subtract(data, prediction)
 
+                # c. Perturb Residual
                 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)
 
+                # d. Update
                 correction = kalman_gain(data_residual)
                 return model_space.add(model_sample, correction)
 
@@ -185,11 +176,13 @@ class LinearBayesianInversion(LinearInversion):
 
 class ConstrainedLinearBayesianInversion(LinearInversion):
     """
-    Solves a linear inverse problem using Bayesian methods subject to an
-    affine subspace constraint `u in A`.
+    Solves a linear inverse problem subject to an affine subspace constraint.
 
-    This interprets the constraint as conditioning the prior on the subspace.
-    The subspace must be defined by a linear equation B(u) = w.
+    This class enforces the constraint `u in A` using either:
+    1. Bayesian Conditioning (Default): p(u | d, u in A).
+       If A is defined geometrically (no explicit equation), an implicit
+       operator (I-P) is used, which requires a robust solver in the subspace.
+    2. Geometric Projection: Projects the unconstrained posterior onto A.
     """
 
     def __init__(
@@ -205,8 +198,8 @@ class ConstrainedLinearBayesianInversion(LinearInversion):
         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.
+            constraint: The affine subspace A.
+            geometric: If True, uses orthogonal projection (Euclidean metric).
                        If False (default), uses Bayesian conditioning.
         """
         super().__init__(forward_problem)
@@ -214,88 +207,37 @@ class ConstrainedLinearBayesianInversion(LinearInversion):
         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:
+    def conditioned_prior_measure(self) -> 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.
+        Computes the prior measure conditioned on the constraint.
         """
-
-        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
-            )
+        return self._constraint.condition_gaussian_measure(
+            self._unconstrained_prior, geometric=self._geometric
+        )
 
     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.
+        Returns the posterior Gaussian measure p(u | d, u in A).
 
         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).
+            preconditioner: Preconditioner for the data update.
+
+        Note: The solver for the constraint update is managed internally by
+        the AffineSubspace object passed at initialization.
         """
-        # 1. Condition Prior (Uses constraint_solver and constraint_preconditioner)
-        cond_prior = self.conditioned_prior_measure(
-            constraint_solver, preconditioner=constraint_preconditioner
-        )
+        # 1. Condition Prior
+        cond_prior = self.conditioned_prior_measure()
 
-        # 2. Solve Bayesian Inverse Problem (Uses solver and preconditioner)
+        # 2. Solve Bayesian Inverse Problem with the new prior
         bayes_inv = LinearBayesianInversion(self.forward_problem, cond_prior)
 
         return bayes_inv.model_posterior_measure(

{pygeoinf-1.3.5 → pygeoinf-1.3.6}/pygeoinf/subspaces.py

@@ -3,29 +3,25 @@ Defines classes for representing affine and linear subspaces.
 
 The primary abstraction is the `AffineSubspace`, which represents a subset of
 a Hilbert space defined by a translation and a closed linear tangent space.
-`LinearSubspace` is a specialization where the translation is zero.
 """
 
 from __future__ import annotations
 from typing import List, Optional, Any, Callable, TYPE_CHECKING
 import numpy as np
+import warnings
 
 from .linear_operators import LinearOperator
 from .hilbert_space import HilbertSpace, Vector, EuclideanSpace
 from .linear_solvers import LinearSolver, CholeskySolver, IterativeLinearSolver
 
 if TYPE_CHECKING:
-    # Avoid circular imports for type checking
-    pass
+    from .gaussian_measure import GaussianMeasure
 
 
 class OrthogonalProjector(LinearOperator):
     """
     Internal engine for subspace projections.
-
     Represents an orthogonal projection operator P = P* = P^2.
-    While this class can be used directly, it is generally recommended to use
-    `AffineSubspace` or `LinearSubspace` for high-level problem definitions.
     """
 
     def __init__(
@@ -52,9 +48,8 @@ class OrthogonalProjector(LinearOperator):
         basis_vectors: List[Vector],
         orthonormalize: bool = True,
     ) -> OrthogonalProjector:
-        """Constructs P from a basis spanning the range."""
+        """Constructs a projector P onto the span of the provided basis vectors."""
         if not basis_vectors:
-            # Return zero operator if basis is empty
             return domain.zero_operator(domain)
 
         if orthonormalize:
@@ -78,7 +73,12 @@ class AffineSubspace:
         translation: Optional[Vector] = None,
         constraint_operator: Optional[LinearOperator] = None,
         constraint_value: Optional[Vector] = None,
+        solver: Optional[LinearSolver] = None,
+        preconditioner: Optional[LinearOperator] = None,
     ) -> None:
+        """
+        Initializes the AffineSubspace.
+        """
         self._projector = projector
 
         if translation is None:
@@ -91,6 +91,15 @@ class AffineSubspace:
         self._constraint_operator = constraint_operator
         self._constraint_value = constraint_value
 
+        # Logic: If explicit equation exists, default to Cholesky.
+        # If implicit, leave None (requires robust solver from user).
+        if self._constraint_operator is not None and solver is None:
+            self._solver = CholeskySolver(galerkin=True)
+        else:
+            self._solver = solver
+
+        self._preconditioner = preconditioner
+
     @property
     def domain(self) -> HilbertSpace:
         return self._projector.domain
@@ -108,27 +117,39 @@ class AffineSubspace:
         return LinearSubspace(self._projector)
 
     @property
-    def has_constraint_equation(self) -> bool:
+    def has_explicit_equation(self) -> bool:
+        """True if defined by B(u)=w, False if defined only by geometry."""
         return self._constraint_operator is not None
 
     @property
     def constraint_operator(self) -> LinearOperator:
+        """
+        Returns B for {u | B(u)=w}.
+        Falls back to (I - P) if no explicit operator exists.
+        """
         if self._constraint_operator is None:
-            raise AttributeError("This subspace is not defined by a linear equation.")
+            return self._projector.complement
         return self._constraint_operator
 
     @property
     def constraint_value(self) -> Vector:
+        """
+        Returns w for {u | B(u)=w}.
+        Falls back to (I - P)x0 if no explicit operator exists.
+        """
         if self._constraint_value is None:
-            raise AttributeError("This subspace is not defined by a linear equation.")
+            complement = self._projector.complement
+            return complement(self._translation)
         return self._constraint_value
 
     def project(self, x: Vector) -> Vector:
+        """Orthogonally projects x onto the affine subspace."""
         diff = self.domain.subtract(x, self.translation)
         proj_diff = self.projector(diff)
         return self.domain.add(self.translation, proj_diff)
 
     def is_element(self, x: Vector, rtol: float = 1e-6) -> bool:
+        """Returns True if x lies in the subspace."""
         proj = self.project(x)
         diff = self.domain.subtract(x, proj)
         norm_diff = self.domain.norm(diff)
@@ -136,6 +157,46 @@ class AffineSubspace:
         scale = norm_x if norm_x > 1e-12 else 1.0
         return norm_diff <= rtol * scale
 
+    def condition_gaussian_measure(
+        self, prior: GaussianMeasure, geometric: bool = False
+    ) -> GaussianMeasure:
+        """
+        Conditions a Gaussian measure on this subspace.
+        """
+        if geometric:
+            # Geometric Projection: u -> P(u - x0) + x0
+            # Affine Map: u -> P(u) + (I-P)x0
+            shift = self.domain.subtract(
+                self.translation, self.projector(self.translation)
+            )
+            return prior.affine_mapping(operator=self.projector, translation=shift)
+
+        else:
+            # Bayesian Conditioning: u | B(u)=w
+
+            # Check for singular implicit operator usage
+            if not self.has_explicit_equation and self._solver is None:
+                raise ValueError(
+                    "This subspace defines the constraint implicitly as (I-P)u = (I-P)x0. "
+                    "The operator (I-P) is singular. You must provide a solver "
+                    "capable of handling singular systems (e.g. MinRes) to the "
+                    "AffineSubspace constructor."
+                )
+
+            # Local imports
+            from .forward_problem import LinearForwardProblem
+            from .linear_bayesian import LinearBayesianInversion
+
+            solver = self._solver
+            preconditioner = self._preconditioner
+
+            constraint_problem = LinearForwardProblem(self.constraint_operator)
+            constraint_inversion = LinearBayesianInversion(constraint_problem, prior)
+
+            return constraint_inversion.model_posterior_measure(
+                self.constraint_value, solver, preconditioner=preconditioner
+            )
+
     @classmethod
     def from_linear_equation(
         cls,
@@ -144,7 +205,7 @@ class AffineSubspace:
         solver: Optional[LinearSolver] = None,
         preconditioner: Optional[LinearOperator] = None,
     ) -> AffineSubspace:
-        """Constructs the subspace {u | B(u) = w}."""
+        """Constructs subspace from B(u)=w."""
         domain = operator.domain
         G = operator @ operator.adjoint
 
@@ -166,7 +227,12 @@ class AffineSubspace:
         projector = OrthogonalProjector(domain, mapping, complement_projector=P_perp_op)
 
         return cls(
-            projector, translation, constraint_operator=operator, constraint_value=value
+            projector,
+            translation,
+            constraint_operator=operator,
+            constraint_value=value,
+            solver=solver,
+            preconditioner=preconditioner,
         )
 
     @classmethod
@@ -176,18 +242,38 @@ class AffineSubspace:
         basis_vectors: List[Vector],
         translation: Optional[Vector] = None,
         orthonormalize: bool = True,
+        solver: Optional[LinearSolver] = None,
+        preconditioner: Optional[LinearOperator] = None,
     ) -> AffineSubspace:
         """
-        Constructs the subspace passing through 'translation' with the given
-        tangent basis.
-
-        Note: This does not define a constraint equation B(u)=w, so it cannot
-        be used directly with ConstrainedLinearBayesianInversion.
+        Constructs an affine subspace from a translation and a basis for the tangent space.
+
+        This method defines the subspace geometrically. The constraint is implicit:
+        (I - P)u = (I - P)x0.
+
+        Args:
+            domain: The Hilbert space.
+            basis_vectors: Basis vectors for the tangent space V.
+            translation: A point x0 in the subspace.
+            orthonormalize: If True, orthonormalizes the basis.
+            solver: A linear solver capable of handling the singular operator (I-P).
+                    Required if you intend to use this subspace for Bayesian conditioning.
+            preconditioner: Optional preconditioner for the solver.
         """
+        if solver is None:
+            warnings.warn(
+                "Constructing a subspace from a tangent basis without a solver. "
+                "This defines an implicit constraint with a singular operator. "
+                "Bayesian conditioning will fail; geometric projection remains available.",
+                UserWarning,
+                stacklevel=2,
+            )
+
         projector = OrthogonalProjector.from_basis(
             domain, basis_vectors, orthonormalize=orthonormalize
         )
-        return cls(projector, translation)
+
+        return cls(projector, translation, solver=solver, preconditioner=preconditioner)
 
     @classmethod
     def from_complement_basis(
@@ -198,24 +284,18 @@ class AffineSubspace:
         orthonormalize: bool = True,
     ) -> AffineSubspace:
         """
-        Constructs the subspace orthogonal to the given basis, passing through
-        'translation'.
-
-        This automatically constructs the constraint operator B such that
-        the subspace is {u | B(u) = B(translation)}.
+        Constructs subspace from complement basis.
+        Constraint is explicit: <u, e_i> = <x0, e_i>.
         """
-        # 1. Orthonormalize basis for stability
         if orthonormalize:
             e_vectors = domain.gram_schmidt(basis_vectors)
         else:
             e_vectors = basis_vectors
 
-        # 2. Construct Projector P_perp
         complement_projector = OrthogonalProjector.from_basis(
-            domain, e_vectors, orthonormalize=False  # Already done
+            domain, e_vectors, orthonormalize=False
         )
 
-        # 3. Construct Projector P = I - P_perp
         def mapping(x: Any) -> Any:
             return domain.subtract(x, complement_projector(x))
 
@@ -223,16 +303,12 @@ class AffineSubspace:
             domain, mapping, complement_projector=complement_projector
         )
 
-        # 4. Construct Constraint Operator B implicitly defined by the basis
-        # B: E -> R^k, u -> [<e_1, u>, ..., <e_k, u>]
-        # Since e_i are orthonormal, BB* = I, which is perfect for solvers.
         codomain = EuclideanSpace(len(e_vectors))
 
         def constraint_mapping(u: Vector) -> np.ndarray:
             return np.array([domain.inner_product(e, u) for e in e_vectors])
 
         def constraint_adjoint(c: np.ndarray) -> Vector:
-            # sum c_i e_i
             res = domain.zero
             for i, e in enumerate(e_vectors):
                 domain.axpy(c[i], e, res)
@@ -242,8 +318,6 @@ class AffineSubspace:
             domain, codomain, constraint_mapping, adjoint_mapping=constraint_adjoint
         )
 
-        # 5. Determine Constraint Value w = B(translation)
-        # If translation is None (zero), w is zero.
         if translation is None:
             _translation = domain.zero
             w = codomain.zero
@@ -251,12 +325,20 @@ class AffineSubspace:
             _translation = translation
             w = B(_translation)
 
-        return cls(projector, _translation, constraint_operator=B, constraint_value=w)
+        solver = CholeskySolver(galerkin=True)
+
+        return cls(
+            projector,
+            _translation,
+            constraint_operator=B,
+            constraint_value=w,
+            solver=solver,
+        )
 
 
 class LinearSubspace(AffineSubspace):
     """
-    Represents a linear subspace (an affine subspace passing through zero).
+    Represents a linear subspace (an affine subspace passing through the origin).
     """
 
     def __init__(self, projector: OrthogonalProjector) -> None:
@@ -272,14 +354,19 @@ class LinearSubspace(AffineSubspace):
 
     @classmethod
     def from_kernel(
-        cls, operator: LinearOperator, solver: Optional[LinearSolver] = None
+        cls,
+        operator: LinearOperator,
+        solver: Optional[LinearSolver] = None,
+        preconditioner: Optional[LinearOperator] = None,
     ) -> LinearSubspace:
         affine = AffineSubspace.from_linear_equation(
-            operator, operator.codomain.zero, solver
+            operator, operator.codomain.zero, solver, preconditioner
         )
         instance = cls(affine.projector)
         instance._constraint_operator = operator
         instance._constraint_value = operator.codomain.zero
+        instance._solver = affine._solver
+        instance._preconditioner = preconditioner
         return instance
 
     @classmethod
@@ -288,11 +375,16 @@ class LinearSubspace(AffineSubspace):
         domain: HilbertSpace,
         basis_vectors: List[Vector],
         orthonormalize: bool = True,
+        solver: Optional[LinearSolver] = None,
+        preconditioner: Optional[LinearOperator] = None,
     ) -> LinearSubspace:
         projector = OrthogonalProjector.from_basis(
             domain, basis_vectors, orthonormalize=orthonormalize
         )
-        return cls(projector)
+        instance = cls(projector)
+        instance._solver = solver
+        instance._preconditioner = preconditioner
+        return instance
 
     @classmethod
     def from_complement_basis(
@@ -304,8 +396,8 @@ class LinearSubspace(AffineSubspace):
         affine = AffineSubspace.from_complement_basis(
             domain, basis_vectors, translation=None, orthonormalize=orthonormalize
         )
-        # Copy constraint info from the affine instance
         instance = cls(affine.projector)
         instance._constraint_operator = affine.constraint_operator
         instance._constraint_value = affine.constraint_value
+        instance._solver = affine._solver
         return instance

{pygeoinf-1.3.5 → pygeoinf-1.3.6}/pygeoinf/symmetric_space/sh_tools.py

@@ -11,16 +11,28 @@ class SHVectorConverter:
     """
     Handles conversion between pyshtools 3D coefficient arrays and 1D vectors.
 
-    This class provides a bridge between the pyshtools data structure for
-    spherical harmonic coefficients, a 3D array of shape (2, lmax+1, lmax+1),
-    and the 1D vector format often used in linear algebra and inverse problems.
+    This class bridges the gap between the `pyshtools` 3D array format
+    (shape `[2, lmax+1, lmax+1]`) and the flat 1D vector format used in
+    linear algebra.
 
-    The vector is ordered by degree l, and within each degree, by order m,
-    from -l to +l.
+    **Vector Layout:**
+    The output vector is ordered first by degree $l$ (ascending from `lmin` to `lmax`),
+    and then by order $m$ (ascending from $-l$ to $+l$).
+
+    The sequence of coefficients is:
+
+    .. math::
+        [u_{l_{min}, -l_{min}}, \dots, u_{l_{min}, l_{min}}, \quad
+         u_{l_{min}+1, -(l_{min}+1)}, \dots, u_{l_{min}+1, l_{min}+1}, \quad \dots]
+
+    **Example (lmin=0):**
+
+    .. math::
+        [u_{0,0}, \quad u_{1,-1}, u_{1,0}, u_{1,1}, \quad u_{2,-2}, u_{2,-1}, u_{2,0}, u_{2,1}, u_{2,2}, \dots]
 
     Args:
         lmax (int): The maximum spherical harmonic degree to include.
-        lmin (int): The minimum spherical harmonic degree to include. Defaults to 2.
+        lmin (int): The minimum spherical harmonic degree to include. Defaults to 0.
     """
 
     def __init__(self, lmax: int, lmin: int = 0):

{pygeoinf-1.3.5 → pygeoinf-1.3.6}/pygeoinf/symmetric_space/sphere.py

@@ -532,30 +532,26 @@ class Lebesgue(SphereHelper, HilbertModule, AbstractInvariantLebesgueSpace):
         )
 
     def to_coefficient_operator(self, lmax: int, lmin: int = 0):
-        """
-        Returns a LinearOperator that maps an element of the space to
-        a vector of its spherical harmonic coefficients within the
-        specified range of degrees.
+        r"""
+        Returns a LinearOperator mapping a function to its spherical harmonic coefficients.
 
-        The output coefficients are ordered in the following manner:
+        The operator maps an element of the Hilbert space to a vector in $\mathbb{R}^k$.
+        The coefficients in the output vector are ordered by degree $l$ (major)
+        and order $m$ (minor), from $-l$ to $+l$.
 
-        u_{00}, u_{1-1}, u_{10}, u_{11}, u_{2-2}, u_{2-1}, u_{20}, u_{21}, u_{22}, ...
+        **Ordering:**
 
-        in this case assuming lmin = 0.
+        .. math::
+            u = [u_{0,0}, \quad u_{1,-1}, u_{1,0}, u_{1,1}, \quad u_{2,-2}, \dots, u_{2,2}, \quad \dots]
 
-        If lmax is larger than the field's lmax, the output will be padded by zeros.
+        (assuming `lmin=0`).
 
         Args:
             lmax: The maximum spherical harmonic degree to include in the output.
-            lmin: The minimum spherical harmonic degree to include in the output.
-                Defaults to 0.
+            lmin: The minimum spherical harmonic degree to include. Defaults to 0.
 
         Returns:
-            A LinearOperator that maps an SHGrid to a NumPy vector of coefficients.
-
-        Notes:
-            This is a left inverse of the from_coefficient_operator so long a the
-            values for lmin and lmax are equal.
+            A LinearOperator mapping `SHGrid` -> `numpy.ndarray`.
         """
 
         converter = SHVectorConverter(lmax, lmin)
@@ -577,27 +573,25 @@ class Lebesgue(SphereHelper, HilbertModule, AbstractInvariantLebesgueSpace):
         return LinearOperator(self, codomain, mapping, adjoint_mapping=adjoint_mapping)
 
     def from_coefficient_operator(self, lmax: int, lmin: int = 0):
-        """
-        Returns a LinearOperator that maps a vector of spherical harmonic coefficients
-        to an element of the space.
+        r"""
+        Returns a LinearOperator mapping a vector of coefficients to a function.
 
-        The input coefficients are ordered in the following manner:
+        The operator maps a vector in $\mathbb{R}^k$ to an element of the Hilbert space.
+        The input vector must follow the standard $l$-major, $m$-minor ordering.
 
-        u_{00}, u_{1-1}, u_{10}, u_{11}, u_{2-2}, u_{2-1}, u_{20}, u_{21}, u_{22}, ...
+        **Ordering:**
 
-        in this case assuming lmin = 0.
+        .. math::
+            v = [u_{0,0}, \quad u_{1,-1}, u_{1,0}, u_{1,1}, \quad u_{2,-2}, \dots, u_{2,2}, \quad \dots]
+
+        (assuming `lmin=0`).
 
         Args:
-            lmax: The maximum spherical harmonic degree to include in the output.
-            lmin: The minimum spherical harmonic degree to include in the output.
-                Defaults to 0.
+            lmax: The maximum spherical harmonic degree expected in the input.
+            lmin: The minimum spherical harmonic degree expected. Defaults to 0.
 
         Returns:
-            A LinearOperator that maps a NumPy vector of coefficients to an SHGrid.
-
-        Notes:
-            This is a right inverse of the to_coefficient_operator so long a the
-            values for lmin and lmax are equal.
+            A LinearOperator mapping `numpy.ndarray` -> `SHGrid`.
         """
 
         converter = SHVectorConverter(lmax, lmin)
@@ -783,30 +777,26 @@ class Sobolev(SphereHelper, MassWeightedHilbertModule, AbstractInvariantSobolevS
         )
 
     def to_coefficient_operator(self, lmax: int, lmin: int = 0):
-        """
-        Returns a LinearOperator that maps an element of the space to
-        a vector of its spherical harmonic coefficients within the
-        specified range of degrees.
+        r"""
+        Returns a LinearOperator mapping a function to its spherical harmonic coefficients.
 
-        The output coefficients are ordered in the following manner:
+        The operator maps an element of the Hilbert space to a vector in $\mathbb{R}^k$.
+        The coefficients in the output vector are ordered by degree $l$ (major)
+        and order $m$ (minor), from $-l$ to $+l$.
 
-        u_{00}, u_{1-1}, u_{10}, u_{11}, u_{2-2}, u_{2-1}, u_{20}, u_{21}, u_{22}, ...
+        **Ordering:**
 
-        in this case assuming lmin = 0.
+        .. math::
+            u = [u_{0,0}, \quad u_{1,-1}, u_{1,0}, u_{1,1}, \quad u_{2,-2}, \dots, u_{2,2}, \quad \dots]
 
-        If lmax is larger than the field's lmax, the output will be padded by zeros.
+        (assuming `lmin=0`).
 
         Args:
             lmax: The maximum spherical harmonic degree to include in the output.
-            lmin: The minimum spherical harmonic degree to include in the output.
-                Defaults to 0.
+            lmin: The minimum spherical harmonic degree to include. Defaults to 0.
 
         Returns:
-            A LinearOperator that maps an SHGrid to a NumPy vector of coefficients.
-
-        Notes:
-            This is a left inverse of the from_coefficient_operator so long a the
-            values for lmin and lmax are equal.
+            A LinearOperator mapping `SHGrid` -> `numpy.ndarray`.
         """
 
         l2_operator = self.underlying_space.to_coefficient_operator(lmax, lmin)
@@ -816,27 +806,25 @@ class Sobolev(SphereHelper, MassWeightedHilbertModule, AbstractInvariantSobolevS
         )
 
     def from_coefficient_operator(self, lmax: int, lmin: int = 0):
-        """
-        Returns a LinearOperator that maps a vector of spherical harmonic coefficients
-        to an element of the space.
+        r"""
+        Returns a LinearOperator mapping a vector of coefficients to a function.
 
-        The input coefficients are ordered in the following manner:
+        The operator maps a vector in $\mathbb{R}^k$ to an element of the Hilbert space.
+        The input vector must follow the standard $l$-major, $m$-minor ordering.
 
-        u_{00}, u_{1-1}, u_{10}, u_{11}, u_{2-2}, u_{2-1}, u_{20}, u_{21}, u_{22}, ...
+        **Ordering:**
 
-        in this case assuming lmin = 0.
+        .. math::
+            v = [u_{0,0}, \quad u_{1,-1}, u_{1,0}, u_{1,1}, \quad u_{2,-2}, \dots, u_{2,2}, \quad \dots]
+
+        (assuming `lmin=0`).
 
         Args:
-            lmax: The maximum spherical harmonic degree to include in the output.
-            lmin: The minimum spherical harmonic degree to include in the output.
-                Defaults to 0.
+            lmax: The maximum spherical harmonic degree expected in the input.
+            lmin: The minimum spherical harmonic degree expected. Defaults to 0.
 
         Returns:
-            A LinearOperator that maps a NumPy vector of coefficients to an SHGrid.
-
-        Notes:
-            This is a right inverse of the to_coefficient_operator so long a the
-            values for lmin and lmax are equal.
+            A LinearOperator mapping `numpy.ndarray` -> `SHGrid`.
         """
 
         l2_operator = self.underlying_space.from_coefficient_operator(lmax, lmin)

{pygeoinf-1.3.5 → pygeoinf-1.3.6}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "pygeoinf"
-version = "1.3.5"
+version = "1.3.6"
 description = "A package for solving geophysical inference and inverse problems"
 authors = ["David Al-Attar and Dan Heathcote"]
 readme = "README.md"