{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "md-title",
   "metadata": {},
   "source": [
    "# Registering FF data to the sim frame\n",
    "\n",
    "Rotate raw far-field experiment CSVs into the simulation frame before calibration, using `graintrace.experiment_rotation_helper`. For each file it applies a sample tilt, builds a Voronoi reconstruction, and appends the rotated orientation matrix `O11..O33`. Use this to prepare per-stress-level FF CSVs for a physically registered [material calibration](material-calibration.rst).\n",
    "\n",
    "**Needs:** NEPER (a Voronoi build per file supplies the rotated `O`).\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\nA folder of numeric-named per-stress-level FF CSVs (`0.csv`, `50.csv`, ...), each with `X, Y, Z, GrainRadius`, Euler columns (`Eul0/1/2`), and the 9-component elastic strain (`eKen11..eKen33`). Raw FF files may already carry `O11..O33`. The repo ships `mwe_data/ff_calibration/`. 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": "import numpy as np\nfrom graintrace.experiment_rotation_helper import (\n    update_experiments, collect_experiment_files,\n)\n\nfiles, stress_levels = collect_experiment_files(\"mwe_data/ff_calibration\")\nupdate_experiments(\n    input_files=files,\n    output_root=\"out/rotated_experiments\",\n    bounding_box=[-477, 528, -487, 532, -1025, 625],\n    auto_fix_bbox=True, bbox_fix_mode=\"remove_points\",\n    rotate_angles=(0, 0, -3.6 / 180 * np.pi),   # sample tilt; unit must match `unit`\n    unit=\"rad\",\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)"
  },
  {
   "cell_type": "markdown",
   "id": "md-key-params",
   "metadata": {},
   "source": "## Key parameters\n\n- `rotate_angles` + `unit`: the sample-to-sim tilt (radians here), applied to both positions and orientations.\n- `bounding_box` + `auto_fix_bbox` / `bbox_fix_mode`: drop out-of-box grains (`remove_points` for production).\n- `elastic_strain_identifier`: the 9 `eKen` columns, scaled by 1e6 if the strain unit is microstrain."
  },
  {
   "cell_type": "markdown",
   "id": "md-outputs",
   "metadata": {},
   "source": "## Outputs\n\n`out/rotated_experiments/<name>.csv` per input, each with rotated `O11..O33` (from `reconstruction.ori`) plus coordinates, Euler angles, and `eKen` columns. These feed [material calibration](material-calibration.rst) as its `data_dir`."
  },
  {
   "cell_type": "markdown",
   "id": "md-gotchas",
   "metadata": {},
   "source": "## Gotchas\n\n- The helper replaces any pre-existing `O` columns with the freshly rotated ones (it drops the raw `O` before concatenating), so there are no duplicate `O11.1` columns.\n- Each file triggers a full NEPER tessellation; a few hundred grains is quick, thousands are slower.\n- For a quick, non-registered calibration you can skip this step and point calibration straight at raw CSVs that already contain `O11..O33` (as in `mwe_data/ff_calibration`)."
  },
  {
   "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
}