pygeoinf 1.0.8__py3-none-any.whl → 1.1.0__py3-none-any.whl

pygeoinf/symmetric_space/symmetric_space.py

@@ -1,99 +1,71 @@
 """
-Module containing the base class for Sobolev spaces defined on symmetric spaces.
+Provides an abstract framework for function spaces on symmetric manifolds.
+
+This module offers a powerful abstract framework for defining Hilbert spaces of
+functions on symmetric spaces (like spheres or tori). The core design
+leverages the spectral properties of the Laplace-Beltrami operator (Δ), which
+is fundamental to the geometry of these spaces.
+
+By inheriting from these base classes and implementing a few key abstract
+methods (like the Laplacian eigenvalues), a concrete class can automatically
+gain a rich set of tools for defining invariant operators and probability
+measures. This is a cornerstone of fields like spatial statistics and
+geometric machine learning.
+
+Key Classes
+-----------
+AbstractInvariantLebesgueSpace
+    An abstract base class for L²-type spaces. It provides methods to construct
+    operators that are functions of the Laplacian (`f(Δ)`) and to build
+    statistically isotropic (rotationally-invariant) Gaussian measures.
+
+AbstractInvariantSobolevSpace
+    An abstract base class for Sobolev spaces (Hˢ). It extends the Lebesgue
+    functionality with features that require higher smoothness, most notably
+    point evaluation via Dirac delta functionals, which is essential for
+
+    connecting the abstract function space to discrete data points.
 """
 
 from __future__ import annotations
 from abc import ABC, abstractmethod
-from typing import Callable, Any, List, Optional
+from typing import Callable, Any, List
 import numpy as np
+from scipy.sparse import diags
 
-from pygeoinf.hilbert_space import HilbertSpace, EuclideanSpace
+from pygeoinf.hilbert_space import EuclideanSpace, HilbertSpace
 from pygeoinf.operators import LinearOperator
-from pygeoinf.forms import LinearForm
+from pygeoinf.linear_forms import LinearForm
 from pygeoinf.gaussian_measure import GaussianMeasure
 
 
-class SymmetricSpaceSobolev(HilbertSpace, ABC):
+class AbstractInvariantLebesgueSpace(ABC):
     """
-    An abstract base class for Sobolev spaces of scalar fields on a symmetric space.
+    An abstract base class for L² function spaces on symmetric manifolds.
 
-    This class provides a common interface for defining function spaces with spatial
-    correlation, typically used in applications like geostatistics and machine
-    learning on manifolds.
+    This ABC defines the interface for spaces of square-integrable functions.
+    It provides a powerful suite of methods for creating invariant
+    operators and Gaussian measures by leveraging the spectrum of the
+    Laplace-Beltrami operator.
     """
 
-    def __init__(
-        self,
-        order: float,
-        scale: float,
-        dim: int,
-        to_components: Callable[[Any], np.ndarray],
-        from_components: Callable[[np.ndarray], Any],
-        inner_product: Callable[[Any, Any], float],
-        to_dual: Callable[[Any], "LinearForm"],
-        from_dual: Callable[["LinearForm"], Any],
-        /,
-        *,
-        add: Optional[Callable[[T_vec, T_vec], T_vec]] = None,
-        subtract: Optional[Callable[[T_vec, T_vec], T_vec]] = None,
-        multiply: Optional[Callable[[float, T_vec], T_vec]] = None,
-        ax: Optional[Callable[[float, T_vec], None]] = None,
-        axpy: Optional[Callable[[float, T_vec, T_vec], None]] = None,
-        copy: Optional[Callable[[T_vec], T_vec]] = None,
-        vector_multiply: Optional[Callable[[T_vec, T_vec], T_vec]] = None,
-    ) -> None:
-        """
-        Args:
-            order: The order of the Sobolev space, related to its smoothness.
-            scale: The characteristic length scale of the Sobolev space.
-            dim: The dimension of the space, or of the finite-dimensional
-                approximating space.
-            to_components: A callable that maps vectors to their component arrays.
-            from_components: A callable that maps component arrays to vectors.
-            inner_product: A callable that implements the inner product on the space.
-            to_dual: A callable that maps a vector to the canonically
-                associated dual vector (a LinearForm).
-            from_dual: A callable that maps a dual vector back to its
-                primal representation in the space.
-            add: Custom implementation for vector addition.
-            subtract: Custom implementation for vector subtraction.
-            multiply: Custom implementation for scalar multiplication.
-            axpy: Custom implementation for the mapping `y -> a*x + y`.
-            copy: Custom implementation for a deep copy of a vector.
-            vector_multiply: Custom implementation for element-wise vector
-                multiplication.
-        """
-        self._order: float = order
-
-        if scale <= 0:
-            raise ValueError("Scale must be positive")
-        self._scale: float = scale
-
-        super().__init__(
-            dim,
-            to_components,
-            from_components,
-            inner_product,
-            to_dual,
-            from_dual,
-            add=add,
-            subtract=subtract,
-            multiply=multiply,
-            ax=ax,
-            axpy=axpy,
-            copy=copy,
-            vector_multiply=vector_multiply,
-        )
-
     @property
-    def order(self) -> float:
-        """The order of the Sobolev space, controlling smoothness."""
-        return self._order
+    @abstractmethod
+    def spatial_dimension(self):
+        """The dimension of the symetric space."""
 
     @property
-    def scale(self) -> float:
-        """The characteristic length scale of the Sobolev space."""
-        return self._scale
+    @abstractmethod
+    def dim(self):
+        """The dimension of the Hilbert space."""
+
+    @abstractmethod
+    def to_components(self, u: Any) -> np.ndarray:
+        """Maps a vector `u` to its real component representation."""
+
+    @abstractmethod
+    def from_components(self, c: np.ndarray) -> Any:
+        """Maps a real component vector back to a vector `u`."""
 
     @abstractmethod
     def random_point(self) -> Any:
@@ -109,7 +81,195 @@ class SymmetricSpaceSobolev(HilbertSpace, ABC):
         return [self.random_point() for _ in range(n)]
 
     @abstractmethod
-    def dirac(self, point: Any) -> "LinearForm":
+    def laplacian_eigenvalue(self, k: int | tuple[int, ...]) -> float:
+        """
+        Returns the eigenvalue of the Laplacian for a given mode index.
+
+        The index `k` can be a single integer (e.g., for a circle) or a
+        tuple of integers (e.g., for a sphere or torus), depending on the
+        geometry of the space.
+
+        Args:
+            k: The index of the eigenvalue to return.
+        """
+
+    @abstractmethod
+    def eigenfunction_norms(self) -> np.ndarray:
+        """Returns a list of the norms of the eigenfunctions."""
+
+    @abstractmethod
+    def invariant_automorphism(self, f: Callable[[float], float]) -> LinearOperator:
+        """
+        Returns an automorphism of the form f(Δ) with f a function
+        that is well-defined on the spectrum of the Laplacian, Δ.
+
+        In order to be well-defined, the function must have appropriate
+        growth properties. For example, in an L² space we need f to be bounded.
+        In Sobolev spaces Hˢ a more complex condition holds depending on the
+        Sobolev order. These conditions on the function are not checked.
+
+        Args:
+            f: A real-valued function that is well-defined on the spectrum
+               of the Laplacian.
+        """
+
+    @abstractmethod
+    def trace_of_invariant_automorphism(self, f: Callable[[float], float]) -> float:
+        """
+        Returns the trace of the automorphism of the form f(Δ) with f a function
+        that is well-defined on the spectrum of the Laplacian.
+
+        Args:
+            f: A real-valued function that is well-defined on the spectrum
+               of the Laplacian.
+        """
+
+    def invariant_gaussian_measure(
+        self,
+        f: Callable[[float], float],
+    ):
+        """
+        Returns a Gaussian measure with covariance of the form f(Δ).
+
+        The covariance operator of the resulting measure is `C = f(Δ)`, where `f`
+        is a function defined on the spectrum of the Laplacian. To be a valid
+        covariance, `f` must be non-negative.
+
+        Args:
+            f: A real-valued, non-negative function that is well-defined on the
+               spectrum of the Laplacian, Δ.
+
+        Notes:
+            The implementation assumes the basis for the HilbertSpace consists
+            of orthogonal eigenvectors of the Laplacian. The `component_mapping`
+            operator used internally handles the mapping from a standard normal
+            distribution in R^n to this (potentially non-normalized) eigenbasis.
+        """
+
+        values = self.eigenfunction_norms()
+        matrix = diags([np.reciprocal(values)], [0])
+        inverse_matrix = diags([values], [0])
+
+        def mapping(c: np.ndarray) -> np.ndarray:
+            return self.from_components(matrix @ c)
+
+        def adjoint_mapping(u: np.ndarray) -> np.ndarray:
+            c = self.to_components(u)
+            return inverse_matrix @ c
+
+        component_mapping = LinearOperator(
+            EuclideanSpace(self.dim), self, mapping, adjoint_mapping=adjoint_mapping
+        )
+        sqrt_covariance = self.invariant_automorphism(lambda k: np.sqrt(f(k)))
+
+        covariance_factor = sqrt_covariance @ component_mapping
+
+        return GaussianMeasure(covariance_factor=covariance_factor)
+
+    def norm_scaled_invariant_gaussian_measure(
+        self, f: Callable[[float], float], std: float = 1
+    ) -> GaussianMeasure:
+        """
+        Returns a Gaussian measure whose covariance is proportional to f(Δ) with
+        f a function that is well-defined on the spectrum of the Laplacian, Δ.
+
+        In order to be well-defined, f(Δ) must be trace class, with this implying
+        decay conditions on f whose form depends on the form of the symmetric space.
+        These conditions on the function are not checked.
+
+        The measure's covariance is scaled such that the expected value for the
+        samples norm is equal to the given standard deviation.
+
+        Args:
+            f: A real-valued function that is well-defined on the spectrum
+            of the Laplacian.
+            std: The desired standard deviation for the norm of samples.
+        """
+        mu = self.invariant_gaussian_measure(f)
+        tr = self.trace_of_invariant_automorphism(f)
+        return (std / np.sqrt(tr)) * mu
+
+    def sobolev_kernel_gaussian_measure(self, order: float, scale: float):
+        """
+        Returns an invariant Gaussian measure with a Sobolev-type covariance
+        equal to (1 + scale^2 * Δ)^-order.
+
+        Args:
+            order: Order parameter for the covariance.
+            scale: Scale parameter for the covariance.
+        """
+        return self.invariant_gaussian_measure(lambda k: (1 + scale**2 * k) ** (-order))
+
+    def norm_scaled_sobolev_kernel_gaussian_measure(
+        self, order: float, scale: float, std: float = 1
+    ):
+        """
+        Returns an invariant Gaussian measure with a Sobolev-type covariance
+        proportional to (1 + scale^2 * Δ)^-order.
+
+        The measure's covariance is scaled such that the expected value for the
+        samples norm is equal to the given standard deviation.
+
+        Args:
+            order: Order parameter for the covariance.
+            scale: Scale parameter for the covariance.
+            std: The desired standard deviation for the norm of samples.
+        """
+        return self.norm_scaled_invariant_gaussian_measure(
+            lambda k: (1 + scale**2 * k) ** -order, std
+        )
+
+    def heat_kernel_gaussian_measure(self, scale: float):
+        """
+        Returns an invariant Gaussian measure with a heat kernel covariance
+        equal to exp(-scale^2 * Δ).
+
+        Args:
+            scale: Scale parameter for the covariance.
+        """
+        return self.invariant_gaussian_measure(lambda k: np.exp(-(scale**2) * k))
+
+    def norm_scaled_heat_kernel_gaussian_measure(self, scale: float, std: float = 1):
+        """
+        Returns an invariant Gaussian measure with a heat kernel covariance
+        proportional to exp(-scale^2 * Δ).
+
+        The measure's covariance is scaled such that the expected value for the
+        samples norm is equal to the given standard deviation.
+
+        Args:
+            scale: Scale parameter for the covariance.
+            std: The desired standard deviation for the norm of samples.
+        """
+        return self.norm_scaled_invariant_gaussian_measure(
+            lambda k: np.exp(-(scale**2) * k), std
+        )
+
+
+class AbstractInvariantSobolevSpace(AbstractInvariantLebesgueSpace):
+    """
+    An ABC for Sobolev spaces (Hˢ) on symmetric manifolds.
+
+    This class extends the Lebesgue space functionality to spaces of functions
+    with a specified degree of smoothness (`order`). The primary motivation for
+    using a Sobolev space is that for a sufficiently high order, point-wise
+    evaluation of a function is a well-defined operation. This is critical for
+    linking abstract function fields to discrete data points.
+    """
+
+    def __init__(self, order: float, scale: float):
+        """
+        Args:
+            spatial_dimension: The dimension of the space.
+            order: The Sobolev order.
+            scale: The Sobolev length-scale.
+        """
+
+        self._order: float = order
+        self._scale: float = scale
+
+    @abstractmethod
+    def dirac(self, point: Any) -> LinearForm:
         """
         Returns the linear functional corresponding to a point evaluation.
 
@@ -118,8 +278,36 @@ class SymmetricSpaceSobolev(HilbertSpace, ABC):
 
         Args:
             point: The point on the symmetric space at which to base the functional.
+
+        Raises:
+            NotImplementedError: If the Sobolev order is less than n/2, with n the spatial dimension.
         """
 
+    @abstractmethod
+    def __eq__(self, other: object) -> bool:
+        """
+        Checks for mathematical equality with another Sobolev space.
+
+        Two spaces are considered equal if they are of the same type and have
+        the same defining parameters.
+        """
+
+    @property
+    def order(self) -> float:
+        """The Sobolev order."""
+        return self._order
+
+    @property
+    def scale(self) -> float:
+        """The Sobolev length-scale."""
+        return self._scale
+
+    def sobolev_function(self, k: float) -> float:
+        """
+        Implementation of the relevant Sobolev function for the space.
+        """
+        return (1 + self.scale**2 * k) ** self.order
+
     def dirac_representation(self, point: Any) -> Any:
         """
 
@@ -130,19 +318,28 @@ class SymmetricSpaceSobolev(HilbertSpace, ABC):
 
         Args:
             point: The point on the symmetric space.
+
+        Raises:
+            NotImplementedError: If the Sobolev order is less than n/2, with n the spatial dimension.
         """
         return self.from_dual(self.dirac(point))
 
-    def point_evaluation_operator(self, points: List[Any]) -> "LinearOperator":
+    def point_evaluation_operator(self, points: List[Any]) -> LinearOperator:
         """
         Returns a linear operator that evaluates a function at a list of points.
 
         The resulting operator maps a function (a vector in this space) to a
-        vector in Euclidean space containing the function's values.
+        vector in Euclidean space containing the function's values at the
+        specified locations. This is the primary mechanism for creating a
+        forward operator that links a function field to a set of discrete
+        measurements.
 
         Args:
             points: A list of points at which to evaluate the functions.
         """
+        if self.order <= self.spatial_dimension / 2:
+            raise NotImplementedError("Order must be greater than n/2")
+
         dim = len(points)
         matrix = np.zeros((dim, self.dim))
 
@@ -154,90 +351,81 @@ class SymmetricSpaceSobolev(HilbertSpace, ABC):
             self, EuclideanSpace(dim), matrix, galerkin=True
         )
 
-    @abstractmethod
-    def invariant_automorphism(self, f: Callable[[float], float]) -> "LinearOperator":
+    def invariant_automorphism(self, f: Callable[[float], float]):
         """
-        Returns an automorphism of the form `f(Delta)` where `Delta` is the Laplacian.
-
-        This uses functional calculus on the Laplace-Beltrami operator to create
-        operators that are invariant to the symmetries of the space.
+        Returns an invariant automorphism of the form f(Δ) making use of the equivalent
+        operator on the underlying Lebesgue space.
 
         Args:
-            f: A scalar function to apply to the eigenvalues of the Laplacian.
+            f: A real-valued function that is well-defined on the spectrum
+               of the Laplacian, Δ.
         """
+        A = self.underlying_space.invariant_automorphism(f)
+        return LinearOperator.from_formally_self_adjoint(self, A)
 
-    @abstractmethod
-    def invariant_gaussian_measure(
-        self, f: Callable[[float], float], /, *, expectation: Optional[Any] = None
-    ) -> "GaussianMeasure":
+    def point_value_scaled_invariant_gaussian_measure(
+        self, f: Callable[[float], float], amplitude: float = 1
+    ):
         """
-        Returns a Gaussian measure with a covariance of the form `f(Delta)`.
+        Returns an invariant Gaussian measure with covariance proportional to f(Δ),
+        where f must be such that this operator is trace-class.
 
-        The covariance operator is defined via functional calculus on the Laplacian,
-        ensuring the resulting measure is statistically invariant under the
-        symmetries of the space.
+        The covariance of the operator is scaled such that the standard deviation
+        of the point-wise values are equal to the given amplitude.
 
         Args:
-            f: The scalar function defining the covariance operator.
-            expectation: The mean of the measure. Defaults to zero.
-        """
+            f: A real-valued function that is well-defined on the spectrum
+               of the Laplacian, Δ.
+            amplitude: The desired standard deviation for the pointwise values.
 
-    def _transform_measure(
-        self, amplitude: float, expectation: Optional[Any], mu: "GaussianMeasure"
-    ) -> "GaussianMeasure":
-        """
-        Scales an invariant measure to match a target pointwise standard deviation.
+        Raises:
+            NotImplementedError: If the Sobolev order is less than n/2, with n the spatial dimension.
 
-        Note:
-            This method assumes statistical homogeneity; it calculates the current
-            variance at a single random point and scales accordingly. The result
-            may vary slightly on each call due to this randomness.
+        Notes:
+            This method applies for symmetric spaces an invariant measures. As a result, the
+            pointwise variance is the same at all points. Internally, a random point is chosen
+            to carry out the normalisation.
         """
-        Q = mu.covariance
-        u = self.dirac_representation(self.random_point())
-        var = self.inner_product(Q(u), u)
-        # Handle the case where variance is zero to avoid division errors
-        if var > 0:
-            mu *= amplitude / np.sqrt(var)
-        return mu.affine_mapping(translation=expectation)
-
-    def sobolev_gaussian_measure(
-        self,
-        order: float,
-        scale: float,
-        amplitude: float,
-        /,
-        *,
-        expectation: Optional[Any] = None,
-    ) -> "GaussianMeasure":
+        point = self.random_point()
+        u = self.dirac_representation(point)
+        mu = self.invariant_gaussian_measure(f)
+        cov = mu.covariance
+        var = self.inner_product(cov(u), u)
+        return (amplitude / np.sqrt(var)) * mu
+
+    def point_value_scaled_sobolev_kernel_gaussian_measure(
+        self, order: float, scale: float, amplitude: float = 1
+    ):
         """
-        Returns an invariant Gaussian measure with a Sobolev-type covariance.
+        Returns an invariant Gaussian measure with a Sobolev-type covariance
+        proportional to (1 + scale^2 * Δ)^-order.
 
-        The covariance operator is `C = (1 + scale^2 * Delta)^-order`, which is
-        commonly used to generate spatially correlated random fields.
+        The covariance of the operator is scaled such that the standard deviation
+        of the point-wise values are equal to the given amplitude.
 
         Args:
             order: Order parameter for the covariance.
             scale: Scale parameter for the covariance.
-            amplitude: The target pointwise standard deviation of the field.
-            expectation: The expectation (mean field). Defaults to zero.
+            amplitude: The desired standard deviation for the pointwise values.
         """
-        mu = self.invariant_gaussian_measure(lambda k: (1 + scale**2 * k) ** -order)
-        return self._transform_measure(amplitude, expectation, mu)
+        return self.point_value_scaled_invariant_gaussian_measure(
+            lambda k: (1 + scale**2 * k) ** -order, amplitude
+        )
 
-    def heat_gaussian_measure(
-        self, scale: float, amplitude: float, /, *, expectation: Optional[Any] = None
-    ) -> "GaussianMeasure":
+    def point_value_scaled_heat_kernel_gaussian_measure(
+        self, scale: float, amplitude: float = 1
+    ):
         """
-        Returns an invariant Gaussian measure with a heat kernel covariance.
+        Returns an invariant Gaussian measure with a heat-kernel covariance
+        proportional to exp(-scale^2 * Δ).
 
-        The covariance operator is `C = exp(-scale^2 * Delta)`, which corresponds
-        to the squared-exponential or Gaussian kernel.
+        The covariance of the operator is scaled such that the standard deviation
+        of the point-wise values are equal to the given amplitude.
 
         Args:
             scale: Scale parameter for the covariance.
-            amplitude: The target pointwise standard deviation of the field.
-            expectation: The expectation (mean field). Defaults to zero.
+            amplitude: The desired standard deviation for the pointwise values.
         """
-        mu = self.invariant_gaussian_measure(lambda k: np.exp(-(scale**2) * k))
-        return self._transform_measure(amplitude, expectation, mu)
+        return self.point_value_scaled_invariant_gaussian_measure(
+            lambda k: np.exp(-(scale**2) * k), amplitude
+        )

{pygeoinf-1.0.8.dist-info → pygeoinf-1.1.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: pygeoinf
-Version: 1.0.8
+Version: 1.1.0
 Summary: A package for solving geophysical inference and inverse problems
 License: BSD-3-Clause
 Author: David Al-Attar and Dan Heathcote

pygeoinf-1.1.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+pygeoinf/__init__.py,sha256=uYRwiHKi4nvzUBwQJxNdt8OZodFQ_nj5rUv2YkDXL9Q,1185
+pygeoinf/direct_sum.py,sha256=r0h-3bK6RQiOMoq086oupYaXgUM4pFIV8XNKOB2q9BE,17095
+pygeoinf/forward_problem.py,sha256=RnnVBMg8Ih7TqZylfSkQ7pdHEowEfCkTiXiKFrxBpnM,9754
+pygeoinf/gaussian_measure.py,sha256=SFnHmEjpcrUy09AfO3fXLLB_SaGwA9oc5PU630e3hNM,22826
+pygeoinf/hilbert_space.py,sha256=42RSYoIPf0hruyysBVoeJGmsmDtTrpaet5YMZnxwgys,22429
+pygeoinf/inversion.py,sha256=p9k_iDVgJGLM1cGlT-0rgRwqdYVdsYC_euTXZk3kuOc,3199
+pygeoinf/linear_bayesian.py,sha256=aIOzTZbjJtdtwHKh5e01iS8iMiyr8XuwGx91udS3VK4,9624
+pygeoinf/linear_forms.py,sha256=Uizipi67i1Sd6m0TzsrJd99Xreo_6V8Db0gMy76fG6g,5953
+pygeoinf/linear_optimisation.py,sha256=7lklTRRBGkz8M9WsfvkDl-eoGkc4Ty7BOJq7LWkdxCg,11091
+pygeoinf/linear_solvers.py,sha256=P9SEjZ1LZdulr2KQrZojbvdCtAm--hMd4EArSu73L34,12154
+pygeoinf/operators.py,sha256=JPDrdLSnM-Y5_CWJ58WDvHBzo3hPoFoUoAOS63QFJmc,32272
+pygeoinf/random_matrix.py,sha256=_XVwXqM_c0SMpy6JU-8IboXpotug6dDDHKdSPAJpH7c,7788
+pygeoinf/symmetric_space/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pygeoinf/symmetric_space/circle.py,sha256=0EHPg2FcvWTOvCb8ualCW0uUp8RuUNfQ7oK6NHXtG1Q,17552
+pygeoinf/symmetric_space/sphere.py,sha256=vKwvTa-9GMNlN-LBUWaEsZ8vM-dZtQtT71UPDSXZufY,20309
+pygeoinf/symmetric_space/symmetric_space.py,sha256=YkRjHucc2cO7IAoyJS5KMdiRBuytRpUfTUsVMHBPZYs,16146
+pygeoinf-1.1.0.dist-info/LICENSE,sha256=GrTQnKJemVi69FSbHprq60KN0OJGsOSR-joQoTq-oD8,1501
+pygeoinf-1.1.0.dist-info/METADATA,sha256=r9MgMBiluq7IGB0ts7Nxxsz1bAeL5tOE2iYskaWvWe8,14375
+pygeoinf-1.1.0.dist-info/WHEEL,sha256=IYZQI976HJqqOpQU6PHkJ8fb3tMNBFjg-Cn-pwAbaFM,88
+pygeoinf-1.1.0.dist-info/RECORD,,