Skip to content

Commit 091b60b

Browse files
lostbeanlostbean
committed
Normalize licenses to MIT, add comprehensive READMEs across all packages
1 parent c73463f commit 091b60b

12 files changed

Lines changed: 259 additions & 684 deletions

File tree

‎LICENSE‎

Lines changed: 21 additions & 675 deletions
Large diffs are not rendered by default.

‎README‎

Whitespace-only changes.

‎README.md‎

Lines changed: 229 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,229 @@
1+
# VirMat: Virtual Microstructure Generator
2+
3+
**VirMat** is a high-performance 2D and 3D virtual microstructure generator written in Haskell, designed for metallurgical and materials science research. It creates synthetic polycrystalline microstructures with user-defined grain size distributions and crystallographic textures, producing output suitable for visualization in [ParaView](https://www.paraview.org/) and analysis with EBSD software.
4+
5+
## Core Features
6+
7+
- **2D and 3D generation** -- produce microstructures in either dimensionality from a single CLI.
8+
- **Statistical grain size control** -- specify Log-Normal, Normal, Uniform, or custom grain diameter distributions; combine multiple distributions for multi-modal populations.
9+
- **Sphere/circle packing** -- optional iterative packing (Verlet integration with damping) to obtain realistic, non-overlapping grain seed placement before tessellation.
10+
- **Voronoi tessellation** -- Delaunay triangulation (DeWall algorithm) followed by dual Voronoi construction via `MicroGraph`.
11+
- **Subdivision surfaces** -- Voronoi facets are converted to Loop subdivision surfaces (`SubZero`) so grain boundaries can be smoothly refined to arbitrary resolution.
12+
- **Crystallographic texture** -- orientations sampled from a Bingham distribution are assigned per grain; IPF coloring is rendered into VTK attributes.
13+
- **Phase transformation** -- a parent microstructure can be overlaid with a finer product microstructure and each product grain inherits the parent grain identity.
14+
- **Export formats**
15+
- VTK Unstructured Grid (`.vtu`) for 3D/2D visualization in ParaView.
16+
- ANG (`.ang`) for 2D EBSD-like data analysis (rasterized from the subdivision mesh).
17+
18+
## Architecture Overview
19+
20+
### Generation Pipeline
21+
22+
```
23+
JobRequest (CLI)
24+
|
25+
v
26+
Grain Size Sampling -- Core.Sampling + Distributions.GrainSize
27+
| (inverse-CDF sampling from composed multi-distributions)
28+
v
29+
Weighted Point Cloud -- GrainDistributionGenerator
30+
| (circles/spheres with diameter-derived radii)
31+
v
32+
[Optional] Sphere Packing -- Core.Packer (Verlet integration, N iterations)
33+
|
34+
v
35+
Delaunay Triangulation -- DeUni (DeWall algorithm, 2D or 3D)
36+
|
37+
v
38+
Voronoi Micro-graph -- Core.VoronoiMicro (dual of Delaunay -> MicroGraph)
39+
|
40+
v
41+
FlexMicro (Subdivision) -- Core.FlexMicro (Loop subdivision surfaces via SubZero)
42+
|
43+
+---> Texture Assignment -- Distributions.Texture.ODFSampling (Bingham sampling)
44+
|
45+
+---> Morphology Query -- Distributions.GrainSize.GrainQuery (area, volume, neighbors)
46+
|
47+
+---> VTK Rendering -- FlexMicro.renderFlexMicro -> .vtu files
48+
|
49+
+---> ANG Rasterization -- IO.Export.ANG.RasterEngine -> .ang files
50+
|
51+
+---> Phase Transformation -- PhaseTrans (parent/product overlay)
52+
```
53+
54+
### Data Flow Types
55+
56+
| Type | Description |
57+
|------|-------------|
58+
| `JobRequest` | Parsed CLI parameters: dimension, grain count/box size, distribution, seed |
59+
| `DistributedPoints v` | Bounding box + weighted point cloud (`SetPoint v`) |
60+
| `Simulation v` | Full state: box, points, Delaunay triangulation, Voronoi micro-graph |
61+
| `FlexMicro v a` | Subdivision-surface microstructure with per-grain property `a` |
62+
| `GrainMorph v` | Computed morphological properties (center, length, area, volume, neighbor count) |
63+
64+
## Packages
65+
66+
VirMat is organized as a multi-package Haskell project. The root package orchestrates the generation pipeline, while specialized functionality lives in git submodule packages under `packages/`:
67+
68+
| Package | Description |
69+
|---------|-------------|
70+
| [DeUni](packages/DeUni) | 3D Convex Hull and Delaunay triangulation using the Marriage-Before-Conquer (MBC) / DeWall algorithm |
71+
| [hammer](packages/hammer) | Metallurgical utilities: `MicroGraph` topology, grain finding, sparse matrices, and VTK generation |
72+
| [sledge](packages/sledge) | Crystallographic orientations, symmetries, Bingham distributions, IPF coloring, and EBSD file formats (ANG, CTF) |
73+
| [linear-vect](packages/linear-vect) | Low-dimensional linear algebra: `Vec2`, `Vec3`, `Vec4`, matrices, quaternions |
74+
| [queryforest](packages/queryforest) | Spatial indexing and nearest-neighbor search (KD-trees, VP-trees) |
75+
| [SubZero](packages/SubZero) | Subdivision surfaces for 1D (lines/curves) and 2D (triangular meshes, Loop scheme) |
76+
| [VTK](packages/VTK) | Library for generating VTK XML files (`.vtu`, `.vti`, etc.) |
77+
| [mcl](packages/mcl) | Markov Cluster Algorithm (MCL) for graph clustering |
78+
79+
## Key Modules and Source Files
80+
81+
### Entry Point
82+
83+
| File | Module | Role |
84+
|------|--------|------|
85+
| `src/Main.hs` | `Main` | CLI entry point; dispatches to `go2D` or `go3D` based on `--2d`/`--3d` flag |
86+
87+
### Core Library (`VirMat.*`)
88+
89+
| File | Module | Role |
90+
|------|--------|------|
91+
| `src/VirMat/Types.hs` | `VirMat.Types` | `Simulation` record: box, point set, triangulation, grain set |
92+
| `src/VirMat/Run2D.hs` | `VirMat.Run2D` | 2D pipeline: sample points, optional packing, Delaunay, Voronoi |
93+
| `src/VirMat/Run3D.hs` | `VirMat.Run3D` | 3D pipeline: same stages for 3D |
94+
| `src/VirMat/Core/Sampling.hs` | `VirMat.Core.Sampling` | Statistical distributions (LogNormal, Normal, Uniform, Custom), inverse-CDF sampling |
95+
| `src/VirMat/Core/Packer.hs` | `VirMat.Core.Packer` | Iterative sphere/circle packing via Verlet integration with force model and damping |
96+
| `src/VirMat/Core/VoronoiMicro.hs` | `VirMat.Core.VoronoiMicro` | Converts Delaunay simplices to Voronoi `MicroGraph` (dual construction) |
97+
| `src/VirMat/Core/FlexMicro.hs` | `VirMat.Core.FlexMicro` | Converts Voronoi polygons/polyhedra to Loop subdivision surfaces; VTK rendering |
98+
99+
### Distributions
100+
101+
| File | Module | Role |
102+
|------|--------|------|
103+
| `src/VirMat/Distributions/GrainSize/GrainDistributionGenerator.hs` | `...GrainDistributionGenerator` | Generates weighted point clouds by grain count or bounding box volume |
104+
| `src/VirMat/Distributions/GrainSize/GrainQuery.hs` | `...GrainQuery` | Computes per-grain morphological properties from subdivision meshes |
105+
| `src/VirMat/Distributions/Texture/ODFSampling.hs` | `...ODFSampling` | Assigns Bingham-sampled crystallographic orientations to grains; IPF RGB coloring |
106+
107+
### I/O
108+
109+
| File | Module | Role |
110+
|------|--------|------|
111+
| `src/VirMat/IO/Import/CommandLine.hs` | `...CommandLine` | CLI parser (optparse-applicative) |
112+
| `src/VirMat/IO/Import/Types.hs` | `...Import.Types` | `JobRequest`, `Dimension`, `StructureSize`, `DistributionType`, `Output` |
113+
| `src/VirMat/IO/Export/ANG/RasterEngine.hs` | `...ANG.RasterEngine` | Triangle rasterization engine that converts `FlexMicro` grains to an ANG grid |
114+
| `src/VirMat/IO/Export/VTK/VTKODFRender.hs` | `...VTK.VTKODFRender` | Renders a discrete ODF to a VTK ImageData (`.vti`) file |
115+
116+
### Other
117+
118+
| File | Module | Role |
119+
|------|--------|------|
120+
| `src/VirMat/PhaseTrans.hs` | `VirMat.PhaseTrans` | Phase transformation simulation: parent/product microstructure overlay |
121+
122+
## Building
123+
124+
### Prerequisites
125+
126+
- [Haskell Stack](https://docs.haskellstack.org/en/stable/) (resolver: `lts-22.11`, GHC 9.6.x)
127+
128+
### With Stack
129+
130+
```bash
131+
# Clone with submodules
132+
git clone --recurse-submodules <repo-url>
133+
cd VirMat
134+
135+
# Build the entire project (root + all packages/)
136+
stack build
137+
138+
# Run the executable
139+
stack exec virmatgen -- --help
140+
```
141+
142+
### With Nix (development shell)
143+
144+
The project provides a Nix flake for a reproducible development environment:
145+
146+
```bash
147+
# Enter the dev shell (provides GHC, Stack, Cabal, HLS, zlib, clang, treefmt)
148+
nix develop
149+
150+
# Then build with Stack as usual
151+
stack build
152+
```
153+
154+
## CLI Usage
155+
156+
The primary executable is `virmatgen`. It generates microstructures based on command-line parameters.
157+
158+
```
159+
virmatgen - Virtual microstructure generator in 3D/2D.
160+
161+
Usage: virmatgen [--3d | --2d]
162+
[--n2d INT | --n2d (DOUBLE,DOUBLE)]
163+
[--packed-n INT | --packed | --random]
164+
[--lnorm (k,mu,mode,o) | --norm (k,mu,s) | --uniform (k,mu,s)] ...
165+
[--seed INT]
166+
-d FILEPATH -s STR
167+
[--showvoronoi] [--showbox] [--showhull]
168+
[--showpoints] [--showsimplex] [--showforces]
169+
```
170+
171+
### Key Options
172+
173+
| Flag | Description | Default |
174+
|------|-------------|---------|
175+
| `--3d` / `--2d` | Dimensionality of the microstructure | `--3d` |
176+
| `--n2d INT` | Number of grains | `500` |
177+
| `--packed` | Enable sphere packing (60 iterations) | enabled |
178+
| `--packed-n INT` | Sphere packing with custom iteration count | -- |
179+
| `--random` | Random (non-packed) grain placement | -- |
180+
| `--lnorm (k,mu,mode,o)` | Log-Normal grain size distribution | -- |
181+
| `--norm (k,mu,s)` | Normal grain size distribution | -- |
182+
| `--uniform (k,mu,s)` | Uniform grain size distribution | -- |
183+
| `--seed INT` | Random seed for reproducibility | system random |
184+
| `-d FILEPATH` | Output directory | required |
185+
| `-s STR` | Sample name | required |
186+
187+
Distribution parameters: `k` = scaling factor, `mu` = average/mean, `s` = variance, `mode` = distribution mode, `o` = offset. Multiple `--lnorm`, `--norm`, and `--uniform` flags can be combined for multi-modal distributions.
188+
189+
### Output Files
190+
191+
| File | Format | Content |
192+
|------|--------|---------|
193+
| `virmat-3d.vtu` | VTK Unstructured Grid | 3D microstructure with grain ID, volume, area, neighbor count, and IPF-ND coloring |
194+
| `virmat-2d.vtu` | VTK Unstructured Grid | 2D microstructure with grain ID, area, boundary length, and neighbor count |
195+
| `virmat-2d.ang` | ANG (EBSD) | Rasterized 2D orientation map for EBSD analysis tools (OIM, MTEX, etc.) |
196+
197+
### Example
198+
199+
```bash
200+
# Generate a 3D microstructure with 200 grains, log-normal size distribution, packed
201+
stack exec virmatgen -- --3d --n2d 200 --packed \
202+
--lnorm '(1.0, 5.0, 3.0, 0.0)' \
203+
--seed 42 \
204+
-d ./output -s mysample
205+
206+
# Generate a 2D microstructure with normal distribution, 100 grains
207+
stack exec virmatgen -- --2d --n2d 100 --packed \
208+
--norm '(1.0, 5.0, 1.0)' \
209+
--seed 42 \
210+
-d ./output -s mysample2d
211+
```
212+
213+
## Dependencies
214+
215+
### Haskell (from Hackage)
216+
217+
`base`, `containers`, `mersenne-random-pure64`, `mtl`, `optparse-applicative`, `random`, `random-fu`, `transformers`, `unordered-containers`, `vector`
218+
219+
### Internal Packages (git submodules)
220+
221+
`DeUni`, `hammer`, `sledge`, `linear-vect`, `SubZero`, `queryforest`, `VTK`, `mcl`
222+
223+
## Author
224+
225+
Edgar Gomes de Araujo (<talktoedgar@gmail.com>)
226+
227+
## License
228+
229+
MIT -- see [LICENSE](./LICENSE).

‎VirMat.cabal‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
name: VirMat
22
version: 0.4.1
3-
license: GPL-3
3+
license: MIT
44
license-file: LICENSE
55
author: Edgar Gomes de Araujo
66
maintainer: Edgar Gomes de Araujo <talktoedgar@gmail.com>

‎packages/DeUni‎

‎packages/SubZero‎

‎packages/VTK‎

‎packages/hammer‎

‎packages/linear-vect‎

‎packages/mcl‎

0 commit comments

Comments
 (0)