#
# DecoTengu - dive decompression library.
#
# Copyright (C) 2013-2018 by Artur Wroblewski <wrobell@riseup.net>
#
# 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/>.
#
"""
Basic Usage
-----------
The DecoTengu dive decompression library exports its main API via
``decotengu`` module.
The calculation of dive profile and decompression table can be performed in
few simple steps by using :func:`~decotengu.create` function, which creates
:class:`DecoTengu engine <Engine>` and :class:`decompression table
<DecoTable>` objects. Having DecoTengu engine object, we need to instruct
it what gas mixes are used after which we can start calculations. The
following example executes calculations for a dive to 35 meters for 40
minutes on air::
>>> import decotengu
>>> engine = decotengu.create()
>>> engine.add_gas(0, 21)
>>> profile = engine.calculate(35, 40)
The :func:`DecoTengu engine calculation <Engine.calculate>` method returns
an iterator with dive profile steps::
>>> for step in profile:
... print(step) # doctest:+ELLIPSIS
Step(phase="start", abs_p=1.0132, time=0.0000, gf=0.3000)
Step(phase="descent", abs_p=4.5080, time=1.7500, gf=0.3000)
Step(phase="const", abs_p=4.5080, time=40.0000, gf=0.3000)
...
Step(phase="ascent", abs_p=1.9119, time=48.6000, gf=0.5750)
...
Step(phase="ascent", abs_p=1.0133, time=87.5000, gf=0.8500)
After dive profile iterator is fully exhausted, the dive table can be used
to obtain all information about decompression stops::
>>> for stop in engine.deco_table:
... print(stop)
DecoStop(depth=18.0, time=1.0)
DecoStop(depth=15.0, time=1.0)
DecoStop(depth=12.0, time=4.0)
DecoStop(depth=9.0, time=6.0)
DecoStop(depth=6.0, time=10.0)
DecoStop(depth=3.0, time=22.0)
and total time of dive decompression obligations::
>>> engine.deco_table.total
44.0
Configuring Decompression Model
-------------------------------
The default decompression model used by DecoTengu library is Buhlmann's
:class:`ZH-L16B <ZH_L16B>` model with gradient factors - ZH-L16B-GF::
>>> import decotengu
>>> engine = decotengu.create()
>>> engine.add_gas(0, 21)
>>> engine.model # doctest:+ELLIPSIS
<decotengu.model.ZH_L16B_GF object at ...>
>>> engine.model.gf_low
0.3
>>> engine.model.gf_high
0.85
We can switch to ZH-L16C-GF decompression model easily::
>>> engine.model = decotengu.ZH_L16C_GF()
>>> profile = engine.calculate(35, 40)
>>> list(profile) # doctest:+ELLIPSIS
[Step...]
>>> engine.deco_table.total
52.0
>>> engine.deco_table[0]
DecoStop(depth=18.0, time=1.0)
>>> engine.deco_table[-1]
DecoStop(depth=3.0, time=26.0)
Above, the total dive decompression time is longer due to ZH-L16C-GF being
more conservative comparing to ZH-L16B-GF.
Gradient factor parameters can be adjusted using ``gf_low`` and ``gf_high``
attributes::
>>> engine.model # doctest:+ELLIPSIS
<decotengu.model.ZH_L16C_GF object at ...>
>>> engine.model.gf_low = 0.2 # vs. 0.30 - first stop deeper
>>> engine.model.gf_high = 0.90 # vs. 0.85 - last stop shorter
>>> profile = engine.calculate(35, 40)
>>> list(profile) # doctest:+ELLIPSIS
[Step...]
>>> engine.deco_table.total
48.0
>>> engine.deco_table[0]
DecoStop(depth=21.0, time=1.0)
>>> engine.deco_table[-1]
DecoStop(depth=3.0, time=24.0)
"""
from .engine import Engine, DecoTable
from .model import ZH_L16B_GF, ZH_L16C_GF, DecoModelValidator
from .flow import sender
from .conveyor import Conveyor
__version__ = '0.14.1'
[docs]def create(time_delta=None, validate=True):
"""
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
:param time_delta: Time between dive steps.
:param validate: Validate decompression data with decompression model
validator.
"""
engine = Engine()
pipeline = []
if validate:
pipeline.append(DecoModelValidator(engine))
if time_delta:
engine.calculate = Conveyor(engine, time_delta)
engine.calculate = sender(engine.calculate, *pipeline)
return engine
__all__ = ['create', 'Engine', 'ZH_L16B_GF', 'ZH_L16C_GF']
# vim: sw=4:et:ai