You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+28Lines changed: 28 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -67,6 +67,34 @@ Never use jupyter notebook unless you are done with your .py file and want to de
67
67
| Christopher Keokot | Intern | Fall 2021 | Plot3D ReactJS GUI ||
68
68
| Tim Beach | Advisor | Fall 2021 | Block splitting help ||
69
69
70
+
# Connectivity & Orientation
71
+
72
+
`connectivity_fast()` finds matching faces between blocks and returns orientation data for each match. When two faces lie on different constant planes (e.g., a K-face connects to a J-face), the varying axes differ and an axis swap may be needed. This is encoded as a `permutation_index` (0–7) using 3 bits:
# 'permutation_matrix': list # 2x2 signed permutation matrix
89
+
# }
90
+
```
91
+
92
+
The 8 permutation matrices are also available as `plot3d.PERMUTATION_MATRICES`.
93
+
94
+
# Documentation
95
+
-[Face Orientation: Cross-Plane Connectivity](docs/notes/unverified_connectivity_findings.md) — why cross-plane face connections need orientation flags beyond lb/ub, and how the 8-permutation system works
96
+
-[Presentation (PowerPoint)](docs/notes/unverified_connectivity_findings.pptx) — visual walkthrough of 2D→3D diagonal combinatorics
97
+
70
98
# Rust Version
71
99
The rust version is available here. This version of the code is useful for creating CFD solvers in rust [Plot3D-RS](https://github.com/pjuangph/plot3d-rs) It has most of the functionality of the python version except for some of the GlennHT pre-processing code.
Copy file name to clipboardExpand all lines: docs/notes/connectivity.rst
+161Lines changed: 161 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -40,6 +40,167 @@ This is the matching face within the omesh
40
40
:figclass:align-center
41
41
42
42
43
+
Face Orientation: Cross-Plane Connectivity
44
+
*********************************************
45
+
46
+
When two connected faces share the **same constant axis** (e.g., both K-constant), the two varying axes are identical and only 4 direction combinations exist. These are fully encodable by the ``lb/ub`` diagonal convention.
47
+
48
+
When faces lie on **different constant planes** (e.g., a K-face connects to a J-face), the varying axes differ. Face A varies in (i, j) while Face B varies in (i, k). This introduces an additional degree of freedom — which axis maps to which:
49
+
50
+
- **No swap**: A(i,j) maps to B(i,k) — 4 direction combos (encodable by lb/ub)
51
+
- **Swapped**: A(i,j) maps to B(k,i) — 4 direction combos (need orientation)
52
+
53
+
**4 × 2 = 8 total permutations. lb/ub only encodes 4.**
54
+
55
+
Permutation Matrix System
56
+
~~~~~~~~~~~~~~~~~~~~~~~~~~
57
+
58
+
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``):
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``.
133
+
134
+
In **Rust**, the ``PERMUTATION_MATRICES`` constant is in ``face_record.rs`` and each ``FaceMatch`` carries an ``Orientation { permutation_index, plane }`` set by ``verify_connectivity``.
135
+
136
+
The ``u`` and ``v`` names are abstract — they map to concrete i/j/k axes depending on which axis is constant:
137
+
138
+
.. list-table:: u/v to axis mapping
139
+
:header-rows: 1
140
+
:widths: 30 35 35
141
+
142
+
* - Constant axis
143
+
- u (outer loop)
144
+
- v (inner loop)
145
+
* - I-constant
146
+
- j
147
+
- k
148
+
* - J-constant
149
+
- i
150
+
- k
151
+
* - K-constant
152
+
- i
153
+
- j
154
+
155
+
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.
156
+
157
+
Legacy Orientation Vector
158
+
~~~~~~~~~~~~~~~~~~~~~~~~~~
159
+
160
+
The older Python ``_compute_orientation()`` in ``connectivity.py`` produces an orientation vector that maps each face1 axis to a face2 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.
173
+
174
+
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.
175
+
176
+
177
+
Directed Diagonal for GHT_CONN Export
178
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
179
+
180
+
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:
181
+
182
+
.. code-block:: text
183
+
184
+
1 1 1 1 25 409 1
185
+
2 409 1 1 1 1 25
186
+
187
+
Here block 2's i-axis runs 409 → 1 (reversed), encoding the cross-plane orientation without a separate permutation matrix.
188
+
189
+
When connectivity is computed in **Python** (via ``connectivity_fast``), the ``lb``/``ub`` values already encode the directed diagonal from the point-match traversal order.
190
+
191
+
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:
192
+
193
+
.. code-block:: python
194
+
195
+
from plot3d.connectivity import reconstruct_directed_diagonal
196
+
197
+
# face_match has ascending lb/ub + permutation_index from Rust JSON
# directed_match now has directed lb/ub and permutation_index = -1
200
+
201
+
The ``export_to_glennht_conn()`` function applies this reconstruction automatically, so callers do not need to call it explicitly.
202
+
203
+
43
204
Plotting Connectivity using Paraview
44
205
****************************************
45
206
This example shows how you can take a mesh created Numeca Autogrid and plot the connecitivity using paraview. With this information, anyone should be able to comprehend the format and export it to whatever solver.
0 commit comments