graintrace.ipf_orientation_tracking#

Build per-entity orientation tracks across load steps for IPF trajectory plots.

OrientationTracker returns a list of (k, 3) orientation arrays (MRP for simulation, Euler for experiment), one per tracked entity, ready for graintrace.plot_postprocessing.plot_ipf_orientation_tracking(). Simulation entities keep a stable id across time (no matching); experiment grains are tracked either by a stable grain_id column or, when ids are not stable across loads, by graph matching (GraphGrainMatcher).

class graintrace.ipf_orientation_tracking.OrientationTracker(ori_tensor='ori_rodrigues', block_id_col='block_id', eul_cols=('Eul0', 'Eul1', 'Eul2'))[source]#

Bases: object

Build per-entity orientation tracks across load steps for IPF plots.

Holds the column/tensor conventions shared by the track builders; each method returns a list of (k, 3) orientation arrays (one per tracked entity) to feed graintrace.plot_postprocessing.plot_ipf_orientation_tracking().

Parameters:

  • ori_tensor (str) – CPFE block tensor name for per-grain simulation orientations (neml2 MRP; default "ori_rodrigues").

  • block_id_col (str) – per-element field-CSV column giving each element’s grain/block id (default "block_id").

  • eul_cols (Sequence[str]) – experiment Euler-angle column/feature names (default Bunge triple).

static compose_tracks(a_to_b_list, seed_ids=None)[source]#

Chain pairwise a_to_b maps into multi-step row tracks.

a_to_b_list[k] maps a row in step k to its match in step k+1 (-1 unmatched). Each track follows one seed row and truncates at the first -1. seed_ids defaults to every row of the first map.

Parameters:
Return type:

List[List[int]]

simulation_grain_tracks(results, grain_ids=None, steps=None)[source]#

Per-grain orientation (MRP) tracks from a CPFE block output.

Grain identity is stable across time, so no matching is needed.

Parameters:

  • results – a SimulationResults.

  • grain_ids (Sequence[int] | None) – grains to track; defaults to all results.grain_ids.

  • steps (Sequence[int] | None) – time-step indices to keep; defaults to all steps.

Returns:

list of (k, 3) MRP arrays, one per grain.

Return type:

List[ndarray]

simulation_element_tracks(results, block_id=None, element_ids=None, steps=None)[source]#

Per-element orientation (MRP) tracks within one grain (fragmentation).

Element membership comes from the block_id column of the per-element field CSVs (block == grain subdomain), so no mesh file is needed; alternatively pass element_ids explicitly.

Parameters:

  • results – a SimulationResults whose field_dir holds per-element CSVs.

  • block_id (int | None) – grain/block id whose elements to track (ignored if element_ids is given).

  • element_ids (Sequence[int] | None) – explicit element ids to track (one track each).

  • steps (Sequence[int] | None) – field-step indices to keep; defaults to all available field steps.

Returns:

list of (k, 3) MRP arrays, one per element.

Return type:

List[ndarray]

experiment_grain_tracks_by_id(step_csvs, seed_grain_ids=None, grain_id_col='grain_id')[source]#

Per-grain Euler tracks across experiment steps by a stable grain-id column.

Use when the per-step CSVs carry a consistent grain_id (no matching).

Parameters:

  • step_csvs (Sequence[str]) – per-step FF CSV paths, ordered by load step.

  • seed_grain_ids (Sequence[int] | None) – grain ids to track; defaults to all ids in the first step.

  • grain_id_col (str) – name of the stable grain-id column.

Returns:

list of (k, 3) Euler arrays, one per seed grain; a grain missing from a step truncates its track there.

Return type:

List[ndarray]

experiment_grain_tracks(graphs, seed_grain_ids=None, message_passing_iter=3, neighbor_selection_param=None, output_dir='grain_tracking_output')[source]#

Per-grain Euler tracks across experiment load steps via graph matching.

Matches grains on consecutive step pairs with GraphGrainMatcher, composes the pairwise a_to_b maps (compose_tracks()), and reads each tracked grain’s Euler angles from the graph node features – the exact nodes the matcher used, so indices stay aligned even when the tessellation dropped out-of-box points.

Parameters:

  • graphs (Sequence) – one grain graph per step (e.g. from VoronoiMeshBuilder.build_graph), ordered by load step.

  • seed_grain_ids (Sequence[int] | None) – first-step node indices to track; defaults to all nodes.

  • message_passing_iter (int) – matcher message-passing iterations.

  • neighbor_selection_param (dict | None) – matcher neighbor-selection params (matcher default if None).

  • output_dir (str) – base directory for the matcher’s per-pair result files.

Returns:

list of (k, 3) Euler arrays, one per seed grain; a grain that stops matching is truncated there.

Return type:

List[ndarray]