Concepts & data formats#

The pipeline#

graintrace runs the grain-scale workflow in four stages:

  1. Reconstruct a 3D microstructure from experimental data. Far-field (FF) grain centroids become a Voronoi/CVT tessellation (NEPER); near-field (NF) and EBSD voxel fields are segmented into grains (flood fill or graph/Leiden clustering). All three are meshed to conformal hex with CUBIT/SCULPT (a NEPER/gmsh tet mesh is a fallback). Multiple FF scan layers are stitched into one grain set by region matching.

  2. Calibrate the crystal-plasticity material model to a macroscopic stress-strain curve with a pyzag analytic-adjoint Taylor model.

  3. Simulate with MOOSE/PUMA CPFE using NEML2 v3 AOTI-compiled models.

  4. Analyze the fields (distributions, macroscopic response, pole figures, IPF coloring) and identify rare events for targeted measurement.

Data types#

FF HEDM data#

Per-scan-layer CSV, whitespace-delimited with an 8-line header. Key columns:

Column

Meaning

X, Y, Z

grain centroid position (micrometers)

GrainRadius

equivalent-sphere radius (micrometers)

Eul0, Eul1, Eul2

Bunge Euler angles (degrees or radians)

Confidence

fit quality (typically filter to >= 0.7 or 0.9)

eFab11..eFab33

fabric/lattice strain tensor (row-major, 9 components)

eKen11..eKen33

Kenesei elastic strain tensor (row-major, 9 components), usually microstrain

ScanID

assigned during stitching

Units are detected automatically: if any Euler value exceeds 2π, the file is in degrees, otherwise radians. Multiple scan layers are Z-shifted before stitching.

NF HEDM data#

Per-layer .mic files in a folder, tab-delimited, with three % metadata lines above the column-name row:

%OrientationRowNr NrMatches RunTime X Y TriEdgeSize UpDown Eul1 Eul2 Eul3 Confidence PhaseNr

NearFieldMeshBuilder reads a folder of .mic files; the exp_file_token parameter is the filename prefix used to find them. Pre-gridded NF data can instead go through NFGridConversion. The full schema, including the metadata lines and the .csv fallback, is in File formats.

Note

graintrace has no .ang reader. EBSD/NF data in .ang form must be converted to the merged-CSV or .mic schema above with your own tooling before it enters the package. See File formats for both target schemas.

EBSD data#

A flat CSV with columns x, y, z, Eul0, Eul1, Eul2, where z is the layer index times the EBSD z-step and the Euler columns are Bunge angles. This feeds VoxelMeshBuilder. Merging per-layer source files into this single CSV is the user’s responsibility; graintrace reads only the merged form.

Orientations#

Orientations are interchanged as NEML2 v3 MRP (tan(θ/4)·axis), the canonical on-disk format. FF orientations.dat is Euler-Bunge in degrees; convert it with graintrace.orientation_helper (which delegates to NEML2). graintrace’s "mrp" label elsewhere means Gibbs/Rodrigues (tan θ/2), which is not the same as NEML2 v3 MRP. Use euler_to_mrp to get the NEML2 form the CPFE model expects.

Meshing#

The recommended CPFE mesh is a conformal hex built with VoxelMeshBuilder (SCULPT). Hex elements behave better for crystal plasticity. The NEPER/GMSH tet mesh (generate_mesh=True on the FF build) is a fallback for when CUBIT/SCULPT is unavailable.