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

pygeoinf/symmetric_space/sphere.py

@@ -1,5 +1,24 @@
 """
-Module for Sobolev spaces on the two-sphere.
+Provides concrete implementations of function spaces on the two-sphere (S²).
+
+This module uses the abstract framework from the symmetric space module to create
+fully-featured `Lebesgue` (L²) and `Sobolev` (Hˢ) Hilbert spaces for functions
+defined on the surface of a sphere.
+
+It utilizes the `pyshtools` library for highly efficient and accurate spherical
+harmonic transforms. Following a compositional design, this module first
+defines a base `Lebesgue` space and then constructs the `Sobolev` space as a
+`MassWeightedHilbertSpace` over it. The module also includes powerful plotting
+utilities built on `cartopy` for professional-quality geospatial visualization.
+
+Key Classes
+-----------
+- `SphereHelper`: A mixin class providing the core geometry, spherical harmonic
+  transform machinery, and `cartopy`-based plotting utilities.
+- `Lebesgue`: A concrete implementation of the L²(S²) space of square-integrable
+  functions on the sphere.
+- `Sobolev`: A concrete implementation of the Hˢ(S²) space of functions with a
+  specified degree of smoothness.
 """
 
 from __future__ import annotations
@@ -7,185 +26,83 @@ from typing import Callable, Any, List, Optional, Tuple, TYPE_CHECKING
 
 import matplotlib.pyplot as plt
 import matplotlib.ticker as mticker
-
 import numpy as np
-
 from scipy.sparse import diags, coo_array
 
 import pyshtools as sh
-
 import cartopy.crs as ccrs
 import cartopy.feature as cfeature
 from cartopy.mpl.ticker import LongitudeFormatter, LatitudeFormatter
 
-from pygeoinf.hilbert_space import EuclideanSpace
+from pygeoinf.hilbert_space import (
+    HilbertModule,
+    MassWeightedHilbertModule,
+)
 from pygeoinf.operators import LinearOperator
-from pygeoinf.symmetric_space.symmetric_space import SymmetricSpaceSobolev
-from pygeoinf.gaussian_measure import GaussianMeasure
+from pygeoinf.linear_forms import LinearForm
+from .symmetric_space import (
+    AbstractInvariantLebesgueSpace,
+    AbstractInvariantSobolevSpace,
+)
+
 
-# This block only runs for type checkers, not at runtime
 if TYPE_CHECKING:
     from matplotlib.figure import Figure
-    from matplotlib.axes import Axes
     from cartopy.mpl.geoaxes import GeoAxes
     from cartopy.crs import Projection
-    from pygeoinf.forms import LinearForm
 
 
-class Sobolev(SymmetricSpaceSobolev):
+class SphereHelper:
     """
-    Implements Sobolev spaces H^s on a two-sphere.
+    A mixin providing common functionality for function spaces on the sphere.
 
-    This class uses `pyshtools` for spherical harmonic transforms. Vectors in the
-    space can be represented either as `pyshtools.SHGrid` objects (spatial
-    domain) or `pyshtools.SHCoeffs` objects (spectral domain), controlled by a flag.
+    This helper is not intended for direct instantiation. It provides the core
+    geometry (radius, grid type), the spherical harmonic transform machinery via
+    `pyshtools`, and `cartopy`-based plotting utilities that are shared by the
+    `Lebesgue` and `Sobolev` space classes.
     """
 
     def __init__(
         self,
         lmax: int,
-        order: float,
-        scale: float,
-        /,
-        *,
-        vector_as_SHGrid: bool = True,
-        radius: float = 1.0,
-        grid: str = "DH",
-    ) -> None:
+        radius: float,
+        grid: str,
+        extend: bool,
+    ):
         """
         Args:
-            lmax: The maximum spherical harmonic degree for truncation.
-            order: The order of the Sobolev space, controlling smoothness.
-            scale: The non-dimensional length-scale for the space.
-            vector_as_SHGrid: If True (default), elements of the space are
-                `pyshtools.SHGrid` objects. Otherwise, they are `pyshtools.SHCoeffs`.
-            radius: The radius of the sphere. Defaults to 1.0.
-            grid: The `pyshtools` grid type (e.g., 'DH', 'DH2', 'GLQ').
-                Defaults to 'DH'.
+            lmax: The maximum spherical harmonic degree to be represented.
+            radius: Radius of the sphere.
+            grid: The `pyshtools` grid type.
+            extend: If True, the spatial grid includes both 0 and 360-degree longitudes.
         """
-
         self._lmax: int = lmax
         self._radius: float = radius
-        self._grid: str = grid
-        self._sampling: int = 2 if self.grid == "DH2" else 1
-        self._extend: bool = True
-        self._normalization: str = "ortho"
-        self._csphase: int = 1
-        self._sparse_coeffs_to_component: coo_array = (
-            self._coefficient_to_component_mapping()
-        )
 
-        dim: int = (lmax + 1) ** 2
-
-        self._vector_as_SHGrid: bool = vector_as_SHGrid
-        if vector_as_SHGrid:
-            super().__init__(
-                order,
-                scale,
-                dim,
-                self._to_components_from_SHGrid,
-                self._from_components_to_SHGrid,
-                self._inner_product_impl,
-                self._to_dual_impl,
-                self._from_dual_impl,
-                ax=self._ax_impl,
-                axpy=self._axpy_impl,
-                vector_multiply=self._vector_multiply_impl,
-            )
+        if grid == "DH2":
+            self._grid = "DH"
+            self._sampling = 2
         else:
-            super().__init__(
-                order,
-                scale,
-                dim,
-                self._to_components_from_SHCoeffs,
-                self._from_components_to_SHCoeffs,
-                self._inner_product_impl,
-                self._to_dual_impl,
-                self._from_dual_impl,
-                ax=self._ax_impl,
-                axpy=self._axpy_impl,
-                vector_multiply=self._vector_multiply_impl,
-            )
-
-        self._metric_tensor: diags = self._degree_dependent_scaling_to_diagonal_matrix(
-            self._sobolev_function
-        )
-        self._inverse_metric_tensor: diags = (
-            self._degree_dependent_scaling_to_diagonal_matrix(
-                lambda l: 1.0 / self._sobolev_function(l)
-            )
-        )
-
-    # ===============================================#
-    #                  Static methods                #
-    # ===============================================#
-
-    @staticmethod
-    def from_sobolev_parameters(
-        order: float,
-        scale: float,
-        /,
-        *,
-        radius: float = 1.0,
-        vector_as_SHGrid: bool = True,
-        grid: str = "DH",
-        rtol: float = 1e-8,
-        power_of_two: bool = False,
-    ) -> "Sobolev":
-        """
-        Creates an instance with `lmax` chosen based on the Sobolev parameters.
-
-        This factory method estimates the spherical harmonic truncation degree
-        (`lmax`) required to represent the space while meeting a specified
-        relative tolerance for the truncation error. This is useful when the
-        required `lmax` is not known a priori.
-
-        Args:
-            order: The order of the Sobolev space, controlling smoothness.
-            scale: The non-dimensional length-scale for the space.
-            radius: The radius of the sphere. Defaults to 1.0.
-            vector_as_SHGrid: If True (default), elements are `SHGrid` objects.
-            grid: The `pyshtools` grid type (e.g., 'DH'). Defaults to 'DH'.
-            rtol: The relative tolerance used to determine the `lmax`.
-            power_of_two: If True, `lmax` is set to the next power of two.
-
-        Returns:
-            An instance of the Sobolev class with a calculated `lmax`.
-        """
-        if order <= 1.0:
-            raise ValueError("This method is only applicable for orders > 1.0")
+            self._grid = grid
+            self._sampling = 1
 
-        summation = 1.0
-        l = 0
-        err = 1.0
-        sobolev_func = lambda deg: (1.0 + scale**2 * deg * (deg + 1)) ** order
+        self._extend: bool = extend
 
-        while err > rtol:
-            l += 1
-            term = (2 * l + 1) / sobolev_func(l)
-            summation += term
-            err = term / summation
-            print(l, err)
-            if l > 10000:
-                raise RuntimeError("Failed to converge on a stable lmax.")
-
-        if power_of_two:
-            n = int(np.log2(l))
-            l = 2 ** (n + 1)
+        # SH coefficient options fixed internally
+        self._normalization: str = "ortho"
+        self._csphase: int = 1
 
-        lmax = l
-        return Sobolev(
-            lmax,
-            order,
-            scale,
-            vector_as_SHGrid=vector_as_SHGrid,
-            radius=radius,
-            grid=grid,
+        # Set up sparse matrix that maps SHCoeff data arrrays into reduced form
+        self._sparse_coeffs_to_component: coo_array = (
+            self._coefficient_to_component_mapping()
         )
 
-    # ===============================================#
-    #                   Properties                  #
-    # ===============================================#
+    def orthonormalised(self) -> bool:
+        """The space is orthonormalised."""
+        return True
+
+    def _space(self):
+        return self
 
     @property
     def lmax(self) -> int:
@@ -202,6 +119,11 @@ class Sobolev(SymmetricSpaceSobolev):
         """The `pyshtools` grid type used for spatial representations."""
         return self._grid
 
+    @property
+    def sampling(self) -> int:
+        """The sampling factor used for spatial representations."""
+        return self._sampling
+
     @property
     def extend(self) -> bool:
         """True if the spatial grid includes both 0 and 360-degree longitudes."""
@@ -217,181 +139,70 @@ class Sobolev(SymmetricSpaceSobolev):
         """The Condon-Shortley phase convention used (1)."""
         return self._csphase
 
-    # ==============================================#
-    #                 Public methods                #
-    # ==============================================#
+    @property
+    def spatial_dimension(self) -> int:
+        """The dimension of the space."""
+        return 2
 
     def random_point(self) -> List[float]:
         """Returns a random point as `[latitude, longitude]`."""
-        latitude = np.random.uniform(-90.0, 90.0)
+        latitude = np.rad2deg(np.arcsin(np.random.uniform(-1.0, 1.0)))
         longitude = np.random.uniform(0.0, 360.0)
         return [latitude, longitude]
 
-    def low_degree_projection(
-        self,
-        truncation_degree: int,
-        /,
-        *,
-        smoother: Optional[Callable[[int], float]] = None,
-    ) -> "LinearOperator":
+    def laplacian_eigenvalue(self, k: [int, int]) -> float:
         """
-        Returns an operator that projects onto a lower-degree space.
-
-        This can be used for truncating or smoothing a field in the spherical
-        harmonic domain.
+        Returns the (l.m)-th eigenvalue of the Laplacian.
 
         Args:
-            truncation_degree: The new maximum degree `lmax`.
-            smoother: An optional callable `f(l)` that applies a degree-dependent
-                weighting factor during projection.
-
-        Returns:
-            A `LinearOperator` that maps from this space to a new, lower-degree
-            `Sobolev` space.
+            k = (l,m): The index of the eigenvalue to return.
         """
-        truncation_degree = (
-            truncation_degree if truncation_degree <= self.lmax else self.lmax
-        )
-        # Default smoother is an identity mapping.
-        f: Callable[[int], float] = smoother if smoother is not None else lambda l: 1.0
-
-        row_dim = (truncation_degree + 1) ** 2
-        col_dim = (self.lmax + 1) ** 2
-
-        # Construct the sparse matrix that performs the coordinate projection.
-        row, col = 0, 0
-        rows, cols, data = [], [], []
-        for l in range(self.lmax + 1):
-            fac = f(l)
-            for _ in range(l + 1):
-                if l <= truncation_degree:
-                    rows.append(row)
-                    row += 1
-                    cols.append(col)
-                    data.append(fac)
-                col += 1
-
-        for l in range(truncation_degree + 1):
-            fac = f(l)
-            for _ in range(1, l + 1):
-                rows.append(row)
-                row += 1
-                cols.append(col)
-                data.append(fac)
-                col += 1
-
-        smat = coo_array(
-            (data, (rows, cols)), shape=(row_dim, col_dim), dtype=float
-        ).tocsc()
-
-        codomain = Sobolev(
-            truncation_degree,
-            self.order,
-            self.scale,
-            vector_as_SHGrid=self._vector_as_SHGrid,
-            radius=self.radius,
-            grid=self._grid,
-        )
-
-        def mapping(u: Any) -> Any:
-            uc = self.to_components(u)
-            vc = smat @ uc
-            return codomain.from_components(vc)
-
-        def adjoint_mapping(v: Any) -> Any:
-            vc = codomain.to_components(v)
-            uc = smat.T @ vc
-            return self.from_components(uc)
+        l = k[0]
+        return l * (l + 1) / self.radius**2
 
-        return LinearOperator(self, codomain, mapping, adjoint_mapping=adjoint_mapping)
-
-    def dirac(self, point: List[float]) -> "LinearForm":
+    def trace_of_invariant_automorphism(self, f: Callable[[float], float]) -> float:
         """
-        Returns the linear functional for point evaluation (Dirac measure).
+        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:
-            point: A list containing `[latitude, longitude]`.
+            f: A real-valued function that is well-defined on the spectrum
+               of the Laplacian.
         """
-        latitude, longitude = point
-        colatitude = 90.0 - latitude
-
-        coeffs = sh.expand.spharm(
-            self.lmax,
-            colatitude,
-            longitude,
-            normalization=self.normalization,
-            degrees=True,
-        )
-        c = self._to_components_from_coeffs(coeffs)
-        # Note: The user confirmed the logic for this return statement is correct
-        # for their use case, despite the base class returning a LinearForm.
-        return self.dual.from_components(c)
-
-    def invariant_automorphism(self, f: Callable[[float], float]) -> "LinearOperator":
-        matrix = self._degree_dependent_scaling_to_diagonal_matrix(f)
-
-        def mapping(x: Any) -> Any:
-            return self.from_components(matrix @ self.to_components(x))
-
-        return LinearOperator.self_adjoint(self, mapping)
+        trace = 0
+        for l in range(self.lmax + 1):
+            for m in range(-l, l + 1):
+                trace += f(self.laplacian_eigenvalue((l, m)))
+        return trace
 
-    def invariant_gaussian_measure(
-        self, f: Callable[[float], float], /, *, expectation: Optional[Any] = None
-    ) -> "GaussianMeasure":
+    def project_function(self, f: Callable[[(float, float)], float]) -> np.ndarray:
         """
-        Returns a Gaussian measure with a covariance of the form `f(Delta)`.
+        Returns an element of the space by projecting a given function.
 
         Args:
-            f: The scalar function `f(l(l+1))` defining the covariance.
-            expectation: The mean of the measure. Defaults to zero.
+            f: A function that takes a point `(lat, lon)` and returns a value.
         """
-
-        def g(l: int) -> float:
-            return np.sqrt(f(l) / (self.radius**2 * self._sobolev_function(l)))
-
-        def h(l: int) -> float:
-            return np.sqrt(self.radius**2 * self._sobolev_function(l) * f(l))
-
-        matrix = self._degree_dependent_scaling_to_diagonal_matrix(g)
-        adjoint_matrix = self._degree_dependent_scaling_to_diagonal_matrix(h)
-        domain = EuclideanSpace(self.dim)
-
-        def mapping(c: np.ndarray) -> Any:
-            return self.from_components(matrix @ c)
-
-        def adjoint_mapping(u: Any) -> np.ndarray:
-            return adjoint_matrix @ self.to_components(u)
-
-        inverse_matrix = self._degree_dependent_scaling_to_diagonal_matrix(
-            lambda l: 1.0 / g(l)
-        )
-        inverse_adjoint_matrix = self._degree_dependent_scaling_to_diagonal_matrix(
-            lambda l: 1.0 / h(l)
+        u = sh.SHGrid.from_zeros(
+            self.lmax, grid=self.grid, extend=self.extend, sampling=self._sampling
         )
+        for j, lon in enumerate(u.lons()):
+            for i, lat in enumerate(u.lats()):
+                u.data[i, j] = f((lat, lon))
 
-        def inverse_mapping(u: Any) -> np.ndarray:
-            return inverse_matrix @ self.to_components(u)
+        return u
 
-        def inverse_adjoint_mapping(c: np.ndarray) -> Any:
-            # Note: This is a formal adjoint mapping.
-            return self.from_components(inverse_adjoint_matrix @ c)
+    def to_coefficient(self, u: sh.SHGrid) -> sh.SHCoeffs:
+        """Maps a function vector to its spherical harmonic coefficients."""
+        return u.expand(normalization=self.normalization, csphase=self.csphase)
 
-        covariance_factor = LinearOperator(
-            domain, self, mapping, adjoint_mapping=adjoint_mapping
-        )
-        inverse_covariance_factor = LinearOperator(
-            self, domain, inverse_mapping, adjoint_mapping=inverse_adjoint_mapping
-        )
-
-        return GaussianMeasure(
-            covariance_factor=covariance_factor,
-            inverse_covariance_factor=inverse_covariance_factor,
-            expectation=expectation,
-        )
+    def from_coefficient(self, ulm: sh.SHCoeffs) -> sh.SHGrid:
+        """Maps spherical harmonic coefficients to a function vector."""
+        grid = self.grid if self._sampling == 1 else "DH2"
+        return ulm.expand(grid=grid, extend=self.extend)
 
     def plot(
         self,
-        f: Any,
+        u: sh.SHGrid,
         /,
         *,
         projection: "Projection" = ccrs.PlateCarree(),
@@ -409,7 +220,7 @@ class Sobolev(SymmetricSpaceSobolev):
         Creates a map plot of a function on the sphere using `cartopy`.
 
         Args:
-            f: The function to be plotted (either an `SHGrid` or `SHCoeffs` object).
+            u: The element to be plotted.
             projection: A `cartopy.crs` projection. Defaults to `PlateCarree`.
             contour: If True, creates a filled contour plot. Otherwise, a `pcolormesh` plot.
             cmap: The colormap name.
@@ -425,14 +236,9 @@ class Sobolev(SymmetricSpaceSobolev):
         Returns:
             A tuple `(figure, axes, image)` containing the Matplotlib and Cartopy objects.
         """
-        field: sh.SHGrid = (
-            f
-            if self._vector_as_SHGrid
-            else f.expand(normalization=self.normalization, csphase=self.csphase)
-        )
 
-        lons = field.lons()
-        lats = field.lats()
+        lons = u.lons()
+        lats = u.lats()
 
         figsize: Tuple[int, int] = kwargs.pop("figsize", (10, 8))
         fig, ax = plt.subplots(figsize=figsize, subplot_kw={"projection": projection})
@@ -448,7 +254,7 @@ class Sobolev(SymmetricSpaceSobolev):
 
         kwargs.setdefault("cmap", cmap)
         if symmetric:
-            data_max = 1.2 * np.nanmax(np.abs(f.data))
+            data_max = 1.2 * np.nanmax(np.abs(u.data))
             kwargs.setdefault("vmin", -data_max)
             kwargs.setdefault("vmax", data_max)
 
@@ -458,14 +264,14 @@ class Sobolev(SymmetricSpaceSobolev):
             im = ax.contourf(
                 lons,
                 lats,
-                field.data,
+                u.data,
                 transform=ccrs.PlateCarree(),
                 levels=levels,
                 **kwargs,
             )
         else:
             im = ax.pcolormesh(
-                lons, lats, field.data, transform=ccrs.PlateCarree(), **kwargs
+                lons, lats, u.data, transform=ccrs.PlateCarree(), **kwargs
             )
 
         if gridlines:
@@ -485,28 +291,12 @@ class Sobolev(SymmetricSpaceSobolev):
 
         return fig, ax, im
 
-    def __eq__(self, other: object) -> bool:
-        """
-        Checks for mathematical equality with another Sobolev space on a sphere.
+    # --------------------------------------------------------------- #
+    #                         private methods                         #
+    # ----------------------------------------------------------------#
 
-        Two spaces are considered equal if they are of the same type and have
-        the same defining parameters.
-        """
-        if not isinstance(other, Sobolev):
-            return NotImplemented
-
-        return (
-            self.lmax == other.lmax
-            and self.order == other.order
-            and self.scale == other.scale
-            and self.radius == other.radius
-            and self.grid == other.grid
-            and self._vector_as_SHGrid == other._vector_as_SHGrid
-        )
-
-    # ==============================================#
-    #                Private methods                #
-    # ==============================================#
+    def _grid_name(self):
+        return self.grid if self._sampling == 1 else "DH2"
 
     def _coefficient_to_component_mapping(self) -> coo_array:
         """Builds a sparse matrix to map `pyshtools` coeffs to component vectors."""
@@ -536,38 +326,10 @@ class Sobolev(SymmetricSpaceSobolev):
             (data, (rows, cols)), shape=(row_dim, col_dim), dtype=float
         ).tocsc()
 
-    def _to_components_from_coeffs(self, coeffs: np.ndarray) -> np.ndarray:
-        """Returns a component vector from a `pyshtools` coefficient array."""
-        f = coeffs.flatten(order="C")
-        return self._sparse_coeffs_to_component @ f
-
-    def _to_components_from_SHCoeffs(self, ulm: sh.SHCoeffs) -> np.ndarray:
-        """Returns a component vector from an `SHCoeffs` object."""
-        return self._to_components_from_coeffs(ulm.coeffs)
-
-    def _to_components_from_SHGrid(self, u: sh.SHGrid) -> np.ndarray:
-        """Returns a component vector from an `SHGrid` object."""
-        ulm = u.expand(normalization=self.normalization, csphase=self.csphase)
-        return self._to_components_from_SHCoeffs(ulm)
-
-    def _from_components_to_SHCoeffs(self, c: np.ndarray) -> sh.SHCoeffs:
-        """Returns an `SHCoeffs` object from its component vector."""
-        f = self._sparse_coeffs_to_component.T @ c
-        coeffs = f.reshape((2, self.lmax + 1, self.lmax + 1))
-        return sh.SHCoeffs.from_array(
-            coeffs, normalization=self.normalization, csphase=self.csphase
-        )
-
-    def _from_components_to_SHGrid(self, c: np.ndarray) -> sh.SHGrid:
-        """Returns an `SHGrid` object from its component vector."""
-        ulm = self._from_components_to_SHCoeffs(c)
-        return ulm.expand(grid=self.grid, extend=self.extend)
-
-    def _degree_dependent_scaling_to_diagonal_matrix(
-        self, f: Callable[[int], float]
-    ) -> diags:
+    def _degree_dependent_scaling_values(self, f: Callable[[int], float]) -> diags:
         """Creates a diagonal sparse matrix from a function of degree `l`."""
-        values = np.zeros(self.dim)
+        dim = (self.lmax + 1) ** 2
+        values = np.zeros(dim)
         i = 0
         for l in range(self.lmax + 1):
             j = i + l + 1
@@ -577,124 +339,262 @@ class Sobolev(SymmetricSpaceSobolev):
             j = i + l
             values[i:j] = f(l)
             i = j
-        return diags([values], [0])
+        return values
 
-    def _sobolev_function(self, l: int) -> float:
-        """The degree-dependent scaling that defines the Sobolev inner product."""
-        return (1.0 + self.scale**2 * l * (l + 1)) ** self.order
+    def _coefficient_to_component(self, ulm: sh.SHCoeffs) -> np.ndarray:
+        """Maps spherical harmonic coefficients to a component vector."""
+        flat_coeffs = ulm.coeffs.flatten(order="C")
+        return self._sparse_coeffs_to_component @ flat_coeffs
 
-    def _inner_product_impl(self, u: Any, v: Any) -> float:
-        """Implements the Sobolev inner product in the spectral domain."""
-        return self.radius**2 * np.dot(
-            self._metric_tensor @ self.to_components(u), self.to_components(v)
+    def _component_to_coefficient(self, c: np.ndarray) -> sh.SHCoeffs:
+        """Maps a component vector to spherical harmonic coefficients."""
+        flat_coeffs = self._sparse_coeffs_to_component.T @ c
+        coeffs = flat_coeffs.reshape((2, self.lmax + 1, self.lmax + 1))
+        return sh.SHCoeffs.from_array(
+            coeffs, normalization=self.normalization, csphase=self.csphase
         )
 
-    def _to_dual_impl(self, u: Any) -> "LinearForm":
-        """Implements the mapping to the dual space."""
-        c = self._metric_tensor @ self.to_components(u) * self.radius**2
-        return self.dual.from_components(c)
 
-    def _from_dual_impl(self, up: "LinearForm") -> Any:
-        """Implements the mapping from the dual space."""
-        c = self._inverse_metric_tensor @ self.dual.to_components(up) / self.radius**2
-        return self.from_components(c)
+class Lebesgue(SphereHelper, HilbertModule, AbstractInvariantLebesgueSpace):
+    """
+    Implementation of the Lebesgue space L² on the sphere.
+
+    This class represents square-integrable functions on a sphere. A function is
+    represented by a `pyshtools.SHGrid` object, which stores its values on a
+    regular grid in latitude and longitude. The L² inner product is defined
+    in the spherical harmonic domain.
+    """
+
+    def __init__(
+        self,
+        lmax: int,
+        /,
+        *,
+        radius: float = 1,
+        grid: str = "DH",
+        extend: bool = True,
+    ):
+
+        if lmax < 0:
+            raise ValueError("lmax must be non-negative")
+
+        self._dim = (lmax + 1) ** 2
+
+        SphereHelper.__init__(self, lmax, radius, grid, extend)
+
+    @property
+    def dim(self) -> int:
+        """The dimension of the space."""
+        return self._dim
+
+    def to_components(self, u: sh.SHGrid) -> np.ndarray:
+        coeff = self.to_coefficient(u)
+        return self._coefficient_to_component(coeff)
+
+    def from_components(self, c: np.ndarray) -> sh.SHGrid:
+        coeff = self._component_to_coefficient(c)
+        return self.from_coefficient(coeff)
 
-    def _ax_impl(self, a: float, x: Any) -> None:
+    def to_dual(self, u: sh.SHGrid) -> LinearForm:
+        coeff = self.to_coefficient(u)
+        cp = self._coefficient_to_component(coeff) * self.radius**2
+        return self.dual.from_components(cp)
+
+    def from_dual(self, up: LinearForm) -> sh.SHGrid:
+        cp = self.dual.to_components(up) / self.radius**2
+        coeff = self._component_to_coefficient(cp)
+        return self.from_coefficient(coeff)
+
+    def ax(self, a: float, x: sh.SHGrid) -> None:
         """
         Custom in-place ax implementation for pyshtools objects.
         x := a*x
         """
-        if self._vector_as_SHGrid:
-            # For SHGrid objects, modify the .data array
-            x.data *= a
-        else:
-            # For SHCoeffs objects, modify the .coeffs array
-            x.coeffs *= a
+        x.data *= a
 
-    def _axpy_impl(self, a: float, x: Any, y: Any) -> None:
+    def axpy(self, a: float, x: sh.SHGrid, y: sh.SHGrid) -> None:
         """
         Custom in-place axpy implementation for pyshtools objects.
         y := a*x + y
         """
-        if self._vector_as_SHGrid:
-            # For SHGrid objects, modify the .data array
-            y.data += a * x.data
-        else:
-            # For SHCoeffs objects, modify the .coeffs array
-            y.coeffs += a * x.coeffs
+        y.data += a * x.data
 
-    def _vector_multiply_impl(self, u1: Any, u2: Any) -> Any:
-        """Implements element-wise multiplication of two fields."""
-        if self._vector_as_SHGrid:
-            return u1 * u2
-        else:
-            u1_field = u1.expand(grid=self.grid, extend=self.extend)
-            u2_field = u2.expand(grid=self.grid, extend=self.extend)
-            u3_field = u1_field * u2_field
-            return u3_field.expand(
-                normalization=self.normalization, csphase=self.csphase
-            )
+    def vector_multiply(self, x1: sh.SHGrid, x2: sh.SHGrid) -> sh.SHGrid:
+        """
+        Computes the pointwise product of two functions.
+        """
+        return x1 * x2
 
+    def eigenfunction_norms(self) -> np.ndarray:
+        """Returns a list of the norms of the eigenfunctions."""
+        return np.fromiter(
+            [self.radius for i in range(self.dim)],
+            dtype=float,
+        )
 
-class Lebesgue(Sobolev):
+    def invariant_automorphism(self, f: Callable[[float], float]) -> LinearOperator:
+        values = self._degree_dependent_scaling_values(
+            lambda l: f(self.laplacian_eigenvalue((l, 0)))
+        )
+        matrix = diags([values], [0])
+
+        def mapping(u):
+            c = matrix @ (self.to_components(u))
+            coeff = self._component_to_coefficient(c)
+            return self.from_coefficient(coeff)
+
+        return LinearOperator.self_adjoint(self, mapping)
+
+    # ================================================================ #
+    #                         Private methods                          #
+    # ================================================================ #
+
+
+class Sobolev(SphereHelper, MassWeightedHilbertModule, AbstractInvariantSobolevSpace):
     """
-    Implements the L^2 space on the two-sphere.
+    Implementation of the Sobolev space Hˢ on the sphere.
 
-    This is a special case of the `Sobolev` class with `order = 0`.
+    This class represents functions with a specified degree of smoothness. It is
+    constructed as a `MassWeightedHilbertModule` over the `Lebesgue` space, where
+    the mass operator weights the spherical harmonic coefficients to enforce
+    smoothness. This is the primary class for defining smooth, random function
+    fields (e.g., for geophysics or climate science).
     """
 
     def __init__(
         self,
         lmax: int,
+        order: float,
+        scale: float,
+        /,
+        radius: float = 1,
+        grid: str = "DH",
+        extend: bool = True,
+    ):
+
+        if lmax < 0:
+            raise ValueError("lmax must be non-negative")
+
+        SphereHelper.__init__(self, lmax, radius, grid, extend)
+        AbstractInvariantSobolevSpace.__init__(self, order, scale)
+
+        lebesgue = Lebesgue(lmax, radius=radius, grid=grid, extend=extend)
+
+        mass_operator = lebesgue.invariant_automorphism(self.sobolev_function)
+        inverse_mass_operator = lebesgue.invariant_automorphism(
+            lambda k: 1.0 / self.sobolev_function(k)
+        )
+
+        MassWeightedHilbertModule.__init__(
+            self, lebesgue, mass_operator, inverse_mass_operator
+        )
+
+    @staticmethod
+    def from_sobolev_parameters(
+        order: float,
+        scale: float,
         /,
         *,
-        vector_as_SHGrid: bool = True,
         radius: float = 1.0,
+        vector_as_SHGrid: bool = True,
         grid: str = "DH",
-    ) -> None:
+        rtol: float = 1e-8,
+        power_of_two: bool = False,
+    ) -> "Sobolev":
         """
+        Creates an instance with `lmax` chosen based on the Sobolev parameters.
+
+        This factory method estimates the spherical harmonic truncation degree
+        (`lmax`) required to represent the space while meeting a specified
+        relative tolerance for the truncation error. This is useful when the
+        required `lmax` is not known a priori.
+
         Args:
-            lmax: The maximum spherical harmonic degree for truncation.
-            vector_as_SHGrid: If True, elements are `SHGrid` objects. Otherwise,
-                they are `SHCoeffs` objects.
-            radius: The radius of the sphere.
-            grid: The `pyshtools` grid type.
+            order: The order of the Sobolev space, controlling smoothness.
+            scale: The non-dimensional length-scale for the space.
+            radius: The radius of the sphere. Defaults to 1.0.
+            grid: The `pyshtools` grid type (e.g., 'DH'). Defaults to 'DH'.
+            rtol: The relative tolerance used to determine the `lmax`.
+            power_of_two: If True, `lmax` is set to the next power of two.
+
+        Returns:
+            An instance of the Sobolev class with a calculated `lmax`.
         """
-        super().__init__(
+        if order <= 1.0:
+            raise ValueError("This method is only applicable for orders > 1.0")
+
+        summation = 1.0
+        l = 0
+        err = 1.0
+        sobolev_func = lambda deg: (1.0 + scale**2 * deg * (deg + 1)) ** order
+
+        while err > rtol:
+            l += 1
+            term = 1 / sobolev_func(l)
+            summation += term
+            err = term / summation
+            if l > 10000:
+                raise RuntimeError("Failed to converge on a stable lmax.")
+
+        if power_of_two:
+            n = int(np.log2(l))
+            l = 2 ** (n + 1)
+
+        lmax = l
+        return Sobolev(
             lmax,
-            0.0,
-            1.0,
-            vector_as_SHGrid=vector_as_SHGrid,
+            order,
+            scale,
             radius=radius,
             grid=grid,
         )
 
+    def __eq__(self, other: object) -> bool:
+        """
+        Checks for mathematical equality with another Sobolev space on a sphere.
 
-class LowPassFilter:
-    """
-    Implements a simple Hann-type low-pass filter in the spherical harmonic domain.
-    """
+        Two spaces are considered equal if they are of the same type and have
+        the same defining parameters (kmax, order, scale, and radius).
+        """
+        if not isinstance(other, Sobolev):
+            return NotImplemented
+
+        return (
+            self.lmax == other.lmax
+            and self.radius == other.radius
+            and self.order == other.order
+            and self.scale == other.scale
+        )
+
+    def eigenfunction_norms(self) -> np.ndarray:
+        """Returns a list of the norms of the eigenfunctions."""
+        values = self._degree_dependent_scaling_values(
+            lambda l: np.sqrt(self.sobolev_function(self.laplacian_eigenvalue((l, 0))))
+        )
+        return self.radius * np.fromiter(values, dtype=float)
 
-    def __init__(self, lower_degree: int, upper_degree: int) -> None:
+    def dirac(self, point: (float, float)) -> LinearForm:
         """
+        Returns the linear functional for point evaluation (Dirac measure).
+
         Args:
-            lower_degree: Below this degree `l`, the filter gain is 1.
-            upper_degree: Above this degree `l`, the filter gain is 0.
+            point: A tuple containing `(latitude, longitude)`.
         """
-        self._lower_degree: int = lower_degree
-        self._upper_degree: int = upper_degree
-
-    def __call__(self, l: int) -> float:
-        if l <= self._lower_degree:
-            return 1.0
-        elif self._lower_degree <= l <= self._upper_degree:
-            return 0.5 * (
-                1.0
-                - np.cos(
-                    np.pi
-                    * (self._upper_degree - l)
-                    / (self._upper_degree - self._lower_degree)
-                )
-            )
-        else:
-            return 0.0
+        latitude, longitude = point
+        colatitude = 90.0 - latitude
+
+        coeffs = sh.expand.spharm(
+            self.lmax,
+            colatitude,
+            longitude,
+            normalization=self.normalization,
+            degrees=True,
+        )
+        ulm = sh.SHCoeffs.from_array(
+            coeffs,
+            normalization=self.normalization,
+            csphase=self.csphase,
+        )
+
+        c = self._coefficient_to_component(ulm)
+        return self.dual.from_components(c)