SimPEG: finite volume simulation and inversion for geophysics

What problem SimPEG is built around

SimPEG stands for Simulation and Parameter Estimation in Geophysics, and the repository description calls it a Python package for simulation and gradient based parameter estimation in the context of geophysical applications. The stated vision is to create a package for finite volume simulation with applications to geophysical imaging and subsurface flow. The features list sets out how that vision is realised. The package is modular with respect to the spatial discretisation, the optimisation routine and the geophysical problem, and it is built with the inverse problem in mind. It provides a framework for geophysical and hydrogeologic problems, supports 1D, 2D and 3D problems, and is designed for large scale inversions. That last phrase is the one to sit with, because a full inversion over a large mesh with many parameters is not a calculation you do interactively, and the design choices follow from that.

The modular decomposition: discretisation, optimisation, problem

The modularity claim is the technical heart of the project, and it is worth spelling out because it is what lets different geophysical methods share machinery. The spatial discretisation is one axis of the modularity, and the pyproject.toml shows that the mesh code lives in a separate package, discretize, at version 0.12 or newer, with geoana at 0.8.1 providing the geometry and coordinate handling. The optimisation routine is the second axis, and the dependency on pymatsolver at 0.3 or newer is the sparse solver layer that a gradient based inversion leans on when it assembles and factors the sensitivity matrix. The geophysical problem itself is the third, which is the part that varies most between a magnetostatic survey and a direct current resistivity line. The support for 1D, 2D and 3D problems follows from the same structure. It is a design that keeps the hard linear algebra in shared code and the physics in per-method code, which is the opposite of a monolithic script and the reason the same inversion code can serve both a magnetics survey and a DC resistivity survey.

The physics that ships as examples

The examples directory is the clearest map of what SimPEG can actually model, and the numbering is a survey of methods. There are examples for maps, gravity, magnetics, direct current resistivity as 04-dcip, frequency domain electromagnetics as 05-fdem, time domain electromagnetics as 06-tdem, natural source electromagnetics as 07-nsem, a version of the resistivity method as 08-vrm, flow as 09-flow, and induced polarization as 10-pgi, plus a 20-published directory for work that has appeared in the literature and an _archived directory. The topic list on the repository matches: direct-current-resistivity, electromagnetics, induced-polarization, magnetotellurics, multiphysics, richards-equation for subsurface flow, and the inverse-problems and optimization vocabulary that goes with them. The finite-volume tag in the topic list is the implementation detail that connects the method list to the package structure, and the multiphysics tag points at the direction the framework is being pushed, joining physics rather than solving one field in isolation.

Installing it, and the dependency floor it sets

The package is published on PyPI as simpeg and on conda-forge, and the README badges point at both channels. The pyproject.toml is where the constraints are stated, and the first one is significant: requires-python is 3.12 or newer, which is a recent floor and will exclude a lot of existing scientific Python environments. The runtime dependencies are numpy at 1.22 or newer, scipy at 1.12 or newer, pymatsolver, matplotlib, discretize, geoana and libdlf, with typing_extensions pulled in only on Python versions below 3.13. Optional dependency groups cover the extensions: dask brings dask, zarr and fsspec for out of core data, choclo provides the electromagnetic forward modelling kernels, reporting uses scooby, plotting adds plotly, sklearn adds scikit-learn, pandas adds pandas, and an all group combines the optional runtime dependencies. The style group pins black at 26.3.1 and flake8 at 7.0.0 with several plugins, which tells you the project enforces formatting rather than leaving it to reviewers.

Running the style and build checks yourself

The Makefile at the repository root is a thin wrapper around the project's own tooling, and it is short enough to read in full. The default check target runs the black, flake, ruff and check-actions targets in sequence.

check: black flake ruff check-actions

The individual targets call the tools directly on the same set of paths, which the Makefile sets as simpeg, examples, tutorials and tests, and the docs target builds the Sphinx documentation with make html inside the docs directory.

docs:
	cd docs;make html

There is a separate target for linting the GitHub Actions workflows themselves with zizmor, which is a habit worth noting, because workflow files are executable code that often escapes review.

How the project is organised, and how it is tested

The repository root tells you how this is a research project with a community around it rather than a single author's library. Alongside the simpeg/ package there is a docs/ directory with its own makefile, an examples/ directory, a tutorials/ directory, and tests/. The build metadata is unusual in a good way: the pyproject.toml uses setuptools_scm, so the version is derived from the git tags, with dynamic = ["version"], and there is a .git_archival.txt file for source archives. Continuous integration runs on Azure Pipelines, with the badge pointing at a pipeline definition on the main branch, and Codecov tracks coverage. There is also a Zenodo DOI badge, which is how the package gets a citable archive for the scientific record, and the repository carries AUTHORS.rst and CITATION.rst, which is a level of formality in the attribution that most packages do not maintain.

Citing the framework, and where the questions go

The README asks users to cite a paper, and there are two. The main one is Cockett, Kang, Heagy, Pidlisecky and Oldenburg from 2015, SimPEG: An open source framework for simulation and gradient based parameter estimation in geophysical applications, in Computers and Geosciences, and the README gives the BibTex for it. If you use the electromagnetics module, there is a second: Heagy, Cockett, Kang, Rosenkjaer and Oldenburg from 2017, A framework for simulation and inversion in electromagnetics, in the same journal, volume 107, pages 1 to 19, with a DOI. The distribution of questions is also documented. If you have a question about a specific use of SimPEG, the fastest route is the Discourse forum at simpeg.discourse.group, or the Mattermost team at mattermost.softwareunderground.org/simpeg for real time chat, and the README asks explicitly that you do not create an issue to ask a question. Weekly meetings are held on Wednesdays at 3:00 PM Pacific Time, with calendar links provided.

The limits, and what it is the wrong tool for

Three things to weigh before adopting. The first is the Python floor of 3.12, which rules out many locked down scientific environments and makes it a package for teams that can move. The second is the honest boundary of the domain: this is a geophysical and hydrogeologic inversion framework, and if your problem is a general PDE inversion outside those fields you are working against the library's assumptions rather than with them, even though the modular structure means the physics can in principle be replaced. The third is the computational cost of what the package is designed for, since a large scale inversion over a fine mesh with many parameters is a long run that needs a cluster and a lot of memory, and the dask and zarr extras exist precisely because the data does not fit on one machine. The alternative to weigh is writing the forward simulation for your specific survey in the numerical library of your choice and using a general purpose optimiser, which keeps the code small and loses the shared sensitivity machinery that makes the gradient based approach practical in the first place.

Editorial conclusion

Adopt SimPEG if you are solving a geophysical or hydrogeologic inverse problem and want the forward simulation, the gradients and the optimisation loop in one framework, because the package is built with the inverse problem in mind and exposes both the discretisation and the solver as swappable pieces. Do not adopt it for a one-off forward calculation where a smaller script would do, and note that it requires Python 3.12 or newer. Before you start, read the paper the README asks you to cite, since the framework and its assumptions are described there, and decide which of the optional dependency groups you need, such as dask, choclo, plotting or sklearn.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. simpeg/simpeg on GitHub