graintrace.similarity_metric_library#

Library of similarity/distance metrics for graph-based field clustering.

graintrace.similarity_metric_library.von_mises_stress_distance(u, v)[source]#

Relative absolute difference of von Mises stress between two 6-component stress vectors.

Parameters:
Return type:

float

graintrace.similarity_metric_library.von_mises_stress_distance_batch(X, edges)[source]#

Vectorized von Mises stress distance over all edges (endpoint index pairs).

Parameters:
Return type:

ndarray

graintrace.similarity_metric_library.misorientation_distance(u, v, angle_convention='bunge', input_angle_type='degrees', symmetry='432', output_unit='degrees')[source]#

Misorientation angle between two orientations, respecting crystal symmetry.

Parameters:
Return type:

float

class graintrace.similarity_metric_library.MisorientationDistEdges(angle_convention='bunge', input_angle_type='degrees', symmetry='432', output_unit='degrees', device='cpu')[source]#

Bases: object

Callable computing symmetry-aware misorientation distances over graph edges.

Parameters:

  • angle_convention (str)

  • input_angle_type (str)

  • symmetry (str)

  • output_unit (str)

  • device (str)

angle_convention: str = 'bunge'#
input_angle_type: str = 'degrees'#
symmetry: str = '432'#
output_unit: str = 'degrees'#
device: str = 'cpu'#
graintrace.similarity_metric_library.make_misorientation_dist_edges(angle_convention='bunge', input_angle_type='degrees', symmetry='432', output_unit='degrees', device='cpu')[source]#

Build a MisorientationDistEdges callable with the given conventions/device.

Parameters:

  • angle_convention (str)

  • input_angle_type (str)

  • symmetry (str)

  • output_unit (str)

  • device (str)

Return type:

MisorientationDistEdges

graintrace.similarity_metric_library.diff_norm_3x3(u, v)[source]#

Frobenius norm of the difference between two flattened 3x3 tensors.

Parameters:
Return type:

float

graintrace.similarity_metric_library.diff_norm_3x3_batch(X, edges)[source]#

Vectorized Frobenius norm of tensor differences over all edges.

Parameters:
Return type:

ndarray

graintrace.similarity_metric_library.abs_scalar_diff_distance(u, v)[source]#

Absolute difference between two single-component scalar feature vectors.

Parameters:
Return type:

float

graintrace.similarity_metric_library.abs_scalar_diff_batch(X, edges)[source]#

Vectorized absolute difference of a single scalar feature over all edges.

Parameters:
Return type:

ndarray

class graintrace.similarity_metric_library.SimilarityMetricLibrary[source]#

Bases: object

Metrics returning SimilarityMetric objects (distance functions where smaller = more similar).

Each method defines the required feature columns and a distance func. The order of feature_cols maps to index order: u[i] corresponds to feature_cols[i]. Distance funcs must be top-level (picklable). Provide dist_edges for a vectorized batch path.

von_mises_stress(cols=None)[source]#

SimilarityMetric for von Mises stress distance.

Parameters:

cols (List[str] | None)

Return type:

SimilarityMetric

misorientation(feature_cols=None, symmetry='432', input_angle_type='degrees', angle_convention='mrp', output_unit='degrees', device='cpu')[source]#

SimilarityMetric for symmetry-aware misorientation distance.

Parameters:

  • feature_cols (List[str] | None)

  • symmetry (str)

  • input_angle_type (str)

  • angle_convention (str)

  • output_unit (str)

  • device (str)

Return type:

SimilarityMetric

abs_scalar_diff(cols)[source]#

SimilarityMetric for the absolute difference of a single scalar feature.

Use for a per-node scalar rare-event field such as misorientation-from-initial (reorientation_deg): a smaller absolute difference = more similar. Compatible with both the GSC stage (dist_edges) and the indicator stage (func).

Parameters:

cols (List[str]) – Exactly one feature column name (the scalar field).

Return type:

SimilarityMetric

nye_tensor_norm(cols=None)[source]#

SimilarityMetric for the Frobenius-norm distance of the Nye tensor.

The distance between two points is \(\lVert \boldsymbol\alpha_u - \boldsymbol\alpha_v \rVert_F\), over the nine row-major components of the Nye tensor.

Warning

cols is accepted and then discarded. The feature columns are always the hard-coded nye_tensor_11 .. nye_tensor_33, whatever is passed. To use the Frobenius distance over a different nine-column tensor, construct the SimilarityMetric directly with func=diff_norm_3x3 and dist_edges=diff_norm_3x3_batch.

Parameters:

cols (List[str] | None) – Ignored. Present for signature compatibility only.

Return type:

SimilarityMetric