pygeoinf: A Python Library for Geophysical Inference
pygeoinf is a Python library for solving geophysical inference and inverse problems in a coordinate-free, abstract framework. It leverages the mathematics of Hilbert spaces to provide a robust and flexible foundation for Bayesian and optimisation-based inference.
Overview
The core philosophy of pygeoinf is to separate the abstract mathematical structure of an inverse problem from its concrete numerical implementation. Instead of manipulating NumPy arrays directly, you work with high-level objects like HilbertSpace, LinearOperator, and GaussianMeasure. This allows you to write code that is more readable, less error-prone, and closer to the underlying mathematics.
The library is built on a few key concepts:
HilbertSpace: The foundational class. It represents a vector space with an inner product, but it abstracts away the specific representation of vectors (e.g., NumPy arrays,pyshtoolsgrids).LinearOperator: Represents linear mappings between Hilbert spaces. These are the workhorses of the library, supporting composition, adjoints, and matrix representations.GaussianMeasure: Generalizes the multivariate normal distribution to abstract Hilbert spaces, providing a way to define priors and noise models.ForwardProblem: Encapsulates the mathematical modeld = A(u) + e, linking the unknown modeluto the observed datad.- Inversion Classes: High-level classes like
LinearBayesianInversionandLinearLeastSquaresInversionprovide ready-to-use algorithms for solving the inverse problem.
Key Features
- Abstract Coordinate-Free Formulation: Write elegant code that mirrors the mathematics of inverse problems.
- Bayesian Inference: Solve inverse problems in a probabilistic framework to obtain posterior distributions over models.
- Optimisation Methods: Includes Tikhonov-regularized least-squares and minimum-norm solutions.
- Extensive Solver Suite: Choose from direct factorisations or matrix-free iterative solvers (e.g., CG, MINRES, LSQR, BiCGStab, FCG) designed for abstract vectors.
- Coupled Systems: Effortlessly build block matrices and direct sum spaces using
HilbertSpaceDirectSumfor joint inversions. - Geometric Constraints: Constrain your inversions using affine subspaces, bounds, and convex sublevel sets.
- Probabilistic Modelling: Define priors and noise models using
GaussianMeasureobjects 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
SparseMatrixLinearOperatorandDiagonalSparseMatrixLinearOperator - Application-Specific Spaces: Provides concrete
HilbertSpaceimplementations for functions on a line, circle, and the two-sphere. - High-Quality Visualisation: Built-in plotting methods for functions on symmetric spaces, now featuring multi-dimensional corner plots for joint posterior distributions.
Advanced Features
- Block Operators: Construct complex operators from smaller components using
BlockLinearOperator,ColumnLinearOperator, andRowLinearOperator. 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. By default, this will perform a minimal installation.
# 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.
# Installation with sphere-related features
pip install pygeoinf[sphere]
For development, you can clone the repository and install using Poetry:
git clone https://github.com/da380/pygeoinf.git
cd pygeoinf
poetry install
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.
# Install all development dependencies (for tests, docs, and tutorials)
poetry install --with dev
Documentation
The full documentation for the library, including the API reference and tutorials, is available at pygeoinf.readthedocs.io.
Tutorials
You can run the interactive tutorials directly in Google Colab to get started with the core concepts of the library.
| Tutorial Name | Link to Colab |
|---|---|
| Tutorial 1 - A first example |  |
| Tutorial 2 - Hilbert spaces | |
| Tutorial 3 - Dual spaces | |
| Tutorial 4 - Linear operators | |
| Tutorial 5 - Linear solvers | |
| Tutorial 6 - Gaussian measures | |
| Tutorial 7 - Minimum norm inversions | |
| Tutorial 8 - Bayesian inversions | |
| Tutorial 9 - Direct sums | |
| Tutorial 10 - Symmetric spaces | |
Contributing
Contributions are welcome! If you would like to contribute, please feel free to fork the repository, make your changes, and submit a pull request. For major changes, please open an issue first to discuss what you would like to change.
License
This project is licensed under the BSD-3-Clause License - see the LICENSE file for details.
1 maintainer
Release files for pygeoinf 1.8.5
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| pygeoinf-1.8.5.tar.gz | 263.4 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| pygeoinf-1.8.5-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 558.2 kB
Release files / pygeoinf-1.8.5.tar.gz
| Download URL | pygeoinf-1.8.5.tar.gz |
|---|---|
| Size | 263.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
47221424fb76b2ddff5c890933f13eddafb13a3e1a5dbc0566cfd1ddd897b936
|
|
BLAKE2b-256 checksum How to use checksums |
6b2d62128fb492b7e71ecbeac7dcb40336245bbb555a20cc9d1e51e1d92e04de
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.4.1 CPython/3.12.13 Linux/6.17.0-1020-azure
|
Release files / pygeoinf-1.8.5-py3-none-any.whl
| Download URL | pygeoinf-1.8.5-py3-none-any.whl |
|---|---|
| Size | 294.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
993cb118bba965d3498243db4f199722c72dffc7f430ef71868726ababa0fb82
|
|
BLAKE2b-256 checksum How to use checksums |
56c0b373141679fb0a93b862b541026915740ecd96e433e4fbb424504caa8e76
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.4.1 CPython/3.12.13 Linux/6.17.0-1020-azure
|
