Virtual microstructure generator for 2D and 3D polycrystalline materials.
VirMat generates synthetic polycrystalline microstructures -- the kind of grain structures you see when you look at a metal under a microscope. Given a statistical description of grain sizes (e.g., "log-normal distribution with mean 5 micrometers"), VirMat produces a realistic 3D (or 2D) arrangement of grains with smooth boundaries, crystallographic orientations, and morphological properties.
The output can be visualized in ParaView (VTK format) or analyzed with EBSD software like OIM or MTEX (ANG format).
Real microstructure characterization is expensive and limited: EBSD scans are 2D slices, serial sectioning is destructive, and 3D EBSD is still slow and costly. Virtual microstructures provide:
- Input for simulations -- finite element models, crystal plasticity simulations, and phase-field models need realistic starting microstructures
- Statistical validation -- compare simulated grain size distributions, neighbor counts, and morphological properties against experimental data
- Parametric studies -- vary grain size, texture, or packing without needing new experiments
- 3D structure from 2D statistics -- generate full 3D microstructures from grain size distributions measured on 2D cross-sections
Grain sizes are drawn from user-specified statistical distributions. Supported distributions:
- Log-normal -- the most common grain size distribution in real materials
- Normal -- symmetric distribution
- Uniform -- constant probability within bounds
- Custom -- arbitrary histogram
- Composed -- combine multiple distributions for multi-modal populations (e.g., bimodal grain sizes after partial recrystallization)
Sampling uses inverse-CDF (cumulative distribution function) interpolation.
Grain seed points are placed as spheres/circles with diameters corresponding to the sampled grain sizes. An optional iterative packing step uses Verlet integration with a force model (quadratic repulsion for overlaps, attraction for free space) to arrange grains into a realistic, non-overlapping configuration.
The packed seed points are triangulated using Delaunay triangulation (via DeUni), then the geometric dual -- the Voronoi tessellation -- is extracted. Each Voronoi cell becomes a grain. The Voronoi dual is stored as a microstructure graph (via hammer) encoding grains, grain boundaries (faces), triple lines (edges), and quadruple points (vertices).
The flat-faceted Voronoi polyhedra are refined using Loop subdivision surfaces (via SubZero). A few levels of subdivision produce smooth, realistic grain boundaries suitable for visualization and analysis.
Each grain is assigned a crystallographic orientation sampled from a Bingham distribution (via sledge). Inverse Pole Figure (IPF) colors are computed and attached as VTK attributes for visualization.
- VTK (
.vtu) -- 3D and 2D microstructures with grain ID, volume, area, neighbor count, and IPF coloring - ANG (
.ang) -- 2D orientation map rasterized from the subdivision mesh, compatible with EBSD analysis tools
VirMat orchestrates several specialized libraries:
| Package | Role |
|---|---|
| DeUni | Delaunay triangulation (Marriage Before Conquer algorithm) |
| hammer | Microstructure graph, grain finding, VTK export |
| sledge | Crystallographic orientations, Bingham distributions, EBSD I/O |
| linear-vect | Low-dimensional linear algebra (vectors, matrices) |
| queryforest | Spatial indexing (VP-trees, KD-trees) |
| SubZero | Subdivision surfaces (Loop scheme) |
| VTK | VTK XML file generation |
| mcl | Markov Cluster Algorithm for graph clustering |
# 3D microstructure, 200 grains, log-normal distribution, packed
virmatgen --3d --n2d 200 --packed \
--lnorm '(1.0, 5.0, 3.0, 0.0)' \
--seed 42 \
-d ./output -s mysample
# 2D microstructure, 100 grains, normal distribution
virmatgen --2d --n2d 100 --packed \
--norm '(1.0, 5.0, 1.0)' \
--seed 42 \
-d ./output -s mysample2d| Flag | Description | Default |
|---|---|---|
--3d / --2d |
Dimensionality | 3D |
--n2d INT |
Number of grains | 500 |
--packed / --packed-n INT |
Enable packing (with optional iteration count) | 60 iterations |
--random |
Random placement (no packing) | -- |
--lnorm (k,mu,mode,o) |
Log-normal distribution | -- |
--norm (k,mu,s) |
Normal distribution | -- |
--uniform (k,mu,s) |
Uniform distribution | -- |
--seed INT |
Random seed | system random |
-d FILEPATH |
Output directory | required |
-s STR |
Sample name | required |
Multiple distribution flags can be combined for multi-modal grain size populations.
# With Nix (recommended)
nix develop
cabal build
# With Stack
stack build
# Run the executable
cabal run virmatgen -- --help
# Run tests
cabal testMIT -- see LICENSE.