Classes and Functions¶
Core API¶

Create decompression engine . 
DecoTengu decompression engine. 


Decompression table summary. 

Dive step information. 

Gas mix configuration. 

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
[source]¶ 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)[source]¶ 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
Gas mix switch depth is the same as current dive step depth, then simply perform gas mix switch.
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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ Calculate collection of decompression stops.
The method returns collection of tuples
destination depth (see
decotengu.Engine._deco_ascent_stages()
method)gas mix (see
decotengu.Engine._deco_ascent_stages()
method)time required to ascent to next decompression stops (usually time required to ascent by 3m)
gradient factor value for next decompression stop or surface
 Parameters
step – Current dive step.
stages – Decompression ascent stages.

_descent_stages
(end_abs_p, gas_list)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ Calculate stages for decofree 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)[source]¶ Perform staged ascent until first decompression stop.
 Parameters
start – Starting dive step.
stages – Dive stages.

_inv_limit
(abs_p, data)[source]¶ 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)[source]¶ 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)[source]¶ 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 ZHL16GF 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)[source]¶ 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')[source]¶ 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')[source]¶ 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.
 FIXME: due to

_step_next_descent
(step, time, gas, phase='descent')[source]¶ 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)[source]¶ 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.

_time_to_pressure
(time, rate)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ Convert absolute pressure to depth.
 Parameters
abs_p – Absolute pressure of depth [bar].

_to_pressure
(depth)[source]¶ Convert depth in meters to absolute pressure in bars.
 Parameters
depth – Depth in meters.

_validate_gas_list
(depth)[source]¶ Validate gas mix list.
ConfigError is raised if any of gas mix rules are violated.
The gas mix rules are
There is one nontravel gas mix on gas mix list.
If no travel gas mixes, then first gas mix is bottom gas and its switch depth is 0m.
All travel gas mixes have different switch depth.
All decompression gas mixes have different switch depth.
All decompression gas mixes have switch depth greater than zero.
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)[source]¶ Add gas mix to the gas mix list.
First nontravel gas mix is bottom gas mix. Any other nontravel 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)[source]¶ 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.
See also

class
decotengu.
DecoTable
(iterable=(), /)[source]¶ Decompression table summary.
The class is a list of decompression stops.
The decompression stops time is in minutes.
See also

append
(depth, time)[source]¶ Add decompression stop.
 Parameters
depth – Depth of decompression stop [m].
time – Time of decompression stop [min].

property
total
¶ Total decompression time.


class
decotengu.engine.
Step
(phase, abs_p, time, gas, data)¶ 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
(depth, o2, n2, he)¶ Gas mix configuration.
 Variables
depth – Gas mix switch depth.
o2 – O2 percentage.
n2 – N2 percentage.
he – Helium percentage.

class
decotengu.engine.
DecoStop
(depth, time)¶ Dive decompression stop information.
 Variables
depth – Depth of decompression stop [m].
time – Length of decompression stops [min].
Decompression Model¶

Data for ZHL16GF decompression model. 
Base abstract class for Buhlmann ZHL16 decompression model with gradient factors by Erik Baker  ZHL16BGF. 

ZHL16BGF decompression model. 

ZHL16CGF decompression model. 


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

class
decotengu.model.
Data
(tissues, gf)¶ Data for ZHL16GF 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 ZHL16 decompression model with gradient factors by Erik Baker  ZHL16BGF.
 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 halflife value.
 Parameters
half_life – Collection of halflife 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.

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¶
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¶

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.

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¶

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

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.
First Decompression Stop Binary Search¶
Find first first decompression stop using Schreiner equation and bisect algorithm. 

class
decotengu.alt.bisect.
BisectFindFirstStop
(engine)[source]¶ Find first first decompression stop using Schreiner equation and bisect algorithm.
Method returns dive step  start of first decompression stop.
Below, by depth we mean absolute pressure of depth expressed in bars.
The first decompression stop depth is searched between depth of starting dive step and target depth parameter. The latter can be surface or any other depth divisible by 3.
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.
Naive Algorithms¶
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.
See also