OpenPNM models porous media as a graph and then solves flow on it

A pore network turns a 3D mesh into a graph of pores and throats

The framing in the repository description is the whole approach: OpenPNM is a package for performing pore network modeling of porous media, and the package metadata describes it as a framework for conducting pore network modeling simulations of multiphase transport in porous media. The topics give the same picture in one line each, with network-graph, porous-media, modeling-tool and scientific-computing. The mechanism is a reduction. A real porous medium is a continuous 3D geometry with voids and solid walls, and simulating fluid flow through that directly is expensive. Pore network modeling replaces the geometry with a graph: the voids become nodes, the narrow connections between them become edges called throats, and the fluid phases are properties attached to the nodes. Flow is then solved on the graph rather than in the volume. That is what makes the framework tractable and also what defines its limits, since everything the simulation knows about the medium comes from the extracted network, and a network that misrepresents the pore structure produces a confidently wrong answer. The framework is used across the topics listed for it, and the site is openpnm.org with the documentation hosted from the same organisation.

pip and conda-forge both carry the package, and developers install in editable mode

Installation is the easy part, and the documentation offers three routes. The PyPI route is a single command:

pip install openpnm

The conda-forge route is the other supported option, and the documentation recommends it as the way to get the Scipy stack, which OpenPNM requires and which the Anaconda Distribution provides most conveniently:

conda install conda-forge::openpnm

For anyone changing the source or contributing, the third route installs the downloaded tree in editable mode:

pip install -e 'path/to/downloaded/files'

The stated advantage of that last route is that you can edit the files and see your changes each time you import OpenPNM. The requirements are explicit in the project metadata, which pins Python to `>=3.11,<3.14`, and the classifier list marks the project as a production and stable release with an operating system classified as independent. The dependency list is long and worth reading before you commit, because it defines the real footprint: numpy, scipy, pandas, matplotlib, networkx, scikit-image, sympy, numba, llvmlite, h5py, jsonschema, docrep, rich, tqdm, transforms3d, pyamg and thermo are all required, with pypardiso pulled in only on non-Darwin x86_64 or AMD64 machines.

macOS on Intel is no longer supported, and the reason is a dependency

The installation notes carry a warning that is easy to miss and expensive to discover late, because it is a note rather than a headline. The documentation states that macOS on x86_64, meaning Intel systems, is no longer supported, and gives the reason: a few dependencies, `triangle` among them, are no longer maintained there, and that breaks the build. It adds that these packages are mostly optional, so if you need OpenPNM on that platform you can still build it from source. That qualification matters. A hard build failure on a laptop where the only local Python is an Intel conda environment is a common way to lose an afternoon, and the fix is available but manual. The packaging metadata also shows the platform-dependency handling in a more compact form, with pypardiso declared only when the platform system is not Darwin and the machine is x86_64 or AMD64, which is the same idea expressed in a dependency marker: the direct sparse solver is provided on the platforms where it can be, and skipped where it cannot. The `extras` optional group adds porespy and ngsolve, which suggests the package is designed to interoperate with the surrounding porous media toolset rather than stand alone.

The examples directory is where you learn the API, and it is organised by intent

The repository layout is a good guide to how the framework expects to be used. The `examples/` directory is split into `applications/`, `contrib/`, `reference/`, `tutorials/` and a `getting_started.ipynb` notebook, and the readme's description of what OpenPNM is for is matched by this structure. Reference notebooks and paper recreations are separated from tutorials and from applications, which is a convention that respects a specific scientific audience: a researcher usually wants to know how to reproduce a published result before they want to know how to build a new simulation. The Makefile makes the notebooks part of the test process rather than a separate concern. There is an `nbtest` target that runs the example notebooks with pytest under the `--nbval-lax` flag, and it explicitly ignores two directories, `examples/paper_recreations/Blunt et al. (2013)` and `examples/paper_recreations/Wu et al. (2010)`, so the recreation of those two papers is excluded from the routine run. That is a small but revealing detail: recreating a published paper is hard enough to automate that the project carves it out of its own test target, which is exactly the kind of honest scoping you want to see in a scientific package.

Two pytest targets and a nightly workflow, plus a dev branch as the default

The default branch is `dev`, not `main`, and the version in the project metadata is `3.6.4-dev1`, which is the detail that tells you how this project is developed. The tagged releases run behind it, with v3.6.0 and v3.6.1 both published on 2026-03-01 and v3.5.5 on 2025-11-15. The `dev` branch is where the next version is assembled, and the presence of a VERSIONING.md file at the root suggests the scheme is written down rather than folklore. The testing is split into two Makefile targets. The `test` target runs the unit tests and ignores the scripts directory, and the `nbtest` target runs the notebooks instead

with the two paper recreation directories excluded. Both are driven by pytest.ini, whose configuration sets the minimum version to 6.0, adds the `--assert=plain` and `-ra -v` options, ignores the docs configuration file, and collects files matching `*.py` with classes named `*Test` and functions named `test_*`, with the test paths set to `test` and `examples`. The continuous integration side is marked by a nightly workflow badge and a codecov badge against the `dev` branch, so coverage is tracked on the development line rather than only on releases.

A peer-reviewed citation is the request, and that sets the expectations

The documentation asks that if you use OpenPNM in a publication you cite a specific paper, Gostick and co-authors, OpenPNM: a pore network modeling package, published in Computing in Science and Engineering, volume 18, number 4, pages 60 to 74, with a DOI. A CITATION.cff file sits at the root for the same purpose. This detail says more about the project than any feature list, because it marks the difference between a code library and a research instrument. A framework that is meant to appear in a peer-reviewed paper has to be citable, versioned, and stable in its numerical behaviour, which is what the production and stable classifier, the tagged releases and the nightly coverage all point toward. The readme also asks that you star the repository so the developers can track the number of users, which it says helps in securing future grant funding, and that is a fair description of how the project is sustained. It is developed by the Porous Materials Engineering and Analysis Lab, PMEAL, in the Department of Chemical Engineering at the University of Waterloo, and the lead developer is named as Prof. Jeff Gostick.

What the framework does not model, and where a different tool fits

The boundary of the abstraction is the limitation to keep in view. A pore network is a reduced representation, and the reduction is a modelling decision rather than a numerical detail, so results depend on how faithfully the extracted network captures the pore structure. For a medium with well-connected pores and a clear void phase, that reduction is defensible and fast. For a medium where the continuum matters, where capillary effects at the solid interface dominate, or where you need to resolve a local boundary condition in space rather than in the graph, a network model answers a different question from the one you are asking. The package description itself says multiphase transport, and the dependency on thermo tells you phase properties come from that library rather than from a built-in fluid database, which is another place where your own choices matter. The alternative to weigh against is a continuum-based approach that solves the flow equations on a voxelised or unstructured representation of the same geometry, keeping the geometry rather than the graph. The difference in approach is exactly the reduction: one keeps the pore space and pays for it in mesh size and solver cost, the other keeps the connectivity and pays for it in how well the extraction is done. Which one is right depends on whether the question is about network-scale behaviour, where OpenPNM's abstraction pays off, or about the geometry itself, where it does not.

Editorial conclusion

OpenPNM is a sound choice for a chemical engineering group that already thinks in terms of pore networks, because it ships the extraction, the network topology, the phase properties and the solvers as one MIT licensed package with a nightly test workflow, and because the examples directory includes reference notebooks and paper recreations to check a result against. It is a poor fit for someone who wants a continuum-scale simulation of a porous medium, since the network is an abstraction of the geometry rather than the geometry itself, and a poor fit if your environment is Intel macOS, which the documentation says is no longer supported. Before adopting it, check that your meshes can be extracted into a network, read the `examples/reference/` notebooks against your own case before trusting a result, and note that the last push to the repository was on 2026-07-21 with the development branch carrying version 3.6.4-dev1.

Frequently asked questions

Official sources

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