Skip to content

Decompression ​

Not a dive computer

dive-math/deco is a reference implementation for planning software and education. Plans must be checked against an approved planner and your training. Never dive a schedule from this library alone.

What it's for ​

Plans multi-level and repeat dives with the Bühlmann ZH-L16C model and Erik Baker's gradient factors. It covers open circuit with deco-gas switches, CCR with a fixed or low/high setpoint, and CCR bailout to open circuit. Each plan reports its stop schedule, runtime, CNS/OTU, gas use and safety warnings. The lower-level functions (tissue loading, ceiling, NDL, time to surface) are public for dive-log tools.

Model ​

Inspired inert gas ​

Pi=(Pamb−PH2O)⋅finert
  • Pamb: ambient pressure (ata) from ataAtDepth, so water and surfacePressure apply.
  • PH2O: alveolar water vapour, default 0.0627 bar (Bühlmann, RQ = 1). Pass waterVapour: 0.0493 (Schreiner, RQ = 0.8) to reproduce Baker's published examples.
  • On CCR: Pi=max(0, Pamb−PH2O−pO2,loop), split in the diluent's He:N₂ ratio. pO2,loop is the setpoint bounded by ambient and by the diluent's ppO₂.

Tissue loading ​

Constant depth (Haldane) and linear depth change (Schreiner), exact, with no time-stepping:

P(t)=Pi0+R(t−1k)−(Pi0−P0−Rk)e−kt,k=ln⁡2t1/2

R is the rate of change of Pi (bar/min); R=0 is Haldane. CCR segments are split where the loop's inert pressure changes slope, so every piece stays exact.

Tolerated pressure and ceiling (Baker) ​

Ptol=Pt−GF⋅aGF/b−GF+1,a=aN2PN2+aHePHePN2+PHe, same for b

The ceiling is the deepest Ptol over the 16 compartments, as a depth.

Gradient factors ​

  • The first stop is found by ascending at GF-low on the 3 m stop grid.
  • From there, GF runs linearly from GF-low at the first stop to GF-high at the surface.
  • A dive whose direct ascent is clear at GF-high (within its NDL) surfaces without stops.

Coefficients ​

ZH-L16C, with compartment 1 = Bühlmann's "1b" (5.0 min N₂ / 1.88 min He). Source: Bühlmann, Völlm & Nussberger, Tauchmedizin (2002), Tabelle 26 (scan); helium cross-checked against Baker, Understanding M-values, Table 3.

Cptt½ N₂a N₂b N₂t½ Hea Heb He
15.01.16960.55781.881.61890.4770
28.01.00000.65143.021.38300.5747
312.50.86180.72224.721.19190.6527
418.50.75620.78256.991.04580.7223
527.00.62000.812610.210.92200.7582
638.30.50430.843414.480.82050.7957
754.30.44100.869320.530.73050.8279
877.00.40000.891029.110.65020.8553
9109.00.37500.909241.200.59500.8757
10146.00.35000.922255.190.55450.8903
11187.00.32950.931970.690.53330.8997
12239.00.30650.940390.340.51890.9073
13305.00.28350.9477115.290.51810.9122
14390.00.26100.9544147.420.51760.9171
15498.00.24800.9602188.240.51720.9217
16635.00.23270.9653240.030.51190.9267

Surface tissues start saturated at (Psurf−PH2O)×0.7902 (N₂ + argon).

Planning defaults ​

OptionDefault
descentRate / ascentRate20 / 10 m/min
stopInterval / lastStopM3 / 3 m (any multiple of stopInterval)
roundStopstrue: every stop ends on a whole minute of runtime (Baker's convention)
maxDecoPpo2 / maxBottomPpo21.6 / 1.4 ata; deco gases switch at the first stop-grid depth where the gas is within maxDecoPpo2
switchMinutes0
safetyStopfalse (3 min at 5 m on no-deco dives when true)
waterVapour0.0627 bar

Level.minutes is the time at depth, after the descent or ascent to it.

Input limits (library guards that bound the planner's work; out-of-range values throw RangeError, in planDive, timeToSurface and bailoutPlan alike):

InputLimit
levels1 to 1000 entries (MAX_LEVELS)
Level.depthM0 to 1000 m (MAX_DEPTH_M)
descentRate / ascentRateat least 0.1 m/min (MIN_RATE_M_PER_MIN)
stopIntervalat least 0.1 m (MIN_STOP_INTERVAL_M)
switchMinutes0 to 1440 min (MAX_DECO_MINUTES)

Gas-switch holds count toward MAX_DECO_MINUTES like stops: past it the plan is truncated with deco-too-long.

  • With surfacePressure: 1.01325, 6 m is 1.613 ata, so O₂ is not selected at 6 m unless maxDecoPpo2 ≥ ~1.62.
  • ndl() excludes off-gassing during the ascent, so it is stricter than the planner's direct-ascent no-stop check.
  • CCR diluent flush: when the setpoint is below the diluent's ppO₂, the loop's ppO₂ is the diluent's, taken as fO2⋅Pamb; the model's inert pressure is then fO2⋅PH2O lower than breathing the diluent on open circuit: about 0.013 bar for air (≈ 0.5 % of the inert pressure where the flush starts), rising with the diluent's O₂ (≈ 1.4 % for EAN32, ≈ 4.7 % for a 50 % diluent at a 0.7 setpoint). This makes the model slightly less conservative in that regime.

CCR bailout ​

bailoutPlan evaluates a bailout at the end of every level below the surface and returns the worst bailout point among the ends of the levels (largest bailout gas requirement; ties go to the longer runtime). For each candidate it replays the bottom to that level's end, then ascends on open circuit on bailoutGases with gas switches at MOD. The bailout starts on the richest bailout gas within maxDecoPpo2 at that depth (the leanest, with a no-breathable-gas warning, if none is). bailoutDepthM and bailoutRuntimeMinutes report where and when the chosen bailout starts.

Cost grows with the number of levels: each candidate runs a full open-circuit deco ascent, so bailoutPlan is roughly one planDive per level. A few levels returns in milliseconds; profiles near the MAX_LEVELS cap (1000 deep CCR levels) can take several seconds. It is synchronous, so in a UI run it off the main thread (e.g. in a Web Worker) for long multi-level profiles.

Air breaks ​

airBreaks schedules periodic breaks onto a lower ppO₂ during decompression. The breaks are run through the tissue model, so stop times grow to make up for them.

ts
airBreaks: {
  oc?:  { onMinutes?: 20, breakMinutes?: 5, triggerPpo2?: 1.4 },
  ccr?: { onMinutes?: 60, breakMinutes?: 5, triggerSetpoint?: 1.3, breakSetpoint?: 0.7 },
}

A mode with no key takes no breaks; { oc: {} } turns on open-circuit breaks with the defaults, and a field left undefined keeps its default. onMinutes and breakMinutes must be at least one minute (MIN_BREAK_CLOCK_MINUTES). OC 20/5 is the common technical-diving O₂ break. CCR 60/5 follows the US Navy MK 16 practice described by Hoyt et al. (2025), who recommend periodic five-minute breaks during decompression at "an inspired PO₂ equivalent to breathing air at the same depth" but prescribe no regimen. The 1.4 OC trigger, 1.3 CCR trigger and 0.7 break setpoint are conventions chosen for this library.

  • The clock runs only during the deco ascent, while the OC inspired ppO₂ (or the CCR setpoint in force) is at or above the trigger. It carries across stops and gas switches. Below the trigger it pauses; a continuous stretch below the trigger of at least breakMinutes counts as a break and resets it.
  • A break starts when the clock is full and the stop isn't clear yet.
  • Break gas. OC: the leanest carried gas (the gas the ascent started on, plus the deco gases) that is breathable at the depth and below the trigger. CCR: the loop at breakSetpoint, bounded by the diluent.
  • A stop may end mid-break. The rest of the break is flown through the ascent (those segments are marked airBreak) and into the next stop. A break that runs out in transit finishes on arrival: the whole travel segment is flown on the break gas, and the leftover transit minutes don't count toward the clock. The clock state for a travel segment (on, paused or mid-break) is judged at its departure depth. The break gas is re-selected at each depth; if none qualifies, the break ends early without resetting the clock.
  • If a break is due but no break gas exists, the plan stays on the normal gas and warns no-break-gas.

Break pieces are separate stop segments with airBreak: true. Each DecoStop reports its breakMinutes. With breaks, clearing is not monotonic in the wait: padding a stop can start a break, and the travel is then flown on the leaner break gas, which can on-gas fast compartments. The stop-time search therefore checks the wait it finds, and a stop rounded up to a whole minute of runtime is re-checked and extended by whole minutes until the next stop is clear. The stop found may be slightly longer than the shortest possible one, never shorter.

Oxygen exposure ​

oxygenLimits picks the CNS limit set: 'noaa-1991' (default) or 'hoyt-2025' (see oxygen exposure). Bottom-profile segments (descents, levels, and ascents between levels) are working unless the level says otherwise: a level's phase applies to the level and the travel into it. The deco ascent (the ascent and stop segments after the last level, including a safety stop) is resting.

DivePlan.oxygen holds the totals (working and resting under Hoyt). Every segment carries the cumulative cnsPercent and otu at its end. dayExposure takes the day's earlier dives and surface intervals (the dailyExposure items) for the daily checks. Those checks have no decay: surface intervals don't reduce them.

Warnings ​

Plans never throw for unsafe-but-valid dives; they return warnings:

  • hypoxic: ppO₂ below 0.16;
  • ppo2-high: above maxBottomPpo2 on descents and levels, or maxDecoPpo2 on the ascent;
  • density-recommended / density-hard: above 5.2 / 6.2 g/L;
  • ceiling-violated: a multi-level ascent above the GF-high ceiling;
  • no-breathable-gas: no gas within the ppO₂ limits at a stop depth;
  • cns-single: NOAA single-exposure CNS over 100 %; cns-working / cns-resting under Hoyt 2025;
  • cns-daily: this dive plus dayExposure over the 24-hour limits;
  • otu-daily: this dive plus dayExposure over 850 OTU (REPEX day 1);
  • no-break-gas: an air break was due at a depth but no break gas was available;
  • deco-too-long: more than 24 h of stops. The plan is truncated: it stops at the depth where it was truncated, and runtimeMinutes and gasUse cover only the planned part.

Examples ​

ts
import { AIR, gas } from 'dive-math/gas'
import { planDive, bailoutPlan, surfaceInterval } from 'dive-math/deco'
const dive = { levels: [{ depthM: 18, minutes: 30, breathing: { kind: 'oc' as const, gas: AIR } }], gfLow: 0.4, gfHigh: 0.85 }
const first = planDive(dive)
first.stops.length // => 0
const second = planDive({ ...dive, startTissues: surfaceInterval(first.endTissues, 60) })
second.runtimeMinutes >= first.runtimeMinutes // => true
const baker = planDive({ levels: [{ depthM: 90, minutes: 15.5, breathing: { kind: 'oc', gas: gas(0.13, 0.5) } }], decoGases: [gas(0.36), gas(0.5), gas(0.8)], gfLow: 0.2, gfHigh: 0.75, waterVapour: 0.0493 })
baker.firstStopM // => 54
baker.runtimeMinutes > 119 && baker.runtimeMinutes < 121 // => true
const ccr = { levels: [{ depthM: 60, minutes: 25, breathing: { kind: 'ccr' as const, diluent: gas(0.18, 0.45), setpoint: 1.3 } }], gfLow: 0.3, gfHigh: 0.8 }
bailoutPlan(ccr, { bailoutGases: [gas(0.18, 0.45), gas(0.5), gas(1)], rmvLpm: 20 }).gasRequired.length // => 3
planDive({ ...ccr, oxygenLimits: 'hoyt-2025' }).oxygen.resting! < 100 // => true
const tmx = { levels: [{ depthM: 60, minutes: 40, breathing: { kind: 'oc' as const, gas: gas(0.18, 0.45) } }], decoGases: [gas(0.5), gas(1)], gfLow: 0.4, gfHigh: 0.85 }
planDive(tmx).runtimeMinutes // => 134.3
planDive({ ...tmx, airBreaks: { oc: { triggerPpo2: 1.3 } } }).runtimeMinutes // => 142.3

Validation ​

  • DecoTengu's worked example: tissue pressures to 6 decimals.
  • Baker, "Clearing Up The Confusion About Deep Stops", Fig. 3: first stop 54 m; every stop within 1 min of the published runtime.
  • GasPlanner's tissue model (MIT), run as a black box: all 16 compartments to 1e-9.
  • An independent clean-room planner (scripts/deco-reference/reference.py): identical schedules to the second.
  • Optional replay of Shearwater Cloud CSV logs (test/fixtures/shearwater/, not published).

Known differences ​

  • GasPlanner / Subsurface interpolate GF differently (more conservative: +0.4 to +10 min on typical dives). GasPlanner also has typos in the N₂ b of compartments 4 and 5.
  • Shearwater doesn't publish its water-vapour value, GF anchoring or rounding.

API ​

See the API reference.

Reference only — verify every fill and dive plan independently.