Crate plot3d 

Plot3D utilities for mesh connectivity, periodicity detection, and I/O.

The crate deliberately mirrors the structure of the legacy Python tooling. For a walkthrough of the rotational periodicity workflow refer to the integration test tests/test_rotational_periodicity.rs::rotational_periodicity_test, which doubles as a usage example in the generated documentation (cargo doc --open).

Diagonal Convention (FaceRecord)

FaceRecord uses il/jl/kl and ih/jh/kh to describe the two diagonal corners of a face on a block. These are not guaranteed to satisfy il <= ih; the ordering encodes orientation. When il > ih, the I-axis is reversed on that face relative to the matching face on the other block.

This matches the GridPro/GlennHT connectivity convention where IMIN,JMIN,KMIN → IMAX,JMAX,KMAX are diagonal corners and reversed indices encode face orientation.

Use the normalized accessors i_lo()/i_hi() when you need min/max values for range iteration or face reconstruction.

Orientation & Permutation System

When two block faces meet at an interface, their parametric (u, v) coordinate systems may be flipped, transposed, or both. The crate encodes all 8 valid orientations as a 3-bit index:

permutation_index = u_reversed | (v_reversed << 1) | (swapped << 2)

The constant PERMUTATION_MATRICES holds the corresponding 2×2 matrices (one per index, 0 through 7). Each matrix transforms face2’s parametric coordinates to align with face1’s.

Index	Binary	u_rev	v_rev	swap	Matrix	Effect
0	000	no	no	no	[[ 1, 0],[ 0, 1]]	identity
1	001	yes	no	no	[[-1, 0],[ 0, 1]]	flip u
2	010	no	yes	no	[[ 1, 0],[ 0,-1]]	flip v
3	011	yes	yes	no	[[-1, 0],[ 0,-1]]	flip both
4	100	no	no	yes	[[ 0, 1],[ 1, 0]]	transpose
5	101	yes	no	yes	[[ 0,-1],[ 1, 0]]	transpose + flip u
6	110	no	yes	yes	[[ 0, 1],[-1, 0]]	transpose + flip v
7	111	yes	yes	yes	[[ 0,-1],[-1, 0]]	transpose + both

The u and v names are abstract parametric axes that map to concrete i/j/k axes depending on which axis is constant on the face:

Constant axis	u (outer loop)	v (inner loop)
I-constant	j	k
J-constant	i	k
K-constant	i	j

Orientation stores the index together with an OrientationPlane tag indicating whether the match is in-plane (same constant axis) or cross-plane (different constant axes, requiring a swap). The connectivity pipeline populates FaceMatch::orientation automatically so downstream code can reconstruct the exact node-to-node mapping without re-sampling block coordinates.

Verification Pipeline

After computing connectivity or periodicity, use the verification functions in the verification module:

1. verify_connectivity — extracts a canonical 2D grid from each face pair, tries all 8 permutation matrices, and picks the one that aligns nodes point-by-point within tolerance. Sets Orientation on each verified match.

2. verify_periodicity — same approach but rotates block1’s face by the periodicity angle before comparing grids.

3. align_face_orientations — for same-dimension in-plane matches, walks all 8 diagonal orientations to find the one where directed I→J→K traversal matches node-by-node.

The recommended pipeline (as used by the connectivity_finder binary):

connectivity_fast → face_matches_to_dict → verify_connectivity
  → align_face_orientations → rotated_periodicity → verify_periodicity

JSON Output Format

The serialization module exports directed lb/ub corners (raw il/jl/kl and ih/jh/kh — no ascending sort). After face_matches_to_dict, block1’s lb physically matches block2’s lb in xyz space, and ub likewise.

{
  "block1": { "block_index": 0, "lb": [0,0,0], "ub": [24,408,0] },
  "block2": { "block_index": 1, "lb": [408,0,0], "ub": [0,0,24] },
  "permutation_index": 5
}

The permutation_index (0-7) is relative to ascending canonical grids (as computed by extract_canonical_grid). It is included as metadata; the directed corners already encode the corner-to-corner mapping.

permutation_matrices_json embeds the full 8-matrix array in the JSON output header so consumers can reconstruct orientations without hard-coding the table.

Re-exports

pub use block::Block;

pub use block::FaceData;

pub use block_analysis::block_connection_matrix;

pub use block_analysis::build_connectivity_graph;

pub use block_analysis::calculate_outward_normals;

pub use block_analysis::check_collinearity;

pub use block_analysis::find_bounding_faces;

pub use block_analysis::find_closest_block;

pub use block_analysis::get_outer_bounds;

pub use block_analysis::standardize_block_orientation;

pub use block_analysis::BlockConnectionOptions;

pub use block_face_functions::create_face_from_diagonals;

pub use block_face_functions::full_face_match;

pub use block_face_functions::full_face_match_transformed;

pub use block_face_functions::get_outer_faces;

pub use block_face_functions::reduce_blocks;

pub use block_face_functions::rotate_block;

pub use block_face_functions::Face;

pub use connectivity::align_face_orientations;

pub use connectivity::connectivity;

pub use connectivity::connectivity_fast;

pub use connectivity::face_matches_to_dict;

pub use connectivity::get_face_intersection;

pub use cylindrical::find_angular_bounding_faces;

pub use cylindrical::to_radius;

pub use cylindrical::to_theta;

pub use differencing::find_edges;

pub use differencing::find_face_edges;

pub use differencing::BlockDiff;

pub use differencing::FaceDiff;

pub use face_record::FaceKey;

pub use face_record::FaceMatch;

pub use face_record::FaceMatchPrinter;

pub use face_record::FaceRecord;

pub use face_record::FaceRecordTraits;

pub use face_record::MatchPoint;

pub use face_record::Orientation;

pub use face_record::OrientationPlane;

pub use face_record::PeriodicPair;

pub use face_record::PERMUTATION_MATRICES;

pub use graph::build_weighted_graph_from_face_matches;

pub use graph::write_ddcmp;

pub use graph::BlockGraph;

pub use graph::WeightAggregate;

pub use metrics::compute_cell_centers;

pub use metrics::compute_cell_volumes;

pub use metrics::compute_face_metrics;

pub use metrics::FaceMetrics;

pub use merge_blocks::combine_2_blocks_mixed_pairing;

pub use merge_blocks::combine_blocks_mixed_pairs;

pub use merge_blocks::combine_nxnxn_cubes_mixed_pairs;

pub use point_match::point_match;

pub use read::read_ap_nasa;

pub use read::read_plot3d_ascii;

pub use read::read_plot3d_binary;

pub use read::BinaryFormat;

pub use read::FloatPrecision;

pub use rotational_periodicity::create_rotation_matrix;

pub use rotational_periodicity::rotate_block_with_matrix;

pub use rotational_periodicity::rotated_periodicity;

pub use rotational_periodicity::rotational_periodicity;

pub use serialization::face_match_from_json;

pub use serialization::face_match_to_json;

pub use serialization::face_record_from_json;

pub use serialization::face_record_to_json;

pub use serialization::permutation_matrices_json;

pub use split_block::split_blocks;

pub use split_block::SplitDirection;

pub use translational_periodicity::translational_periodicity;

pub use utils::apply_rotation;

pub use utils::compute_min_gcd;

pub use utils::Endian;

pub use verification::apply_permutation;

pub use verification::determine_plane;

pub use verification::extract_canonical_grid;

pub use verification::try_all_permutations;

pub use verification::verify_connectivity;

pub use verification::verify_match;

pub use verification::verify_partial_match;

pub use verification::verify_periodicity;

pub use verification::verify_translational_periodicity;

pub use write::write_plot3d;

pub use dual_graph::build_cell_graph;

pub use dual_graph::cell_index;

pub use dual_graph::global_cell_id;

pub use dual_graph::CellGraph;

pub use flat_data::build_flat_mesh;

pub use flat_data::FlatMesh;

Modules

block

block_analysis

Block-level analysis: connectivity graphs, orientation standardization, bounding face detection, and outward normal computation.

block_face_functions

connectivity

Block-to-block face connectivity detection.

cylindrical

Cylindrical coordinate transforms and angular bounding face detection.

differencing

Forward and backward differencing for structured grid edges.

dual_graph

Cell-level dual graph for finite-volume discretization on multi-block structured grids.

face_pool

Cylindrical-coordinate face pool and edge matching utilities for rotational periodicity detection.

face_record

Core data types for face connectivity: FaceRecord, FaceMatch, MatchPoint, and Orientation.

flat_data

Flat SoA (Structure of Arrays) mesh representation for GPU finite-volume solvers.

graph

Graph partitioning utilities for structured multi-block grids.

merge_blocks

metrics

Finite-volume geometry metrics for structured Plot3D blocks.

point_match

Point matching utilities for structured grid faces.

read

rotational_periodicity

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

serialization

JSON serialization for face records and face matches.

split_block

Block splitting utilities that preserve multi-grid compatibility.

translational_periodicity

Translational periodicity detection for structured multi-block grids.

utils

verification

Gold-standard verification for connectivity and periodicity.

write

Constants

PI

Pi constant matching the active Float precision. Archimedes’ constant (π)

Type Aliases

Float

Floating-point precision type used throughout the crate. Defaults to f64; enable the f32 Cargo feature for single precision.