documentation updates

Author: pjuangph

.gitignore

@@ -6,6 +6,8 @@
 # vs code folders
 .vscode/
 *.p3d
+# Allow test data p3d files
+!python/tests/data/cross_plane_pair.p3d
 *.x
 *.lock
 python/mesh.pickle

docs/notes/connectivity.rst

@@ -52,23 +52,86 @@ When faces lie on **different constant planes** (e.g., a K-face connects to a J-
 
 **4 × 2 = 8 total permutations. lb/ub only encodes 4.**
 
-The ``orientation`` vector solves this. It is computed by ``_compute_orientation()`` in ``connectivity.py`` and maps each face1 axis to a face2 axis:
+Permutation Matrix System
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. code-block:: python
-
-    # orientation = [d1_maps_to, d2_maps_to, d3_maps_to]
-    # 1-indexed: 1=I, 2=J, 3=K
-    #
-    # Example: orientation = [2, 1, 3]
-    #   face1 I-axis -> face2 J-axis
-    #   face1 J-axis -> face2 I-axis
-    #   face1 K-axis -> face2 K-axis
+Both the Python and Rust implementations encode all 8 orientations as a 3-bit ``permutation_index`` into an array of 2×2 signed matrices (``PERMUTATION_MATRICES``):
 
-Direction (forward/reverse) is encoded in the ``lb/ub`` values, not in the orientation vector. The ``verify.py`` module's ``_generate_permutations()`` tests all 8 combinations (4 direct + 4 transposed) to confirm the match.
+.. code-block:: text
 
-For a detailed analysis with diagrams, see the `Root Cause Analysis <https://github.com/nasa/Plot3D_utilities/blob/main/docs/notes/unverified_connectivity_findings.md>`_ document.
+    permutation_index = u_reversed | (v_reversed << 1) | (swapped << 2)
 
-**Rust version**: The `plot3d-rs <https://github.com/pjuangph/plot3d-rs>`_ crate mirrors this logic but stores orientation as flags: ``Orientation { swapped, u_reversed, v_reversed }``. Both representations encode the same 8 permutations.
+.. list-table:: The 8 Permutation Matrices
+   :header-rows: 1
+   :widths: 8 8 8 8 8 20 20
+
+   * - 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
+
+In **Python**, the ``PERMUTATION_MATRICES`` constant is defined in ``connectivity.py`` and ``_orient_vec_to_permutation()`` converts the legacy orientation vector to a ``permutation_index``.
+
+In **Rust**, the ``PERMUTATION_MATRICES`` constant is in ``face_record.rs`` and each ``FaceMatch`` carries an ``Orientation { permutation_index, plane }`` set by ``verify_connectivity``.
 
 The ``u`` and ``v`` names are abstract — they map to concrete i/j/k axes depending on which axis is constant:
 
@@ -91,6 +154,52 @@ The ``u`` and ``v`` names are abstract — they map to concrete i/j/k axes depen
 
 So ``u_reversed: true`` means the outer-loop axis runs opposite direction on block2 vs block1, and ``v_reversed: true`` means the inner-loop axis runs opposite.
 
+Legacy Orientation Vector
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The older Python ``_compute_orientation()`` in ``connectivity.py`` produces an orientation vector that maps each face1 axis to a face2 axis:
+
+.. code-block:: python
+
+    # orientation = [d1_maps_to, d2_maps_to, d3_maps_to]
+    # 1-indexed: 1=I, 2=J, 3=K
+    #
+    # Example: orientation = [2, 1, 3]
+    #   face1 I-axis -> face2 J-axis
+    #   face1 J-axis -> face2 I-axis
+    #   face1 K-axis -> face2 K-axis
+
+Direction (forward/reverse) is encoded in the ``lb/ub`` values, not in the orientation vector. The ``_orient_vec_to_permutation()`` function converts this vector to a ``permutation_index`` for the unified system. The verification modules (``verify_connectivity`` / ``verify_periodicity``) test all 8 permutations to confirm the match.
+
+For a detailed analysis with diagrams, see the `Root Cause Analysis <https://github.com/nasa/Plot3D_utilities/blob/main/docs/notes/unverified_connectivity_findings.md>`_ document.
+
+
+Directed Diagonal for GHT_CONN Export
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The GlennHT connectivity file (``.ght_conn``) uses a **directed diagonal** convention where each face is specified by two corners ``(IMIN, JMIN, KMIN)`` and ``(IMAX, JMAX, KMAX)``. For cross-plane matches, the traversal direction is encoded by allowing the "max" corner to be less than the "min" corner on reversed axes. For example:
+
+.. code-block:: text
+
+    1   1   1   1   25  409   1
+    2 409   1   1    1    1  25
+
+Here block 2's i-axis runs 409 → 1 (reversed), encoding the cross-plane orientation without a separate permutation matrix.
+
+When connectivity is computed in **Python** (via ``connectivity_fast``), the ``lb``/``ub`` values already encode the directed diagonal from the point-match traversal order.
+
+When connectivity is computed in **Rust** (via the ``connectivity-finder`` binary in grid-packed), the JSON output uses ascending ``lo``/``hi`` bounds with a ``permutation_index`` (0-7). Use ``reconstruct_directed_diagonal()`` to convert these to directed ``lb``/``ub`` before exporting:
+
+.. code-block:: python
+
+    from plot3d.connectivity import reconstruct_directed_diagonal
+
+    # face_match has ascending lb/ub + permutation_index from Rust JSON
+    directed_match = reconstruct_directed_diagonal(face_match)
+    # directed_match now has directed lb/ub and permutation_index = -1
+
+The ``export_to_glennht_conn()`` function applies this reconstruction automatically, so callers do not need to call it explicitly.
+
 
 Plotting Connectivity using Paraview
 ****************************************

docs/notes/exporting.rst

@@ -1,6 +1,15 @@
 Exporting to GlennHT Connectivity Files
 ###############################################
-This is an example of how I read a mesh, convert it to ascii, save it, find connectivity, find periodicty and export to glennht format. 
+
+.. note::
+
+    The GHT_CONN file uses a **directed diagonal** convention where cross-plane
+    matches encode traversal direction in the corner ordering (e.g., ``IMIN > IMAX``
+    means the i-axis is reversed). ``export_to_glennht_conn()`` handles this
+    automatically via ``reconstruct_directed_diagonal()``. See
+    :ref:`Directed Diagonal for GHT_CONN Export <connectivity>` for details.
+
+This is an example of how I read a mesh, convert it to ascii, save it, find connectivity, find periodicty and export to glennht format.
 In this example we will use the file `PahtCascade-ASCII <https://nasa-public-data.s3.amazonaws.com/plot3d_utilities/PahtCascade-ASCII.xyz>`_
 
 .. code-block:: python 

docs/notes/periodicity.rst

@@ -32,4 +32,20 @@ In this example we will use the file  `PahtCascade-ASCII <https://nasa-public-da
     :width: 800px
     :align: center
     :alt: periodic surface block 2 exit of the domain
-    :figclass: align-center
+    :figclass: align-center
+
+Verification
+**************
+
+After computing periodic matches, call ``verify_periodicity`` to confirm that
+face pairs align after rotation and to set the correct ``permutation_index``
+(0-7) from the ``PERMUTATION_MATRICES`` system. This is the same 8-permutation
+scheme used for connectivity — see :doc:`connectivity` for the full table.
+
+.. code-block:: python
+
+    from plot3d import verify_periodicity
+
+    verified, mismatched = verify_periodicity(
+        blocks, periodic_surfaces, rotation_angle_rad, rotation_axis='x', tol=1e-4
+    )

python/plot3d/connectivity.py

@@ -86,7 +86,6 @@
 """
 
 
-
 def _orient_vec_to_permutation(orient_vec: list, lb1: list, ub1: list,
                                lb2: list, ub2: list) -> Tuple[int, str]:
     """Convert an orientation vector to a ``(permutation_index, plane)`` tuple.

python/plot3d/glennht/export_functions.py

@@ -551,22 +551,22 @@ def summarize_contiguous(records: List[Dict[str, Any]]) -> Dict[str, Any]:
     }
 
 
-def export_to_glennht_conn(matches:List[Dict[str, Dict[int, str]]],outer_faces:List[Dict[str,int]],filename:str, 
+def export_to_glennht_conn(matches:List[Dict[str, Dict[int, str]]],outer_faces:List[Dict[str,int]],filename:str,
                            gif_pairs:List[List[Dict[str, int]]],gif_faces:List[List[Dict[str, int]]],
                                volume_zones:List[Dict[str,Any]]):
-    """Exports the connectivity to GlennHT format 
+    """Exports the connectivity to GlennHT format
 
     Args:
-        matches (Dict[str,Dict[int,str]]): Any matching faces between blocks 
-        outer_faces (Dict[str,int]): Non matching faces of all blocks or surfaces to consider 
+        matches (Dict[str,Dict[int,str]]): Any matching faces between blocks
+        outer_faces (Dict[str,int]): Non matching faces of all blocks or surfaces to consider
     """
     lines = list()
-    
+
     # Print face matches
     blocks = ['block1','block2']
     nMatches = len(matches)
-    lines.append(f'{nMatches}\n') # Print number of matches 
-    for match in matches:                        
+    lines.append(f'{nMatches}\n') # Print number of matches
+    for match in matches:
         for block in blocks:
             block_indx = match[block]['block_index']+1 # type: ignore # block1 and block2 are arbitrary names, the key is the block index 
             lb = match[block]['lb'] # type: ignore