Add mass-balance config + LSTM-AE (ONNX/pt) + NPW localization eval_results.json

README.md

@@ -0,0 +1,121 @@
+---
+license: mit
+library_name: pytorch
+pipeline_tag: time-series-forecasting
+tags:
+  - oil-gas
+  - petrochemical
+  - pipeline-monitoring
+  - leak-detection
+  - scada
+  - anomaly-detection
+  - lstm-autoencoder
+  - mass-balance
+  - aria-ai
+model-index:
+  - name: pipelinewatch-leak-detector
+    results:
+      - task:
+          type: anomaly-detection
+        dataset:
+          name: PipelineWatch synthetic SCADA test episodes (54 held-out)
+          type: alirezaaminzadeh/pipelinewatch-scada-synthetic
+        metrics:
+          - type: detection_rate_overall
+            value: 1.0
+          - type: mean_time_to_detect_seconds_mass_balance
+            value: 70.0
+          - type: mean_time_to_detect_seconds_lstm_ae
+            value: 41.25
+          - type: mean_false_alarms_per_hour_mass_balance
+            value: 0.356
+          - type: mean_false_alarms_per_hour_lstm_ae
+            value: 3.842
+---
+
+# PipelineWatch — Leak Detector (Mass-Balance + LSTM-Autoencoder + NPW Localization)
+
+Two complementary leak detectors plus a best-effort negative-pressure-wave (NPW) leak-location
+estimator, trained/calibrated on the fully synthetic [`pipelinewatch-scada-synthetic`](https://huggingface.co/datasets/alirezaaminzadeh/pipelinewatch-scada-synthetic)
+dataset. Part of the [Aria AI](https://aria-ai.ir) `Aria PetroOps` → "Pipeline Monitoring (midstream)" module validation.
+
+## Data honesty
+
+Trained and evaluated **entirely on a synthetic hydraulic/SCADA simulation** (see the dataset card).
+Pipeline length, wave speed, and friction constants are assumed textbook values, not calibrated to any
+real pipeline. **Do not treat the numbers below as a guarantee of field performance** — they measure
+whether the *methodology* works on a controlled, honestly-labeled synthetic benchmark. A real pilot needs
+re-calibration against the target line's own historian data before any threshold is trusted operationally.
+
+## Two detectors, an explicit trade-off — not a single "best" model
+
+| Detector | Overall detection rate | Mean TTD (s) | False-alarm episodes (of 30 normal test) | Mean false alarms/hour |
+|---|---:|---:|---:|---:|
+| **Mass-balance (primary)** | 100% | 70.0 | 5 (16.7%) | 0.36 |
+| LSTM-Autoencoder (fast secondary) | 100% | **41.25** | 21 (70.0%) | 3.84 |
+
+**Mass-balance is recommended as the primary/first-line trigger** because, at an identical 100%
+detection rate on the held-out test episodes, it has a far lower false-alarm rate. **The LSTM-Autoencoder
+detects leaks roughly 30-40% faster on average** (see the by-severity breakdown below) and is recommended
+as a fast *corroborating* secondary signal — e.g. "raise confidence" rather than "raise the alarm alone" —
+given its higher false-alarm rate on this synthetic data. This is a genuine, measured trade-off, not a
+modeling error; both directions are reported below rather than only publishing whichever number looks best.
+
+### By severity (time-to-detect, seconds after true onset)
+
+| Severity | Mass-balance mean / median TTD | LSTM-AE mean / median TTD |
+|---|---:|---:|
+| Small (1-3% of flow) | 91.25 / 82.5 | 50.0 / 52.5 |
+| Medium (3-8% of flow) | 66.25 / 70.0 | 43.1 / 42.5 |
+| Large (8-20% of flow) | 52.5 / 52.5 | 30.6 / 35.0 |
+
+Both detectors reach **100% detection on every severity band** on the 54 held-out test episodes (8-8-8
+per severity among the 24 test leak episodes) — but note the dataset is a controlled, low-instrumentation-noise
+simulation; see `published_baselines` in `eval_results.json` for how real fielded systems' sensitivity
+varies (often 0.5-40% of flow depending on sensor spacing and instrumentation quality).
+
+## Best-effort NPW leak localization
+
+Standard negative-pressure-wave time-of-arrival technique (textbook pipeline-engineering method, not a
+vendor's proprietary algorithm): cross-correlating high-pass-filtered inlet/outlet pressure around the
+detection time estimates the arrival-time difference `dt`, and `location_km_from_inlet = 0.5*(L + c*dt)`.
+Evaluated on all 24 test leak episodes (using the primary mass-balance detector's alarm time as the trigger):
+
+| | Mean abs. error (km) | Median abs. error (km) |
+|---|---:|---:|
+| **Overall** (pipe length 60 km) | 13.37 | 8.43 |
+| Small leaks | 12.68 | 15.27 |
+| Medium leaks | 13.72 | 7.88 |
+| Large leaks | 13.72 | 5.78 |
+
+**This is explicitly best-effort/demo-grade, reported honestly including the cases where it does not work
+well** — accuracy is meaningfully worse for small leaks (weak signal-to-noise for the pressure transient)
+than for large ones. A real deployment would need a much better-instrumented, higher-sample-rate pressure
+system and a calibrated wave speed to get field-grade localization accuracy.
+
+## Files
+
+- `lstm_ae.onnx` / `lstm_ae.pt` — LSTM-Autoencoder (encoder LSTM → latent → MLP decoder, same architecture
+  family as `refineryguard-lstm-ae`); ONNX used for CPU inference in the Space.
+- `scaler.joblib` — `StandardScaler` fit on the 4 detector columns from normal-only train episodes.
+- `mass_balance_config.joblib` — calibrated `(window, persist, mu, sigma, k)` for the mass-balance detector.
+- `thresholds.joblib` — LSTM-AE reconstruction-error alarm threshold (99th percentile of a held-out normal
+  calibration split, never seen during gradient training).
+- `eval_results.json` / `manifest.json` — full reproducible evaluation protocol and dataset manifest.
+
+## Reproducibility note
+
+The mass-balance detector's numbers above are exactly reproducible (`python scripts/run_pipeline.py`
+regenerates them bit-for-bit given the fixed seed). The LSTM-AE's numbers have minor run-to-run
+floating-point jitter from PyTorch's multi-threaded CPU kernels even with all seeds fixed — the qualitative
+finding (faster detection, higher false-alarm rate than mass-balance) is stable across reruns, but exact
+decimals may shift by a few percent.
+
+## Related
+
+- Dataset: [alirezaaminzadeh/pipelinewatch-scada-synthetic](https://huggingface.co/datasets/alirezaaminzadeh/pipelinewatch-scada-synthetic)
+- Space: [alirezaaminzadeh/pipelinewatch-leak-detection](https://huggingface.co/spaces/alirezaaminzadeh/pipelinewatch-leak-detection)
+- Sibling anomaly-detection projects: [alirezaaminzadeh/refineryguard-lstm-ae](https://huggingface.co/alirezaaminzadeh/refineryguard-lstm-ae), [alirezaaminzadeh/rotaguard-rul-lstm](https://huggingface.co/alirezaaminzadeh/rotaguard-rul-lstm)
+- Product: [aria-ai.ir](https://aria-ai.ir)
+
+MIT · Aria AI Engineering Team

eval_results.json

@@ -0,0 +1,143 @@
+{
+  "protocol": {
+    "honesty": "100% synthetic hydraulic/SCADA simulation (see src/pipelinewatch/simulate.py). Pipeline length (60 km), pressure-wave speed (1.1 km/s), and the friction/pressure relationship are ASSUMED textbook-typical values -- NOT calibrated to any real, named pipeline or customer asset. A real pilot deployment must replace/calibrate these constants against actual SCADA historian data from the specific line before any number below, especially the NPW localization error, is trusted for field use.",
+    "n_episodes": 180,
+    "n_train_episodes": 126,
+    "n_test_episodes": 54,
+    "sample_interval_s": 5,
+    "severity_bands_pct_of_nominal_flow": {
+      "small": [
+        1,
+        3
+      ],
+      "medium": [
+        3,
+        8
+      ],
+      "large": [
+        8,
+        20
+      ]
+    },
+    "mass_balance_calibration": {
+      "window_samples": 36,
+      "persist_windows": 6,
+      "k": 3.0,
+      "threshold": 1.7525218250941839,
+      "note": "mu/sigma/k calibrated on normal-only TRAIN episodes only; detection_rate/false_alarm below is measured on held-out TEST episodes."
+    }
+  },
+  "mass_balance": {
+    "small": {
+      "n_episodes": 8,
+      "detection_rate": 1.0,
+      "mean_ttd_s": 91.25,
+      "median_ttd_s": 82.5
+    },
+    "medium": {
+      "n_episodes": 8,
+      "detection_rate": 1.0,
+      "mean_ttd_s": 66.25,
+      "median_ttd_s": 70.0
+    },
+    "large": {
+      "n_episodes": 8,
+      "detection_rate": 1.0,
+      "mean_ttd_s": 52.5,
+      "median_ttd_s": 52.5
+    },
+    "overall": {
+      "n_episodes": 24,
+      "detection_rate": 1.0,
+      "mean_ttd_s": 70.0,
+      "median_ttd_s": 67.5
+    },
+    "false_alarm": {
+      "n_normal_episodes": 30,
+      "episodes_with_false_alarm_fraction": 0.16666666666666666,
+      "mean_false_alarms_per_hour": 0.3557202408522464
+    }
+  },
+  "lstm_ae": {
+    "small": {
+      "n_episodes": 8,
+      "detection_rate": 1.0,
+      "mean_ttd_s": 50.0,
+      "median_ttd_s": 52.5
+    },
+    "medium": {
+      "n_episodes": 8,
+      "detection_rate": 1.0,
+      "mean_ttd_s": 43.125,
+      "median_ttd_s": 42.5
+    },
+    "large": {
+      "n_episodes": 8,
+      "detection_rate": 1.0,
+      "mean_ttd_s": 30.625,
+      "median_ttd_s": 35.0
+    },
+    "overall": {
+      "n_episodes": 24,
+      "detection_rate": 1.0,
+      "mean_ttd_s": 41.25,
+      "median_ttd_s": 40.0
+    },
+    "false_alarm": {
+      "n_normal_episodes": 30,
+      "episodes_with_false_alarm_fraction": 0.7,
+      "mean_false_alarms_per_hour": 3.8418079096045186
+    },
+    "training_history": {
+      "best_val_mse": 0.03187253326177597,
+      "epochs_ran": 25.0
+    },
+    "threshold": 0.0505700446665287,
+    "window_samples": 36
+  },
+  "npw_localization": {
+    "n_localized": 24,
+    "mean_abs_error_km": 13.373748620341866,
+    "median_abs_error_km": 8.42794804230748,
+    "by_severity": {
+      "small": {
+        "n": 8,
+        "mean_abs_error_km": 12.681819882133222,
+        "median_abs_error_km": 15.265277817152366
+      },
+      "medium": {
+        "n": 8,
+        "mean_abs_error_km": 13.716801975487986,
+        "median_abs_error_km": 7.878984101297062
+      },
+      "large": {
+        "n": 8,
+        "mean_abs_error_km": 13.722624003404391,
+        "median_abs_error_km": 5.783308992666312
+      }
+    },
+    "method": "Cross-correlation of high-pass-filtered inlet/outlet pressure around the detection time; location_km_from_inlet = 0.5*(L + c*dt).",
+    "based_on_detector": "mass_balance",
+    "caveat": "Best-effort/demo-grade estimator, not a calibrated field system. Accuracy degrades substantially for small leaks (weak signal-to-noise) -- see by_severity breakdown."
+  },
+  "primary_detector": "mass_balance",
+  "primary_detector_rationale": "detection_rate tied (1.00); mass_balance has a lower false-alarm rate (0.36/h vs lstm_ae 3.84/h) on held-out normal test episodes, so it is recommended as the primary/first-line trigger. lstm_ae detects leaks faster on average (lower time-to-detect) and is recommended as a fast corroborating secondary signal, not as the sole trigger, given its higher false-alarm rate on this synthetic data.",
+  "published_baselines": [
+    {
+      "method": "Statistical volume/mass balance LDS (field deployment survey)",
+      "finding": "Reported sensitivity/response ranges from a 0.5% leak detected within 5 minutes on a short, well-instrumented segment, down to a 12% leak in 180 minutes on a >400 km large-separation offshore segment (sensitivity is strongly limited by sensor spacing and transient operations, not a single fixed number).",
+      "citation": "Atmosi, 'The challenges for effective leak detection on large diameter pipelines' (field deployment case studies). https://www.atmosi.com/us/news-events/blogs/the-challenges-for-effective-leak-detection-on-large-diameter-pipelines/"
+    },
+    {
+      "method": "Mass-balance leak detection with packing-term correction (transient flow)",
+      "finding": "Detection threshold of about 3% of mass flow over several minutes, contingent on pressure-wave-velocity uncertainty being minimized.",
+      "citation": "Pipeline leak detection based on mass balance: Importance of the packing term (transient-flow mass-balance LDS study). https://www.academia.edu/17624416/Pipeline_leak_detection_based_on_mass_balance_Importance_of_the_packing_term"
+    },
+    {
+      "method": "Unsupervised autoencoder-integrated model (TKAN-AE) on real urban pipeline field data",
+      "finding": "93.1% segment-wise precision detecting simulated leaks injected into real urban water-pipeline SCADA data (Shanghai field experiments).",
+      "citation": "Temporal Kolmogorov-Arnold Network with Autoencoder Integration for unsupervised pipeline leak detection. Sensors 2025, 25(2), 384. https://www.mdpi.com/1424-8220/25/2/384"
+    }
+  ],
+  "pipeline_seconds": 113.9
+}

lstm_ae.onnx

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

lstm_ae.pt

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

manifest.json

@@ -0,0 +1,224 @@
+{
+  "name": "pipelinewatch-scada-synthetic",
+  "source": "100% synthetic hydraulic/SCADA simulation -- no real pipeline, historian, or customer data.",
+  "n_episodes": 180,
+  "n_samples_per_episode": 2160,
+  "sample_interval_s": 5,
+  "columns": [
+    "t_s",
+    "inlet_flow_m3h",
+    "outlet_flow_m3h",
+    "inlet_pressure_kpa",
+    "outlet_pressure_kpa",
+    "temperature_c",
+    "episode_id",
+    "leak_active",
+    "leak_rate_pct",
+    "leak_location_km",
+    "leak_severity_class"
+  ],
+  "detector_columns": [
+    "inlet_flow_m3h",
+    "outlet_flow_m3h",
+    "inlet_pressure_kpa",
+    "outlet_pressure_kpa"
+  ],
+  "severity_bands_pct_of_nominal_flow": {
+    "small": [
+      1,
+      3
+    ],
+    "medium": [
+      3,
+      8
+    ],
+    "large": [
+      8,
+      20
+    ]
+  },
+  "train_episode_ids": [
+    0,
+    1,
+    2,
+    3,
+    4,
+    5,
+    6,
+    8,
+    9,
+    11,
+    14,
+    15,
+    16,
+    17,
+    18,
+    19,
+    21,
+    23,
+    24,
+    25,
+    26,
+    27,
+    29,
+    31,
+    32,
+    33,
+    34,
+    35,
+    37,
+    38,
+    40,
+    42,
+    43,
+    44,
+    46,
+    48,
+    49,
+    50,
+    51,
+    52,
+    53,
+    54,
+    55,
+    56,
+    57,
+    58,
+    62,
+    64,
+    65,
+    66,
+    67,
+    68,
+    69,
+    70,
+    71,
+    72,
+    74,
+    76,
+    77,
+    79,
+    80,
+    83,
+    87,
+    88,
+    90,
+    93,
+    94,
+    95,
+    98,
+    101,
+    103,
+    104,
+    105,
+    106,
+    107,
+    108,
+    110,
+    111,
+    112,
+    113,
+    116,
+    117,
+    118,
+    119,
+    120,
+    121,
+    122,
+    124,
+    126,
+    127,
+    128,
+    129,
+    130,
+    131,
+    132,
+    133,
+    136,
+    137,
+    138,
+    139,
+    141,
+    142,
+    143,
+    144,
+    146,
+    150,
+    152,
+    154,
+    155,
+    158,
+    159,
+    160,
+    161,
+    162,
+    163,
+    164,
+    165,
+    166,
+    169,
+    171,
+    172,
+    174,
+    176,
+    177,
+    178,
+    179
+  ],
+  "test_episode_ids": [
+    7,
+    10,
+    12,
+    13,
+    20,
+    22,
+    28,
+    30,
+    36,
+    39,
+    41,
+    45,
+    47,
+    59,
+    60,
+    61,
+    63,
+    73,
+    75,
+    78,
+    81,
+    82,
+    84,
+    85,
+    86,
+    89,
+    91,
+    92,
+    96,
+    97,
+    99,
+    100,
+    102,
+    109,
+    114,
+    115,
+    123,
+    125,
+    134,
+    135,
+    140,
+    145,
+    147,
+    148,
+    149,
+    151,
+    153,
+    156,
+    157,
+    167,
+    168,
+    170,
+    173,
+    175
+  ]
+}

mass_balance_config.joblib

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

scaler.joblib

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

thresholds.joblib

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