pygeoinf 1.2.6__py3-none-any.whl → 1.2.8__py3-none-any.whl

pygeoinf/linear_solvers.py

@@ -239,6 +239,18 @@ class IterativeLinearSolver(LinearSolver):
     An abstract base class for iterative linear solvers.
     """
 
+    def __init__(self, /, *, preconditioning_method: LinearSolver = None) -> None:
+        """
+        Args:
+            preconditioning_method: A LinearSolver from which to generate a preconditioner
+                once the operator is known.
+
+        Notes:
+            If a preconditioner is provided to either the call or solve_linear_system
+            methods, then it takes precedence over the preconditioning method.
+        """
+        self._preconditioning_method = preconditioning_method
+
     @abstractmethod
     def solve_linear_system(
         self,
@@ -263,16 +275,13 @@ class IterativeLinearSolver(LinearSolver):
     def solve_adjoint_linear_system(
         self,
         operator: LinearOperator,
-        preconditioner: Optional[LinearOperator],
+        adjoint_preconditioner: Optional[LinearOperator],
         x: Vector,
         y0: Optional[Vector],
     ) -> Vector:
         """
         Solves the adjoint linear system A*y = x for y.
         """
-        adjoint_preconditioner = (
-            None if preconditioner is None else preconditioner.adjoint
-        )
         return self.solve_linear_system(operator.adjoint, adjoint_preconditioner, x, y0)
 
     def __call__(
@@ -295,12 +304,27 @@ class IterativeLinearSolver(LinearSolver):
                 original operator.
         """
         assert operator.is_automorphism
+
+        if preconditioner is None:
+            if self._preconditioning_method is None:
+                _preconditioner = None
+                _adjoint_preconditions = None
+            else:
+                _preconditioner = self._preconditioning_method(operator)
+        else:
+            _preconditioner = preconditioner
+
+        if _preconditioner is None:
+            _adjoint_preconditioner = None
+        else:
+            _adjoint_preconditioner = _preconditioner.adjoint
+
         return LinearOperator(
             operator.codomain,
             operator.domain,
-            lambda y: self.solve_linear_system(operator, preconditioner, y, None),
+            lambda y: self.solve_linear_system(operator, _preconditioner, y, None),
             adjoint_mapping=lambda x: self.solve_adjoint_linear_system(
-                operator, preconditioner, x, None
+                operator, _adjoint_preconditioner, x, None
             ),
         )
 
@@ -327,6 +351,7 @@ class ScipyIterativeSolver(IterativeLinearSolver):
         method: str,
         /,
         *,
+        preconditioning_method: LinearSolver = None,
         galerkin: bool = False,
         **kwargs,
     ) -> None:
@@ -337,6 +362,9 @@ class ScipyIterativeSolver(IterativeLinearSolver):
             **kwargs: Keyword arguments to be passed directly to the SciPy solver
                 (e.g., rtol, atol, maxiter, restart).
         """
+
+        super().__init__(preconditioning_method=preconditioning_method)
+
         if method not in self._SOLVER_MAP:
             raise ValueError(
                 f"Unknown solver method '{method}'. Available methods: {list(self._SOLVER_MAP.keys())}"
@@ -410,6 +438,7 @@ class CGSolver(IterativeLinearSolver):
         self,
         /,
         *,
+        preconditioning_method: LinearSolver = None,
         rtol: float = 1.0e-5,
         atol: float = 0.0,
         maxiter: Optional[int] = None,
@@ -423,6 +452,9 @@ class CGSolver(IterativeLinearSolver):
             callback (callable, optional): User-supplied function to call
                 after each iteration with the current solution vector.
         """
+
+        super().__init__(preconditioning_method=preconditioning_method)
+
         if not rtol > 0:
             raise ValueError("rtol must be positive")
         self._rtol: float = rtol
@@ -463,7 +495,7 @@ class CGSolver(IterativeLinearSolver):
 
         num = domain.inner_product(r, z)
 
-        for i in range(maxiter):
+        for _ in range(maxiter):
             # Check for convergence
             if domain.squared_norm(r) <= tol_sq:
                 break

pygeoinf/random_matrix.py

@@ -385,3 +385,117 @@ def random_cholesky(
         cholesky_factor = temp_factor * sqrt_s_inv
 
         return cholesky_factor
+
+
+def random_diagonal(
+    matrix: MatrixLike,
+    size_estimate: int,
+    /,
+    *,
+    method: str = "variable",
+    use_rademacher: bool = False,
+    max_samples: int = None,
+    rtol: float = 1e-2,
+    block_size: int = 10,
+    parallel: bool = False,
+    n_jobs: int = -1,
+) -> np.ndarray:
+    """
+    Computes an approximate diagonal of a square matrix using Hutchinson's method.
+
+    This algorithm uses a progressive, iterative approach to estimate the diagonal.
+    It starts with an initial number of samples and adds new blocks of random
+    vectors until the estimate of the diagonal converges to a specified tolerance.
+
+    Args:
+        matrix: The (m, n) matrix or LinearOperator to analyze.
+        size_estimate: For 'fixed' method, the exact target rank. For 'variable'
+                       method, this is the initial rank to sample.
+        method ({'variable', 'fixed'}): The algorithm to use.
+            - 'variable': (Default) Progressively samples to find the rank needed
+                          to meet tolerance `rtol`, stopping at `max_rank`.
+            - 'fixed': Returns a basis with exactly `size_estimate` columns.
+        use_rademacher: If true, draw components from [-1,1]. Default method draws
+            normally distributed components.
+        max_samples: For 'variable' method, a hard limit on the number of samples.
+                     Ignored if method='fixed'. Defaults to dimension of matrix.
+        rtol: Relative tolerance for the 'variable' method. Ignored if
+              method='fixed'.
+        block_size: Number of new vectors to sample per iteration in 'variable'
+                    method. Ignored if method='fixed'.
+        parallel: Whether to use parallel matrix multiplication.
+        n_jobs: Number of jobs for parallelism.
+
+    Returns:
+        A 1D numpy array of size n containing the approximate diagonal of the matrix.
+    """
+
+    m, n = matrix.shape
+    if m != n:
+        raise ValueError("Input matrix must be square to estimate a diagonal.")
+
+    if max_samples is None:
+        max_samples = n
+
+    num_samples = min(size_estimate, max_samples)
+    if use_rademacher:
+        z = np.random.choice([-1.0, 1.0], size=(n, num_samples))
+    else:
+        z = np.random.randn(n, num_samples)
+
+    if parallel:
+        az = parallel_mat_mat(matrix, z, n_jobs)
+    else:
+        az = matrix @ z
+
+    diag_sum = np.sum(z * az, axis=1)
+    diag_estimate = diag_sum / num_samples
+
+    if method == "fixed":
+        return diag_estimate
+
+    if num_samples >= max_samples:
+        return diag_estimate
+
+    converged = False
+    while num_samples < max_samples:
+        old_diag_estimate = diag_estimate.copy()
+
+        # Generate a NEW block of random vectors
+        samples_to_add = min(block_size, max_samples - num_samples)
+        if use_rademacher:
+            z_new = np.random.choice([-1.0, 1.0], size=(n, samples_to_add))
+        else:
+            z_new = np.random.randn(n, samples_to_add)
+
+        if parallel:
+            az_new = parallel_mat_mat(matrix, z_new, n_jobs)
+        else:
+            az_new = matrix @ z_new
+
+        new_diag_sum = np.sum(z_new * az_new, axis=1)
+
+        # Update the running average
+        total_samples = num_samples + samples_to_add
+        diag_estimate = (diag_sum + new_diag_sum) / total_samples
+
+        # Check for convergence
+        norm_new_diag = np.linalg.norm(diag_estimate)
+        if norm_new_diag > 0:
+            error = np.linalg.norm(diag_estimate - old_diag_estimate) / norm_new_diag
+            if error < rtol:
+                converged = True
+                break
+
+        # Update sums and counts for next iteration
+        diag_sum += new_diag_sum
+        num_samples = total_samples
+
+    if not converged and num_samples >= max_samples:
+        warnings.warn(
+            f"Tolerance {rtol} not met before reaching max_samples={max_samples}. "
+            "Result may be inaccurate. Consider increasing `max_samples` or `rtol`.",
+            UserWarning,
+        )
+
+    return diag_estimate

{pygeoinf-1.2.6.dist-info → pygeoinf-1.2.8.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: pygeoinf
-Version: 1.2.6
+Version: 1.2.8
 Summary: A package for solving geophysical inference and inverse problems
 License: BSD-3-Clause
 Author: David Al-Attar and Dan Heathcote
@@ -64,22 +64,15 @@ git clone https://github.com/da380/pygeoinf.git
 cd pygeoinf
 poetry install
 ```
-
-You can install the optional dependencies for running tests, building documentation, or running the tutorials by using the --with flag.
+You can install all optional dependencies for development—including tools for running the test suite, 
+building the documentation, and running the Jupyter tutorials—by using the ```--with``` flag and specifying the ```dev``` group.
 
 ```bash
-# To install dependencies for running the test suite
-poetry install --with tests
-
-# To install dependencies for building the documentation
-poetry install --with docs
+# Install all development dependencies (for tests, docs, and tutorials)
+poetry install --with dev
+```
 
-# To install dependencies for running the Jupyter tutorials
-poetry install --with tutorials
 
-# You can also combine them
-poetry install --with tests,docs,tutorials
-```
 
 ## Documentation
 
@@ -245,9 +238,9 @@ The output of the above script will look similar to the following figure:
 
 ## Future Plans
 
-`pygeoinf` is under active development. Future work will focus on expanding the library's capabilities to address a broader range of geophysical problems. Key areas for development include:
+`pygeoinf` is under active development. Current work is focused on expanding the library's capabilities to address a broader range of geophysical problems. Key areas for development include:
 
-* **Generalised Backus-Gilbert Methods**: Implementation of a generalised Backus-Gilbert framework for linear inference problems, building on the work of [Al-Attar(2021)](https://arxiv.org/abs/2104.12256). The focus will be on constructing direct estimates of specific properties of interest (i.e., linear functionals of the model) from data, without needing to first solve for the full model itself.
+* **Generalised Backus-Gilbert Methods**: Implementation of a generalised Backus-Gilbert framework for linear inference problems. The focus will be on constructing direct estimates of specific properties of interest (i.e., linear functionals of the model) from data, without needing to first solve for the full model itself.
 
 * **Non-linear Optimisation**: Extension of the current optimisation framework to handle non-linear inverse problems. This will involve creating a general interface where users can provide their own non-linear forward mapping, a misfit functional, and methods for computing gradients (and optionally Hessians) for use in gradient-based optimisation algorithms.
 

{pygeoinf-1.2.6.dist-info → pygeoinf-1.2.8.dist-info}/RECORD

@@ -1,28 +1,28 @@
-pygeoinf/__init__.py,sha256=r5dumZhCLtuk9I-YXFDKnXB8t1gzjmgmjazkbqrZQpQ,1505
+pygeoinf/__init__.py,sha256=pV9UXNrRXAIagU4eTmHf2Qi0CtVgOp0sqLnltgBFoKc,1650
 pygeoinf/backus_gilbert.py,sha256=vpIWvryUIy6pHWhT9A4bVB3A9MuTll1MyN9U8zmVI5c,3783
 pygeoinf/checks/hilbert_space.py,sha256=Kr7PcOGrNIISezty0FBj5uXavIHC91yjCp2FVGNlHeE,7931
 pygeoinf/checks/linear_operators.py,sha256=RkmtAW6e5Zr6EuhX6GAt_pI0IWu2WZ-CrfjSBN_7dsU,4664
 pygeoinf/checks/nonlinear_operators.py,sha256=Rn9LTftyw5eGU3akx6xYNUJVGvX9J6gyTEXVFgLfYqs,5601
 pygeoinf/direct_sum.py,sha256=1RHPJI_PoEvSRH9AmjX-v88IkSW4uT2rPSt5pmZQEZY,19377
 pygeoinf/forward_problem.py,sha256=NnqWp7iMfkhHa9d-jBHzYHClaAfhKmO5D058AcJLLYg,10724
-pygeoinf/gaussian_measure.py,sha256=EOUyBYT-K9u2ZD_uwPXDv17BJHk-L0RM55jfIR-DmXY,24020
+pygeoinf/gaussian_measure.py,sha256=zYpvQ29jBpWE2tDTF1rXZQiSICDuoxizVP4ZJr1k6Fk,23665
 pygeoinf/hilbert_space.py,sha256=0NCCG-OOHysdXYEFUs1wtJhGgOnuKvjZCZg8NJZO-DA,25331
 pygeoinf/inversion.py,sha256=RV0hG2bGnciWdja0oOPKPxnFhYzufqdj-mKYNr4JJ_o,6447
 pygeoinf/linear_bayesian.py,sha256=L1cJkeHtba4fPXZ8CmiLRBtuG2fmzG228M_iEar-iP8,9643
 pygeoinf/linear_forms.py,sha256=sgynBvlQ35CaH12PKU2vWPHh9ikrmQbD5IASCUQtlbw,9197
-pygeoinf/linear_operators.py,sha256=p03t2Azvdd4gakJws-myYDYDthyEskylsg6wODKbzJk,36424
+pygeoinf/linear_operators.py,sha256=HToie5nllV0PQFa-QzETtIPKveWnt2dkWiaWTJa6fTw,64577
 pygeoinf/linear_optimisation.py,sha256=UbSr6AOPpR2sRYoN1Pvv24-Zu7_XlJk1zE1IhQu83hg,12428
-pygeoinf/linear_solvers.py,sha256=mPhPiWKW82WHul_tfc0Xf-Y0GRtZQcPxfwEsWXh9G6M,15706
+pygeoinf/linear_solvers.py,sha256=v-7yjKsa67Ts5EcyJzCdpj-aF0qBrA-akq0kLe59DS4,16843
 pygeoinf/nonlinear_forms.py,sha256=eQudA-HfedbURvRmzVvU8HfNCxHTuWUpdDoWe_KlA4Y,7067
 pygeoinf/nonlinear_operators.py,sha256=X4_UMV1Rn4MqorjfN4P_UTckzCb4Gy1XceR3Ix8G4F8,7170
 pygeoinf/nonlinear_optimisation.py,sha256=skK1ikn9GrVYherD64Qt9WrEYHA2NAJ48msOu_J8Oig,7431
 pygeoinf/parallel.py,sha256=VVFvNHszy4wSa9LuErIsch4NAkLaZezhdN9YpRROBJo,2267
-pygeoinf/random_matrix.py,sha256=afEUFuoVbkFobhC9Jy9SuGb4Yib-fn3pQyiWUqXrA-8,13629
+pygeoinf/random_matrix.py,sha256=71l6eAXQ2pRMleaz1lXud6O1F78ugKyp3vHcRBXhdwM,17661
 pygeoinf/symmetric_space/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 pygeoinf/symmetric_space/circle.py,sha256=7Bz9BfSkbDnoz5-HFwTsAQE4a09jUapBePwoCK0xYWw,18007
 pygeoinf/symmetric_space/sphere.py,sha256=5elw48I8A2i5EuRyYnm4craVp-ZB2_bBy9QQ15GytxE,23144
 pygeoinf/symmetric_space/symmetric_space.py,sha256=Q3KtfCtHO0_8LjsdKtH-5WVhRQurt5Bdk4yx1D2F5YY,17977
-pygeoinf-1.2.6.dist-info/LICENSE,sha256=GrTQnKJemVi69FSbHprq60KN0OJGsOSR-joQoTq-oD8,1501
-pygeoinf-1.2.6.dist-info/METADATA,sha256=HJkNlabCyoWvQ9Ogvwp2PPIUX1-jJKTyN1glD706FtQ,15376
-pygeoinf-1.2.6.dist-info/WHEEL,sha256=IYZQI976HJqqOpQU6PHkJ8fb3tMNBFjg-Cn-pwAbaFM,88
-pygeoinf-1.2.6.dist-info/RECORD,,
+pygeoinf-1.2.8.dist-info/LICENSE,sha256=GrTQnKJemVi69FSbHprq60KN0OJGsOSR-joQoTq-oD8,1501
+pygeoinf-1.2.8.dist-info/METADATA,sha256=BLWdHc9FE8C4X7L0y9xHAdQfY3_pkzljiNPIPZAqfH4,15169
+pygeoinf-1.2.8.dist-info/WHEEL,sha256=IYZQI976HJqqOpQU6PHkJ8fb3tMNBFjg-Cn-pwAbaFM,88
+pygeoinf-1.2.8.dist-info/RECORD,,