Python tool for microstructure analysis and generation of 3D microstructure models

Authors: Mahesh R.G Prasad, Abhishek Biswas, Golsa Tolooei Eshlaghi, Ronak Shoghi, Napat Vajragupta, Yousef Rezek, Hrushikesh Uday Bhimavarapu, Jun Xue, Alexander Hartmaier
Organization: ICAMS / Ruhr-Universität Bochum, Germany
Contact: alexander.hartmaier@rub.de

Kanapy is a python package for generating complex three-dimensional (3D) synthetic polycrystalline microstructures. The microstructures are built based on statistical information about phase and grain morphologies, given as size distributions and aspect ratio distrubitions of grains and phase regions. Furthermore, crystallographic texture is considered in form of orientation distribution functions (ODF) and misorientation distribution functions (MDF). Kanapy offers tools to analyze EBSD maps with respect to the morphology and texture of microstructures. Based on this experimental data, it generates 3D synthetic microstructures mimicking real ones in a statistical sense.

The basic implementation of Kanapy is done in form of a Python Appplication Programming Interface (API). There is also a command line interface (CLI) for administrative functions and and Graphical User Interface (GUI), which is still under development.

Features

Kanapy offers a Python Application Programming Interface (API).
Possibility to analyze experimental microstructures based on orix functions.
Support of multiphase microstructures.
Generation of 3D microstructure morphology based on statistical features as size distributions and aspect ratio distributions of grains and phase regions.
Crystallographic texture reconstruction using orientations from experimental data in form of Orientation Distribution Function (ODF).
Optimal orientation assignment based on measured Misorientation Distribution Function (MDF) that maintains correct statistical description of high-angle or low-angle grain boundary characteristics.
Independent execution of individual modules through easy data storage and handling.
In-built hexahedral mesh generator for representation of complex polycrystalline microstructures in form of voxels.
Efficient generation of space filling structures by particle dynamics method.
Collision handling of particles through a two-layer collision detection method employing the Octree spatial data structure and the bounding sphere hierarchy.
Option to generate spherical particle position and radius files that can be read by the Voronoi tessellation software Neper.
Option to generate input files for finite-element packages.
Import and export of voxel structures according to following the modular materials data schema published on GitHub for data transfer between different tools.

Installation

The preferred method to use Kanapy is within Anaconda or Miniconda, into which it can be easily installed from conda-forge by

$ conda install conda-forge::kanapy

$ conda install kanapy -c conda-forge

Generally, it can be installed within any Python environment supporting the package installer for python (pip) from its latest PyPi release via the shell command

$ pip install kanapy

Alternatively, the most recent version of the complete repository, including the source code, documentation and examples, can be cloned and installed locally. It is recommended to create a conda environment before installation. This can be done by the following the command line instructions

$ git clone https://github.com/ICAMS/Kanapy.git ./kanapy
$ cd kanapy
$ conda env create -f environment.yml
$ conda activate knpy
(knpy) $ python -m pip install .

Kanapy is now installed along with all its dependencies. The correct installation with this method can be tested with

(knpy) $ kanapy runTests

Using Kanapy in your Python scripts

After installation by any of those methods, the package can be used as API within python, e.g. by importing the entire package with

import kanapy as knpy

Command line tools

Kanapy supports some command line tools, a list of supported tools can be displayed with

(knpy) $ kanapy --help

Graphical User Interface (GUI)

The alpha-version of the GUI can be started with the shell command

(knpy) $ kanapy gui

Examples

Kanapy comes with several examples in form of Python scripts and Juypter notebooks. If you want to create a local copy of the kanapy/examples directory within the current working directory (cwd), please run the command

(knpy) $ kanapy copyExamples

Kanapy notebooks can also be used on Binder.

Documentation

The Kanapy documentation is available online on GitHub Pages: https://icams.github.io/Kanapy/ and can directly be displayed with

(knpy) $ kanapy readDocs

The documentation for Kanapy is generated using Sphinx.

Dependencies

Below are the listed dependencies for running Kanapy:

NumPy for array manipulation.
SciPy for functionalities like Convexhull.
Matplotlib for plotting and visualizing.
orix for reading and analyzing EBSD maps and for generation of crystal orientations
NetworkX generating graph networks of microstructures
scikit-image processing of microstructure images

Citation

The preferred way to cite Kanapy is:

@article{Biswas2020,
  doi = {10.5281/zenodo.3662366},
  url = {https://doi.org/10.5281/zenodo.3662366},
  author = {Abhishek Biswas and Mahesh R.G. Prasad and Napat Vajragupta and Alexander Hartmaier},
  title = {Kanapy: Synthetic polycrystalline microstructure generator with geometry and texture},
  journal = {Zenodo},
  year = {2020}
}

Related works and applications

Prasad et al., (2019). Kanapy: A Python package for generating complex synthetic polycrystalline microstructures. Journal of Open Source Software, 4(43), 1732. https://doi.org/10.21105/joss.01732
Biswas, Abhishek, R.G. Prasad, Mahesh, Vajragupta, Napat, & Hartmaier, Alexander. (2020, February 11). Kanapy: Synthetic polycrystalline microstructure generator with geometry and texture (Version v2.0.0). Zenodo. http://doi.org/10.5281/zenodo.3662366
Biswas, A., Prasad, M.R.G., Vajragupta, N., ul Hassan, H., Brenne, F., Niendorf, T. and Hartmaier, A. (2019), Influence of Microstructural Features on the Strain Hardening Behavior of Additively Manufactured Metallic Components. Adv. Eng. Mater., 21: 1900275. http://doi.org/10.1002/adem.201900275
Biswas, A., Vajragupta, N., Hielscher, R. & Hartmaier, A. (2020). J. Appl. Cryst. 53, 178-187. https://doi.org/10.1107/S1600576719017138
Biswas, A., Prasad, M.R.G., Vajragupta, N., Kostka, A., Niendorf, T. and Hartmaier, A. (2020), Effect of Grain Statistics on Micromechanical Modeling: The Example of Additively Manufactured Materials Examined by Electron Backscatter Diffraction. Adv. Eng. Mater., 22: 1901416. http://doi.org/10.1002/adem.201901416
R.G. Prasad, M., Biswas, A., Geenen, K., Amin, W., Gao, S., Lian, J., Röttger, A., Vajragupta, N. and Hartmaier, A. (2020), Influence of Pore Characteristics on Anisotropic Mechanical Behavior of Laser Powder Bed Fusion--Manufactured Metal by Micromechanical Modeling. Adv. Eng. Mater., https://doi.org/10.1002/adem.202000641

Version history

v3: Introduction of Python API
v4: Import and export of microstructures in form of voxels
v5: Pure Python version, support of CLI functions suspended
v6: Major revision of internal data structure and statistical microstructure parameters
v6.1: Full support of dual-phase and porous microstructures
v6.2: Possibility of other geometries than ellipsoids as basic microstructure shapes
v6.3: Implementation of velocity-Verlet algorithm to integrate particle trajectories during packing
v6.4: Support of the modular materials data schema for import and export of microstructures
v6.5: Switched to orix library for EBSD import and analysis and generation of textures to have a pure Python code. The MTEX backend is still available with [Kanapy-mtex](https://github.c

Kanapy

Install / Use

README