OpenPNM is an open-source code to simulate multi-phase flow within porous media. It is based on a pore-network approach, i.e. the complex morphology of solid and non-solid space within a porous medium is abstracted by a network of pores and throats. Typically an analytical solution or a 1D numerical solution can be derived for each pair of pores connected by a throat. Hence instead of solving the governing equations for multiphase flow on a complex geometry, a much simpler system of algebraic or ordinary differential equation can be solved.

Development Team

The core development team for OpenPNM is located at the Porous Materials Engineering & Analysis Lab (PMEAL) led by Dr. Jeff Gostick. A small but dedicated team is constantly updating and extending the code base. The AFCC Automotive Fuel Cell Cooperation Corp. was an early and long time sponsor of this project. The development page is located at Github.

As this is an Open Source project, anyone is welcome to join the development team.

License and Attribution

OpenPNM is released under the MIT license, hence free to use and to extend under a very permissive license.

As a courtesy to the authors and the considerable work which has gone into this package, the authors ask to cite the following article in an academic publication:

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

Operating System Requirements

OpenPNM can run within any running python environment on any operating system. It is Python 3.X compliant. I personally run an Anaconda python environment. The following commands create the environment used in this post:

conda create -n pnm python=3.5 anaconda
source activate pnm

pip install OpenPNM

The 3D visualizations are created by Paraview. I tried, and failed, to use Mayavi2 with Python 3.5 directly within the Jupyer notebook. I think Mayavi2 and Python 3.X needs a little more time to mature.

Publications

OpenPNM has been used in several publications. For a growing list of paper, pleas check this google scholar link.

Feature Highlights

Python Ecosystem

OpenFCST uses the SciPy ecosystem (mainly scipy and matplotlib).

Topology Generation

Easy generation of cubic and random networks with arbitrary conductivity. Input and output routines for other network formats.

Topology Manipulation

Easy manipulation of the stored network topology, e.g. finding and labelling specific pores for boundary conditions, merging networks to enable multiscale simulations, …

Geomerty Engine

Generation of geometric properties necessary for pore network calculations, e.g. pore size, throat size, …

Physics Engine

Easy generation of the physical properties necessary for pore network simulations: viscosity, hydraulic conductance, diffusivity, …

Algorithm Library

Large library of pore network algorithms are already implemented: invasion percolation, capillary drainage, mass diffusion, permeability, …

OpenPNM Basic Architecture

The core classes of OpenPNM inherit from the dictionary class. Below is a simple ingeritance diagram of the core OpenPNM classes.

Class architecture and inheritance diagram of OpenFCST (taken from the OpenFCST documentation).

Small Showcase Demonstrations

Based on the online example library, I have created a few small demonstration simulations and visualizations.

  • Mercury Intrusion Porisimetry (MIP) on a cubic network with random pore and throat sizes,
  • Mercury Intrusion Porisimetry (MIP) on a random Delaunay network.
  • Ordinary Percolation (OP) on a random Delaunay network.
MIP on a random cubic network

Topology and Geometry Setup

cubic pore network (pore location))

Pore locations of a default cubic network.

OpenPNM comes with a machinery to create various topologies and geometries. The topology generates the number of pores (or nodes in network theory language) and connects them by¬† throats (edges). Basic operations can now be executed: check for connected regions, connectivity plots and some others. The geometry generators attach some geometric information to the topolgy: e.g. pore sizes, throat sizes, throat lengths, …

In the statistical plot below, we can observe that the pore and throat diameters are discretely drawn from a normal distribution. The coordicantio number shows the eight corner node with a coordination number of three, the edge nodes (4), face nodes (5) and internal node (6).

cubic network statisticsMIP algorithm

OpenPNM based MIP experiment on a cubic network.The drainage algorithm simulates a capillary drainage experiment by applying a list of increasing capillary pressures and invading all throats that are accessible and invadable at the given pressure.

The capillary pressure is calculated based on the throat radius, the surface tension of the invading phase and the contact angle. In this particular case the invading fluid is mercury. The algorithm returns the drainage curve (right) and attaches the step in which a praticular pore was invaded as well as the pressure at invasion time. This allows us to create a visualization of the invasion sequence in Paraview (below).

MIP simulation on a cubic network conducted by OpenPNM. 3D scene generated with Paraview, movie generated with GIMP.

MIP on a random Delaunay Network

Topology and Geometry Setup

Topology of a network generated with the Delaunay/Voronoi algorithm.

In the previous example, we have generated a simple cubic network. In this example we will use randomly placed points to generate our network. The main problem for random points is to figure out which points should be connected. One solution to this problem is to utilize a suite of tools used in the meshing community: Delaunay Triangulations and Voronoi Diagrams. The image on the left shows one example of such a network. Additional pores were added on the cube boundary to allow for an easy identification of injection pores. The very simplistic approach used in this algorithm generates artificially large pores close to the outer faces of the geometry. To generate a more realistic porous medium, the detection and generation of boundary face pores has to be done with more care and sophistication.

Geometric properties

Now the sizes of pores and throats needs to be calculated. IN this example we will use the Voronoi diagram of the Delaunay tessellation to find the shape of pores and throats. The image below shows the pores and pore edges generated by the Voronoi diagram. The green dots denote the pore centres given by the Delaunay points.

Visualization of the pore and throat space of the based on the Voronoi algorithm.

To simplify the visualization, OpenPNM allows to select a specific pore and draw the cross sections of all connected pores. The pore selected in the plot before is connected to six other pores (hence coordination number of 6)

Calculation of the fibre sizing. The black and green lines denote the polygonal cage of connected pores, the red circle denotes the throat diameter.

As observed before, our simplistic addition of boundary pores, leads to some obvious anomalies in the distributions shown below: The boundary pores only connect to one internal pore, hence their coordination number is 1. The boundary pores have volume 0, to not influence the saturation calculation.

Histogram of the key geometric properties: throat diameter, pore diameter, throat lengths and coordination numbers.

Similarity to fibrous materials

A cross section of the porous network defined by the Delaunay/voronoi algorithm pair. White denotes fibres, black the void space.

One of the attractions of this type of network is the similarity to fibrous materials. OpenPNM allows to visualize (see right image) a cross section of this geometry type and one can observe a striking similarity to real materials (e.g. gas diffusion layers for fuel cell applications).

Graph of the porosity of a single slice along the three Cartesian axis.

MIP algorithm

Simulation of a MIP based on a random Delaunay network.

The drainage algorithm simulates a capillary drainage experiment by applying a list of increasing capillary pressures and invading all throats that are accessible and invadable at the given pressure.

The capillary pressure is calculated based on the throat radius, the surface tension of the invading phase and the contact angle. In this particular case the invading fluid is mercury. The algorithm returns the drainage curve (right) and attaches the step in which a praticular pore was invaded as well as the pressure at invasion time. This allows us to create a visualization of the invasion sequence in Paraview (below).

MIP intrusion simulation of a network generated by the Delaunay and Voronoi algorithms.

OP on a random Delaunay Network

Topology and Geometry Setup

The topology and geometry for ths section is identical to the previous one.

OP algorithm

Invasion percolation of a water phase into a Delaunay/Voronoi random network.

The drainage algorithm simulates a capillary drainage experiment by applying a list of increasing capillary pressures and invading all throats that are accessible and invadable at the given pressure. In contrast to the previous section, the invading fluid is now water instead of mercury.

The capillary pressure is calculated based on the throat radius, the surface tension of the invading phase and the contact angle. In this particular case the invading fluid is mercury. The algorithm returns the drainage curve (right) and attaches the step in which a praticular pore was invaded as well as the pressure at invasion time. This allows us to create a visualization of the invasion sequence in Paraview (below).

Ordinary percolation simulation of water into a porous network generated by the Delaunay/Voronoi algorithm. Simulation with OpenPNM and visualization with Paraview.

Conclusions and Additional Material

Conclusions

This was a quick introduction to the OpenPNM package. Using the Delaunay/Voronoy topology and geometry generators, we managed to create almost realistic looking fibrous materials. For more realistic simulations, a few more steps would be required, but I think the general idea is visible.

For more information, please visit the project page and the excellent examples and documentation available through it.

Additional Material

Bitbucket Repository

The Bitbucket repository for this worksheet can be found here.

It can be viewed below or in a full screen Jupyter-Notebook window or below in a smaller iframe:

Jupyter Notebook

Changelog

Action Date Description
Creation + Publication 2017.09.08 Initial publication through WordPress. Forwards to Twitter, Facebook and LinkedIN
Status Completed

Disclaimer

I am doing this as a hobby, so take all of this with care …

License to Graphs and Photos

Unless otherwise stated all figures are published under the most non restrictive Creative Commons License:
CC0
To the extent possible under law, Andreas Putz has waived all copyright and related or neighbouring rights to the graphs and material shown above.

%d bloggers like this:
Title
Caption
File name
Size
Alignment
Link to
  Open new windows
  Rel nofollow