beyucel / kanapy

Synthetic microstructure generator. Online documentation can be found here:

Overview

Kanapy is a python package for generating complex synthetic polycrystalline microstructures. The general implementation is done in Python with the performance critical part for the geometry module implemented in C++. The Python bindings for the code written in C++ are generated using the lightweight header-only library pybind11. The C++ part of the implementation utilizes the Eigen library for efficient linear algebra calculations. The texture module of Kanapy is implemented as MATLAB functions. It also utilizes several algorithms implemented in MTEX for texture analysis.

Motivation

An accurate representation of the material microstructure is fundamental in understanding the relationship between microstructure and its corresponding mechanical behavior. In this regard, Kanapy is developed to be a robust and an efficient tool to generate synthetic microstructures within the micro mechanical framework for Finite Element Method (FEM) simulations. It is designed to model simple and complex grain morphologies and to systematically incorporate texture data directly from experiments concurrently maintaining the numerical efficiency of the micromechanical model. Kanapy is developed to overcome the limitations of spatial tessellation methods and to provide an alternative to the existing Random Sequential Addition technique of microstructure geometry generation.

Figure: Kanapy workflow.

Features

• User interface to kanapy through CLI.
• Efficient collision handling of particles through a two-layer collision detection method employing the Octree spatial data structure and the bounding sphere hierarchy.
• Efficient ODF reconstruction directly using orientations from experimantal data.
• Optimal orientaion assignment based on Measured misorientation distribution.
• Independent execution of individual modules through easy data storage and handling.
• In-built hexahedral mesh generator for complex polycrystalline microstructures.
• Flexibility in the choice of the particle packing time step to be sent for voxelization (meshing).
• 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 the commercial finite-element software Abaqus.
• High-performance for the critical part of the geometry code using Python-C++ bindings.

Installation

CMake is used for building extensions; if it is not installed on your machine, follow this CMake documentation to install it. The preferred method to install kanapy is through Anaconda or Miniconda Python distributions. If you do not have any, we suggest installing miniconda.

Once done, create a virtual environment for Kanapy installation and clone the repository to a desired location and install.

$ conda create -y -n knpy python=3.6 pip git
$ conda activate knpy
(knpy) $ git clone https://github.com/mrgprasad/kanapy.git <location to clone>/kanapy-master
(knpy) $ cd kanapy-master/
(knpy) $ conda install -y -c conda-forge --file requirements.txt
(knpy) $ pip install -e .

Kanapy is now installed along with all its dependencies. If you intend to use Kanapy's texture module, link Kanapy with MATLAB and MTEX installations by running: kanapy setuptexture and follow the instructions.

Note

1. knpy can be replaced with any name for your environment.
2. For older versions of anaconda/miniconda use: source activate knpy

Tip

To learn more about managing environments see Anaconda documentation.

Running tests

Kanapy uses pytest to perform all its unit testing. Run: (knpy) $ kanapy tests

Documentation build

Documentation for kanapy is generated using Sphinx. Run: (knpy) $ kanapy docs. The HTML documentation can be found at ../kanapy-master/docs/index.html.

Dependencies

Kanapy requires a working C/C++ compiler on your machine. On Linux/Mac OS, the gcc toolchain will work well. The lightweight header-only library pybind11 is used to create Python bindings for the code written in C++. The C++ function will be complied by linking the Eigen library (present in the directory ../kanapy-master/libs/). CMake builds this extension.

Kanapy's texture module requires MATLAB and MTEX to be installed on your machine. Make sure to use MATLAB v2015a and above.

Core dependencies

Below are the listed dependencies for running kanapy:

• NumPy for array manipulation.
• Scipy for functionalities like Convexhull.
• pybind11 for creating python bindings for C++ code.
• Eigen for C++ linear algebra operations.
• pytest for running kanapy unit tests.
• sphinx for generating documentation.
• MATLAB for texture modules.
• MTEX for texture modules.

Optional dependencies

• Matplotlib for plotting and visualizing.
• OVITO for visualizing simulation data.

Citation

The preferred way to cite Kanapy is:

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

License

Kanapy is made available under the MIT license.

About

The name kanapy is derived from the sanskrit word káṇa meaning particle. Kanapy is primarily developed at the Interdisciplinary Center for Advanced Materials Simulation (ICAMS), Ruhr-University Bochum - Germany. Our goal is to build a complete synthetic microstructure generation tool for research and industry use.