{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "md-title",
   "metadata": {},
   "source": [
    "# FF Voronoi reconstruction\n",
    "\n",
    "Reconstruct a 3D microstructure from far-field (FF) HEDM grain centroids via NEPER Voronoi/CVT tessellation, using `VoronoiMeshBuilder`. Use this to produce per-grain orientations, a per-grain initial elastic-strain file, and a `.tess` reconstruction to feed CPFE or graph building.\n",
    "\n",
    "**Needs:** NEPER (and gmsh if `generate_mesh=True`).\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\nAn FF grain CSV with `X, Y, Z` (and optional `GrainRadius`), Euler columns (`Eul0/1/2`), and a 9-component elastic strain (`eKen11..eKen33`). The repo ships `mwe_data/ff_calibration/0.csv` (500 grains). See [the raw FF format](../concepts.rst)."
  },
  {
   "cell_type": "markdown",
   "id": "md-recipe",
   "metadata": {},
   "source": "## Recipe"
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "code-recipe",
   "metadata": {},
   "outputs": [],
   "source": "from graintrace.construct_voronoi_mesh import VoronoiMeshBuilder\n\nbuilder = VoronoiMeshBuilder(\n    input_csv=\"mwe_data/ff_calibration/0.csv\",\n    output_dir=\"out/FF\",\n    bounding_box=[-477, 528, -487, 532, -1025, 625],   # xlo,xhi,ylo,yhi,zlo,zhi\n    dim=3, weighted=False,\n    auto_fix_bbox=True, bbox_fix_mode=\"remove_points\",\n    auto_rotate=False, rotate_angles=(0, 0, 0),\n    angle_identifier=[\"Eul0\", \"Eul1\", \"Eul2\"],\n    orientation_descriptor=\"euler-bunge\", orientation_active_convention=True,\n    elastic_strain_identifier=[f\"eKen{i}{j}\" for i in (1, 2, 3) for j in (1, 2, 3)],\n    strain_unit=\"microstrain\", unit=\"rad\",             # unit of the Euler angles\n)\nbuilder.build_voronoi(\n    generate_mesh=False,         # default; True -> NEPER/GMSH tet .msh (fallback only)\n    option=\"centroid\",           # \"voronoi\" | \"centroid\" | \"centroidsize\"\n    CVT_iter=1000, morphoalgo=\"subplex\",\n    mesh_quality_min=0.7, relative_el_size=2.0,\n)"
  },
  {
   "cell_type": "markdown",
   "id": "md-key-params",
   "metadata": {},
   "source": "## Key parameters\n\n- `bounding_box`: `[xlo,xhi,ylo,yhi,zlo,zhi]` in micrometers. `auto_fix_bbox` + `bbox_fix_mode` handle out-of-box points (`remove_points` for production).\n- `unit` (`\"rad\"`/`\"deg\"`) must match the actual Euler units; `strain_unit` is the unit of the ee columns.\n- `option` / `CVT_iter` / `morphoalgo`: tessellation morphology and CVT optimization.\n- `generate_mesh`: keep `False`. The default CPFE mesh is a SCULPT hex built from `reconstruction_reformatted.csv` via `VoxelMeshBuilder` (see [meshing](meshing.rst)); the NEPER/GMSH tet `.msh` is a fallback only."
  },
  {
   "cell_type": "markdown",
   "id": "md-outputs",
   "metadata": {},
   "source": "## Outputs (in `output_dir`)\n\n- `reconstruction.tess` / `reconstruction.ori` (9-col rotation matrix) / `reconstruction.msh` (GMSH tet, only if `generate_mesh=True`).\n- `orientations.dat`: per-grain Euler, always degrees after an FF build.\n- `reconstruction_cpfe_ee.csv`: per-grain initial elastic strain (12 columns: `x, y, z` + 9).\n- `reconstruction_reformatted.csv`: per-voxel grain IDs + Euler (FF -> voxel input)."
  },
  {
   "cell_type": "markdown",
   "id": "md-gotchas",
   "metadata": {},
   "source": "## Gotchas\n\n- `orientations.dat` is in degrees regardless of input units; a downstream `VoxelMeshBuilder` needs `angle_type=\"degrees\"`, and CPFE needs `orientation_helper.euler_to_mrp(...)`."
  },
  {
   "cell_type": "markdown",
   "id": "md-full-script",
   "metadata": {},
   "source": "**Full script:** [examples/demonstrate_farfield.py](https://github.com/applied-material-modeling/graintrace/blob/main/examples/demonstrate_farfield.py)"
  }
 ],
 "metadata": {
  "nbsphinx": {
   "execute": "never"
  },
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "name": "python"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}