MSUtils - Microstructure Utilities

MSUtils is a collection of utilities and scripts for creating, processing and exporting voxelized microstructure data which can be readily used in FFT-based solvers such as FANS.

Installation

We use Pixi for package management. If you don't have Pixi installed, install pixi via:

curl -fsSL https://pixi.sh/install.sh | sh

Clone the repository and install the required packages:

git clone https://github.com/DataAnalyticsEngineering/MSUtils.git
cd MSUtils/
pixi shell

Microstructure generation

These modules produce periodic voxelized microstructures (numpy arrays / HDF5 datasets) of heterogeneous materials which can be readily used in FFT-based solvers such as FANS.

• Neper-based microstructures: (MSUtils/neper/)

  • NeperMicrostructure.py: Generate Neper raster tessellations and export labelled voxel images and per-grain rotation matrices.
  • NeperGBErosion.py: Rasterize finite-thickness grain boundaries from Neper face geometry and export the eroded image with its per-grain rotation matrices.
  • NeperFoam.py: Rasterize the edges of periodic Neper tessellations as strut-based foam microstructures.
  • Rotation matrices map crystal-frame column vectors into the sample frame: v_sample = Q @ v_crystal. Their columns are therefore the crystal x, y and z axes expressed in sample coordinates.

• Triply periodic minimal surface (TPMS) based microstructures: (MSUtils/TPMS/)

  • tpms.py: Generate TPMS (Gyroid, Schwarz P, Diamond, Neovius, IWP, Lidinoid, etc.) based microstructures. Supports binarization modes (solid/shell) and threshold-finding for target volume fractions.
  • tpms_functions.py: The raw implicit functions used by the TPMS generator.

• Spinodal microstructures: (MSUtils/spinodoids/)

  • generate_spinodal_microstructure.py: Spectral filtering method to synthesize spinodal-like microstructures with control over volume fraction, feature size and anisotropy.

• Lattice based microstructures: (MSUtils/lattices/)

  • lattice_definitions.py: Unit-cell vertex + edge definitions for many lattices (BCC, FCC, octet, auxetic, etc.).
  • LatticeMicrostructure.py: Draw struts for lattice unit-cells onto a voxel grid.

Microstructure utilities

Utilities for file I/O, conversions, and practical helpers.

• MSUtils/general/

  • MicrostructureImage.py - Core class for microstructure data: read/write HDF5 datasets with permute-order handling, metadata, and volume fraction calculation.
  • resize_image.py - Resize and smooth 3D labelled voxelized microstructure images to any target image resolution.
  • h52xdmf.py - Convert HDF5 datasets into XDMF XML for ParaView. Supports scalar/vector/tensor attributes and time-series handling.
  • merge_h5_files.py - Merge multiple HDF5 files into one by recursively copying groups/datasets.

• MSUtils/ComBo/

  • ComBoMicrostructureImage.py - Morphologically sound coarse-graining via composite boxels (ComBo) as described in our paper.

• MSUtils/sampling/

  • generate_loadpaths.py - Samples quasi-uniform equal-area directions on the unit hypersphere using the LeopardiSampler (See paper for further details). Using the sampled directions, produce linear strain ramps to user limits on deviatoric and volumetric strain magnitude and exporting the load paths to JSON that can be used in the input file for FANS.

Acknowledgements

Funded by Deutsche Forschungsgemeinschaft (DFG, German Research Foundation) under Germany’s Excellence Strategy - EXC 2075 – 390740016. Contributions by Felix Fritzen are funded by Deutsche Forschungsgemeinschaft (DFG, German Research Foundation) within the Heisenberg program - DFG-FR2702/8 - 406068690; DFG-FR2702/10 - 517847245 and through NFDI-MatWerk - NFDI 38/1 - 460247524. We acknowledge the support of the Stuttgart Center for Simulation Science (SimTech).

Contact

If you have questions or need support, please open an issue. You can contact Sanath Keshav (keshav.@mib.uni-stuttgart.de) with any other inquiries.

---