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.

• Voronoi based microstructures: (MSUtils/voronoi/)

  • VoronoiSeeds.py: Sampling strategies for Voronoi seed placement (sobol, halton, lhs-lloyd, lattice/honeycomb) and lattice vectors.
  • VoronoiTessellation.py: Build periodic Voronoi tessellations, compute analytical crystal volumes, interface areas, structure tensors and export to VTU.
  • voronoi_foam.py: Rasterize Voronoi edges into strut-based foam microstructures.
  • VoronoiImage.py: Rasterize seeds into a labelled voxel image using a periodic KDTree (nearest-seed labelling).
  • VoronoiGBErosion.py: Erode Voronoi images to identify grain-boundary voxels, tag grain-boundary IDs and save grain-boundary metadata.

• 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.).
  • lattice_image.py: Draw struts for lattice unit-cells onto a voxel grid.

• Textile based microstructures: (MSUtils/TexGen/)

  • Example scripts demonstrating how to generate and export TexGen models to VTU, then use vtk2h5.py to get HDF5 datasets of textile based microstructures.

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.
  • ComBoMicrostructureImage.py - Morphologically sound coarse-graining via composite boxels (ComBo) as described in our paper.
  • resize_image.py - Resize and smooth 3D labelled voxelized microstructure images to any target image resolution.
  • vtk2h5.py - Convert VTI/VTU cell-centered meshes into HDF5 datasets inferred on a regular cell-center grid.
  • 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/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.

---