Calculated decompression and future gas switches

[readme42]

Ascents ignore future gas switches — and the error propagates into deco status, heatmap, and CNS displays

TL;DR

Our ZHL-16C/GF implementation tracks tissue loading correctly across recorded gas switches, but every forward-looking calculation (TTS, deco schedule, stop times) assumes the diver breathes the currently active gas all the way to
the surface. Real dive computers plan the ascent with all carried deco gases. For any dive with a deco gas (e.g. air bottom gas + EAN50), our calculated TTS is significantly inflated until the moment the switch is actually recorded —
and every metric derived from that simulation inherits the error.

Current behavior

processProfileWithGasSegments (lib/core/deco/buhlmann_algorithm.dart) walks the recorded profile and correctly splits tissue-loading segments at gas-switch boundaries. So the instantaneous tissue state is right.

But at each sample it calls getDecoStatus(...) with one gas — the one active at that timestamp — and the whole simulation chain underneath (calculateDecoSchedule → _simulateAscent / _calculateStopTime → calculateTts) uses
that single fN2/fHe for the entire simulated ascent. The planner has no concept of "the diver is carrying EAN50 and will switch at 21 m".

What this looks like

Example: 45 m dive, air bottom gas, EAN50 for deco (switch at 21 m on ascent).

• During the bottom phase, the calculated TTS is the cost of an air-only ascent: off-gassing at the 9/6/3 m stops on a gas with 79% N2 instead of 50%. Stop times — especially the long shallow stops — come out far too long.
• At the recorded gas switch, the remaining ascent is suddenly simulated on EAN50, so the calculated TTS curve drops in a discontinuous step that corresponds to no real change in deco obligation.
• A dive computer on the same dive (which plans with all enabled gases) shows a much lower, smooth TTS the whole time. Side by side, our calculated curve overshoots the recorded one through the bottom phase and early ascent, then snaps
  onto it after the switch.

Visualization

PR #137 fixed the TTS display in DC mode — and switching to calculated mode now makes the problem clearly visible:

TTS goes to the moon, then falls back down at the gas switch (and is still too high afterwards):

For comparison, the recorded TTS from the dive computer on the same dive — the computer plans with all carried gases, so the curve is smooth, much lower, and reaches 0 at the surface. This is what our calculation should converge
towards:

Why this matters beyond the TTS line

The per-sample DecoStatus produced by this simulation is the input for several downstream features, so the single-gas assumption is not just a cosmetic offset on one curve:

• Deco status / stop schedule: the displayed stop depths and stop times per sample come from the same air-only planned ascent, so the deco obligation is overstated.
• Heatmap / tissue visualizations: instantaneous tissue state is correct for the recorded past, but anything that colors or classifies based on the simulated ascent (in-deco state, projected clearing) reflects the wrong plan.
• CNS / O2 exposure: projections that include the remaining deco are based on the wrong ascent — too much time at stops, on the wrong gas, so the predicted O2 exposure for the rest of the dive is wrong in both directions (longer
  stops, but on a leaner gas than the diver will actually breathe). - Anything else consuming DecoStatus (warnings, summary stats like max TTS) inherits the same error.
  ## Proposed fix

Variant 1 - gas-aware ascent:

1. Pass the dive's full gas list (or remaining gas segments) into calculateDecoSchedule / calculateTts as availableGases.
2. During the simulated ascent, decide which gas the simulated diver breathes. There are two reasonable models:
   • Ideal ascent (what modern tec dive computers do): at each stop/leg pick the best available gas for that depth (highest O2 within a deco ppO2 limit, e.g. 1.6 bar MOD) — the same way dive computers and Subsurface plan. This reproduces what the computer on the diver's wrist displayed during the dive.
   • Real ascent: since we are post-processing a recorded dive, the future gas switches are actually known — replay the diver's recorded switch depths/times in the simulation. This matches what really happened on that dive, even
     when the diver switched earlier or later than the ideal plan. 3. Keep the recorded-profile tissue loading exactly as it is — that part is already correct.

This changes calculated TTS for every multi-gas dive in the log (values will go down), so screenshots/expectations in tests need updating, and it's worth re-validating against real computer recordings afterwards.

Variant 2 - separate it clearly:

Instead of changing the ascent, we could also separate the ui into two different mode, switchable by toggle or overlay or something else:

• ascent calculated without future gas switches (as it is now)

• ascent based on real dc export data, no calculations at all

  Open questions

  • Which gases count as "available" for the planner: all cylinders attached to the dive, or only ones flagged as deco gases?
  • Ideal vs. real ascent (see above): should the planner pick gases by a configurable deco ppO2 (1.4/1.6) with an auto-switch at the resulting MOD, or should it use the switch depths the diver actually recorded?
  • CCR/SCR dives need a separate rule (setpoint-driven, not gas-switch-driven).

  How others solve it

  

  Subsurface simply shows both values — TTS (recorded) and TTS (calc) — side by side, and that's it: the calculated value is just a number you can ignore. In Submersion the calculated values drive far more of the UI — deco
  status, CNS visualization, heatmap, warnings — and all of it currently runs on the non-gas-switch-aware simulation nobody would dive. So unlike Subsurface, we can't just live with the discrepancy; the calculation - imho - itself needs to be gas-aware.

Any opinions on that topic?

I'm fine implementing these things - but I would like to get consens on how we want to have it before.

relates to #298

@ericgriffin
@hancockks

[readme42]

@ericgriffin

How do we want to handle this in the future?

I would suggest to do what dive computers do: Expect that gas switches will be done at best point in time during ascent: When reaching ppo2 of 1.6. And when not switching or switching too late: add penalty and then calculate with the in reality used gases. Maybe even make it clear in the graph that for such a "penalty period" a better gas would have been appropriate.

[ericgriffin]

@readme42 what you've suggested sounds good to me.