decodaitengu 1.0.0__py3-none-any.whl

decodaitengu/__init__.py

@@ -0,0 +1,107 @@
+# DecoDaiTengu - dive decompression library.
+#
+# Copyright (C) 2013-2014 by Artur Wroblewski <wrobell@pld-linux.org>
+# Copyright (C) 2024 Contributors
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+
+"""DecoDaiTengu - dive decompression library.
+
+A modern, typed Python library for Bühlmann ZH-L16B/C decompression
+calculations with gradient factors, CNS/OTU tracking, and trimix support.
+
+Quick start::
+
+    from decodaitengu import plan_dive, Gas
+
+    result = plan_dive(
+        depth=35,
+        bottom_time=40,
+        back_gas=Gas(21, 0),  # air
+        gf=(30, 85),
+    )
+    print(f"Runtime: {result.runtime:.0f} min")
+    print(f"Deco: {result.total_deco:.0f} min")
+    for stop in result.stops:
+        print(f"  {stop.depth:.0f}m for {stop.time:.0f} min")
+
+Trimix example::
+
+    from decodaitengu import plan_dive, Gas, ZHL16C
+
+    result = plan_dive(
+        depth=50,
+        bottom_time=25,
+        back_gas=Gas(21, 35),
+        deco_gases=[Gas(50, 0, switch_depth=21), Gas(100, 0, switch_depth=6)],
+        model=ZHL16C,
+        gf=(30, 85),
+    )
+"""
+
+from .models import ZHL16B, ZHL16C, DecoModel
+from .planning import plan_dive
+from .tracking import CNSMethod, CNSTracker, OTUTracker
+from .types import (
+    Cylinder,
+    DecoStop,
+    DiveSummary,
+    Gas,
+    GasUsage,
+    Phase,
+    Step,
+    TissueState,
+)
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "plan_dive",
+    "Gas",
+    "ZHL16B",
+    "ZHL16C",
+    "DecoModel",
+    "Cylinder",
+    "TissueState",
+    "DiveSummary",
+    "DecoStop",
+    "Step",
+    "Phase",
+    "GasUsage",
+    "CNSTracker",
+    "CNSMethod",
+    "OTUTracker",
+    # Legacy compat
+    "create",
+]
+
+
+def create(*args: object, **kwargs: object) -> None:
+    """Legacy API stub — the old Engine-based API has been removed.
+
+    Raises RuntimeError with migration instructions.
+    """
+    raise RuntimeError(
+        "decodaitengu.create() is no longer available.\n"
+        "\n"
+        "The legacy Engine API from decotengu has been replaced with a simpler\n"
+        "functional API. To migrate:\n"
+        "\n"
+        "  OLD (decotengu):\n"
+        "    import decotengu\n"
+        "    engine = decotengu.create()\n"
+        "    engine.add_gas(0, 21)\n"
+        "    profile = engine.calculate(35, 40)\n"
+        "    list(profile)\n"
+        "    print(engine.deco_table.total)\n"
+        "\n"
+        "  NEW (decodaitengu):\n"
+        "    from decodaitengu import plan_dive, Gas\n"
+        "    result = plan_dive(depth=35, bottom_time=40, back_gas=Gas(21, 0))\n"
+        "    print(result.total_deco)\n"
+        "\n"
+        "See README.md or https://github.com/notionparallax/decodaitengu for full docs."
+    )

decodaitengu/const.py

@@ -0,0 +1,45 @@
+#
+# DecoTengu - dive decompression library.
+#
+# Copyright (C) 2013-2014 by Artur Wroblewski <wrobell@pld-linux.org>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#
+
+WATER_VAPOUR_PRESSURE_Q08 = 0.0493
+WATER_VAPOUR_PRESSURE_Q09 = 0.0567
+# source: [mpdfd]
+# used in: OSTC
+WATER_VAPOUR_PRESSURE_Q10 = 0.0627
+WATER_VAPOUR_PRESSURE_DEFAULT = WATER_VAPOUR_PRESSURE_Q10
+
+SURFACE_PRESSURE = 1.01325
+
+METER_TO_BAR = 0.09985
+LOG_2 = 0.6931471805599453
+SCALE = 10
+EPSILON = 10**-SCALE
+ROUND_VALUE = 0.499999
+MINUTE = 1
+TIME_3M = 0.3  # time [min] to ascent/descent at 10m/min
+
+#
+# number based on performance test for dive profile presented in
+# Baker "Deep Stops" paper, see also
+#
+#   decotengu.tests.integration.test_engine.ProfileTestCase.test_deepstop
+#
+DECO_STOP_SEARCH_TIME = 8
+
+# vim: sw=4:et:ai

decodaitengu/models/__init__.py

@@ -0,0 +1,27 @@
+#
+# DecoTengu - dive decompression library.
+#
+# Copyright (C) 2013-2014 by Artur Wroblewski <wrobell@pld-linux.org>
+# Copyright (C) 2024 Contributors
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#
+
+"""Decompression models package."""
+
+from .base import DecoModel
+from .zhl16b import ZHL16B
+from .zhl16c import ZHL16C
+
+__all__ = ["DecoModel", "ZHL16B", "ZHL16C"]

decodaitengu/models/base.py

@@ -0,0 +1,239 @@
+#
+# DecoTengu - dive decompression library.
+#
+# Copyright (C) 2013-2014 by Artur Wroblewski <wrobell@pld-linux.org>
+# Copyright (C) 2024 Contributors
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#
+
+"""Base decompression model interface and shared calculations.
+
+Implements the ZH-L16-GF decompression model framework with gradient factors
+by Erik Baker. Subclasses provide specific coefficient tables (ZHL-16B, ZHL-16C).
+
+Equations
+---------
+Schreiner Equation (tissue gas loading):
+    P = P_alv + R * (t - 1/k) - (P_alv - P_i - R/k) * e^(-k*t)
+
+Bühlmann Equation with gradient factors (ascent ceiling):
+    P_l = (P - A * gf) / (gf / B + 1.0 - gf)
+
+For trimix (combined N2 + He):
+    A = (A_n2 * P_n2 + A_he * P_he) / (P_n2 + P_he)
+    B = (B_n2 * P_n2 + B_he * P_he) / (P_n2 + P_he)
+    P_ceiling = (P_n2 + P_he - A * gf) / (gf / B + 1 - gf)
+"""
+
+import math
+from dataclasses import dataclass
+from typing import Protocol
+
+from .. import const
+from ..types import Gas, TissueState
+
+
+@dataclass(frozen=True, slots=True)
+class ModelParams:
+    """Coefficient table for a ZH-L16 variant.
+
+    :param n2_half_life: N2 half-life times for 16 compartments [min].
+    :param n2_a: N2 Bühlmann 'a' coefficients.
+    :param n2_b: N2 Bühlmann 'b' coefficients.
+    :param he_half_life: He half-life times for 16 compartments [min].
+    :param he_a: He Bühlmann 'a' coefficients.
+    :param he_b: He Bühlmann 'b' coefficients.
+    """
+
+    n2_half_life: tuple[float, ...]
+    n2_a: tuple[float, ...]
+    n2_b: tuple[float, ...]
+    he_half_life: tuple[float, ...]
+    he_a: tuple[float, ...]
+    he_b: tuple[float, ...]
+
+
+class DecoModel(Protocol):
+    """Protocol defining the decompression model interface."""
+
+    params: ModelParams
+    gf_low: float
+    gf_high: float
+
+    def init(self, surface_pressure: float) -> TissueState: ...
+    def load(
+        self,
+        tissues: TissueState,
+        abs_p: float,
+        time: float,
+        gas: Gas,
+        rate: float,
+    ) -> TissueState: ...
+    def ceiling(self, tissues: TissueState, gf: float) -> float: ...
+    def compartment_ceilings(self, tissues: TissueState, gf: float) -> tuple[float, ...]: ...
+
+
+def eq_schreiner(
+    p_i: float,
+    p_alv: float,
+    rate: float,
+    time: float,
+    k: float,
+) -> float:
+    """Calculate inert gas pressure in a tissue compartment using Schreiner equation.
+
+    :param p_i: Initial inert gas pressure in tissue compartment [bar].
+    :param p_alv: Alveolar pressure of inspired inert gas [bar].
+    :param rate: Rate of change of inert gas pressure [bar/min].
+    :param time: Time of exposure [min].
+    :param k: Gas decay constant (ln2 / half_life).
+    :returns: Final inert gas pressure in tissue compartment [bar].
+    """
+    return p_alv + rate * (time - 1.0 / k) - (p_alv - p_i - rate / k) * math.exp(-k * time)
+
+
+def eq_gf_limit(
+    gf: float,
+    p_n2: float,
+    p_he: float,
+    a_n2: float,
+    b_n2: float,
+    a_he: float,
+    b_he: float,
+) -> float:
+    """Calculate ascent ceiling of a tissue compartment.
+
+    Uses Bühlmann equation extended with gradient factors by Erik Baker,
+    with the weighted a/b approach for combined N2 + He loading.
+
+    :param gf: Gradient factor value (0 < gf <= 1.5).
+    :param p_n2: Current tissue nitrogen pressure [bar].
+    :param p_he: Current tissue helium pressure [bar].
+    :param a_n2: Bühlmann 'a' coefficient for nitrogen.
+    :param b_n2: Bühlmann 'b' coefficient for nitrogen.
+    :param a_he: Bühlmann 'a' coefficient for helium.
+    :param b_he: Bühlmann 'b' coefficient for helium.
+    :returns: Absolute pressure of ascent ceiling [bar].
+    """
+    p = p_n2 + p_he
+    if p <= 0:
+        return 0.0
+    a = (a_n2 * p_n2 + a_he * p_he) / p
+    b = (b_n2 * p_n2 + b_he * p_he) / p
+    return (p - a * gf) / (gf / b + 1.0 - gf)
+
+
+class ZHL16GF:
+    """Base implementation of Bühlmann ZH-L16 with gradient factors.
+
+    Subclasses must set the `params` class variable with appropriate coefficients.
+
+    :param gf_low: Gradient factor low (controls first stop depth). Default 0.30.
+    :param gf_high: Gradient factor high (controls last stop duration). Default 0.85.
+    """
+
+    params: ModelParams  # Must be set by subclass
+
+    def __init__(self, gf_low: float = 0.30, gf_high: float = 0.85) -> None:
+        self.gf_low = gf_low
+        self.gf_high = gf_high
+        self._n2_k = tuple(const.LOG_2 / hl for hl in self.params.n2_half_life)
+        self._he_k = tuple(const.LOG_2 / hl for hl in self.params.he_half_life)
+
+    def init(self, surface_pressure: float) -> TissueState:
+        """Initialise tissue compartments for surface saturation.
+
+        :param surface_pressure: Ambient pressure at surface [bar].
+        :returns: Initial tissue state with all compartments at surface equilibrium.
+        """
+        # Standard air composition: 79.02% N2
+        p_n2 = 0.7902 * (surface_pressure - const.WATER_VAPOUR_PRESSURE_DEFAULT)
+        p_he = 0.0
+        return TissueState(
+            n2_pressures=tuple([p_n2] * 16),
+            he_pressures=tuple([p_he] * 16),
+        )
+
+    def load(
+        self,
+        tissues: TissueState,
+        abs_p: float,
+        time: float,
+        gas: Gas,
+        rate: float,
+    ) -> TissueState:
+        """Calculate tissue gas loading for all compartments.
+
+        Applies the Schreiner equation to each compartment for both N2 and He.
+
+        :param tissues: Current tissue state.
+        :param abs_p: Absolute pressure at current depth [bar].
+        :param time: Time of exposure [min].
+        :param gas: Gas mix being breathed.
+        :param rate: Pressure rate change [bar/min] (+descent, -ascent, 0=const).
+        :returns: Updated tissue state after exposure.
+        """
+        f_n2 = gas.n2 / 100.0
+        f_he = gas.he / 100.0
+        p_alv_n2 = f_n2 * (abs_p - const.WATER_VAPOUR_PRESSURE_DEFAULT)
+        p_alv_he = f_he * (abs_p - const.WATER_VAPOUR_PRESSURE_DEFAULT)
+        r_n2 = f_n2 * rate
+        r_he = f_he * rate
+
+        new_n2 = []
+        new_he = []
+        for i in range(16):
+            new_n2.append(
+                eq_schreiner(tissues.n2_pressures[i], p_alv_n2, r_n2, time, self._n2_k[i])
+            )
+            new_he.append(
+                eq_schreiner(tissues.he_pressures[i], p_alv_he, r_he, time, self._he_k[i])
+            )
+        return TissueState(
+            n2_pressures=tuple(new_n2),
+            he_pressures=tuple(new_he),
+        )
+
+    def ceiling(self, tissues: TissueState, gf: float) -> float:
+        """Calculate the overall ascent ceiling pressure.
+
+        Returns the maximum (shallowest limit) across all compartments.
+
+        :param tissues: Current tissue state.
+        :param gf: Gradient factor to use.
+        :returns: Absolute pressure of ascent ceiling [bar].
+        """
+        return max(self.compartment_ceilings(tissues, gf))
+
+    def compartment_ceilings(self, tissues: TissueState, gf: float) -> tuple[float, ...]:
+        """Calculate ascent ceiling for each tissue compartment.
+
+        :param tissues: Current tissue state.
+        :param gf: Gradient factor to use.
+        :returns: Tuple of ceiling pressures for each compartment.
+        """
+        params = self.params
+        return tuple(
+            eq_gf_limit(
+                gf,
+                tissues.n2_pressures[i],
+                tissues.he_pressures[i],
+                params.n2_a[i],
+                params.n2_b[i],
+                params.he_a[i],
+                params.he_b[i],
+            )
+            for i in range(16)
+        )

decodaitengu/models/zhl16b.py

@@ -0,0 +1,150 @@
+#
+# DecoTengu - dive decompression library.
+#
+# Copyright (C) 2013-2014 by Artur Wroblewski <wrobell@pld-linux.org>
+# Copyright (C) 2024 Contributors
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#
+
+"""ZH-L16B decompression model with gradient factors.
+
+ZH-L16B-GF is the original Bühlmann model variant used for dive table
+calculations. Coefficients sourced from Erik Baker's gfdeco.f implementation.
+"""
+
+from .base import ZHL16GF, ModelParams
+
+ZHL16B_PARAMS = ModelParams(
+    n2_half_life=(
+        5.0,
+        8.0,
+        12.5,
+        18.5,
+        27.0,
+        38.3,
+        54.3,
+        77.0,
+        109.0,
+        146.0,
+        187.0,
+        239.0,
+        305.0,
+        390.0,
+        498.0,
+        635.0,
+    ),
+    n2_a=(
+        1.1696,
+        1.0000,
+        0.8618,
+        0.7562,
+        0.6667,
+        0.5600,
+        0.4947,
+        0.4500,
+        0.4187,
+        0.3798,
+        0.3497,
+        0.3223,
+        0.2850,
+        0.2737,
+        0.2523,
+        0.2327,
+    ),
+    n2_b=(
+        0.5578,
+        0.6514,
+        0.7222,
+        0.7825,
+        0.8126,
+        0.8434,
+        0.8693,
+        0.8910,
+        0.9092,
+        0.9222,
+        0.9319,
+        0.9403,
+        0.9477,
+        0.9544,
+        0.9602,
+        0.9653,
+    ),
+    he_half_life=(
+        1.88,
+        3.02,
+        4.72,
+        6.99,
+        10.21,
+        14.48,
+        20.53,
+        29.11,
+        41.20,
+        55.19,
+        70.69,
+        90.34,
+        115.29,
+        147.42,
+        188.24,
+        240.03,
+    ),
+    he_a=(
+        1.6189,
+        1.3830,
+        1.1919,
+        1.0458,
+        0.9220,
+        0.8205,
+        0.7305,
+        0.6502,
+        0.5950,
+        0.5545,
+        0.5333,
+        0.5189,
+        0.5181,
+        0.5176,
+        0.5172,
+        0.5119,
+    ),
+    he_b=(
+        0.4770,
+        0.5747,
+        0.6527,
+        0.7223,
+        0.7582,
+        0.7957,
+        0.8279,
+        0.8553,
+        0.8757,
+        0.8903,
+        0.8997,
+        0.9073,
+        0.9122,
+        0.9171,
+        0.9217,
+        0.9267,
+    ),
+)
+
+
+class ZHL16B(ZHL16GF):
+    """ZH-L16B-GF decompression model.
+
+    Used for dive table calculations. This is the legacy model retained
+    for backward compatibility. Prefer ZHL16C for new applications.
+
+    Coefficients sourced from Erik Baker's gfdeco.f.
+    """
+
+    params = ZHL16B_PARAMS