PorousPy - Create and analyze porous materials

Introduction

Porouspy is a python package to analyze porous microstructures, such as gas diffusion electrodes, membranes or porous soil.

Its key functions are:

• Multiphase fluid simulations
  • Pressure driven stationary intrusion
  • Dynamic intrusion / extrusion with trapping
• Analysis
  • Pore size distribution
  • Interfacial areas between two phases
  • Two-point correlation
• Stochastic reconstruction of porous media
  • Pluri-Gaussian Structures (Membrane-like)
  • Boolean structures (particle-like or fibrous-like)
  • PTFE, ionomer, binder
• Visualization of structures
  • Saving the structures as vti. Paraview file
  • Generating videos, images from the simulations

The basis of all porouspy functions are 3D numpy arrays, which we call structures. Each element of this array corresponds to one voxel (3D pixel) of the structure. The value of the voxel is a material ID between 0 and 255 (unsigned integer 8). Here, 0 is typically reserved for empty space (pores) while 255 is typically used for the main material of the structure. Hence a two dimensional example for a porous structure with pores (0) and solid material (255) looks like:

>>> import numpy as np
>>> structure = np.array([...])
>>> structure
[[0,0,  0,  0,  0]
[ 0,255,0,  0,  0]
[ 0,255,255,0,  0]
[ 0,0,  255,255,0]
[ 0,0,  0,  0,  0]]

These structures can be either created via the reconstruction functions or imported from other sources. A common option is a micro-CT scan. The 3D scan can be binarized (transformed into 2 distinct material phases) with a thresholding algorithm like the Otsu-Algorithm. Afterwards, we can use the binary structure in a similar way. In general, structures may contain as many materials as you want.

The basis of the models and simulations are the python packages numpy and scipy. However, to speed up the simulations, the cupy package is used, which allows to use the GPU for calculations. This increases the speed of the simulations by a factor of 10-100. Note however, that memory on the GPU is often much more limited. For relevant doamin sizes, a GPU with at least 10 GB of memory is recommended.

The algorithms (fluid flow, reconstructions etc.) are written in two levels of hirachy. The lower level are the 'pure' calculation functions or class. These are given all parameters and only do the calculations. However, they do not store or visualize the calculations by themselves. For this purpose, they expose non-implemented functions, which are implemented in the higher level functions or classes. Hence, the user can implement their own visualization or storage functions.

Installation

Installation of python packages and porouspy

The following packages are required to run porouspy:

• cupy (at least version 13)
• pyvista (to visualize the structures, save as vtk)
• scikit-image (for image processing)
• numba (speed up calculation of two-point correlation)
• matplotlib (plotting)
• pillow (save slices of images)
• pandas (save data as csv files)
• pytest (test functions)
• imageio (save images, videos)
• pyav (save videos)
• pyyaml (load data from yaml files)
• furthrmind (metadata storage)
• tqdm (progress bar)

conda create -n porouspy python=3.12

Run the following command to install the packages:

conda install -c conda-forge cupy scikit-image numba pillow pandas pytest pyyaml matplotlib tqdm

To install the correct imageio version, please run:

pip install imageio[pyav]

and only then

conda install -c conda-forge pyvista

Of course, you also need to install the porouspy package itself. This can be done by typing into the terminal:

>>> pip install -e .

if you are in the porouspy folder.

Using porouspy

The best way to use porouspy is via the scripts package. Here, you can find several scripts, which show how to use reconstruction and analysis functions.