pygeoinf 1.3.9__tar.gz → 1.4.0__tar.gz

{pygeoinf-1.3.9 → pygeoinf-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pygeoinf
-Version: 1.3.9
+Version: 1.4.0
 Summary: A package for solving geophysical inference and inverse problems
 License: BSD-3-Clause
 License-File: LICENSE
@@ -16,6 +16,7 @@ Provides-Extra: sphere
 Requires-Dist: Cartopy (>=0.23.0,<0.24.0) ; extra == "sphere"
 Requires-Dist: joblib (>=1.5.2,<2.0.0)
 Requires-Dist: matplotlib (>=3.0.0)
+Requires-Dist: numba (>=0.63.1,<0.64.0)
 Requires-Dist: numpy (>=1.26.0)
 Requires-Dist: pyqt6 (>=6.0.0)
 Requires-Dist: pyshtools (>=4.0.0) ; extra == "sphere"

{pygeoinf-1.3.9 → pygeoinf-1.4.0}/pygeoinf/gaussian_measure.py

@@ -455,10 +455,10 @@ class GaussianMeasure:
         if n < 1:
             raise ValueError("Number of samples must be a positive integer.")
 
-        # Step 1: Draw samples (Parallelized)
+        # Draw samples
         samples = self.samples(n, parallel=parallel, n_jobs=n_jobs)
 
-        # Step 2: Compute variance using vector arithmetic
+        # Compute variance using vector arithmetic
         expectation = self.expectation
         variance = self.domain.zero
 
@@ -469,6 +469,42 @@ class GaussianMeasure:
 
         return variance
 
+    def sample_pointwise_std(
+        self, n: int, /, *, parallel: bool = False, n_jobs: int = -1
+    ) -> Vector:
+        """
+        Estimates the pointwise standard deviation by drawing n samples.
+
+        Args:
+            n: Number of samples to draw.
+            parallel: If True, draws samples in parallel.
+            n_jobs: Number of CPU cores to use. -1 means all available.
+        """
+        variance = self.sample_pointwise_variance(n, parallel=parallel, n_jobs=n_jobs)
+        return self.domain.vector_sqrt(variance)
+
+    def with_dense_covariance(self, parallel: bool = False, n_jobs: int = -1):
+        """
+        Forms a new Gaussian measure equivalent to the existing one, but
+        with its covariance matrix stored in dense form. The dense matrix
+        calculation can optionally be parallelised.
+
+        Args:
+            parallel: If True, computes the covariance in parallel.
+            n_jobs: Number of CPU cores to use. -1 means all available.
+
+        Returns:
+            The new Gaussian measure.
+        """
+
+        covariance_matrix = self.covariance.matrix(
+            dense=True, galerkin=True, parallel=parallel, n_jobs=n_jobs
+        )
+
+        return GaussianMeasure.from_covariance_matrix(
+            self.domain, covariance_matrix, expectation=self.expectation
+        )
+
     def affine_mapping(
         self, /, *, operator: LinearOperator = None, translation: Vector = None
     ) -> GaussianMeasure:
@@ -546,7 +582,7 @@ class GaussianMeasure:
 
         # Pass the parallelization arguments directly to the matrix creation method
         cov_matrix = self.covariance.matrix(
-            dense=True, parallel=parallel, n_jobs=n_jobs
+            dense=True, galerkin=True, parallel=parallel, n_jobs=n_jobs
         )
 
         try:

{pygeoinf-1.3.9 → pygeoinf-1.4.0}/pygeoinf/hilbert_space.py

@@ -547,6 +547,12 @@ class HilbertModule(HilbertSpace, ABC):
             The product of the two vectors.
         """
 
+    @abstractmethod
+    def vector_sqrt(self, x: Vector) -> Vector:
+        """
+        Returns the square root of a vector.
+        """
+
 
 class EuclideanSpace(HilbertSpace):
     """
@@ -829,3 +835,12 @@ class MassWeightedHilbertModule(MassWeightedHilbertSpace, HilbertModule):
         is itself an instance of `HilbertModule`.
         """
         return self.underlying_space.vector_multiply(x1, x2)
+
+    def vector_sqrt(self, x: Vector) -> Vector:
+        """
+        Computes vector multiplication by delegating to the underlying space.
+
+        Note: This assumes the underlying space provided during initialization
+        is itself an instance of `HilbertModule`.
+        """
+        return self.underlying_space.vector_sqrt(x)

{pygeoinf-1.3.9 → pygeoinf-1.4.0}/pygeoinf/linear_operators.py

@@ -102,10 +102,13 @@ class LinearOperator(NonLinearOperator, LinearOperatorAxiomChecks):
         self.__adjoint_mapping: Callable[[Any], Any]
         self.__dual_mapping: Callable[[Any], Any]
 
+        self.__using_default_dual_and_adjoint = False
+
         if dual_mapping is None:
             if adjoint_mapping is None:
                 self.__dual_mapping = self._dual_mapping_default
                 self.__adjoint_mapping = self._adjoint_mapping_from_dual
+                self.__using_default_dual_and_adjoint = True
             else:
                 self.__adjoint_mapping = adjoint_mapping
                 self.__dual_mapping = self._dual_mapping_from_adjoint
@@ -919,6 +922,35 @@ class LinearOperator(NonLinearOperator, LinearOperatorAxiomChecks):
         self, galerkin: bool, parallel: bool, n_jobs: int
     ) -> np.ndarray:
 
+        # Optimization: If the codomain is smaller than the domain, it is cheaper
+        # to compute the matrix of the adjoint/dual (which has fewer columns)
+        # and transpose the result.
+
+        # Note: This recursion naturally terminates because the adjoint/dual
+        # swaps the domain and codomain. In the recursive call,
+        # (codomain.dim < domain.dim) will be False, forcing the standard path.
+
+        # If the operator has its dual and adjoint actions done using the
+        # default implementation, this optimisation is skipped.
+        if (
+            self.codomain.dim < self.domain.dim
+            and not self.__using_default_dual_and_adjoint
+        ):
+            if galerkin:
+                # For Galerkin representations: Matrix(L) = Matrix(L*).T
+                return self.adjoint.matrix(
+                    dense=True, galerkin=True, parallel=parallel, n_jobs=n_jobs
+                ).T
+            else:
+                # For Standard representations: Matrix(L) = Matrix(L').T
+                return self.dual.matrix(
+                    dense=True, galerkin=False, parallel=parallel, n_jobs=n_jobs
+                ).T
+
+        # --- Standard Column-wise Construction ---
+        # This block executes if optimization is not applicable (or in the
+        # recursive base case).
+
         scipy_op_wrapper = self.matrix(galerkin=galerkin)
 
         if not parallel:

{pygeoinf-1.3.9 → pygeoinf-1.4.0}/pygeoinf/symmetric_space/circle.py

@@ -24,7 +24,7 @@ Key Classes
 
 from __future__ import annotations
 
-from typing import Callable, Tuple, Optional, Any
+from typing import Callable, Tuple, Optional, Any, List
 import matplotlib.pyplot as plt
 import numpy as np
 from scipy.fft import rfft, irfft
@@ -226,6 +226,40 @@ class CircleHelper:
         ax.fill_between(self.angles(), u - u_bound, u + u_bound, **kwargs)
         return fig, ax
 
+    def geodesic_quadrature(
+        self, p1: float, p2: float, n_points: int
+    ) -> Tuple[List[float], np.ndarray]:
+        """
+        Returns quadrature points and weights for the shortest arc between p1 and p2.
+
+        Args:
+            p1: Starting angle in radians.
+            p2: Ending angle in radians.
+            n_points: Number of quadrature points.
+
+        Returns:
+            points: A list of angles (floats) along the shortest arc.
+            weights: Integration weights scaled by the arc length.
+        """
+        # Calculate the shortest signed angular distance on the circle
+        # This ensures we take the "inner" arc rather than the long way around.
+        diff = (p2 - p1 + np.pi) % (2 * np.pi) - np.pi
+        arc_length = np.abs(diff) * self.radius
+
+        # Get standard Gauss-Legendre nodes (x) and weights (w) on [-1, 1]
+        x, w = np.polynomial.legendre.leggauss(n_points)
+
+        # Map nodes to the angular interval [p1, p1 + diff]
+        # t moves from 0 to 1 as x moves from -1 to 1
+        t = (x + 1) / 2.0
+        angles = p1 + t * diff
+
+        # Scale weights: (w * 0.5) maps [-1, 1] to [0, 1]
+        # Multiplying by total arc_length gives the proper integration weights.
+        scaled_weights = w * (arc_length / 2.0)
+
+        return angles.tolist(), scaled_weights
+
     def _coefficient_to_component(self, coeff: np.ndarray) -> np.ndarray:
         """Packs complex Fourier coefficients into a real component vector."""
         # For a real-valued input, the output of rfft (real FFT) has
@@ -346,6 +380,12 @@ class Lebesgue(CircleHelper, HilbertModule, AbstractInvariantLebesgueSpace):
             return False
         return True
 
+    def vector_sqrt(self, u: np.ndarray) -> np.ndarray:
+        """
+        Returns the pointwise square root of a function.
+        """
+        return np.sqrt(u)
+
     def invariant_automorphism_from_index_function(self, g: Callable[[int], float]):
         """
         Implements an invariant automorphism of the form f(Δ) using Fourier

{pygeoinf-1.3.9 → pygeoinf-1.4.0}/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.

{pygeoinf-1.3.9 → pygeoinf-1.4.0}/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

pygeoinf-1.4.0/pygeoinf/symmetric_space/wigner.py

@@ -0,0 +1,284 @@
+import numpy as np
+import numba as nb
+
+
+@nb.jit(nopython=True, cache=True)
+def _wigner_start_values(l, n, theta):
+    """
+    Computes the boundary values for the recursion (l == |n|).
+    Corresponds to WignerMinOrder/WignerMaxOrder in C++.
+    """
+    # Use log-space arithmetic for stability
+    # Corresponds to lines 86-105 in Wigner.h
+
+    half = 0.5
+    sin_half = np.sin(half * theta)
+    cos_half = np.cos(half * theta)
+
+    # Handle tiny angles (log stability)
+    # Note: In a full implementation, check for strict 0 or pi,
+    # but float precision usually handles this with small eps.
+    log_sin = np.log(sin_half) if sin_half > 1e-15 else -1e15
+    log_cos = np.log(cos_half) if cos_half > 1e-15 else -1e15
+
+    Fl = float(l)
+    Fn = float(n)
+
+    # Formula from WignerMinOrder
+    # exp( 0.5 * (lgamma(2l+1) - lgamma(l-n+1) - lgamma(l+n+1)) + ... )
+    term = np.exp(
+        half
+        * (
+            np.math.lgamma(2 * Fl + 1)
+            - np.math.lgamma(Fl - Fn + 1)
+            - np.math.lgamma(Fl + Fn + 1)
+        )
+        + (Fl + Fn) * log_sin
+        + (Fl - Fn) * log_cos
+    )
+
+    # Returns (min_val, max_val)
+    # min_val corresponds to m = -l (if n is negative logic)
+    # Based on WignerDetails logic, we return the value for m=-l and m=l
+
+    # Note: The C++ code handles sign flips based on n.
+    # We simplify for the standard case.
+    val_minus_l = term
+    val_plus_l = term * ((-1) ** (n + l))  # From MinusOneToPower in WignerMaxOrder
+
+    return val_minus_l, val_plus_l
+
+
+@nb.jit(nopython=True, cache=True)
+def compute_wigner_d_recursive(l_max, m_max, n, theta):
+    """
+    Direct port of GSHTrans::Wigner::Compute.
+    Returns a flat array of coefficients and an offset array to index it.
+    """
+
+    # 1. Precompute inverse square roots for integer factors
+    #    (Matches PreCompute in Wigner.h)
+    size_pre = 2 * l_max + 5
+    sqrt_inv = np.zeros(size_pre)
+    sqrt_val = np.zeros(size_pre)
+    for i in range(1, size_pre):
+        sqrt_val[i] = np.sqrt(i)
+        sqrt_inv[i] = 1.0 / sqrt_val[i]
+
+    # 2. Calculate storage size and offsets
+    #    We assume 'All' m-range for simplicity (m goes from -min(l, m_max) to min(l, m_max))
+    n_abs = abs(n)
+    offsets = np.zeros(l_max + 2, dtype=np.int64)
+    current_offset = 0
+
+    for l in range(l_max + 1):
+        offsets[l] = current_offset
+        if l >= n_abs:
+            effective_m_max = min(l, m_max)
+            # Size = (effective_m_max - (-effective_m_max)) + 1
+            current_offset += 2 * effective_m_max + 1
+
+    data = np.zeros(current_offset, dtype=np.float64)
+    cos_theta = np.cos(theta)
+
+    # 3. Main Recursion Loop
+    #    Iterate degrees l from |n| to l_max
+    for l in range(n_abs, l_max + 1):
+
+        m_lim = min(l, m_max)
+        row_len = 2 * m_lim + 1
+
+        # Pointers to current and previous data in the flat array
+        ptr = offsets[l]
+        ptr_minus_1 = offsets[l - 1] if l > 0 else -1
+        ptr_minus_2 = offsets[l - 2] if l > 1 else -1
+
+        # A. Base Case: l = |n|
+        if l == n_abs:
+            val_min, val_max = _wigner_start_values(l, n, theta)
+
+            # If n is positive, we start filling from the "left" (m=-l) logic
+            # The C++ code separates logic for n>=0 and n<0.
+            # Assuming n=0 for common cases, or standard alignment:
+
+            # Fill directly. For l=|n|, usually there is only one valid starting m
+            # if we strictly followed the "Sector" logic, but Wigner.h fills the row.
+            # We will use the boundary values logic.
+
+            # Simple fill for l=|n|: usually 0 except at boundaries?
+            # The C++ code lines 326-338 imply it fills the whole row for l=|n|.
+            # But mathematically only m=-l or m=l are non-zero at the start of recursion?
+            # Actually, for l=n, d^n_{n,m} is computable.
+
+            # To be safe and "passably efficient", we only set the edges
+            # and let the loop fill (though loop is empty for size 1).
+            if m_lim == l:  # If we have full range
+                if n >= 0:
+                    data[ptr] = val_min  # m = -l
+                    data[ptr + row_len - 1] = val_max  # m = +l
+                else:
+                    data[ptr] = val_max  # Flip logic
+                    data[ptr + row_len - 1] = val_min
+
+            # Note: For l=|n|, intermediate m's are handled by specific logic
+            # or are zero? In Wigner.h line 334, it loops w/ WignerMaxUpperIndex.
+            # For simplicity in this port, we assume we just need the recursion seeds.
+
+        # B. One-term recursion: l = |n| + 1
+        elif l == n_abs + 1:
+            # Range of m for previous row (l-1)
+            m_lim_prev = min(l - 1, m_max)
+
+            # Iterate over m. The C++ code is careful about indices.
+            # We map m to index: index = m + m_lim
+
+            # Pre-calc coefficients
+            alpha_base = (2 * l - 1) * l * cos_theta * sqrt_inv[l + n_abs]
+            beta_base = (2 * l - 1) * sqrt_inv[l + n_abs]
+            if n < 0:
+                beta_base *= -1
+
+            # Loop over 'interior' m (those that exist in l-1)
+            # m goes from -m_lim_prev to m_lim_prev
+            for m in range(-m_lim_prev, m_lim_prev + 1):
+                # Indices
+                idx_prev = m + m_lim_prev  # Index in l-1 row
+                idx_curr = m + m_lim  # Index in l row
+
+                f1 = (alpha_base - beta_base * m) * sqrt_inv[l - m] * sqrt_inv[l + m]
+                data[ptr + idx_curr] = f1 * data[ptr_minus_1 + idx_prev]
+
+            # Add Boundaries (m = -l and m = +l) if they fit in m_max
+            if m_lim == l:
+                val_min, val_max = _wigner_start_values(l, n, theta)
+                data[ptr] = val_min  # m = -l
+                data[ptr + row_len - 1] = val_max  # m = l
+
+        # C. Two-term recursion: l > |n| + 1
+        else:
+            m_lim_prev = min(l - 1, m_max)
+            m_lim_prev2 = min(l - 2, m_max)
+
+            # Terms for recursion
+            # Matches C++ Lines 397-402
+            inv_l_minus_1 = 1.0 / (l - 1.0)
+
+            alpha = (2 * l - 1) * l * cos_theta * sqrt_inv[l - n] * sqrt_inv[l + n]
+            beta = (2 * l - 1) * n * sqrt_inv[l - n] * sqrt_inv[l + n] * inv_l_minus_1
+            gamma = (
+                l
+                * sqrt_val[l - 1 - n]
+                * sqrt_val[l - 1 + n]
+                * sqrt_inv[l - n]
+                * sqrt_inv[l + n]
+                * inv_l_minus_1
+            )
+
+            # 1. Fill Interior (where m exists in l-2)
+            # Range where we can use two-term: m in intersection of l-1 and l-2
+            m_start_2term = -m_lim_prev2
+            m_end_2term = m_lim_prev2
+
+            for m in range(m_start_2term, m_end_2term + 1):
+                idx_curr = m + m_lim
+                idx_prev = m + m_lim_prev
+                idx_prev2 = m + m_lim_prev2
+
+                denom = sqrt_inv[l - m] * sqrt_inv[l + m]
+                f1 = (alpha - beta * m) * denom
+                f2 = gamma * sqrt_val[l - 1 - m] * sqrt_val[l - 1 + m] * denom
+
+                term1 = f1 * data[ptr_minus_1 + idx_prev]
+                term2 = f2 * data[ptr_minus_2 + idx_prev2]
+
+                data[ptr + idx_curr] = term1 - term2
+
+            # 2. Fill Lower Gap (if m_max allows, between l-2 and l-1)
+            # This corresponds to "one-point recursion" logic for growing edges
+            # The gap is m = -(l-1). It exists in l-1 but not l-2.
+            if m_lim_prev > m_lim_prev2:  # If l-1 has wider range than l-2
+                # Logic for m = -(l-1)
+                m = -(l - 1)
+                if abs(m) <= m_lim:
+                    idx_curr = m + m_lim
+                    idx_prev = m + m_lim_prev
+                    # Use 1-term expansion (simplified from C++ lines 360-370)
+                    # f1 derived from boundary conditions
+                    f1 = (
+                        (2 * l - 1)
+                        * (l * (l - 1) * cos_theta - m * n)
+                        * sqrt_inv[l - n]
+                        * sqrt_inv[l + n]
+                        * sqrt_inv[l - m]
+                        * sqrt_inv[l + m]
+                        * inv_l_minus_1
+                    )
+
+                    data[ptr + idx_curr] = f1 * data[ptr_minus_1 + idx_prev]
+
+                # Logic for m = +(l-1)
+                m = l - 1
+                if abs(m) <= m_lim:
+                    idx_curr = m + m_lim
+                    idx_prev = m + m_lim_prev
+                    f1 = (
+                        (2 * l - 1)
+                        * (l * (l - 1) * cos_theta - m * n)
+                        * sqrt_inv[l - n]
+                        * sqrt_inv[l + n]
+                        * sqrt_inv[l - m]
+                        * sqrt_inv[l + m]
+                        * inv_l_minus_1
+                    )
+
+                    data[ptr + idx_curr] = f1 * data[ptr_minus_1 + idx_prev]
+
+            # 3. Fill Outer Boundaries (m = -l and m = +l)
+            if m_lim == l:
+                val_min, val_max = _wigner_start_values(l, n, theta)
+                data[ptr] = val_min
+                data[ptr + row_len - 1] = val_max
+
+    # 4. Optional: Orthogonal Normalization (Matches GSHTrans::Ortho)
+    #    Multiply by sqrt(2l+1) / sqrt(4pi) ?
+    #    Your C++ code multiplies by (inv_sqrt_pi / 2) * sqrt(2l+1)
+    #    We apply this to match your output exactly.
+    inv_sqrt_pi = 0.5641895835477563
+    factor = inv_sqrt_pi / 2.0
+
+    for l in range(n_abs, l_max + 1):
+        norm_factor = factor * np.sqrt(2 * l + 1)
+        start = offsets[l]
+        end = start + (2 * min(l, m_max) + 1)
+        data[start:end] *= norm_factor
+
+    return data, offsets
+
+
+class WignerRecursion:
+    def __init__(self, l_max, m_max, n):
+        self.l_max = l_max
+        self.m_max = m_max
+        self.n = n
+
+        # JIT compile immediately with dummy data to avoid lag on first real use
+        compute_wigner_d_recursive(1, 1, 0, 0.1)
+
+    def compute(self, theta):
+        """
+        Computes Wigner elements for angle theta.
+        Returns:
+            data (np.array): Flat array of coefficients.
+            offsets (np.array): Indices where each degree l starts.
+        """
+        return compute_wigner_d_recursive(self.l_max, self.m_max, self.n, theta)
+
+    def get_index(self, l, m, offsets):
+        """Helper to find index in flat array"""
+        if l < abs(self.n) or l > self.l_max:
+            return -1
+        m_lim = min(l, self.m_max)
+        if abs(m) > m_lim:
+            return -1
+        # Offset + (m - m_min) where m_min is -m_lim
+        return offsets[l] + (m + m_lim)

{pygeoinf-1.3.9 → pygeoinf-1.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "pygeoinf"
-version = "1.3.9"
+version = "1.4.0"
 description = "A package for solving geophysical inference and inverse problems"
 authors = ["David Al-Attar and Dan Heathcote"]
 readme = "README.md"
@@ -18,6 +18,7 @@ joblib = "^1.5.2"
 pyshtools = { version = ">=4.0.0", optional = true }
 Cartopy = { version = "^0.23.0", optional = true }
 threadpoolctl = "^3.6.0"
+numba = "^0.63.1"
 
 [tool.poetry.extras]
 sphere = ["pyshtools", "Cartopy"]
@@ -53,3 +54,5 @@ build-backend = "poetry.core.masonry.api"
 # harmonic degree, ignore the ambiguous variable name warning (E741).
 "pygeoinf/symmetric_space/sphere.py" = ["E741"]
 "pygeoinf/symmetric_space/sh_tools.py" = ["E741"]
+"pygeoinf/symmetric_space/wigner.py" = ["E741"]
+"pygeoinf/rough_work/*" = ["E741"]