Publish task-preserving HJ checkpoints and model card

Three registered seeds, validation-selected thresholds, aggregate evaluation, limitations, and links to GitHub and supplementary movies.

LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Ehsan Roohi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

MODEL_CARD_LIMITATIONS.md

@@ -0,0 +1,16 @@
+# Intended use and limitations
+
+The checkpoints are research artifacts for segmentation of shocks and
+vortex-core candidates in two-dimensional compressible CFD fields following the
+documented input contract. They are not a flow solver, a substitute for CFD
+convergence checks, or a universal detector.
+
+Training supervision is physics-derived and weak. CFD Dice values measure
+agreement with corrected weak references, not human ground truth. Analytic
+vortex and SU2-ray evaluations are independent bounded controls but do not
+measure complete post-shock vortex accuracy or full-front precision. Sigmoid
+scores are not independently calibrated probabilities. Near-wall vorticity,
+strong shear, contact-like layers, numerical oscillations and unfamiliar grids
+remain possible failure modes. Users must inspect overlays and preserve the
+separation among ML-only, physics-only and hybrid products.
+

README.md

@@ -1,3 +1,70 @@
 ---
 license: mit
+library_name: pytorch
+pipeline_tag: image-segmentation
+tags:
+- computational-fluid-dynamics
+- compressible-flow
+- shock-detection
+- vortex-detection
+- multi-label-segmentation
+- task-preserving-adaptation
+datasets:
+- custom
+metrics:
+- dice
 ---
+
+# Task-Preserving Shock–Vortex Segmentation (HJ)
+
+This repository contains the three registered checkpoints of the task-preserving
+harmonized joint (HJ) network used for overlapping shock and vortex-core
+segmentation in compressible CFD. The model consumes primitive flow fields plus
+deterministic differential diagnostics and returns independent sigmoid fields;
+shock and vortex labels are therefore allowed to overlap.
+
+The architecture has a shared encoder with widths `[10, 20, 40, 80]` and
+task-specific shock and vortex decoders. During corrected-target shock
+adaptation, the encoder and complete vortex pathway are frozen. Only the shock
+decoder and projection are updated, giving exact retained-task preservation by
+construction and direct array replay.
+
+## Registered results
+
+Means and sample standard deviations over seeds 20260904–20260906:
+
+| Evaluation | Result |
+|---|---:|
+| Airfoil shock Dice, corrected weak reference | 0.936 ± 0.004 |
+| Cylinder shock Dice, corrected weak reference | 0.939 ± 0.024 |
+| Retained airfoil core Dice | 0.827 ± 0.048 |
+| Retained cylinder core Dice | 0.228 ± 0.020 |
+| Independent analytic-vortex disk Dice | 0.672 ± 0.086 |
+| Independent analytic centre recovery | 0.889 ± 0.192 |
+| Continued-SU2 finite-ray coverage | 1.000 ± 0.000 |
+| Continued-SU2 conditional normal MAE | 0.00284c ± 0.00092c |
+
+Core probability drift is exactly zero for all three seeds over all 129
+seed–field evaluations. These results do **not** establish human-ground-truth
+accuracy, universal geometry transfer, or complete-front validation. The CFD
+Dice references are physics-derived weak references; the analytic vortex and
+finite SU2 rays are distinct bounded controls.
+
+## Files
+
+- `checkpoint_seed2026090X.pt`: task-preserving HJ checkpoint.
+- `thresholds_seed2026090X.json`: validation-selected operating point.
+- `aggregate.json`: complete three-seed aggregate used by the manuscript.
+- `MODEL_CARD_LIMITATIONS.md`: intended use and limitations.
+
+## Code, media and demo
+
+- [Source code and reproducibility material](https://github.com/Ehsan-Roohi/ShockVortexML)
+- [Original-quality supplementary movies](https://github.com/Ehsan-Roohi/ShockVortexML/releases/tag/movies-localfront-v2-20260909)
+- [Author’s YouTube channel](https://www.youtube.com/@ehsan_roohi)
+- Interactive Space: linked from this model page after publication.
+
+## License and citation
+
+Released under the MIT License. The manuscript is under review/preparation;
+please use the repository citation metadata until a DOI is assigned.

aggregate.json

@@ -0,0 +1,329 @@
+{
+  "seeds": [
+    20260904,
+    20260905,
+    20260906
+  ],
+  "arms": {
+    "hj_restricted": {
+      "label": "Task-preserving HJ",
+      "parameters": 268496,
+      "trainable_parameters": 75891,
+      "shock_dice": {
+        "airfoil": {
+          "mean": 0.9357071988455214,
+          "sample_sd": 0.004202090216577011,
+          "values": [
+            0.9344757083049362,
+            0.9322584471635962,
+            0.9403874410680321
+          ]
+        },
+        "cylinder": {
+          "mean": 0.9386199049068382,
+          "sample_sd": 0.02439132578156726,
+          "values": [
+            0.9633139318703084,
+            0.9380027911530677,
+            0.9145429916971386
+          ]
+        }
+      },
+      "core_dice": {
+        "airfoil": {
+          "mean": 0.8269258635545622,
+          "sample_sd": 0.04765046704785947,
+          "values": [
+            0.8326573417737513,
+            0.8714513644366197,
+            0.7766688844533156
+          ]
+        },
+        "cylinder": {
+          "mean": 0.2277874006486062,
+          "sample_sd": 0.02043299476214628,
+          "values": [
+            0.21611023364740484,
+            0.21587098195068724,
+            0.25138098634772654
+          ]
+        }
+      },
+      "core_probability_max_drift_by_seed": [
+        0.0,
+        0.0,
+        0.0
+      ],
+      "core_probability_bit_exact_by_seed": [
+        true,
+        true,
+        true
+      ],
+      "analytic_vortex_dice": {
+        "mean": 0.6724153508806848,
+        "sample_sd": 0.08568023829738895,
+        "values": [
+          0.5769273709675609,
+          0.697739762255559,
+          0.7425789194189347
+        ]
+      },
+      "analytic_centre_recovery": {
+        "mean": 0.8888888888888888,
+        "sample_sd": 0.1924500897298753,
+        "values": [
+          0.6666666666666666,
+          1.0,
+          1.0
+        ]
+      },
+      "parallel_shear_core_fraction_by_seed": [
+        0.0,
+        0.0,
+        0.0
+      ],
+      "su2_ray_coverage": {
+        "mean": 1.0,
+        "sample_sd": 0.0,
+        "values": [
+          1.0,
+          1.0,
+          1.0
+        ]
+      },
+      "su2_normal_mae_c": {
+        "mean": 0.0028370008979655163,
+        "sample_sd": 0.0009152518358685503,
+        "values": [
+          0.002958751756579843,
+          0.0018669673584372772,
+          0.0036852835788794285
+        ]
+      },
+      "su2_absolute_angle_error_deg": {
+        "mean": 0.18143140034565305,
+        "sample_sd": 0.06487893122310609,
+        "values": [
+          0.21318896960592185,
+          0.22431372796385815,
+          0.10679150346717918
+        ]
+      }
+    },
+    "unet_decoder": {
+      "label": "Shared-decoder U-Net",
+      "parameters": 267639,
+      "trainable_parameters": 107982,
+      "shock_dice": {
+        "airfoil": {
+          "mean": 0.935129593481926,
+          "sample_sd": 0.010422196951165707,
+          "values": [
+            0.9373893805309734,
+            0.9237628932698358,
+            0.9442365066449688
+          ]
+        },
+        "cylinder": {
+          "mean": 0.8952466680148627,
+          "sample_sd": 0.02168587314766801,
+          "values": [
+            0.9029934022401697,
+            0.8707512695811054,
+            0.9119953322233133
+          ]
+        }
+      },
+      "core_dice": {
+        "airfoil": {
+          "mean": 0.0826739706460272,
+          "sample_sd": 0.07363293735241894,
+          "values": [
+            0.031190445940795324,
+            0.16701517391824225,
+            0.049816292079044054
+          ]
+        },
+        "cylinder": {
+          "mean": 0.0006778472151364567,
+          "sample_sd": 0.0010449639082319893,
+          "values": [
+            0.0,
+            0.0018812602293524971,
+            0.0001522814160568731
+          ]
+        }
+      },
+      "core_probability_max_drift_by_seed": [
+        0.9986276626586914,
+        0.9993672966957092,
+        0.9808923602104187
+      ],
+      "core_probability_bit_exact_by_seed": [
+        false,
+        false,
+        false
+      ],
+      "analytic_vortex_dice": {
+        "mean": 0.08138905594173194,
+        "sample_sd": 0.06587599798052739,
+        "values": [
+          0.06842924398390403,
+          0.022956100595298717,
+          0.15278182324599307
+        ]
+      },
+      "analytic_centre_recovery": {
+        "mean": 0.4722222222222222,
+        "sample_sd": 0.5023094811118091,
+        "values": [
+          0.4166666666666667,
+          0.0,
+          1.0
+        ]
+      },
+      "parallel_shear_core_fraction_by_seed": [
+        0.0,
+        0.0,
+        0.0
+      ],
+      "su2_ray_coverage": {
+        "mean": 1.0,
+        "sample_sd": 0.0,
+        "values": [
+          1.0,
+          1.0,
+          1.0
+        ]
+      },
+      "su2_normal_mae_c": {
+        "mean": 0.00303275559886716,
+        "sample_sd": 0.00037233965760421583,
+        "values": [
+          0.003356846392082894,
+          0.0026260457607492488,
+          0.003115374643769338
+        ]
+      },
+      "su2_absolute_angle_error_deg": {
+        "mean": 0.19599332091759744,
+        "sample_sd": 0.0681041637364286,
+        "values": [
+          0.22607250461241507,
+          0.2438791543721152,
+          0.11802830376826208
+        ]
+      }
+    },
+    "hj_joint": {
+      "label": "Joint HJ control",
+      "parameters": 268496,
+      "trainable_parameters": 268496,
+      "shock_dice": {
+        "airfoil": {
+          "mean": 0.9579573129256692,
+          "sample_sd": 0.0012847180825509754,
+          "values": [
+            0.9566206394057329,
+            0.9580684437295857,
+            0.9591828556416889
+          ]
+        },
+        "cylinder": {
+          "mean": 0.9550029949711734,
+          "sample_sd": 0.021041558444334304,
+          "values": [
+            0.96236045950239,
+            0.9312706353897836,
+            0.9713778900213463
+          ]
+        }
+      },
+      "core_dice": {
+        "airfoil": {
+          "mean": 0.38242093516209885,
+          "sample_sd": 0.3819531226443472,
+          "values": [
+            0.7809354789713089,
+            0.346802921008104,
+            0.019524405506883606
+          ]
+        },
+        "cylinder": {
+          "mean": 0.10417600929204775,
+          "sample_sd": 0.08639857863261999,
+          "values": [
+            0.1185937184552822,
+            0.18245874281475988,
+            0.011475566606101176
+          ]
+        }
+      },
+      "core_probability_max_drift_by_seed": [
+        0.9097776412963867,
+        0.9530678987503052,
+        0.970103919506073
+      ],
+      "core_probability_bit_exact_by_seed": [
+        false,
+        false,
+        false
+      ],
+      "analytic_vortex_dice": {
+        "mean": 0.593029778671725,
+        "sample_sd": 0.1915973306070832,
+        "values": [
+          0.3750270075978114,
+          0.7346751674685614,
+          0.6693871609488024
+        ]
+      },
+      "analytic_centre_recovery": {
+        "mean": 0.8611111111111112,
+        "sample_sd": 0.24056261216234404,
+        "values": [
+          0.5833333333333334,
+          1.0,
+          1.0
+        ]
+      },
+      "parallel_shear_core_fraction_by_seed": [
+        0.0,
+        0.0,
+        0.0
+      ],
+      "su2_ray_coverage": {
+        "mean": 1.0,
+        "sample_sd": 0.0,
+        "values": [
+          1.0,
+          1.0,
+          1.0
+        ]
+      },
+      "su2_normal_mae_c": {
+        "mean": 0.002473480977439144,
+        "sample_sd": 0.00021664348876689025,
+        "values": [
+          0.002471484269415214,
+          0.002691115919064767,
+          0.002257842743837451
+        ]
+      },
+      "su2_absolute_angle_error_deg": {
+        "mean": 0.1494419299895185,
+        "sample_sd": 0.045027183385208974,
+        "values": [
+          0.1930990552509229,
+          0.10315955775708403,
+          0.15206717696054853
+        ]
+      }
+    }
+  },
+  "scope": {
+    "segmentation": "43 development-test fields per seed; weak corrected targets; thresholds selected on 43 validation fields only",
+    "analytic_vortex": "48 states from 24 correlated two-time analytic trajectories; no training or calibration",
+    "su2": "five finite analytical ray segments per seed; exposed-development fields; conditional localization"
+  }
+}

checkpoint_seed20260904.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:cc9c132c724b8f7517724d4f037f241c6941b90e048dfb877d346773ed733099
+size 1103349

checkpoint_seed20260905.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ae1dc8c0b3819eba4ce6387157b486b92514ec924de88500a2a639f98cc47b08
+size 1103349

checkpoint_seed20260906.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:af4bc7ae0988a9383dab5d8241bbd8c5705de717b8c30d4e417ef2cf1186edab
+size 1103349

thresholds_seed20260904.json

@@ -0,0 +1,5 @@
+{
+  "shock": 0.97,
+  "vortex_core": 0.85,
+  "selection": "validation-only family-macro corrected weak Dice; core threshold inherited"
+}

thresholds_seed20260905.json

@@ -0,0 +1,5 @@
+{
+  "shock": 0.97,
+  "vortex_core": 0.85,
+  "selection": "validation-only family-macro corrected weak Dice; core threshold inherited"
+}

thresholds_seed20260906.json

@@ -0,0 +1,5 @@
+{
+  "shock": 0.97,
+  "vortex_core": 0.85,
+  "selection": "validation-only family-macro corrected weak Dice; core threshold inherited"
+}