pygeoinf 1.3.7__py3-none-any.whl → 1.3.9__py3-none-any.whl

pygeoinf/subspaces.py

@@ -1,18 +1,22 @@
 """
-Defines classes for representing affine and linear subspaces.
+Defines classes for representing affine and linear subspaces, including
+hyperplanes and half-spaces.
 
 The primary abstraction is the `AffineSubspace`, which represents a subset of
 a Hilbert space defined by a translation and a closed linear tangent space.
+This module integrates with the `subset` module, allowing subspaces to be
+treated as standard geometric sets.
 """
 
 from __future__ import annotations
 from typing import List, Optional, Any, Callable, TYPE_CHECKING
-import numpy as np
 import warnings
+import numpy as np
 
 from .linear_operators import LinearOperator
 from .hilbert_space import HilbertSpace, Vector, EuclideanSpace
 from .linear_solvers import LinearSolver, CholeskySolver, IterativeLinearSolver
+from .subsets import Subset, EmptySet
 
 if TYPE_CHECKING:
     from .gaussian_measure import GaussianMeasure
@@ -30,12 +34,26 @@ class OrthogonalProjector(LinearOperator):
         mapping: Callable[[Any], Any],
         complement_projector: Optional[LinearOperator] = None,
     ) -> None:
+        """
+        Initializes the orthogonal projector.
+
+        Args:
+            domain: The Hilbert space on which the projector acts.
+            mapping: The function implementing the projection P(x).
+            complement_projector: An optional LinearOperator representing (I - P).
+                If provided, it avoids re-computing the complement when requested.
+        """
         super().__init__(domain, domain, mapping, adjoint_mapping=mapping)
         self._complement_projector = complement_projector
 
     @property
     def complement(self) -> LinearOperator:
-        """Returns the projector onto the orthogonal complement (I - P)."""
+        """
+        Returns the projector onto the orthogonal complement (I - P).
+
+        If a complement projector was not provided at initialization, one is
+        constructed automatically as the difference between the identity and self.
+        """
         if self._complement_projector is None:
             identity = self.domain.identity_operator()
             self._complement_projector = identity - self
@@ -48,7 +66,19 @@ class OrthogonalProjector(LinearOperator):
         basis_vectors: List[Vector],
         orthonormalize: bool = True,
     ) -> OrthogonalProjector:
-        """Constructs a projector P onto the span of the provided basis vectors."""
+        """
+        Constructs a projector P onto the span of the provided basis vectors.
+
+        Args:
+            domain: The Hilbert space.
+            basis_vectors: A list of vectors spanning the subspace.
+            orthonormalize: If True, performs Gram-Schmidt orthonormalization
+                on the basis vectors before constructing the projector.
+                If False, assumes the basis is already orthonormal.
+
+        Returns:
+            An OrthogonalProjector instance.
+        """
         if not basis_vectors:
             return domain.zero_operator(domain)
 
@@ -62,9 +92,14 @@ class OrthogonalProjector(LinearOperator):
         return cls(domain, tensor_op)
 
 
-class AffineSubspace:
+class AffineSubspace(Subset):
     """
     Represents an affine subspace A = x0 + V.
+
+    This class serves two primary roles:
+    1. A geometric subset that can project points and check membership.
+    2. A constraint definition for Bayesian inversion (conditioning a Gaussian
+       measure on the subspace).
     """
 
     def __init__(
@@ -78,7 +113,19 @@ class AffineSubspace:
     ) -> None:
         """
         Initializes the AffineSubspace.
+
+        Args:
+            projector: The orthogonal projector P onto the tangent space V.
+            translation: A vector x0 in the subspace. Defaults to the origin.
+            constraint_operator: The operator B defining the subspace implicitly
+                as {u | B(u) = w}. Used for Bayesian conditioning.
+            constraint_value: The RHS vector w for the implicit definition.
+            solver: A LinearSolver used to invert the constraint operator during
+                conditioning. If None, defaults to a CholeskySolver if an
+                explicit constraint operator is provided.
+            preconditioner: An optional preconditioner for iterative solvers.
         """
+        super().__init__(projector.domain)
         self._projector = projector
 
         if translation is None:
@@ -100,20 +147,24 @@ class AffineSubspace:
 
         self._preconditioner = preconditioner
 
-    @property
-    def domain(self) -> HilbertSpace:
-        return self._projector.domain
-
     @property
     def translation(self) -> Vector:
+        """Returns the translation vector x0."""
         return self._translation
 
     @property
     def projector(self) -> OrthogonalProjector:
+        """Returns the orthogonal projector P onto the tangent space."""
         return self._projector
 
+    @property
+    def solver(self) -> Optional[LinearSolver]:
+        """Returns the linear solver associated with this subspace."""
+        return self._solver
+
     @property
     def tangent_space(self) -> LinearSubspace:
+        """Returns the LinearSubspace V parallel to this affine subspace."""
         return LinearSubspace(self._projector)
 
     @property
@@ -124,8 +175,10 @@ class AffineSubspace:
     @property
     def constraint_operator(self) -> LinearOperator:
         """
-        Returns B for {u | B(u)=w}.
-        Falls back to (I - P) if no explicit operator exists.
+        Returns the operator B defining the subspace as {u | B(u)=w}.
+
+        If no explicit operator was provided (geometric construction), this
+        falls back to the complement projector (I - P).
         """
         if self._constraint_operator is None:
             return self._projector.complement
@@ -134,8 +187,9 @@ class AffineSubspace:
     @property
     def constraint_value(self) -> Vector:
         """
-        Returns w for {u | B(u)=w}.
-        Falls back to (I - P)x0 if no explicit operator exists.
+        Returns the value w defining the subspace as {u | B(u)=w}.
+
+        If no explicit operator was provided, this falls back to (I - P)x0.
         """
         if self._constraint_value is None:
             complement = self._projector.complement
@@ -143,25 +197,66 @@ class AffineSubspace:
         return self._constraint_value
 
     def project(self, x: Vector) -> Vector:
-        """Orthogonally projects x onto the affine subspace."""
+        """
+        Orthogonally projects a vector x onto the affine subspace.
+
+        Formula: P_A(x) = P(x - x0) + x0
+        """
         diff = self.domain.subtract(x, self.translation)
         proj_diff = self.projector(diff)
         return self.domain.add(self.translation, proj_diff)
 
-    def is_element(self, x: Vector, rtol: float = 1e-6) -> bool:
-        """Returns True if x lies in the subspace."""
+    def is_element(self, x: Vector, /, *, rtol: float = 1e-6) -> bool:
+        """
+        Returns True if the vector x lies within the subspace.
+
+        Checks if the projection residual ||x - P_A(x)|| is small relative
+        to the norm of x (or 1.0).
+
+        Args:
+            x: The vector to check.
+            rtol: Relative tolerance for the residual check.
+        """
         proj = self.project(x)
         diff = self.domain.subtract(x, proj)
         norm_diff = self.domain.norm(diff)
+
+        # Scale tolerance by norm of x to handle units/scaling, consistent with Sphere/Ball
         norm_x = self.domain.norm(x)
-        scale = norm_x if norm_x > 1e-12 else 1.0
+        scale = max(1.0, norm_x)
         return norm_diff <= rtol * scale
 
+    @property
+    def boundary(self) -> Subset:
+        """
+        Returns the boundary of the affine subspace.
+
+        Geometrically, an affine subspace (like a line or plane) is a closed
+        manifold without a boundary. Returns EmptySet.
+        """
+        return EmptySet(self.domain)
+
     def condition_gaussian_measure(
         self, prior: GaussianMeasure, geometric: bool = False
     ) -> GaussianMeasure:
         """
         Conditions a Gaussian measure on this subspace.
+
+        Args:
+            prior: The prior Gaussian measure.
+            geometric: If True, performs a geometric projection of the measure
+                (equivalent to conditioning on "measurement = truth" with infinite
+                precision, effectively squashing the distribution onto the
+                subspace).
+                If False (default), performs standard Bayesian conditioning
+                using the constraint equation B(u) = w.
+
+        Returns:
+            The posterior (conditioned) GaussianMeasure.
+
+        Raises:
+            ValueError: If geometric=False and the subspace was constructed
+                without a solver capable of handling the constraint operator.
         """
         if geometric:
             # Geometric Projection: u -> P(u - x0) + x0
@@ -183,7 +278,7 @@ class AffineSubspace:
                     "AffineSubspace constructor."
                 )
 
-            # Local imports
+            # Local imports to avoid circular dependency
             from .forward_problem import LinearForwardProblem
             from .linear_bayesian import LinearBayesianInversion
 
@@ -205,7 +300,16 @@ class AffineSubspace:
         solver: Optional[LinearSolver] = None,
         preconditioner: Optional[LinearOperator] = None,
     ) -> AffineSubspace:
-        """Constructs subspace from B(u)=w."""
+        """
+        Constructs a subspace defined by the linear equation B(u) = w.
+
+        Args:
+            operator: The linear operator B.
+            value: The RHS vector w.
+            solver: Solver used to invert the Gram matrix (B B*) during
+                construction and later conditioning. Defaults to CholeskySolver.
+            preconditioner: Optional preconditioner for iterative solvers.
+        """
         domain = operator.domain
         G = operator @ operator.adjoint
 
@@ -284,8 +388,16 @@ class AffineSubspace:
         orthonormalize: bool = True,
     ) -> AffineSubspace:
         """
-        Constructs subspace from complement basis.
-        Constraint is explicit: <u, e_i> = <x0, e_i>.
+        Constructs a subspace defined by orthogonality to a set of complement basis vectors.
+
+        The subspace is defined as {u | <u - x0, v_i> = 0} for all v_i in basis.
+        This provides an explicit constraint operator B where B(u)_i = <u, v_i>.
+
+        Args:
+            domain: The Hilbert space.
+            basis_vectors: Basis vectors for the orthogonal complement.
+            translation: A point x0 in the subspace.
+            orthonormalize: If True, orthonormalizes the complement basis.
         """
         if orthonormalize:
             e_vectors = domain.gram_schmidt(basis_vectors)
@@ -342,13 +454,23 @@ class LinearSubspace(AffineSubspace):
     """
 
     def __init__(self, projector: OrthogonalProjector) -> None:
+        """
+        Initializes the LinearSubspace.
+
+        Args:
+            projector: The orthogonal projector P onto the subspace.
+        """
         super().__init__(projector, translation=None)
 
     @property
     def complement(self) -> LinearSubspace:
+        """
+        Returns the orthogonal complement of this subspace as a new LinearSubspace.
+        """
         op_perp = self.projector.complement
         if isinstance(op_perp, OrthogonalProjector):
             return LinearSubspace(op_perp)
+        # Wrap if the complement isn't strictly an OrthogonalProjector instance
         p_perp = OrthogonalProjector(self.domain, op_perp._mapping)
         return LinearSubspace(p_perp)
 
@@ -359,13 +481,22 @@ class LinearSubspace(AffineSubspace):
         solver: Optional[LinearSolver] = None,
         preconditioner: Optional[LinearOperator] = None,
     ) -> LinearSubspace:
+        """
+        Constructs the subspace corresponding to the kernel (null space) of an operator.
+        K = {u | A(u) = 0}.
+
+        Args:
+            operator: The operator A.
+            solver: Solver used for the Gram matrix (A A*).
+            preconditioner: Optional preconditioner.
+        """
         affine = AffineSubspace.from_linear_equation(
             operator, operator.codomain.zero, solver, preconditioner
         )
         instance = cls(affine.projector)
         instance._constraint_operator = operator
         instance._constraint_value = operator.codomain.zero
-        instance._solver = affine._solver
+        instance._solver = affine.solver
         instance._preconditioner = preconditioner
         return instance
 
@@ -378,6 +509,16 @@ class LinearSubspace(AffineSubspace):
         solver: Optional[LinearSolver] = None,
         preconditioner: Optional[LinearOperator] = None,
     ) -> LinearSubspace:
+        """
+        Constructs a linear subspace from a set of basis vectors.
+
+        Args:
+            domain: The Hilbert space.
+            basis_vectors: List of vectors spanning the subspace.
+            orthonormalize: Whether to orthonormalize the basis.
+            solver: Optional solver for implicit constraints (see AffineSubspace.from_tangent_basis).
+            preconditioner: Optional preconditioner.
+        """
         projector = OrthogonalProjector.from_basis(
             domain, basis_vectors, orthonormalize=orthonormalize
         )
@@ -393,11 +534,20 @@ class LinearSubspace(AffineSubspace):
         basis_vectors: List[Vector],
         orthonormalize: bool = True,
     ) -> LinearSubspace:
+        """
+        Constructs a linear subspace defined by orthogonality to a complement basis.
+        S = {u | <u, v_i> = 0}.
+
+        Args:
+            domain: The Hilbert space.
+            basis_vectors: Basis vectors for the complement.
+            orthonormalize: Whether to orthonormalize the complement basis.
+        """
         affine = AffineSubspace.from_complement_basis(
             domain, basis_vectors, translation=None, orthonormalize=orthonormalize
         )
         instance = cls(affine.projector)
         instance._constraint_operator = affine.constraint_operator
         instance._constraint_value = affine.constraint_value
-        instance._solver = affine._solver
+        instance._solver = affine.solver
         return instance

pygeoinf/symmetric_space/sphere.py

@@ -691,7 +691,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/utils.py

@@ -0,0 +1,15 @@
+from threadpoolctl import threadpool_limits
+
+
+def configure_threading(n_threads: int = 1):
+    """
+    Sets the maximum number of threads used by underlying linear algebra
+    backends (MKL, OpenBLAS, etc.).
+
+    Args:
+        n_threads: The number of threads to allow.
+                   Set to 1 for serial execution (safe for multiprocessing).
+                   Set to -1 or None to use all available cores.
+    """
+    threadpool_limits(limits=n_threads)
+    print(f"Backend threading restricted to {n_threads} thread(s).")

{pygeoinf-1.3.7.dist-info → pygeoinf-1.3.9.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pygeoinf
-Version: 1.3.7
+Version: 1.3.9
 Summary: A package for solving geophysical inference and inverse problems
 License: BSD-3-Clause
 License-File: LICENSE
@@ -20,6 +20,7 @@ Requires-Dist: numpy (>=1.26.0)
 Requires-Dist: pyqt6 (>=6.0.0)
 Requires-Dist: pyshtools (>=4.0.0) ; extra == "sphere"
 Requires-Dist: scipy (>=1.16.1)
+Requires-Dist: threadpoolctl (>=3.6.0,<4.0.0)
 Description-Content-Type: text/markdown
 
 # pygeoinf: A Python Library for Geophysical Inference

{pygeoinf-1.3.7.dist-info → pygeoinf-1.3.9.dist-info}/RECORD

@@ -1,4 +1,4 @@
-pygeoinf/__init__.py,sha256=OdtIgD3aF4LQ4UzponWblw4nQihRntqnni7m1DPdd5I,4076
+pygeoinf/__init__.py,sha256=vLr6Mx7aSFc3Gtntyt29f7eYx79UAEVuKV2GznCQjNI,4808
 pygeoinf/auxiliary.py,sha256=lfoTt9ZH4y8SAV8dKZi5EWx1oF_JtxtBMSmlFYqJYfE,1610
 pygeoinf/backus_gilbert.py,sha256=eFi4blSwOCsg_NuH6WD4gcgjvzvu5g5WpWahGobSBdM,3694
 pygeoinf/checks/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -7,7 +7,7 @@ pygeoinf/checks/linear_operators.py,sha256=945ECCM7nEPuE00_5Tb8o2pG5IYbNtDSqwKNh
 pygeoinf/checks/nonlinear_operators.py,sha256=pFHQrbQslrbBM9J_p1-4TQoETsupVICKtTtKFSWBfsk,7533
 pygeoinf/direct_sum.py,sha256=7V0qrwFGj0GN-p_zzffefPrIB0dPu5dshLTxem1mQGE,19274
 pygeoinf/forward_problem.py,sha256=NnqWp7iMfkhHa9d-jBHzYHClaAfhKmO5D058AcJLLYg,10724
-pygeoinf/gaussian_measure.py,sha256=bBh64xHgmLFl27krn9hkf8qDQjop_39x69cyhJgUHN8,26219
+pygeoinf/gaussian_measure.py,sha256=RVwBJSilzluOibjdvhBsJ2YUm4_rgjRk9fNLsjirUy0,27222
 pygeoinf/hilbert_space.py,sha256=Yc0Jw0A8Jo12Zpgb_9dhcF7CD77S1IDMrSTDFHpTRB8,27340
 pygeoinf/inversion.py,sha256=RV0hG2bGnciWdja0oOPKPxnFhYzufqdj-mKYNr4JJ_o,6447
 pygeoinf/linear_bayesian.py,sha256=qzWEVaNe9AwG5GBmGHgVHswEMFKBWvOOJDlS95ahyxc,8877
@@ -19,16 +19,18 @@ pygeoinf/nonlinear_forms.py,sha256=t7lk-Bha7Xdk9eiwXMmS0F47oTR6jW6qQ3HkgRGk54A,7
 pygeoinf/nonlinear_operators.py,sha256=AtkDTQfGDzAnfFDIgiKfdk7uPEI-j_ZA3CNvY5A3U8w,7144
 pygeoinf/nonlinear_optimisation.py,sha256=skK1ikn9GrVYherD64Qt9WrEYHA2NAJ48msOu_J8Oig,7431
 pygeoinf/parallel.py,sha256=VVFvNHszy4wSa9LuErIsch4NAkLaZezhdN9YpRROBJo,2267
-pygeoinf/plot.py,sha256=Uw9PCdxymUiAkFF0BS0kUAZBRWL6sh89FJnSIxtp_2s,13664
-pygeoinf/preconditioners.py,sha256=81PnzoQZzsf5mvXBYsHuadf1CdiGFlMbQn_tC2xPQ1k,4503
+pygeoinf/plot.py,sha256=kc63kIo55bmwTM1Mu0fSDJoR8I98F69ma_OrK6QK7xs,14310
+pygeoinf/preconditioners.py,sha256=B4sBQefWpK_SovkbX0Y2LVFLUgRE-JX-iMhUDscyW5U,4504
 pygeoinf/random_matrix.py,sha256=-U_3-yrVos_86EfNy1flULsWY-Y9G9Yy1GKoSS2gn60,17828
-pygeoinf/subspaces.py,sha256=FJobjDRr8JG1zz-TjBsncJ1M5phQYwbttlaGuJz9ycU,13779
+pygeoinf/subsets.py,sha256=jp25hdQ9rsZ7cckMJFiXLSx554dgBwtqwnRWi8AsUOY,26029
+pygeoinf/subspaces.py,sha256=oPSZx2B07kg2SRQEVk8bBWXnGqvXuJngC0PFiSij78M,19949
 pygeoinf/symmetric_space/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 pygeoinf/symmetric_space/circle.py,sha256=GuwVmLdHGTMxMrZfyXIPP3pz_y971ntlD5pl42lKJZ0,18796
 pygeoinf/symmetric_space/sh_tools.py,sha256=EDZm0YRZefvCfDjAKZatZMM3UqeTi-Npiflnc1E5slk,3884
-pygeoinf/symmetric_space/sphere.py,sha256=wYaZ2wqkQAHw9pn4vP_6LR9HAXSpzCncCh24xmSSC5A,28481
+pygeoinf/symmetric_space/sphere.py,sha256=-H2PQxwTLI-AyzNaRgEKF62Z_oTYa_Mw_iHxfws7oGc,28494
 pygeoinf/symmetric_space/symmetric_space.py,sha256=pEIZZYWsdegrYCwUs3bo86JTz3d2LsXFWdRYFa0syFs,17963
-pygeoinf-1.3.7.dist-info/METADATA,sha256=rJugIyw0YNv6ccIFCnXNmISbwUclP-V8Zt1ZDLbqPpw,16482
-pygeoinf-1.3.7.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
-pygeoinf-1.3.7.dist-info/licenses/LICENSE,sha256=GrTQnKJemVi69FSbHprq60KN0OJGsOSR-joQoTq-oD8,1501
-pygeoinf-1.3.7.dist-info/RECORD,,
+pygeoinf/utils.py,sha256=UIrO5w2aenzENryuZUYxg6q3MQqk0rFTgbhl_FY10V0,529
+pygeoinf-1.3.9.dist-info/METADATA,sha256=sijNo47xI0AoFtPRVVZYyC9NYKCM-RypsluzG8Zwt5E,16528
+pygeoinf-1.3.9.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+pygeoinf-1.3.9.dist-info/licenses/LICENSE,sha256=GrTQnKJemVi69FSbHprq60KN0OJGsOSR-joQoTq-oD8,1501
+pygeoinf-1.3.9.dist-info/RECORD,,