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
[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.
 destination depth (see

_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
[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].

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 ZHL16GF decompression model. 
decotengu.model.ZH_L16_GF () 
Base abstract class for Buhlmann ZHL16 decompression model with gradient factors by Erik Baker  ZHL16BGF. 
decotengu.model.ZH_L16B_GF () 
ZHL16BGF decompression model. 
decotengu.model.ZH_L16C_GF () 
ZHL16CGF 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 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¶
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.

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.
First Decompression Stop Binary Search¶
decotengu.alt.bisect.BisectFindFirstStop (engine) 
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¶
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. See also