Classes and Functions¶

Core API¶

`decotengu.create`([time_delta, validate])	Create decompression engine .
`decotengu.Engine`()	DecoTengu decompression engine.
`decotengu.DecoTable`([iterable])	Decompression table summary.
`decotengu.engine.Step`(phase, abs_p, time, …)	Dive step information.
`decotengu.engine.GasMix`(depth, o2, n2, he)	Gas mix configuration.
`decotengu.engine.DecoStop`(depth, time)	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 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)[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 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)[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.

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

_switch_gas(step, gas)[source]¶

Switch gas mix.

The switch results in new dive step.

_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 non-travel 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 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.

See also

decotengu.Engine._validate_gas_list()

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

decotengu.Engine._validate_gas_list()

See also

decotengu.Engine.add_gas()

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

decotengu.engine.DecoStop

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¶

`decotengu.model.Data`(tissues, gf)	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(tissues, gf)¶

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.

See also

decotengu.model.ZH_L16_GF.gf_limit()
decotengu.model.ZH_L16_GF._tissue_loader()

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.

See also

decotengu.model.ZH_L16_GF._tissue_loaders()
decotengu.model.ZH_L16_GF._tissue_loader()

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.

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.

__call__(start, abs_p, gas)[source]¶

Execute binary search to find first decompression stop.

Parameters

start – Starting dive step indicating current depth.
abs_p – Absolute pressure of target depth - surface or gas switch depth.
gas – Gas mix configuration.

See also

decotengu.Engine._find_first_stop()

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

decotengu.Engine._deco_stop()

__call__(start, time, gas, gf)[source]¶: Execute dive decompression stop using 1min intervals.

See also

decotengu.Engine._deco_stop()