Tutorials#

One notebook per workflow stage, each linking to the matching algorithm page and API reference. Read a tutorial for how to do it; read the algorithm page for why it works.

Reading order#

The stages chain, and the tutorials are ordered to match. A complete experimental study runs left to right:

raw HEDM scans  ->  stitch  ->  reconstruct  ->  mesh  ->  CPFE  ->  analyse

If you are evaluating graintrace rather than using it, start at the analysis end: Post-CPFE analysis & plotting and Rare-event identification (REI) run on shipped sample data with nothing but pip install graintrace, so you can see what the package produces before installing anything heavy.

Two tiers#

Whether a tutorial shows you real output depends on what it needs to run.

Tier	What it means
A	Runs with no external binary. Every number and figure on the page was produced by running the code above it — nothing is hand-written.
B	Needs NEPER, CUBIT/SCULPT, or MOOSE/PUMA. None of those exist in CI or Colab, so these notebooks are annotated code listings with no stored output. Each one names its external requirement at the top, and the table below says exactly which binary.

Tier A splits again by where the execution happens, which is worth knowing if you are editing one:

Tutorial	How its output is produced
Rare-event identification on a 2D field, Rare-event identification on a 3D field, Comparing two REI point clouds, Rare-event identification (REI)	No stored output; `nbsphinx` executes them during the documentation build, so a broken cell breaks CI. The first three generate their own synthetic data and therefore carry an “Open in Colab” badge.
Post-CPFE analysis & plotting, Reorientation and fragmentation	Outputs executed locally and committed, because both need NEML2 v3 for the orientation maths and NEML2 is not pip-installable in CI. Re-run them after editing: `jupyter nbconvert --execute --inplace` from `docs/tutorials/`.

Neither of the last two gets a Colab badge: they read ../../mwe_data/, which only exists in a checkout.

What each Tier B tutorial needs#

Reproduce these by running the matching script from Examples in a configured environment. The required capability is the only thing standing between the listing and a figure:

Tutorial	Needs	Why
HEDM scan simulation and stitching	`neper`	Generates the synthetic crystal and the z-scans being stitched.
Microstructure generation	`neper`	The tessellation is the output.
FF Voronoi reconstruction	`neper`	Voronoi/CVT reconstruction from FF centroids.
Registering FF data to the sim frame	`neper`	One Voronoi build per file supplies the rotated `O11..O33`.
Grain tracking across load steps	`neper`	Builds the per-step grain graphs that are matched.
NF mesh reconstruction	`psculpt` + `epu` (CUBIT)	Hexahedral meshing of the segmented voxel grid.
Voxel segmentation and meshing	`psculpt` + `epu` (CUBIT)	Same; the segmentation half is pure Python.
Meshing a grain grid into hex	`psculpt` + `epu` (CUBIT)	The `mesher="voxel"` path needs nothing, the `"sculpt"` path needs CUBIT.
CPFE simulation	`puma-opt` + `neml2-compile`, CUDA recommended	Runs the finite-element solve.
CPFE (NF geometry + FF initial strain)	`neper` + CUBIT + `puma-opt`	Spans the whole pipeline in one notebook.
Material calibration	NEML2 v3 + `pyzag`	No binary needed, but NEML2 v3 is not pip-installable, so CI cannot build it. This is the one Tier B tutorial that could become Tier A on a machine with NEML2 installed.

Note

Tier A notebooks address data as ../../mwe_data/..., relative to docs/tutorials/, because that is the working directory nbsphinx gives the kernel. Tier B notebooks use repository-root-relative paths and are meant to be run from the root of a checkout. If a path does not resolve, that is which convention you are on.

Data & microstructure

Calibration & simulation

Analysis

Reference

Examples