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

pygeoinf/subspaces.py

@@ -0,0 +1,403 @@
+"""
+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.
+"""
+
+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:
+    from .gaussian_measure import GaussianMeasure
+
+
+class OrthogonalProjector(LinearOperator):
+    """
+    Internal engine for subspace projections.
+    Represents an orthogonal projection operator P = P* = P^2.
+    """
+
+    def __init__(
+        self,
+        domain: HilbertSpace,
+        mapping: Callable[[Any], Any],
+        complement_projector: Optional[LinearOperator] = None,
+    ) -> None:
+        super().__init__(domain, domain, mapping, adjoint_mapping=mapping)
+        self._complement_projector = complement_projector
+
+    @property
+    def complement(self) -> LinearOperator:
+        """Returns the projector onto the orthogonal complement (I - P)."""
+        if self._complement_projector is None:
+            identity = self.domain.identity_operator()
+            self._complement_projector = identity - self
+        return self._complement_projector
+
+    @classmethod
+    def from_basis(
+        cls,
+        domain: HilbertSpace,
+        basis_vectors: List[Vector],
+        orthonormalize: bool = True,
+    ) -> OrthogonalProjector:
+        """Constructs a projector P onto the span of the provided basis vectors."""
+        if not basis_vectors:
+            return domain.zero_operator(domain)
+
+        if orthonormalize:
+            e_vectors = domain.gram_schmidt(basis_vectors)
+        else:
+            e_vectors = basis_vectors
+
+        # P = sum (v_i x v_i)
+        tensor_op = LinearOperator.self_adjoint_from_tensor_product(domain, e_vectors)
+        return cls(domain, tensor_op)
+
+
+class AffineSubspace:
+    """
+    Represents an affine subspace A = x0 + V.
+    """
+
+    def __init__(
+        self,
+        projector: OrthogonalProjector,
+        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:
+            self._translation = projector.domain.zero
+        else:
+            if not projector.domain.is_element(translation):
+                raise ValueError("Translation vector not in domain.")
+            self._translation = translation
+
+        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
+
+    @property
+    def translation(self) -> Vector:
+        return self._translation
+
+    @property
+    def projector(self) -> OrthogonalProjector:
+        return self._projector
+
+    @property
+    def tangent_space(self) -> LinearSubspace:
+        return LinearSubspace(self._projector)
+
+    @property
+    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:
+            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:
+            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)
+        norm_x = self.domain.norm(x)
+        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,
+        operator: LinearOperator,
+        value: Vector,
+        solver: Optional[LinearSolver] = None,
+        preconditioner: Optional[LinearOperator] = None,
+    ) -> AffineSubspace:
+        """Constructs subspace from B(u)=w."""
+        domain = operator.domain
+        G = operator @ operator.adjoint
+
+        if solver is None:
+            solver = CholeskySolver(galerkin=True)
+
+        if isinstance(solver, IterativeLinearSolver):
+            G_inv = solver(G, preconditioner=preconditioner)
+        else:
+            G_inv = solver(G)
+
+        intermediate = G_inv(value)
+        translation = operator.adjoint(intermediate)
+        P_perp_op = operator.adjoint @ G_inv @ operator
+
+        def mapping(x: Any) -> Any:
+            return domain.subtract(x, P_perp_op(x))
+
+        projector = OrthogonalProjector(domain, mapping, complement_projector=P_perp_op)
+
+        return cls(
+            projector,
+            translation,
+            constraint_operator=operator,
+            constraint_value=value,
+            solver=solver,
+            preconditioner=preconditioner,
+        )
+
+    @classmethod
+    def from_tangent_basis(
+        cls,
+        domain: HilbertSpace,
+        basis_vectors: List[Vector],
+        translation: Optional[Vector] = None,
+        orthonormalize: bool = True,
+        solver: Optional[LinearSolver] = None,
+        preconditioner: Optional[LinearOperator] = None,
+    ) -> AffineSubspace:
+        """
+        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, solver=solver, preconditioner=preconditioner)
+
+    @classmethod
+    def from_complement_basis(
+        cls,
+        domain: HilbertSpace,
+        basis_vectors: List[Vector],
+        translation: Optional[Vector] = None,
+        orthonormalize: bool = True,
+    ) -> AffineSubspace:
+        """
+        Constructs subspace from complement basis.
+        Constraint is explicit: <u, e_i> = <x0, e_i>.
+        """
+        if orthonormalize:
+            e_vectors = domain.gram_schmidt(basis_vectors)
+        else:
+            e_vectors = basis_vectors
+
+        complement_projector = OrthogonalProjector.from_basis(
+            domain, e_vectors, orthonormalize=False
+        )
+
+        def mapping(x: Any) -> Any:
+            return domain.subtract(x, complement_projector(x))
+
+        projector = OrthogonalProjector(
+            domain, mapping, complement_projector=complement_projector
+        )
+
+        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:
+            res = domain.zero
+            for i, e in enumerate(e_vectors):
+                domain.axpy(c[i], e, res)
+            return res
+
+        B = LinearOperator(
+            domain, codomain, constraint_mapping, adjoint_mapping=constraint_adjoint
+        )
+
+        if translation is None:
+            _translation = domain.zero
+            w = codomain.zero
+        else:
+            _translation = translation
+            w = B(_translation)
+
+        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 the origin).
+    """
+
+    def __init__(self, projector: OrthogonalProjector) -> None:
+        super().__init__(projector, translation=None)
+
+    @property
+    def complement(self) -> LinearSubspace:
+        op_perp = self.projector.complement
+        if isinstance(op_perp, OrthogonalProjector):
+            return LinearSubspace(op_perp)
+        p_perp = OrthogonalProjector(self.domain, op_perp._mapping)
+        return LinearSubspace(p_perp)
+
+    @classmethod
+    def from_kernel(
+        cls,
+        operator: LinearOperator,
+        solver: Optional[LinearSolver] = None,
+        preconditioner: Optional[LinearOperator] = None,
+    ) -> LinearSubspace:
+        affine = AffineSubspace.from_linear_equation(
+            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
+    def from_basis(
+        cls,
+        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
+        )
+        instance = cls(projector)
+        instance._solver = solver
+        instance._preconditioner = preconditioner
+        return instance
+
+    @classmethod
+    def from_complement_basis(
+        cls,
+        domain: HilbertSpace,
+        basis_vectors: List[Vector],
+        orthonormalize: bool = True,
+    ) -> LinearSubspace:
+        affine = AffineSubspace.from_complement_basis(
+            domain, basis_vectors, translation=None, orthonormalize=orthonormalize
+        )
+        instance = cls(affine.projector)
+        instance._constraint_operator = affine.constraint_operator
+        instance._constraint_value = affine.constraint_value
+        instance._solver = affine._solver
+        return instance

pygeoinf/symmetric_space/sh_tools.py

@@ -0,0 +1,107 @@
+"""
+Module collecting some small helper functions or classes.
+"""
+
+from typing import Optional
+
+import numpy as np
+
+
+class SHVectorConverter:
+    """
+    Handles conversion between pyshtools 3D coefficient arrays and 1D vectors.
+
+    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.
+
+    **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 0.
+    """
+
+    def __init__(self, lmax: int, lmin: int = 0):
+        if not isinstance(lmax, int) or not isinstance(lmin, int):
+            raise TypeError("lmax and lmin must be integers.")
+        if lmin > lmax:
+            raise ValueError("lmin cannot be greater than lmax.")
+
+        self.lmax = lmax
+        self.lmin = lmin
+        self.vector_size = (self.lmax + 1) ** 2 - self.lmin**2
+
+    def to_vector(self, coeffs: np.ndarray) -> np.ndarray:
+        """Converts a pyshtools 3D coefficient array to a 1D vector.
+
+        If the input coefficients have a smaller lmax than the converter,
+        the missing high-degree coefficients in the output vector will be zero.
+
+        Args:
+            coeffs (np.ndarray): A pyshtools-compatible coefficient array
+                of shape (2, l_in+1, l_in+1).
+
+        Returns:
+            np.ndarray: A 1D vector of the coefficients from lmin to lmax.
+        """
+        lmax_in = coeffs.shape[1] - 1
+        vec = np.zeros(self.vector_size)
+        loop_lmax = min(self.lmax, lmax_in)
+
+        for l in range(self.lmin, loop_lmax + 1):
+            start_idx = l**2 - self.lmin**2
+            sin_part = coeffs[1, l, 1 : l + 1][::-1]
+            cos_part = coeffs[0, l, 0 : l + 1]
+            vec[start_idx : start_idx + l] = sin_part
+            vec[start_idx + l : start_idx + 2 * l + 1] = cos_part
+
+        return vec
+
+    def from_vector(
+        self, vec: np.ndarray, output_lmax: Optional[int] = None
+    ) -> np.ndarray:
+        """Converts a 1D vector back to a pyshtools 3D coefficient array.
+
+        This method can create an array that is larger (zero-padding) or
+        smaller (truncating) than the lmax of the converter.
+
+        Args:
+            vec (np.ndarray): A 1D vector of coefficients.
+            output_lmax (Optional[int]): The desired lmax for the output array.
+                If None, defaults to the converter's lmax.
+
+        Returns:
+            np.ndarray: A pyshtools-compatible coefficient array.
+        """
+        if vec.size != self.vector_size:
+            raise ValueError("Input vector has incorrect size.")
+
+        # If output_lmax is not specified, default to the converter's lmax
+        lmax_out = output_lmax if output_lmax is not None else self.lmax
+
+        # Create the output array of the desired size, initialized to zeros
+        coeffs = np.zeros((2, lmax_out + 1, lmax_out + 1))
+
+        # Determine the loop range: iterate up to the minimum of the two lmax values
+        loop_lmax = min(self.lmax, lmax_out)
+
+        for l in range(self.lmin, loop_lmax + 1):
+            start_idx = l**2 - self.lmin**2
+            coeffs[1, l, 1 : l + 1] = vec[start_idx : start_idx + l][::-1]
+            coeffs[0, l, 0 : l + 1] = vec[start_idx + l : start_idx + 2 * l + 1]
+
+        return coeffs

pygeoinf/symmetric_space/sphere.py

@@ -41,6 +41,7 @@ except ImportError:
     )
 
 from pygeoinf.hilbert_space import (
+    EuclideanSpace,
     HilbertModule,
     MassWeightedHilbertModule,
 )
@@ -50,12 +51,14 @@ from .symmetric_space import (
     AbstractInvariantLebesgueSpace,
     AbstractInvariantSobolevSpace,
 )
+from .sh_tools import SHVectorConverter
 
 
 if TYPE_CHECKING:
     from matplotlib.figure import Figure
     from cartopy.mpl.geoaxes import GeoAxes
     from cartopy.crs import Projection
+    from pyshtools import SHGrid
 
 
 class SphereHelper:
@@ -528,6 +531,87 @@ class Lebesgue(SphereHelper, HilbertModule, AbstractInvariantLebesgueSpace):
             f"extend={self.extend}"
         )
 
+    def to_coefficient_operator(self, lmax: int, lmin: int = 0):
+        r"""
+        Returns a LinearOperator mapping a function to its spherical harmonic coefficients.
+
+        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$.
+
+        **Ordering:**
+
+        .. 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]
+
+        (assuming `lmin=0`).
+
+        Args:
+            lmax: The maximum spherical harmonic degree to include in the output.
+            lmin: The minimum spherical harmonic degree to include. Defaults to 0.
+
+        Returns:
+            A LinearOperator mapping `SHGrid` -> `numpy.ndarray`.
+        """
+
+        converter = SHVectorConverter(lmax, lmin)
+        codomain = EuclideanSpace(converter.vector_size)
+
+        def mapping(u: SHGrid) -> np.ndarray:
+            ulm = self.to_coefficients(u)
+            return converter.to_vector(ulm.coeffs)
+
+        def adjoint_mapping(data: np.ndarray) -> SHGrid:
+            coeffs = converter.from_vector(data, output_lmax=self.lmax)
+            ulm = sh.SHCoeffs.from_array(
+                coeffs,
+                normalization=self.normalization,
+                csphase=self.csphase,
+            )
+            return self.from_coefficients(ulm) / self.radius**2
+
+        return LinearOperator(self, codomain, mapping, adjoint_mapping=adjoint_mapping)
+
+    def from_coefficient_operator(self, lmax: int, lmin: int = 0):
+        r"""
+        Returns a LinearOperator mapping a vector of coefficients to a function.
+
+        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.
+
+        **Ordering:**
+
+        .. 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 expected in the input.
+            lmin: The minimum spherical harmonic degree expected. Defaults to 0.
+
+        Returns:
+            A LinearOperator mapping `numpy.ndarray` -> `SHGrid`.
+        """
+
+        converter = SHVectorConverter(lmax, lmin)
+        domain = EuclideanSpace(converter.vector_size)
+
+        def mapping(data: np.ndarray) -> SHGrid:
+            coeffs = converter.from_vector(data, output_lmax=self.lmax)
+            ulm = sh.SHCoeffs.from_array(
+                coeffs,
+                normalization=self.normalization,
+                csphase=self.csphase,
+            )
+            return self.from_coefficients(ulm)
+
+        def adjoint_mapping(u: SHGrid) -> np.ndarray:
+            ulm = self.to_coefficients(u)
+            return converter.to_vector(ulm.coeffs) * self.radius**2
+
+        return LinearOperator(domain, self, mapping, adjoint_mapping=adjoint_mapping)
+
 
 class Sobolev(SphereHelper, MassWeightedHilbertModule, AbstractInvariantSobolevSpace):
     """
@@ -691,3 +775,58 @@ class Sobolev(SphereHelper, MassWeightedHilbertModule, AbstractInvariantSobolevS
             f"grid={self.grid}\n"
             f"extend={self.extend}"
         )
+
+    def to_coefficient_operator(self, lmax: int, lmin: int = 0):
+        r"""
+        Returns a LinearOperator mapping a function to its spherical harmonic coefficients.
+
+        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$.
+
+        **Ordering:**
+
+        .. 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]
+
+        (assuming `lmin=0`).
+
+        Args:
+            lmax: The maximum spherical harmonic degree to include in the output.
+            lmin: The minimum spherical harmonic degree to include. Defaults to 0.
+
+        Returns:
+            A LinearOperator mapping `SHGrid` -> `numpy.ndarray`.
+        """
+
+        l2_operator = self.underlying_space.to_coefficient_operator(lmax, lmin)
+
+        return LinearOperator.from_formal_adjoint(
+            self, l2_operator.codomain, l2_operator
+        )
+
+    def from_coefficient_operator(self, lmax: int, lmin: int = 0):
+        r"""
+        Returns a LinearOperator mapping a vector of coefficients to a function.
+
+        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.
+
+        **Ordering:**
+
+        .. 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 expected in the input.
+            lmin: The minimum spherical harmonic degree expected. Defaults to 0.
+
+        Returns:
+            A LinearOperator mapping `numpy.ndarray` -> `SHGrid`.
+        """
+
+        l2_operator = self.underlying_space.from_coefficient_operator(lmax, lmin)
+
+        return LinearOperator.from_formal_adjoint(l2_operator.domain, self, l2_operator)

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

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