{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "md-title",
   "metadata": {},
   "source": [
    "# Microstructure generation\n",
    "\n",
    "Generate synthetic grain structures with NEPER via `CrystalGenerator`. This page collects vetted morpho-string and iteration-budget recipes distilled from 12 studied cases spanning equiaxed, lamellar, columnar, and elongated grains and lognormal, normal, and bimodal size distributions. For meshing the generated grid, see [meshing](meshing.rst).\n",
    "\n",
    "**Needs:** NEPER.\n",
    "\n",
    "<div class=\"admonition warning\">\n",
    "<p class=\"admonition-title\">Tier B: needs NEPER</p>\n",
    "<p>This notebook needs the <code>neper</code> binary, which is not available in CI or Google Colab, so it is <strong>not executed when these docs are built</strong>. It ships as an annotated code listing with <strong>no stored output</strong> \u2014 nothing on this page is a hand-written or fabricated result. Run it in a configured environment (see the <a href=\"../install.rst\">installation guide</a>) to produce the figures, and run it from the <strong>repository root</strong> so the <code>mwe_data/</code> paths resolve.</p>\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "md-inputs",
   "metadata": {},
   "source": "## Inputs\n\nNone. Generation is driven entirely by a morpho string and a bounding box. The `examples/demonstrate_hedm_anisotropic.py` example runs the 12-case anisotropic study; `examples/demonstrate_synthetic_cpfe.py` generates, meshes, and runs CPFE."
  },
  {
   "cell_type": "markdown",
   "id": "md-recipe",
   "metadata": {},
   "source": "## Recipe"
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "code-recipe-equiaxed",
   "metadata": {},
   "outputs": [],
   "source": "from graintrace.generate_random_crystal import CrystalGenerator\n\ncg = CrystalGenerator(\n    output_dir=\"out\",\n    bounding_box=[-500, 500, -500, 500, -500, 500],   # 1 mm cube\n    dim=3,\n    seed=42,\n)\n\n# Equiaxed, normal size distribution\ncg.generate_tessellation(\n    morpho_args={\"type\": \"raw\", \"morpho_str\": \"diameq:normal(100, 20)\"},\n    iterations=5000,\n    extra_neper_args=[\"-reg\", \"1\"],\n)"
  },
  {
   "cell_type": "markdown",
   "id": "md-elongated",
   "metadata": {},
   "source": "For elongated or anisotropic grains, append `aspratio(x, y, z)` to the morpho string. The following elongates roughly 3x along z, matching `examples/demonstrate_hedm_anisotropic.py`. Use the higher iteration budget and keep `-reg 1`:"
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "code-recipe-elongated",
   "metadata": {},
   "outputs": [],
   "source": "z_aspect = 3.0\ncg.generate_tessellation(\n    morpho_args={\n        \"type\": \"raw\",\n        \"morpho_str\": f\"diameq:lognormal(130, 5),aspratio(1, 1, {z_aspect})\",\n    },\n    iterations=20000,            # elongated -> use the 20k budget\n    extra_neper_args=[\"-reg\", \"1\"],\n)"
  },
  {
   "cell_type": "markdown",
   "id": "md-aspratio-note",
   "metadata": {},
   "source": "`aspratio` sets grain shape only. Far-field HEDM cannot recover true grain morphology from centroids; NF-HEDM is the genuine source of grain morphology. Use the elongated generator for benchmarks or ground truth, not to infer shape from FF. See [the pitfalls page](../pitfalls.rst)."
  },
  {
   "cell_type": "markdown",
   "id": "md-key-params",
   "metadata": {},
   "source": "## Key parameters\n\n- `seed`: a fixed integer gives a bit-identical `.tess` across runs.\n- `morpho_args={\"type\": \"raw\", ...}`: pass `morpho_str` directly. This is the only path that exposes NEPER's full recipe grammar (mixtures, coupled constraints, columnar, lamellar, `aspratio`).\n- `extra_neper_args=[\"-reg\", \"1\"]`: removes sub-resolution artifact cells; use for equiaxed, columnar, and elongated, skip for lamellar.\n- `iterations`: 5000 for normal, 15000 for bimodal, 20000 for lognormal-tail or elongated. More iterations reduce the loss and improve agreement with the prescribed distribution; beyond about 50,000 the loss decreases slowly.\n- `n`: the grain count is derived automatically (`-n from_morpho`) when the morpho string carries a size scale (`diameq:...`); otherwise pass `n=<int>`.\n\nThe API applies the `-reg 1` cleanup plus an optional post-hoc `r >= 5 um` filter, then writes the canonical outputs (`voronoi.tess`, `.geo`, `.ori`, `.stcell`, `.csv`)."
  },
  {
   "cell_type": "markdown",
   "id": "md-limitations",
   "metadata": {},
   "source": "## Known limitations (NEPER 4.10.2-45)\n\n- **Lamellar takes a single scalar width only.** `lamellar(w=<distribution>)` inline aborts; `lamellar(w=file(...))` reads per-grain values from a file. Varying-width lamellar requires multiple steps.\n- **Columnar takes a single axis letter only.** `columnar(v=<axis_letter>)` (e.g. `v=z`) is the only working form; the vector form `columnar(v=(0,0,1))` hangs NEPER indefinitely.\n- **Columnar cross-section sigma has a Poisson floor.** For single-mode columnar recipes NEPER hits the mean but delivers a coefficient of variation near 0.36 regardless of the target sigma. Bimodal columnar fits well because the mixture gives the optimizer more variance.\n- **Bimodal mixture weights are by count, not volume.** Two peaks at 40 and 100 um with 50/50 weights means 50/50 grain counts, not equal volume fractions."
  },
  {
   "cell_type": "markdown",
   "id": "md-outputs",
   "metadata": {},
   "source": "## Outputs (in `output_dir`)\n\n- `voronoi.tess`: the tessellation.\n- `voronoi.csv`: per-grain centroids, sizes, and orientations.\n- `voronoi.stcell`: per-cell statistics used for the distribution check.\n- `.geo` / `.ori`: geometry and orientation files."
  },
  {
   "cell_type": "markdown",
   "id": "md-gotchas",
   "metadata": {},
   "source": "## Gotchas\n\n- After generation, confirm that the achieved grain-size distribution matches the prescribed one: plot the histogram from `voronoi.stcell` against the target PDF. Non-agreement means too few iterations or one of the NEPER limitations above.\n- Use the minimum number of grains that faithfully represents the target distribution. Fewer grains means fewer mesh elements and shorter CPFE wall-clock; add grains only when the histogram or the CPFE quantity of interest fails to converge."
  },
  {
   "cell_type": "markdown",
   "id": "md-full-script",
   "metadata": {},
   "source": "**Full script:** [examples/demonstrate_hedm_anisotropic.py](https://github.com/applied-material-modeling/graintrace/blob/main/examples/demonstrate_hedm_anisotropic.py)"
  }
 ],
 "metadata": {
  "nbsphinx": {
   "execute": "never"
  },
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "name": "python"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}