Classes and Functions

Core API

decotengu.create([time_delta, validate]) Create decompression engine .
decotengu.Engine() DecoTengu decompression engine.
decotengu.DecoTable Decompression table summary.
decotengu.engine.Step Dive step information.
decotengu.engine.GasMix Gas mix configuration.
decotengu.engine.DecoStop Dive decompression stop information.
decotengu.create(time_delta=None, validate=True)[source]

Create decompression engine .

The decompression model validation is enabled by default.

Usage

>>> import decotengu
>>> engine = decotengu.create()
>>> engine.add_gas(0, 21)
>>> data = list(engine.calculate(35, 40))
>>> engine.deco_table.total
44.0
Parameters:
  • time_delta – Time between dive steps.
  • validate – Validate decompression data with decompression model validator.
class decotengu.Engine

DecoTengu decompression engine.

Use decompression engine to calculate dive profile and decompression information.

Variables:
  • model – Decompression model.
  • surface_pressure – Surface pressure [bar].
  • ascent_rate – Ascent rate during a dive [m/min].
  • descent_rate – Descent rate during a dive [m/min].
  • last_stop_6m – If true, then last deco stop is at 6m (not default 3m).
  • deco_table – List of decompression stops.
  • _gas_list – List of gas mixes.
  • _deco_stop_search_time – Time limit for decompression stop linear search.
_ascent_switch_gas(step, gas)

Switch to specified gas mix, ascending if necessary.

The method is used to switch gas during dive ascent when ascent is performed to depth being multiply of 3m. Two scenarios are implemented

  1. Gas mix switch depth is the same as current dive step depth, then simply perform gas mix switch.
  2. Gas mix switch depth is shallower than current dive step depth
    • ascend to gas mix switch depth
    • perform gas mix switch
    • ascend to next depth, which is multiply of 3m

Gas mix switch is done in place, takes no time at the moment, but in the future this should be configurable.

A tuple of gas mix switch dive steps is returned.

Parameters:
  • step – Current dive step.
  • gas – Gas to switch to.
_can_ascend(abs_p, time, data, gf=None)

Check if a diver can ascend from current depth without violating ascent ceiling limit.

Parameters:
  • abs_p – Absolute pressure of current depth [bar].
  • time – Time of ascent [min].
  • data – Decompression model data.
  • gf – Gradient factor to be used for ceiling check.
_ceil_pressure_3m(abs_p)

Calculate absolute pressure value, so when converted to meters its value is divisible by 3.

Parameters:abs_p – Input absolute pressure [bar].
_deco_ascent_stages(start_abs_p, gas_list)

Calculate stages for decompression ascent.

Ascent stage is a tuple

  • absolute pressure of destination depth
  • gas mix

The ascent stages are calculated using gas mix list. The absolute pressure of destination depth is gas switch depth rounded down to multiply of 3m and then converted to pressure, for example:

 0m  21%         3.1bar (21m)  21%
22m  50%   ->    1.6bar (6m)   50%
 6m 100%         1.0bar (0m)  100%

Only gas mixes, which switch depth is shallower than start depth, are used for decompression ascent stages calculation.

Parameters:
  • gas_list – List of gas mixes - bottom and decompression gas mixes.
  • start_abs_p – Absolute pressure of decompression start depth.
_deco_staged_ascent(start, stages)

Perform staged asccent within decompression zone.

Parameters:
  • start – Starting dive step.
  • stages – Dive stages.

See also

decotengu.Engine._ascent_stages_deco()

_deco_stop(step, next_time, gas, gf)

Calculate decompression stop.

The length of a decompression stop is guarded by gradient factor of next decompression stop - the current decompression stop lasts until it is allowed to ascent to next stop.

Parameters:
  • step – Start of current decompression stop.
  • next_time – Time required to ascent to next deco stop [min].
  • gas – Gas mix configuration.
  • gf – Gradient factor value of next decompression stop.
_deco_stops(step, stages)

Calculate collection of decompression stops.

The method returns collection of tuples

Parameters:
  • step – Current dive step.
  • stages – Decompression ascent stages.
_descent_stages(end_abs_p, gas_list)

Calculate stages for dive descent.

Descent stage is a tuple

  • absolute pressure of destination depth
  • gas mix

The descent stages are calculated using gas mix list. The absolute pressure of destination depth is switch depth of next gas mix absolute pressure of destination depth, for example for end_abs_p = 6.6bar:

 0m  30%        4.6bar (36m)  30%
36m  21%   ->   6.6bar (56m)  21%

If switch depth of last gas mix is equal to the destination depth, then descent stage is not included for it. It means that descent is performed to the bottom on travel gas only and it is responsbility of the caller to perform appropriate bottom gas switch.

Parameters:
  • end_abs_p – Absolute pressure of destination depth.
  • gas_list – List of gas mixes - travel and bottom gas mixes.
_dive_ascent(start, gas_list)

Dive ascent from starting dive step.

The method checks if the ascent is part of NDL dive before dive ascent starts.

If dive is decompression dive, then ascent is divided into two phases

  • ascent to first decompression stop
  • ascent performing decompression stops
Parameters:
  • start – Starting dive step.
  • gas_list – List of gas mixes - bottom and decompression gas mixes.
_dive_descent(abs_p, gas_list)

Dive descent from surface to absolute pressure of destination depth.

The last gas on the gas mix list is bottom gas, others are travel gas mixes.

Parameters:
  • abs_p – Absolute pressure of destination depth.
  • gas_list – List of gas mixes - travel and bottom gas mixes.
_find_first_stop(start, abs_p, gas)

Find first first decompression stop using Schreiner equation.

Method returns dive step - start of first decompression stop.

Below, by depth we mean absolute pressure of depth expressed in bars.

The depth of first decompression stop is the shallowest depth, which does not breach the ascent limit imposed by ascent ceiling. The depth is divisble by 3.

The first decompression stop depth is found by ascending to adjusted value of current ascent ceiling limit. The current ascent ceiling value is always adjusted, so its value in meters is divisible by 3. The ascent is repeated while it is possible to do so and until target depth.

Parameters:
  • start – Starting dive step indicating current depth.
  • abs_p – Absolute pressure of target depth - surface or gas switch depth.
  • gas – Gas mix configuration.
_free_ascent_stages(gas_list)

Calculate stages for deco-free ascent.

Ascent stage is a tuple

  • absolute pressure of destination depth
  • gas mix

The ascent stages are calculated using gas mix list. The absolute pressure of destination depth is gas switch depth rounded up to multiply of 3m and then converted to pressure, for example:

 0m  21%        3.4bar (24m)  21%
22m  50%   ->   1.6bar  (6m)  50%
 6m 100%        1.0bar  (0m) 100%
Parameters:gas_list – List of gas mixes - bottom and decompression gas mixes.
_free_staged_ascent(start, stages)

Perform staged ascent until first decompression stop.

Parameters:
  • start – Starting dive step.
  • stages – Dive stages.
_inv_limit(abs_p, data)

Return true if decompression model data does not violate decompression model ceiling limit invariant.

The invariant is

Absolute pressure (depth) has to be deeper or at the same depth as absolute pressure of ceiling limit.
Parameters:
  • abs_p – Absolute pressure of current depth.
  • data – Decompression model data.
_n_stops(start_abs_p, end_abs_p=None)

Calculate amount of decompression stops required between start and end depths.

Parameters:
  • start_abs_p – Absolute pressure of starting depth.
  • end_abs_p – Absolute pressure of ending depth (surface pressure if null).
_ndl_ascent(start, gas)

Check if NDL ascent to the surface is possible from starting dive step.

Return the surface dive step if NDL ascent is possible, null otherwise.

NDL ascent is performed to the surface usually using bottom gas (NOTE: not always possible - exceptions not implemented yet).

To calculate surface dive step, the surface decompression model parameters are applied, i.e. for ZH-L16-GF decompression model, gradient factor value is set to GF high parameter.

Parameters:
  • start – Starting dive step.
  • gas – Gas mix used during NDL ascent.
_pressure_to_time(pressure, rate)

Convert pressure change into time using depth change rate.

The returned time is in minutes.

Parameters:
  • pressure – Pressure change [bar].
  • rate – Rate of depth change [m/min].
_step_next(step, time, gas, phase='const')

Calculate next dive step at constant depth and advanced by specified amount of time.

Parameters:
  • step – Current dive step.
  • time – Time spent at current depth [min].
  • gas – Gas mix configuration.
  • data – Decompression model data.
  • phase – Dive phase.
_step_next_ascent(step, time, gas, gf=None, phase='ascent')

Calculate next dive step when ascent is performed for specified period of time.

FIXME: due to gf parameter this method is deco model dependant,
this has to be improved
Parameters:
  • step – Current dive step.
  • time – Time to ascent from current dive step [min].
  • gas – Gas mix configuration.
  • data – Decompression model data.
  • phase – Dive phase.
_step_next_descent(step, time, gas, phase='descent')

Calculate next dive step when descent is performed for specified period of time.

Parameters:
  • step – Current dive step.
  • time – Time to descent from current dive step [min].
  • gas – Gas mix configuration.
  • phase – Dive phase.
_step_start(abs_p, gas)

Create the very first dive step.

The first step is initialized with decompression data calculated for surface.

The dive starting depth is usually surface, but any depth can be specified, i.e. when descent part of the dive is to be skipped.

Parameters:
  • abs_p – Absolute pressure of dive starting depth.
  • gas – Gas mix configuration.
_switch_gas(step, gas)

Switch gas mix.

The switch results in new dive step.

_time_to_pressure(time, rate)

Convert time into pressure change using depth change rate.

Parameters:
  • time – Time [min].
  • rate – Rate of depth change [m/min].
_tissue_pressure_ascent(abs_p, time, gas, data)

Calculate tissues gas loading after ascent.

Parameters:
  • abs_p – Starting pressure indicating the depth [bar].
  • time – Time of ascent [min].
  • gas – Gas mix configuration.
  • data – Decompression model data.
_tissue_pressure_const(abs_p, time, gas, data)

Calculate tissues gas loading after exposure for specified amount of time at depth.

Parameters:
  • abs_p – Absolute pressure indicating the depth [bar].
  • time – Time at depth [min].
  • gas – Gas mix configuration.
  • data – Decompression model data.
_tissue_pressure_descent(abs_p, time, gas, data)

Calculate tissues gas loading after descent.

Parameters:
  • abs_p – Starting pressure indicating the depth [bar].
  • time – Time of descent [min].
  • gas – Gas mix configuration.
  • data – Decompression model data.
_to_depth(abs_p)

Convert absolute pressure to depth.

Parameters:abs_p – Absolute pressure of depth [bar].
_to_pressure(depth)

Convert depth in meters to absolute pressure in bars.

Parameters:depth – Depth in meters.
_validate_gas_list(depth)

Validate gas mix list.

ConfigError is raised if any of gas mix rules are violated.

The gas mix rules are

  1. There is one non-travel gas mix on gas mix list.
  2. If no travel gas mixes, then first gas mix is bottom gas and its switch depth is 0m.
  3. All travel gas mixes have different switch depth.
  4. All decompression gas mixes have different switch depth.
  5. All decompression gas mixes have switch depth greater than zero.
  6. There is no gas mix with switch depth deeper than maximum dive depth.
Parameters:depth – Maximum dive depth.
add_gas(depth, o2, he=0, travel=False)

Add gas mix to the gas mix list.

First non-travel gas mix is bottom gas mix. Any other non-travel gas mix is decompression gas mix.

See decotengu.engine.Engine._validate_gas_list() method documentation for more gas mix list rules.

Parameters:
  • depth – Switch depth of gas mix.
  • o2 – O2 percentage, i.e. 80.
  • he – Helium percentage, i.e. 18.
  • travel – Travel gas mix if true.
calculate(depth, time, descent=True)

Start dive profile calculation for specified dive depth and bottom time.

The method returns an iterator of dive steps.

Before the calculation the gas mix list is validated. See decotengu.engine.Engine._validate_gas_list() method documentation for the list of gas mix list rules.

Parameters:
  • depth – Maximum depth [m].
  • time – Dive bottom time [min].
  • descent – Skip descent part of a dive if set to false.
class decotengu.DecoTable

Decompression table summary.

The class is a list of decompression stops.

The decompression stops time is in minutes.

append(depth, time)

Add decompression stop.

Parameters:
  • depth – Depth of decompression stop [m].
  • time – Time of decompression stop [min].
total

Total decompression time.

class decotengu.engine.Step

Dive step information.

Variables:
  • phase – Dive phase.
  • abs_p – Absolute pressure at depth [bar].
  • time – Time of dive [min].
  • gas – Gas mix configuration.
  • data – Decompression model data.
class decotengu.engine.GasMix

Gas mix configuration.

Variables:
  • depth – Gas mix switch depth.
  • o2 – O2 percentage.
  • n2 – N2 percentage.
  • he – Helium percentage.
class decotengu.engine.DecoStop

Dive decompression stop information.

Variables:
  • depth – Depth of decompression stop [m].
  • time – Length of decompression stops [min].

Decompression Model

decotengu.model.Data Data for ZH-L16-GF decompression model.
decotengu.model.ZH_L16_GF() Base abstract class for Buhlmann ZH-L16 decompression model with gradient factors by Erik Baker - ZH-L16B-GF.
decotengu.model.ZH_L16B_GF() ZH-L16B-GF decompression model.
decotengu.model.ZH_L16C_GF() ZH-L16C-GF decompression model.
decotengu.model.eq_gf_limit(gf, p_n2, p_he, ...) Calculate ascent ceiling limit of a tissue compartment using Buhlmann equation extended with gradient factors by Erik Baker.
class decotengu.model.Data

Data for ZH-L16-GF decompression model.

Variables:
  • tissues – Tissues gas loading. Tuple of pair numbers - each pair holds value of inert gas pressure (N2, He) in a tissue compartment.
  • gf – Gradient factor value.
class decotengu.model.ZH_L16_GF[source]

Base abstract class for Buhlmann ZH-L16 decompression model with gradient factors by Erik Baker - ZH-L16B-GF.

Variables:
  • gf_low – Gradient factor low parameter.
  • gf_high – Gradient factor high parameter.
  • water_vapour_pressure – Water vapour pressure.
  • n2_k_const – Gas decay constants \(k\) for nitrogen for each tissue compartment.
  • he_k_const – Gas decay constants \(k\) for helium for each tissues compartment.
_exp(time, k)[source]

Calculate value of exponential function for time and gas decay constant \(k\).

Parameters:
  • time – Time of exposure [min].
  • k – Gas decay constant \(k\) for a tissue compartment.
_k_const(half_life)[source]

Calculate gas decay constant \(k\) for each tissue compartment half-life value.

Parameters:half_life – Collection of half-life values for each tissue compartment.
_tissue_loader(abs_p, f_gas, rate, k_const)[source]

Create function to load tissue compartment with inert gas.

The created function uses Schreiner equation and has the following parameters

time
Time of exposure [min] at depth (\(T_{time}\)).
p_i
Initial (current) pressure of inert gas in tissue compartment [bar] (\(P_{i}\)).
tissue_no
Number of tissue compartment in the decompression model (starting with zero).

See Schreiner Equation section for details.

Parameters:
  • abs_p – Absolute pressure of current depth [bar] (\(P_{abs}\)).
  • f_gas – Inert gas fraction, i.e. for air it is 0.79 (\(F_{gas}\)).
  • rate – Pressure rate change [bar/min] (\(P_{rate}\)).
  • k_const – Collection of gas decay constants for each tissue compartment (\(k\)).
_tissue_loaders(abs_p, gas, rate)[source]

Create function to load tissue compartment with inert gas for each inert gas specified in gas mix configuration.

Parameters:
  • abs_p – Absolute pressure of current depth [bar] (\(P_{abs}\)).
  • gas – Gas mix configuration.
  • rate – Pressure rate change [bar/min] (\(P_{rate}\)).
ceiling_limit(data, gf=None)[source]

Calculate pressure of ascent ceiling limit using decompression model data.

The pressure is the shallowest depth a diver can reach without decompression sickness. If pressure limit is 3 bar, then diver should not go shallower than 20m.

FIXME: the method signature is gradient factor specific, the
signature has to be made decompression model independent
Parameters:
  • data – Decompression model data.
  • gf – Gradient factor value, gf_low by default.
gf_limit(gf, data)[source]

Calculate pressure of ascent ceiling for each tissue compartment.

The method returns a tuple of values - a pressure value for each tissue compartment.

Parameters:
  • gf – Gradient factor.
  • data – Decompression model data.
init(surface_pressure)[source]

Initialize pressure of inert gas in all tissues.

The method uses starting tissue pressure values for nitrogen and helium.

Parameters:surface_pressure – Surface pressure [bar].
load(abs_p, time, gas, rate, data)[source]

Calculate gas loading for all tissue compartments.

The method returns decompression data model information.

Parameters:
  • abs_p – Absolute pressure [bar] (current depth).
  • time – Time of exposure [min] (i.e. time of ascent).
  • gas – Gas mix configuration.
  • rate – Pressure rate change [bar/min].
  • data – Decompression model data.
class decotengu.model.ZH_L16B_GF[source]

ZH-L16B-GF decompression model.

class decotengu.model.ZH_L16C_GF[source]

ZH-L16C-GF decompression model.

decotengu.model.eq_gf_limit(gf, p_n2, p_he, a_n2, b_n2, a_he, b_he)[source]

Calculate ascent ceiling limit of a tissue compartment using Buhlmann equation extended with gradient factors by Erik Baker.

The returned value is absolute pressure of depth of the ascent ceiling.

Parameters:
  • gf – Gradient factor value.
  • p_n2 – Current tissue pressure for nitrogen.
  • p_he – Current tissue pressure for helium.
  • a_n2 – Nitrox Buhlmann coefficient A.
  • b_n2 – Nitrox Buhlmann coefficient B.
  • a_he – Helium Buhlmann coefficient A.
  • b_he – Helium Buhlmann coefficient B.

Dive Phases

decotengu.engine.Phase Dive phase enumeration.
class decotengu.engine.Phase[source]

Dive phase enumeration.

The dive phases are

START
Start of a dive. It happens at begining of the dive (time=0min, depth=0min). Only one dive step can exist with such dive phase.
DESCENT
Descent during dive - current dive step is deeper than previous one.
CONST
Constant depth during dive - current dive step is at the same depth as previous one.
ASCENT
Ascent during dive - current dive step is shallower than previous one.
DECO_STOP
Decompression stop. Current dive step is at the same depth as previous one and ascent is not possible until allowed by decompression model.
GAS_SWITCH
Gas mix switch. Current dive step is at the same depth as previous one. The time of current and previous dive steps is the same.

Dive Profile Expansion

decotengu.conveyor.Conveyor(engine, time_delta) Conveyor to expand dive profile into more granular dive steps.
class decotengu.conveyor.Conveyor(engine, time_delta)[source]

Conveyor to expand dive profile into more granular dive steps.

The conveyor is used to override Engine.calculate method, for example:

>>> import decotengu
>>> engine = decotengu.Engine()
>>> engine.add_gas(0, 21)
>>> engine.calculate = Conveyor(engine, 1) # dive step every 1min
>>> profile = engine.calculate(50, 20)
>>> for step in profile:
...     print(step)     
Step(phase="start", abs_p=1.0132, time=0.0000, ...)
Step(phase="descent", abs_p=3.0103, time=1.0000, ...)
Step(phase="descent", abs_p=5.0072, time=2.0000, ...)
Step(phase="descent", abs_p=6.0057, time=2.5000, ...)
...
Variables:
  • engine – DecoTengu decompression engine.
  • time_delta – Time delta to increase dive steps granulity [min].
  • f_calc – Orignal DecoTengu decompression engine calculation method.
__call__(*args, **kw)[source]

Execute original Engine.calculate method and expand dive steps.

trays(start_time, end_time)[source]

Return count of trays and time rest.

The count of trays is amount of time delta values existing between start and end time (exclusive). The time rest is amount of minutes between last tray and end of time.

The information calculated by the method enables us to increase dive step granulity, i.e:

>>> import decotengu
>>> engine = decotengu.Engine()
>>> conveyor = Conveyor(engine, 1)
>>> conveyor.trays(1.7, 4)
(2, 0.2999999999999998)

For time delta 1 minute, there are two dive steps to be inserted. The remaining time between last inserted dive step and ending step is 0.3 minute (20s).

Parameters:
  • start_time – Starting time [min].
  • end_time – Ending time [min].

Tabular Tissue Calculator

decotengu.alt.tab.tab_engine(engine) Override DecoTengu engine object attributes and methods, so it is possible to use tabular tissue calculator.
decotengu.alt.tab.TabExp(n2_k_const, he_k_const) Tabular calculator.
decotengu.alt.tab.tab_engine(engine)[source]

Override DecoTengu engine object attributes and methods, so it is possible to use tabular tissue calculator.

Parameters:engine – DecoTengu engine object.
class decotengu.alt.tab.TabExp(n2_k_const, he_k_const)[source]

Tabular calculator.

Calculate value of exponential function using precomputed values for exp function.

Variables:_kt_exp – Collection of precomputed values of exp function for nitrogen and helium decay constants \(k\).
__call__(time, k)[source]

Calculate exponential function value using precomputed values and the property

\[e^{x + y} = e^x * e^y\]
Parameters:
  • time – Time of exposure [min].
  • k – Gas decay constant \(k\) for a tissue compartment.

Naive Algorithms

decotengu.alt.naive.DecoStopStepper(engine) Execute decompression stop using 1min intervals.
class decotengu.alt.naive.DecoStopStepper(engine)[source]

Execute decompression stop using 1min intervals.

The algorithm is quite inefficient, but is used by some of the diving computers and software, so this class is created for comparison purposes.

Variables:engine – DecoTengu decompression engine.
__call__(start, time, gas, gf)[source]

Execute dive decompression stop using 1min intervals.