pygeoinf 1.3.8__py3-none-any.whl → 1.4.0__py3-none-any.whl

pygeoinf/symmetric_space/sphere.py

@@ -101,11 +101,6 @@ class SphereHelper:
         self._normalization: str = "ortho"
         self._csphase: int = 1
 
-        # Set up sparse matrix that maps SHCoeff data arrrays into reduced form
-        self._sparse_coeffs_to_component: coo_array = (
-            self._coefficient_to_component_mapping()
-        )
-
     def orthonormalised(self) -> bool:
         """The space is orthonormalised."""
         return True
@@ -341,6 +336,221 @@ class SphereHelper:
 
         return fig, ax, im
 
+    def plot_geodesic(
+        self,
+        p1: Tuple[float, float],
+        p2: Tuple[float, float],
+        ax: Optional["GeoAxes"] = None,
+        n_points: int = 100,
+        **kwargs,
+    ) -> Tuple["Figure", "GeoAxes"]:
+        """
+        Plots a geodesic curve onto a Cartopy map.
+        """
+        # Generate points via our quadrature logic (returns lats, lons)
+        points, _ = self.geodesic_quadrature(p1, p2, n_points=n_points)
+        lats, lons = zip(*points)
+
+        # 2. Get/Create Axes
+        if ax is None:
+            fig, ax = plt.subplots(
+                figsize=kwargs.pop("figsize", (10, 8)),
+                subplot_kw={"projection": ccrs.PlateCarree()},
+            )
+        else:
+            fig = ax.get_figure()
+
+        # 3. Plot with the Geodetic transform
+        # This 'transform' handles the conversion to whatever projection 'ax' uses.
+        kwargs.setdefault("color", "black")
+        kwargs.setdefault("linewidth", 2)
+
+        # We use Geodetic() here because our points were generated along a great circle
+        ax.plot(lons, lats, transform=ccrs.Geodetic(), **kwargs)
+
+        return fig, ax
+
+    def plot_geodesic_network(
+        self,
+        paths: List[Tuple[Tuple[float, float], Tuple[float, float]]],
+        ax: Optional["GeoAxes"] = None,
+        n_points: int = 50,
+        **kwargs,
+    ) -> Tuple["Figure", "GeoAxes"]:
+        """
+        Plots a network of geodesic paths onto a Cartopy map.
+
+        This method iterates through a list of source-receiver pairs and renders
+        each as a great-circle arc. It is useful for visualizing the spatial
+        coverage of a tomographic survey.
+
+        Args:
+            paths: A list of ((lat1, lon1), (lat2, lon2)) tuples.
+            ax: An existing cartopy GeoAxes object. If None, a new figure is created.
+            n_points: Number of points used to render each curve. A lower value
+                (e.g., 50) is often sufficient for batch plotting many lines.
+            **kwargs: Keyword arguments passed to the underlying plot calls
+                (e.g., color, alpha, linewidth).
+
+        Returns:
+            A tuple (figure, axes) containing the plot objects.
+        """
+
+        # Setup/Verify Axes
+        if ax is None:
+            figsize = kwargs.pop("figsize", (12, 10))
+            fig, ax = plt.subplots(
+                figsize=figsize, subplot_kw={"projection": ccrs.PlateCarree()}
+            )
+            ax.set_global()
+            ax.coastlines()
+        else:
+            fig = ax.get_figure()
+
+        # Set default styling for a "network" look
+        # Using a lower alpha and thinner lines helps prevent clutter
+        # when many paths overlap.
+        kwargs.setdefault("color", "black")
+        kwargs.setdefault("linewidth", 0.8)
+        kwargs.setdefault("alpha", 0.5)
+
+        # Batch plot all geodesics
+        for p1, p2 in paths:
+            self.plot_geodesic(p1, p2, ax=ax, n_points=n_points, **kwargs)
+
+        # Extract unique sources and receivers for marking
+        sources = list(set([tuple(p[0]) for p in paths]))
+        receivers = list(set([tuple(p[1]) for p in paths]))
+
+        src_lats, src_lons = zip(*sources)
+        rec_lats, rec_lons = zip(*receivers)
+
+        # Plot Sources (Stars)
+        src_style = kwargs.pop("source_kwargs", {})
+        src_style.setdefault("marker", "*")
+        src_style.setdefault("color", "gold")
+        src_style.setdefault("s", 150)
+        src_style.setdefault("edgecolor", "black")
+        src_style.setdefault("zorder", 5)  # Ensure markers are on top
+
+        ax.scatter(src_lons, src_lats, transform=ccrs.Geodetic(), **src_style)
+
+        # Plot Receivers (Dots)
+        rec_style = kwargs.pop("receiver_kwargs", {})
+        rec_style.setdefault("marker", "o")
+        rec_style.setdefault("color", "red")
+        rec_style.setdefault("s", 50)
+        rec_style.setdefault("edgecolor", "white")
+        rec_style.setdefault("zorder", 5)
+
+        ax.scatter(rec_lons, rec_lats, transform=ccrs.Geodetic(), **rec_style)
+
+        return fig, ax
+
+    def sample_power_measure(
+        self,
+        measure,
+        n_samples,
+        /,
+        *,
+        lmin=None,
+        lmax=None,
+        parallel: bool = False,
+        n_jobs: int = -1,
+    ):
+        """
+        Takes in a Gaussian measure on the space, draws n_samples from
+        and returns samples for the spherical harmonic power at degrees in
+        the indicated range.
+        """
+
+        lmin = 0 if lmin is None else lmin
+        lmax = self.lmax if lmax is None else min(self.lmax, lmax)
+
+        samples = measure.samples(n_samples, parallel=parallel, n_jobs=n_jobs)
+
+        powers = []
+        for u in samples:
+            ulm = self.to_coefficients(u)
+            powers.append(ulm.spectrum(lmax=lmax, convention="power")[lmin:])
+
+        return powers
+
+    def geodesic_quadrature(
+        self, p1: Tuple[float, float], p2: Tuple[float, float], n_points: int
+    ) -> Tuple[List[Tuple[float, float]], np.ndarray]:
+        """
+        Generates Gauss-Legendre quadrature points and weights along a great-circle arc.
+
+        This implementation converts the start and end latitudes and longitudes into
+        unit vectors, calculates the central angle (omega), and interpolates the
+        geodesic path using SLERP.
+
+        Args:
+            p1: Start point as (latitude, longitude) in degrees.
+            p2: End point as (latitude, longitude) in degrees.
+            n_points: Number of quadrature points to generate.
+
+        Returns:
+            points: A list of (lat, lon) tuples in degrees along the geodesic.
+            weights: Integration weights scaled by the total arc length (R * omega).
+        """
+
+        # Coordinate Transforms (Degrees -> Radians -> Unit Vectors)
+        def to_vector(lat, lon):
+            lat_rad, lon_rad = np.radians(lat), np.radians(lon)
+            return np.array(
+                [
+                    np.cos(lat_rad) * np.cos(lon_rad),
+                    np.cos(lat_rad) * np.sin(lon_rad),
+                    np.sin(lat_rad),
+                ]
+            )
+
+        def to_latlon(vec):
+            # Normalize for numerical stability before converting back
+            vec = vec / np.linalg.norm(vec)
+            lat_rad = np.arcsin(vec[2])
+            lon_rad = np.arctan2(vec[1], vec[0])
+            return (np.degrees(lat_rad), np.degrees(lon_rad))
+
+        v1, v2 = to_vector(*p1), to_vector(*p2)
+
+        # Calculate Central Angle (omega)
+        dot_product = np.clip(np.dot(v1, v2), -1.0, 1.0)
+        omega = np.arccos(dot_product)
+
+        # Handle identical points edge case
+        if omega < 1e-10:
+            return [p1] * n_points, np.zeros(n_points)
+
+        # Handle antipodal points (non-unique path)
+        if np.abs(omega - np.pi) < 1e-10:
+            raise ValueError(
+                "Points are antipodal; the great circle path is not unique."
+            )
+
+        # Generate Gauss-Legendre Nodes and Weights
+        x, w = np.polynomial.legendre.leggauss(n_points)
+
+        # Map Nodes to Path Parameter t in [0, 1] and scale weights
+        # t = (x + 1) / 2 maps [-1, 1] to [0, 1]
+        # Weights are scaled by (total_arc_length / 2)
+        t_vals = (x + 1) / 2.0
+        scaled_weights = w * (self.radius * omega / 2.0)
+
+        # Spherical Linear Interpolation (SLERP) for each node
+        sin_omega = np.sin(omega)
+        points = []
+
+        for t in t_vals:
+            coeff1 = np.sin((1 - t) * omega) / sin_omega
+            coeff2 = np.sin(t * omega) / sin_omega
+            v_interp = coeff1 * v1 + coeff2 * v2
+            points.append(to_latlon(v_interp))
+
+        return points, scaled_weights
+
     # --------------------------------------------------------------- #
     #                         private methods                         #
     # ----------------------------------------------------------------#
@@ -378,28 +588,19 @@ class SphereHelper:
 
     def _degree_dependent_scaling_values(self, f: Callable[[int], float]) -> diags:
         """Creates a diagonal sparse matrix from a function of degree `l`."""
-        dim = (self.lmax + 1) ** 2
-        values = np.zeros(dim)
-        i = 0
-        for l in range(self.lmax + 1):
-            j = i + l + 1
-            values[i:j] = f(l)
-            i = j
-        for l in range(1, self.lmax + 1):
-            j = i + l
-            values[i:j] = f(l)
-            i = j
-        return values
+        ls = np.arange(self.lmax + 1)
+        f_vectorized = np.vectorize(f)
+        values = f_vectorized(ls)
+        counts = 2 * ls + 1
+        return np.repeat(values, counts)
 
     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
+        return sh.shio.SHCilmToVector(ulm.coeffs)
 
     def _component_to_coefficients(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))
+        coeffs = sh.shio.SHVectorToCilm(c)
         return sh.SHCoeffs.from_array(
             coeffs, normalization=self.normalization, csphase=self.csphase
         )
@@ -475,6 +676,14 @@ class Lebesgue(SphereHelper, HilbertModule, AbstractInvariantLebesgueSpace):
         """
         return x1 * x2
 
+    def vector_sqrt(self, x: sh.SHGrid) -> sh.SHGrid:
+        """
+        Returns the pointwise square root of a function.
+        """
+        y = x.copy()
+        y.data = np.sqrt(x.data)
+        return y
+
     def __eq__(self, other: object) -> bool:
         """
         Checks for mathematical equality with another Sobolev space on a sphere.
@@ -691,7 +900,7 @@ class Sobolev(SphereHelper, MassWeightedHilbertModule, AbstractInvariantSobolevS
         err = 1.0
 
         def sobolev_func(deg):
-            return (1.0 + scale**2 * deg * (deg + 1)) ** order
+            return (1.0 + (scale / radius) ** 2 * deg * (deg + 1)) ** order
 
         while err > rtol:
             l += 1

pygeoinf/symmetric_space/symmetric_space.py

@@ -29,7 +29,7 @@ AbstractInvariantSobolevSpace
 
 from __future__ import annotations
 from abc import ABC, abstractmethod
-from typing import Callable, Any, List
+from typing import Callable, Any, List, Tuple, Optional
 
 
 import numpy as np
@@ -120,6 +120,29 @@ class AbstractInvariantLebesgueSpace(ABC):
             g: A function that takes an eigenvalue index and returns a real value.
         """
 
+    @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.
+        """
+
+    @abstractmethod
+    def geodesic_quadrature(
+        self, p1: Any, p2: Any, n_points: int
+    ) -> Tuple[List[Any], np.ndarray]:
+        """
+        Returns quadrature points and weights for a geodesic between p1 and p2.
+
+        Returns:
+            points: List of manifold coordinates.
+            weights: Integration weights scaled by the line element.
+        """
+
     def invariant_automorphism(self, f: Callable[[float], float]) -> LinearOperator:
         """
         Returns an automorphism of the form f(Δ) with f a function
@@ -143,17 +166,6 @@ class AbstractInvariantLebesgueSpace(ABC):
             lambda k: f(self.laplacian_eigenvalue(k))
         )
 
-    @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],
@@ -469,3 +481,146 @@ class AbstractInvariantSobolevSpace(AbstractInvariantLebesgueSpace):
         return self.point_value_scaled_invariant_gaussian_measure(
             lambda k: np.exp(-(scale**2) * k), amplitude
         )
+
+    def geodesic_integral(
+        self, p1: Any, p2: Any, n_points: Optional[int] = None
+    ) -> LinearForm:
+        """
+        Returns a linear functional representing the line integral of a function
+        along a geodesic path.
+
+        This method approximates the integral :math:`\\int_{\\gamma} u(s) ds`, where
+        :math:`\\gamma` is the shortest path (geodesic) connecting points `p1` and `p2`.
+        The integral is represented as a :class:`LinearForm` in the dual space,
+        constructed by summing weighted point evaluations (Dirac measures) along
+        the path.
+
+        For Hilbert spaces with a specified :attr:`scale`, the method can
+        automatically determine the required quadrature density to resolve the
+        smooth features of the space's sensitivity kernels.
+
+        Args:
+            p1 (Any): The starting point of the geodesic. The type is manifold-dependent
+                (e.g., float for :class:`Circle`, tuple for :class:`Sphere`).
+            p2 (Any): The end point of the geodesic.
+            n_points (int, optional): The number of Gauss-Legendre quadrature points.
+                If None, it is heuristically determined as:
+                :math:`n = \\lceil (\\text{arc\\_length} / \\text{scale}) \\times 2 \\rceil`.
+                This ensures at least two points per characteristic length-scale,
+                providing stable sampling of the sensitivity kernel. Defaults to None.
+
+        Returns:
+            LinearForm: A linear functional whose action on a vector `u` computes
+                 the approximated line integral.
+
+        Raises:
+            NotImplementedError: If the Sobolev order :math:`s` is less than or
+                equal to half the spatial dimension :math:`n/2`.
+        """
+        if self.order <= self.spatial_dimension / 2:
+            raise NotImplementedError(
+                f"Order {self.order} is too low for point evaluation on a "
+                f"{self.spatial_dimension}D manifold."
+            )
+
+        # Heuristic quadrature density determination
+        if n_points is None:
+            # Perform a minimal call to determine the total arc length via weights
+            _, temp_weights = self.geodesic_quadrature(p1, p2, n_points=2)
+            arc_length = np.sum(temp_weights)
+
+            # Scale-based heuristic (Nyquist-like sampling)
+            n_points = int(np.ceil((arc_length / self.scale) * 2.0))
+            n_points = max(2, n_points)
+
+        #  Retrieve final manifold-specific points and weights
+        points, weights = self.geodesic_quadrature(p1, p2, n_points)
+
+        #  Aggregate weighted components into the dual space representation
+        # The components of a LinearForm represent the functional in the dual basis
+        total_components = np.zeros(self.dim)
+        for pt, weight in zip(points, weights):
+            # Accumulate the weighted Riesz representation of each Dirac delta
+            total_components += weight * self.dirac(pt).components
+
+        return LinearForm(self, components=total_components)
+
+    def geodesic_integral_representation(
+        self, p1: Any, p2: Any, n_points: Optional[int] = None
+    ) -> Any:
+        """
+        Returns the Riesz representation (sensitivity kernel) of the line integral.
+
+        This maps the LinearForm (the integral functional) back into the
+        primal Hilbert space. Visualizing this vector reveals the "sensitivity"
+        of the line integral to perturbations at different locations in the domain.
+
+        Args:
+            p1, p2: Start and end points of the geodesic.
+            n_points: Number of quadrature points.
+        """
+        # Create the functional and map it to a vector in the space
+        integral_form = self.geodesic_integral(p1, p2, n_points)
+        return self.from_dual(integral_form)
+
+    def path_average_operator(self, paths, n_points=None):
+        """
+        Constructs a tomographic operator mapping a function field to its
+        line integrals along a set of geodesic paths.
+
+        Note: Despite the name, this operator returns the line integral
+        (the dual pairing of the function with the path functional) rather
+        than a normalized average, unless the user manually scales the forms.
+        This corresponds to the 'path average' convention often used in
+        seismic and atmospheric tomography.
+
+        Args:
+            paths (List[Tuple[Any, Any]]): A list of start and end point pairs
+                defining the geodesics.
+            n_points (int, optional): The number of quadrature points per path.
+                If None, the heuristic based on the Sobolev scale is used.
+
+        Returns:
+            LinearOperator: An operator mapping Space -> EuclideanSpace(len(paths)).
+                The adjoint of this operator performs the 'back-projection'
+                mapping data residuals into the function space.
+        """
+        # Generate the set of linear functionals representing each path integral
+        # The integral logic is handled by the Abstract Geodesic Integral method
+        path_forms = [
+            self.geodesic_integral(p1, p2, n_points=n_points) for p1, p2 in paths
+        ]
+
+        # Convert the list of forms into a single LinearOperator mapping
+        return LinearOperator.from_linear_forms(path_forms)
+
+    def random_source_receiver_paths(
+        self, n_sources: int, n_receivers: int
+    ) -> List[Tuple[Any, Any]]:
+        """
+        Generates a list of source-receiver pairs by connecting every source to
+        every receiver.
+
+        This method uses the existing :meth:`random_points` logic to generate
+        coordinates appropriate for the specific symmetric space. For a set
+        of S sources and R receivers, this returns a list of S*R paths.
+
+        Args:
+            n_sources: The number of random source locations to generate.
+            n_receivers: The number of random receiver locations to generate.
+
+        Returns:
+            List[Tuple[Any, Any]]: A list of tuples, where each tuple contains
+                a (source, receiver) pair.
+        """
+        # Generate the points using the existing base class method
+        sources = self.random_points(n_sources)
+        receivers = self.random_points(n_receivers)
+
+        # Create the full-mesh network
+        paths = []
+        for src in sources:
+            for rec in receivers:
+                paths.append((src, rec))
+
+        return paths