Module rotational_periodicity 

Utilities for detecting rotational periodicity in structured multi-block grids.

This module mirrors the behaviour of the original Python tooling and is covered end-to-end by the integration test in tests/test_rotational_periodicity.rs. Generate HTML documentation with cargo doc --open to browse rendered versions of these notes alongside the Rust API surface.

Three-Phase Periodicity Algorithm

The rotated_periodicity function (via rotational_periodicity_core) detects periodic face pairs across a rotation angle in three phases:

Phase 1 — Full-face matching via parallel theta bucketing

All outer faces are inserted into a FacePool that buckets them by their angular (theta) coordinate in cylindrical space. For each face, the rotated counterpart’s theta range is computed and candidate faces in the matching bucket are tested with full_face_match_transformed. When all four rotated corners match a candidate’s corners within tolerance, a PeriodicPair is recorded. This phase runs in parallel across all outer faces.

Phase 2 — Split-face matching with corner pre-check

Remaining unmatched faces are tested for partial overlap. Before the expensive get_face_intersection, a quick corner pre-check confirms that at least one rotated corner lies near a candidate face. When a partial match is found, both faces are split along the intersection boundary. Matched sub-faces produce PeriodicPair records and remnants re-enter the pool. This loop runs until convergence — there is no iteration limit (earlier versions had a hardcoded limit of 50 which was insufficient; Phase 2 may need 100+ iterations).

Phase 3 — Edge-based matching

Any faces still unmatched after Phase 2 are tested using edge geometry. Face edges are extracted and compared via count_edge_matches in the FacePool. This catches degenerate or thin-strip faces that the area-based intersection misses.

Use [verify_periodicity] to confirm that every matched periodic pair has coincident nodes after rotation.

Functions

create_rotation_matrix

Rotation matrix for the requested axis.

rotate_block_with_matrix

Rotate a block using a precomputed rotation matrix.

rotated_periodicity

Rotate the entire mesh by an arbitrary angle and recover periodic matches.

rotational_periodicity

Detect rotational periodicity by reducing grids by the minimum shared GCD, running the 3-phase matching algorithm, then scaling results back.