A Python package for performing pore network modeling of porous media


https://travis-ci.org/PMEAL/OpenPNM.svg?branch=master https://readthedocs.org/projects/openpnm/badge/?version=latest

Overview of OpenPNM

OpenPNM is an open source project aiming to provide porous media researchers with a ready-made framework for performing a wide range of pore network simulations. The main features and capabilities of OpenPNM are:

Defines a universal means of representing any network topology based on a sparse representation of the adjacency matrix - Includes network generators for creating cubic or random networks with arbitrary connectivity
Provides a set of tools for querying, inspecting, and manipulating topology - Including finding neighboring pores, labeling specific locations, adding or removing pores and throats, joining networks, subdividing and merging pores to create multiscale models, and much more
Stores pore and throat property data in vectorized format - Allows for fast calculations even on large networks - Supports the familiar and advanced array access features such as direct indexing, slicing, Boolean masking, etc.
A mechanism for calculating the pore-scale properties that define the geometrical (i.e. pore radius), thermophysical (i.e. viscosity), and physics (i.e. hydraulic conductance) properties of the simulation - The interdependence of some properties on other properties is naturally included so values can be regenerated when changes occur (i.e. viscosity can be updated when temperature changed) - This mechanism was designed to allow users to easily create new customized pore-scale models suitable for their specific domain - A wide assortment of pore-scale transport parameter, pore size calculations, and thermophysical property models are included
A suite of algorithms for performing network simulations - Including invasion percolation, capillary drainage, mass diffusion, permeability and so on.
Supports saving, loading, importing and exporting data in numerous formats - Allows importing networks generated or extracted by other code, as well as exporting data for post-processing and visualization - Saving and loading of simulations allows for batch processing of simulations to be analyzed at a later point

Example Usage

The following code block illustrates how to use OpenPNM to perform a mercury intrusion porosimetry simulation in just 10 lines:

>>> import OpenPNM as op
>>> pn = op.Network.Cubic(shape=[10, 10, 10], spacing=0.0001)
>>> geo = op.Geometry.Stick_and_Ball(network=pn, pores=pn.Ps,
...                                  throats=pn.Ts)
>>> Hg = op.Phases.Mercury(network=pn)
>>> Air = op.Phases.Air(network=pn)
>>> phys = op.Physics.Standard(network=pn, phase=Hg, pores=pn.Ps,
...                            throats=pn.Ts)
>>> MIP = op.Algorithms.Drainage(network=pn)
>>> MIP.setup(invading_phase=Hg, defending_phase=Air)
>>> MIP.set_inlets(pores=pn.pores(['top', 'bottom']))
>>> MIP.run()

The network can be visualized in Paraview giving the following:


The drainage curve can be visualized with MIP.plot_drainage_curve() giving something like this:


A collection of examples is available as a separate Github repository: OpenPNM-Examples.


OpenPNM can be installed from the Python Package index using:

pip install openpnm

Or the source code can be downloaded from Github and installed by running:

python setup.py

Release Management and Versioning

OpenPNM uses Semantic Versioning (i.e. X.Y.Z) to label releases. All major and minor versions (X.Y.z) are available on PyPI, but bugfixes (x.y.Z) updates are not generally pushed unless the bug is particularly egregious.

OpenPNM uses the Github Flow system of Git branching. Any code added to master is done via Pull Requests (PRs). When new PRs are merged into the master branch, they are generally not given a new version number. Once enough new features have been added, or a sufficient amount of time has passed, the minor release number (x.Y.z) will be incremented. Any code added to the Master branch between incrementing the version number is subject to change, but once a version number has been tagged to code can be considered up-to-date and stable.

OpenPNM depends on several other packages widely known as the Scipy Stack. It is our policy to always support the latest version of all these packages and their dependencies.

The main developer for this project is Prof. Jeff Gostick (jgostick@gmail.com).

Related Links

OpenPNM Homepage - http://openpnm.org
Github is used to host the code - https://www.github.com/PMEAL/OpenPNM
Github is also used as the project's issue and bug tracker - https://www.github.com/PMEAL/OpenPNM/issues
A collection of examples using OpenPNM is available in a separate repository - https://www.github.com/PMEAL/OpenPNM-Examples
The documentation is hosted on ReadTheDocs - http://openpnm.readthedocs.org/
Gitter is used to help users with questions about using the code - https://gitter.im/PMEAL/OpenPNM
Scipy is a major component of OpenPNM - http://www.scipy.org
Anaconda is the most general way to setup a numerical Python environment - https://www.continuum.io/downloads
WinPython is a slightly easier way to use numerical Python on Windows - https://github.com/winpython/winpython
Spyder is the recommended IDE when working with OpenPNM, it is included in Ananconda and WinPython - https://github.com/spyder-ide/spyder
Paraview is suggested for visualizing OpenPNM data - http://www.paraview.org

Licence and Citation

OpenPNM is completely free to use and is offered under the permissive MIT License.

If you do use OpenPNM in an academic work the developers ask that you cite the following paper, which outlines the design principles and general uses of OpenPNM:

Gostick et al. OpenPNM: A pore network modeling package. Computing in Science & Engineering. 18(4), p60-74.

A link to this article can be found here.