Documentation Status Anaconda-Server Badge PyPI version pumapy Tests

Porous Microstructure Analysis (PuMA)

The stable releases of PuMA can be found on the official NASA Github repository, whereas the latest development can be found on the development Gitlab repository. Access the PuMA documentation for detailed use of each function or to get started with the tutorial.

The Porous Microstructure Analysis (PuMA) software has been developed to compute effective material properties and perform material response simulations on digitized microstructures of porous media. PuMA is able to import digital three-dimensional images obtained from X-ray microtomography or to generate artificial microstructures that mimic real materials. PuMA also provides a module for interactive 3D visualizations. Version 3 includes modules to compute simple morphological properties such as porosity, volume fractions, pore diameter, and specific surface area. Additional capabilities include the determination of effective thermal and electrical conductivity (both radiative and solid conduction - including the ability to simulate local anisotropy for the latter); effective diffusivity and tortuosity from the continuum to the rarefied regime; techniques to determine the local material orientation, as well as the mechanical properties (elasticity coefficient), and the permeability of a material.

Some examples of microstructures that have been run in the past are shown in the pictures below, together with PuMA’s software architecture schematic.

System requirements

UNIX (tested on MacOS 10.14.1+, Ubuntu 12.04+, RHEL, and CentOS). On Windows, only the python distribution (pumapy) is available.

Indicative recommended specs (varies depending on the material property):

  • 8 GB of ram for small simulations (5003 or smaller)

  • 16-32 GB of ram for medium simulations (8003 range)

  • 32+ GB of ram for large simulations (above 10003)

Installation

To install PuMA, a conda distribution must be installed on your machine. To test whether conda is installed, run “conda” from a terminal to see if the command is recognized. If not, conda can be installed by following the instructions here.

Binaries (UNIX and Windows)

Once the conda command is working, all the PuMA components can be installed by executing the following command in a terminal: (Note: The “solving environment” step can take a while on some systems so please be patient)

conda create -y --name puma conda-forge::puma

If only the pumapy python package is needed, it can be installed directly using:

pip install pumapy

On UNIX (i.e. Mac or Linux), the conda command installs the PuMA C++ library, pumapy python package and GUI.

On Windows, only the pumapy python package is available, so both commands are equivalent.

Note: TexGen (C++ library to create artificial weaves) is only installed when using conda on UNIX, because it needs more advanced compilation. A friendly warning will appear when TexGen is not installed and pumapy is imported.

Build from source (UNIX-only)

This is the recommended installation for developers that need to make modifications to PuMA. The installation is broken into two sections:

  1. Installation of basic dependencies that may be missing from your system

  2. Download the repository, build the source code and install the binaries

Step 1 of the installation varies slightly based on the system. Open a terminal, navigate to the directory you would like PuMA installed, and execute one of the following lines:

xcode-select --install                                                                 # run this on MacOS
sudo apt-get install git build-essential mesa-common-dev                               # Debian (Ubuntu)
sudo yum group install "Development Tools"; sudo yum install git g++ mesa-libGL-devel  # Fedora (CentOS, RHEL)

Note: If XCode command line tools are already installed, the command will result in an error, which is not a problem.

Now that the necessary dependencies have been installed, you can go ahead with Step 2 of the installation:

git clone https://github.com/nasa/puma.git
cd puma; chmod +x installer.sh; ./installer.sh

After installation, close the terminal and open a new one.

Uninstalling PuMA

To uninstall PuMA and all the installed dependencies, execute the following:

conda remove -y --name puma --all

Running PuMA

PuMA relies on a conda environment in order to manage its software dependencies and environment variables. It is therefore important to always activate the environment before using any of PuMA’s functionalities. Once the installation is complete, the PuMA GUI can be launched by running:

conda activate puma
pumaGUI

You can follow the jupyter notebook tutorial, which shows the typical function usage for both PuMA C++ and pumapy. This can also be run directly in Google Colaboratory by following this link.

How to setup PuMA on the NAS cluster:

In order to install PuMA on the NASA supercomputing cluster, some modules need to be loaded and environment variables need to be set. This can be achieved by adding the following commands to the ~/.profile file before the installation:

module use -a /swbuild/analytix/tools/modulefiles
module load miniconda3/v4
module load /nasa/modulefiles/pkgsrc/sles12/gcc/6.2
export CONDA_PKGS_DIRS=/nobackup/$USER/.conda/pkgs
export CONDA_ENVS_PATH=/nobackup/$USER/.conda/envs
conda config --append envs_dirs /nobackup/$USER/.conda/envs
source activate

Citing PuMA

If you use PuMA in your research, please use the following BibTeX entries to cite it:

@article{puma2021,
  title={Update 3.0 to “PuMA: The Porous Microstructure Analysis software”,(PII: S2352711018300281)},
  author={Ferguson, Joseph C and Semeraro, Federico and Thornton, John M and Panerai, Francesco and Borner, Arnaud and Mansour, Nagi N},
  journal={SoftwareX},
  volume={15},
  pages={100775},
  year={2021},
  publisher={Elsevier}
}
@article{puma2018,
  title={PuMA: The porous microstructure analysis software},
  author={Ferguson, Joseph C and Panerai, Francesco and Borner, Arnaud and Mansour, Nagi N},
  journal={SoftwareX},
  volume={7},
  pages={81--87},
  year={2018},
  publisher={Elsevier}
}

See the publications file for a full list of papers on PuMA and its numerical methods.

Common errors and bug reporting

This is a list of the common errors encountered during the setup and how to solve them:

  • If PuMA was partially installed but was interrupted, this can cause errors when trying to install the software. To fix this, first follow the instructions to uninstall puma, and then repeat the installation procedure

  • If an error “make: Warning: File … has modification time … s in the future” is displayed, then run “sudo apt install ntp” (or equivalent for your distribution)

If any bugs are found, or if the software crashes for any reason, please open an issue at this link and/or contact either of the authors mentioned below.

Contributing to PuMA

Since PuMA is a free open-source code, any user is welcome to contribute or collaborate however they would like. If you are interested in significant development for your research goals, please contact either of the authors mentioned below.

Authors

Creator: Joseph Ferguson joseph.ferguson@stanford.edu

Maintainer: Federico Semeraro federico.semeraro@nasa.gov

Contributors: Francesco Panerai, John M. Thornton, Arnaud Borner, Jeremie B. Meurisse, Nagi N. Mansour