{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "gt-intro",
   "metadata": {},
   "source": [
    "# Grain tracking across load steps\n",
    "\n",
    "Track and match grains across two load steps by building a grain graph from each FF reconstruction and matching them via message passing, using `VoronoiMeshBuilder.build_graph` and `GraphGrainMatcher`. Use this when you have two FF grain CSVs of the same sample at different loads or times and want a grain correspondence.\n",
    "\n",
    "**Needs:** NEPER (tessellation for the graph).\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": "gt-inputs",
   "metadata": {},
   "source": "## Inputs\n\nTwo FF grain CSVs of the same sample at two load steps, each with `X, Y, Z`, Euler columns (`Eul0/1/2`), and a 9-component elastic strain (`eKen11..eKen33`). The repo ships `mwe_data/synthetic_load_exp/expsyn_146time.csv` and `expsyn_160time.csv`. See [concepts](../concepts.rst) for the raw FF format."
  },
  {
   "cell_type": "markdown",
   "id": "gt-recipe-md",
   "metadata": {},
   "source": "## Recipe"
  },
  {
   "cell_type": "code",
   "id": "gt-recipe-code",
   "metadata": {},
   "execution_count": null,
   "outputs": [],
   "source": "from graintrace.construct_voronoi_mesh import VoronoiMeshBuilder\nfrom graintrace.grain_graph_matching import GraphGrainMatcher\n\neKen = [f\"eKen{i}{j}\" for i in (1, 2, 3) for j in (1, 2, 3)]\n\ndef make(csv, out, bbox):\n    b = VoronoiMeshBuilder(\n        input_csv=csv, output_dir=out, bounding_box=bbox, dim=3, weighted=False,\n        auto_fix_bbox=False, auto_rotate=False,\n        angle_identifier=[\"Eul0\", \"Eul1\", \"Eul2\"], orientation_descriptor=\"euler-bunge\",\n        orientation_active_convention=True, elastic_strain_identifier=eKen,\n        strain_unit=\"microstrain\",\n    )\n    return b.build_graph(CVT_iter=10)\n\nga = make(\"mwe_data/synthetic_load_exp/expsyn_146time.csv\", \"out/track_a\",\n          [-200, 200, -173.205, 173.205, 0, 650])\ngb = make(\"mwe_data/synthetic_load_exp/expsyn_160time.csv\", \"out/track_b\",\n          [-200, 200, -173.205, 173.205, 0, 680])\n\nGraphGrainMatcher(graph_a=ga, graph_b=gb, output_dir=\"out/grain_tracking\").match_grains(\n    message_passing_iter=3,\n    neighbor_selection_param={\"lambda\": 0.00125, \"iterations\": 100, \"tolerance\": 1e-6},\n)"
  },
  {
   "cell_type": "markdown",
   "id": "gt-key-params",
   "metadata": {},
   "source": "## Key parameters\n\n- `bounding_box`: per load step; each step can have a different z-extent.\n- `build_graph(CVT_iter=...)`: CVT iterations for the tessellation the graph is built on.\n- `match_grains(message_passing_iter, neighbor_selection_param)`: the message-passing depth and the neighbor-selection optimization (`lambda`, `iterations`, `tolerance`)."
  },
  {
   "cell_type": "markdown",
   "id": "gt-outputs",
   "metadata": {},
   "source": "## Outputs\n\nThe grain correspondence between the two graphs (matched IDs and mapping, plus diagnostics) is written to `output_dir`."
  },
  {
   "cell_type": "markdown",
   "id": "gt-gotchas",
   "metadata": {},
   "source": "## Gotchas\n\n- Orientations are read as Euler-Bunge; keep `angle_identifier` and `orientation_descriptor` consistent with the data.\n- This uses `build_graph` rather than a full mesh, so no GMSH or CUBIT is needed. NEPER must be resolvable (see [installation](../install.rst))."
  },
  {
   "cell_type": "markdown",
   "id": "gt-full-example",
   "metadata": {},
   "source": "## Full example\n\n**Full script:** [examples/demonstrate_graintracking.py](https://github.com/applied-material-modeling/graintrace/blob/main/examples/demonstrate_graintracking.py)"
  }
 ],
 "metadata": {
  "nbsphinx": {
   "execute": "never"
  },
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "name": "python"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}