Module connectivity 

Block-to-block face connectivity detection.

The core data types (FaceRecord, FaceMatch, MatchPoint, Orientation) live in crate::face_record. This module provides the algorithms that populate them.

Three-Phase Connectivity Algorithm

The connectivity_fast function detects face matches in three phases:

Phase 1 – Full-face matching using canonical grids + permutation matrices

For every pair of outer faces, corner comparison is used as a quick pre-filter. Candidate matches are then verified by extracting both faces as canonical 2D grids (ascending index order) and trying all 8 [PERMUTATION_MATRICES] on face B. When Face_B * permutation == Face_A within tolerance, the match is confirmed and the winning permutation_index is stored in FaceMatch::orientation.

Phase 2 – Partial / split-face node-by-node matching

Remaining unmatched faces are tested for partial overlap via get_face_intersection. When a partial match is found, both faces are split along the intersection boundary. The matched sub-faces produce FaceMatch records, while the leftover remnants are fed back into the pool for subsequent iterations. This loop continues until no new matches are discovered during a full pass.

Phase 3 – Fresh-face validation with all-node AABB pre-checks

After Phase 2 converges, any remaining unmatched faces may still have partial overlaps with faces that were already matched in Phases 1 or 2. Phase 3 re-examines these by computing axis-aligned bounding boxes (AABBs) using all face nodes (not just corners), then testing AABB overlap before calling get_face_intersection. This catches edge cases where two corners of a sub-face lie outside the bounding diagonal of a candidate face, which the 2-corner AABB would miss.

Post-processing

After matching, align_face_orientations can optionally correct the diagonal corners of block2 in each FaceMatch so that they encode the detected orientation. This embeds the permutation directly into the il/jl/kl and ih/jh/kh fields, which is the format expected by solvers that use the GridPro/GlennHT diagonal convention.

Tolerance

The default spatial tolerance used for vertex comparisons is [DEFAULT_TOL] (1e-6). Both connectivity and connectivity_fast accept an explicit tolerance parameter to override this default.

Verification

Use [verify_connectivity] after running connectivity to confirm that all matched face pairs have coincident nodes.

Functions

align_face_orientations

Find the correct orientation for each face match using permutation matrices.

connectivity

Determine face-to-face connectivity and exterior faces for all blocks.

connectivity_fast

Connectivity computation performed on GCD-reduced blocks.

face_matches_to_dict

Establish diagonal correspondence for face-match records.

find_matching_blocks

Recursively match all faces between a pair of blocks.

get_face_intersection

Compute the coincident nodes between two faces on separate blocks.