---
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

The Space displays the extended multistructure pipeline used in Movies S9/S10:
the learned local shock-front model with fixed front extraction, retained
core/wake branches and the PM-v4 expanding-flow region. This pipeline differs
from the three registered HJ control checkpoints in this repository. The
metrics above describe those HJ controls, not the extended movie pipeline.
The Space includes the figure provenance and links to the movie release.

- [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](https://huggingface.co/spaces/ehsanroohi/ShockVortexML-Demo)

## 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.