Add gas.py

gas.py

@@ -0,0 +1,52 @@
+"""Gas consumption and gas-switch planning.
+
+SAC/consumption formula cross-checked against DAN's "Estimating Your Air
+Consumption" and multiple independent dive-training SAC-rate references,
+which all agree on the same normalization:
+
+    ATA(depth) = depth_m / 10 + 1
+    volume_used = SAC_surface_L_per_min * ATA * time_min
+
+Gas-switch selection follows standard technical-diving practice: at any
+point during ascent, breathe the richest available gas whose MOD (maximum
+operating depth, from a configurable max ppO2) is at or below the current
+depth.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from buhlmann import Gas, depth_to_pressure
+
+
+@dataclass
+class CylinderGas:
+    """A gas the diver is carrying, with a name for display."""
+
+    gas: Gas
+    name: str
+    max_ppo2: float = 1.4
+
+    @property
+    def mod_m(self) -> float:
+        return self.gas.mod_m(self.max_ppo2)
+
+
+def ata(depth_m: float) -> float:
+    """Atmospheres absolute at a given depth."""
+    return depth_to_pressure(depth_m) / depth_to_pressure(0.0)
+
+
+def gas_volume_used(sac_l_per_min: float, depth_m: float, time_min: float) -> float:
+    """Litres of gas consumed breathing at a constant depth for time_min."""
+    return sac_l_per_min * ata(depth_m) * time_min
+
+
+def select_gas(available: list, depth_m: float) -> CylinderGas:
+    """Pick the richest (highest fO2) available gas whose MOD is safe at
+    this depth. Falls back to the gas with the deepest MOD if none is
+    nominally safe (better than returning nothing to breathe)."""
+    usable = [g for g in available if g.mod_m >= depth_m - 1e-9]
+    if usable:
+        return max(usable, key=lambda g: g.gas.fo2)
+    return max(available, key=lambda g: g.mod_m)