pygeoinf 1.2.7__tar.gz → 1.2.9__tar.gz

{pygeoinf-1.2.7 → pygeoinf-1.2.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: pygeoinf
-Version: 1.2.7
+Version: 1.2.9
 Summary: A package for solving geophysical inference and inverse problems
 License: BSD-3-Clause
 Author: David Al-Attar and Dan Heathcote
@@ -10,12 +10,11 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
-Requires-Dist: Cartopy (>=0.23.0,<0.24.0)
+Provides-Extra: sphere
 Requires-Dist: joblib (>=1.5.2,<2.0.0)
 Requires-Dist: matplotlib (>=3.0.0)
 Requires-Dist: numpy (>=1.26.0)
 Requires-Dist: pyqt6 (>=6.0.0)
-Requires-Dist: pyshtools (>=4.0.0)
 Requires-Dist: scipy (>=1.16.1)
 Description-Content-Type: text/markdown
 
@@ -47,16 +46,31 @@ The library is built on a few key concepts:
 * **Optimisation Methods**: Includes Tikhonov-regularized least-squares and minimum-norm solutions.
 * **Probabilistic Modelling**: Define priors and noise models using `GaussianMeasure` objects on abstract spaces.
 * **Randomized Algorithms**: Utilizes randomized SVD and Cholesky decompositions for efficient low-rank approximations of large operators.
+* **Specialized Operator Variants**: Efficient implementations for `DiagonalSparseMatrixLinearOperator` and `NormalSumOperator`.
 * **Application-Specific Spaces**: Provides concrete `HilbertSpace` implementations for functions on a **line**, **circle**, and the **two-sphere**.
 * **High-Quality Visualisation**: Built-in plotting methods for functions on symmetric spaces, including map projections via `cartopy`.
 
+## Advanced Features
+
+* **Block Operators**: Construct complex operators from smaller components using `BlockLinearOperator`, `ColumnLinearOperator`, and `RowLinearOperator`. This is ideal for coupled inverse problems.
+* **Parallelisation**: Many expensive operations are parallelized with `joblib`, including dense matrix construction and randomized algorithms.
+
 ## Installation
 
-The package can be installed directly using pip:
+The package can be installed directly using pip. By default, this will perform a minimal installation.
 
 ```bash
+# Minimal installation
 pip install pygeoinf
 ```
+
+To include the functionality for functions on the sphere, you can install the `sphere` extra. This provides support for `pyshtools` and `Cartopy`.
+
+```bash
+# Installation with sphere-related features
+pip install pygeoinf[sphere]
+```
+
 For development, you can clone the repository and install using Poetry:
 
 ```bash
@@ -65,21 +79,15 @@ 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
+# Install all development dependencies (for tests, docs, and tutorials)
+poetry install --with dev
+```
 
-# To install dependencies for building the documentation
-poetry install --with docs
 
-# To install dependencies for running the Jupyter tutorials
-poetry install --with tutorials
-
-# You can also combine them
-poetry install --with tests,docs,tutorials
-```
 
 ## Documentation
 
@@ -240,20 +248,30 @@ The output of the above script will look similar to the following figure:
 * NumPy
 * SciPy
 * Matplotlib
-* pyshtools (for `sphere.py`)
-* Cartopy (for plotting in `sphere.py`)
+* joblib
 
-## Future Plans
+### Optional (`sphere`)
+
+* pyshtools
+* Cartopy
+
+## Recent Updates
 
-`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, and recent updates have expanded its capabilities to address a broader range of geophysical problems. Key improvements 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.
+* **Non-Linear Inverse Problems**: The library now supports non-linear inverse problems through the `NonLinearOperator` and `NonLinearForm` classes. This allows you to define and solve problems where the relationship between model parameters and data is non-linear. The framework includes support for Fréchet derivatives, enabling the use of gradient-based optimisation methods.
+
+* **Advanced Optimisation Algorithms**: To complement the non-linear framework, `pygeoinf` now includes a suite of optimisation algorithms. You can use the custom `GradientDescent` solver or leverage the power of SciPy's optimization library with methods like 'BFGS', 'L-BFGS-B', and 'Newton-CG'. Derivative-free methods such as 'Powell' and 'Nelder-Mead' are also supported for problems where gradients are unavailable.
+
+* **Backus-Gilbert Methods**: The foundations for the Backus-Gilbert method have been implemented. While this feature is still evolving, the core components are in place for you to begin exploring this powerful inference technique.
+
+## Future Plans
 
-* **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.
+Future development will focus on the following areas:
 
-* **Non-linear Bayesian Inference**: Development of methods for non-linear Bayesian problems. Planned approaches include linearizing the problem around the maximum a posteriori (MAP) solution to estimate posterior uncertainty, and using this linearization to construct efficient proposal distributions for Markov chain Monte Carlo (MCMC) sampling methods.
+* **Non-linear Bayesian Inference**: We plan to develop methods for non-linear Bayesian problems, including techniques for linearizing the problem around the maximum a posteriori (MAP) solution to estimate posterior uncertainty. This will also involve constructing efficient proposal distributions for Markov chain Monte Carlo (MCMC) sampling methods.
 
-* **New Geophysical Hilbert Spaces**: Addition of further `HilbertSpace` implementations tailored to specific geophysical applications. A primary focus will be on creating spaces for functions defined within a **spherical annulus** (spherical shell), which is essential for problems in global seismology and mantle tomography.
+* **New Geophysical Hilbert Spaces**: We will be adding more `HilbertSpace` implementations for specific geophysical applications. A key focus will be on creating spaces for functions defined within a **spherical annulus** (spherical shell), which is crucial for problems in global seismology and mantle tomography.
 
 
 ## Contributing

{pygeoinf-1.2.7 → pygeoinf-1.2.9}/README.md

@@ -26,16 +26,31 @@ The library is built on a few key concepts:
 * **Optimisation Methods**: Includes Tikhonov-regularized least-squares and minimum-norm solutions.
 * **Probabilistic Modelling**: Define priors and noise models using `GaussianMeasure` objects on abstract spaces.
 * **Randomized Algorithms**: Utilizes randomized SVD and Cholesky decompositions for efficient low-rank approximations of large operators.
+* **Specialized Operator Variants**: Efficient implementations for `DiagonalSparseMatrixLinearOperator` and `NormalSumOperator`.
 * **Application-Specific Spaces**: Provides concrete `HilbertSpace` implementations for functions on a **line**, **circle**, and the **two-sphere**.
 * **High-Quality Visualisation**: Built-in plotting methods for functions on symmetric spaces, including map projections via `cartopy`.
 
+## Advanced Features
+
+* **Block Operators**: Construct complex operators from smaller components using `BlockLinearOperator`, `ColumnLinearOperator`, and `RowLinearOperator`. This is ideal for coupled inverse problems.
+* **Parallelisation**: Many expensive operations are parallelized with `joblib`, including dense matrix construction and randomized algorithms.
+
 ## Installation
 
-The package can be installed directly using pip:
+The package can be installed directly using pip. By default, this will perform a minimal installation.
 
 ```bash
+# Minimal installation
 pip install pygeoinf
 ```
+
+To include the functionality for functions on the sphere, you can install the `sphere` extra. This provides support for `pyshtools` and `Cartopy`.
+
+```bash
+# Installation with sphere-related features
+pip install pygeoinf[sphere]
+```
+
 For development, you can clone the repository and install using Poetry:
 
 ```bash
@@ -44,21 +59,15 @@ 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
+# Install all development dependencies (for tests, docs, and tutorials)
+poetry install --with dev
+```
 
-# To install dependencies for building the documentation
-poetry install --with docs
 
-# To install dependencies for running the Jupyter tutorials
-poetry install --with tutorials
-
-# You can also combine them
-poetry install --with tests,docs,tutorials
-```
 
 ## Documentation
 
@@ -219,20 +228,30 @@ The output of the above script will look similar to the following figure:
 * NumPy
 * SciPy
 * Matplotlib
-* pyshtools (for `sphere.py`)
-* Cartopy (for plotting in `sphere.py`)
+* joblib
 
-## Future Plans
+### Optional (`sphere`)
+
+* pyshtools
+* Cartopy
+
+## Recent Updates
 
-`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, and recent updates have expanded its capabilities to address a broader range of geophysical problems. Key improvements 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.
+* **Non-Linear Inverse Problems**: The library now supports non-linear inverse problems through the `NonLinearOperator` and `NonLinearForm` classes. This allows you to define and solve problems where the relationship between model parameters and data is non-linear. The framework includes support for Fréchet derivatives, enabling the use of gradient-based optimisation methods.
+
+* **Advanced Optimisation Algorithms**: To complement the non-linear framework, `pygeoinf` now includes a suite of optimisation algorithms. You can use the custom `GradientDescent` solver or leverage the power of SciPy's optimization library with methods like 'BFGS', 'L-BFGS-B', and 'Newton-CG'. Derivative-free methods such as 'Powell' and 'Nelder-Mead' are also supported for problems where gradients are unavailable.
+
+* **Backus-Gilbert Methods**: The foundations for the Backus-Gilbert method have been implemented. While this feature is still evolving, the core components are in place for you to begin exploring this powerful inference technique.
+
+## Future Plans
 
-* **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.
+Future development will focus on the following areas:
 
-* **Non-linear Bayesian Inference**: Development of methods for non-linear Bayesian problems. Planned approaches include linearizing the problem around the maximum a posteriori (MAP) solution to estimate posterior uncertainty, and using this linearization to construct efficient proposal distributions for Markov chain Monte Carlo (MCMC) sampling methods.
+* **Non-linear Bayesian Inference**: We plan to develop methods for non-linear Bayesian problems, including techniques for linearizing the problem around the maximum a posteriori (MAP) solution to estimate posterior uncertainty. This will also involve constructing efficient proposal distributions for Markov chain Monte Carlo (MCMC) sampling methods.
 
-* **New Geophysical Hilbert Spaces**: Addition of further `HilbertSpace` implementations tailored to specific geophysical applications. A primary focus will be on creating spaces for functions defined within a **spherical annulus** (spherical shell), which is essential for problems in global seismology and mantle tomography.
+* **New Geophysical Hilbert Spaces**: We will be adding more `HilbertSpace` implementations for specific geophysical applications. A key focus will be on creating spaces for functions defined within a **spherical annulus** (spherical shell), which is crucial for problems in global seismology and mantle tomography.
 
 
 ## Contributing

{pygeoinf-1.2.7 → pygeoinf-1.2.9}/pygeoinf/__init__.py

@@ -9,6 +9,7 @@ from .random_matrix import (
     random_svd,
     random_eig,
     random_cholesky,
+    random_diagonal,
 )
 
 from .hilbert_space import (
@@ -32,7 +33,14 @@ from .linear_forms import (
 
 from .nonlinear_operators import NonLinearOperator
 
-from .linear_operators import LinearOperator, DiagonalLinearOperator, NormalSumOperator
+from .linear_operators import (
+    LinearOperator,
+    MatrixLinearOperator,
+    DenseMatrixLinearOperator,
+    SparseMatrixLinearOperator,
+    DiagonalSparseMatrixLinearOperator,
+    NormalSumOperator,
+)
 
 
 from .gaussian_measure import (

{pygeoinf-1.2.7 → pygeoinf-1.2.9}/pygeoinf/gaussian_measure.py

@@ -28,11 +28,11 @@ from scipy.sparse import diags
 from scipy.stats import multivariate_normal
 
 
-from .hilbert_space import EuclideanSpace, HilbertModule
+from .hilbert_space import EuclideanSpace, HilbertModule, Vector
 
 from .linear_operators import (
     LinearOperator,
-    DiagonalLinearOperator,
+    DiagonalSparseMatrixLinearOperator,
 )
 
 from .direct_sum import (
@@ -40,17 +40,6 @@ from .direct_sum import (
 )
 
 
-# This block only runs for type checkers, not at runtime, to prevent
-# circular import errors while still allowing type hints.
-if TYPE_CHECKING:
-    from .hilbert_space import HilbertSpace, EuclideanSpace
-    from .operators import LinearOperator, DiagonalLinearOperator
-    from .direct_sum import BlockDiagonalLinearOperator
-
-# Define a generic type for vectors in a Hilbert space
-Vector = TypeVar("Vector")
-
-
 class GaussianMeasure:
     """
     Represents a Gaussian measure on a Hilbert space.
@@ -76,29 +65,29 @@ class GaussianMeasure:
         inverse_covariance_factor: LinearOperator = None,
     ) -> None:
         """
-        Initializes the GaussianMeasure.
+         Initializes the GaussianMeasure.
 
         The measure can be defined in several ways, primarily by providing
-        either a covariance operator or a covariance factor.
-
-        Args:
-            covariance (LinearOperator, optional): A self-adjoint and positive
-                semi-definite linear operator on the domain.
-            covariance_factor (LinearOperator, optional): A linear operator L
-                such that the covariance C = L @ L*.
-            expectation (vector, optional): The expectation (mean) of the
-                measure. Defaults to the zero vector of the space.
-            sample (callable, optional): A function that returns a random
-                sample from the measure. If a `covariance_factor` is given,
-                a default sampler is created.
-            inverse_covariance (LinearOperator, optional): The inverse of the
-                covariance operator (the precision operator).
-            inverse_covariance_factor (LinearOperator, optional): A factor Li
-                of the inverse covariance, such that C_inv = Li.T @ Li.
-
-        Raises:
-            ValueError: If neither `covariance` nor `covariance_factor`
-                is provided.
+         either a covariance operator or a covariance factor.
+
+         Args:
+             covariance (LinearOperator, optional): A self-adjoint and positive
+                 semi-definite linear operator on the domain.
+             covariance_factor (LinearOperator, optional): A linear operator L
+                 such that the covariance C = L @ L*.
+             expectation (vector, optional): The expectation (mean) of the
+                 measure. Defaults to the zero vector of the space.
+             sample (callable, optional): A function that returns a random
+                 sample from the measure. If a `covariance_factor` is given,
+                 a default sampler is created.
+             inverse_covariance (LinearOperator, optional): The inverse of the
+                 covariance operator (the precision operator).
+             inverse_covariance_factor (LinearOperator, optional): A factor Li
+                 of the inverse covariance, such that C_inv = Li.T @ Li.
+
+         Raises:
+             ValueError: If neither `covariance` nor `covariance_factor`
+                 is provided.
         """
         if covariance is None and covariance_factor is None:
             raise ValueError(
@@ -186,7 +175,7 @@ class GaussianMeasure:
                 "Standard deviation vector does not have the correct length"
             )
         euclidean = EuclideanSpace(domain.dim)
-        covariance_factor = DiagonalLinearOperator(
+        covariance_factor = DiagonalSparseMatrixLinearOperator.from_diagonal_values(
             euclidean, domain, standard_deviations
         )
         return GaussianMeasure(