Metadata-Version: 2.4
Name: decodaitengu
Version: 1.4.2
Summary: DecoDaiTengu - dive decompression library (fork of DecoTengu)
Project-URL: Repository, https://github.com/notionparallax/decodaitengu
Author-email: Artur Wroblewski <wrobell@pld-linux.org>
License-Expression: GPL-3.0-or-later
License-File: COPYING
Keywords: buhlmann,decompression,dive,diving,gradient-factors
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: hypothesis>=6.0; extra == 'dev'
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pre-commit>=3.7; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# DecoDaiTengu

A modern Python dive decompression library implementing the Bühlmann ZH-L16B/C
decompression model with Erik Baker's gradient factors.

This is a modernised fork of the original [DecoTengu](http://git.savannah.gnu.org/cgit/decotengu.git)
library (v0.14.1, 2018) by Artur Wroblewski.

## Features

- **ZH-L16B-GF and ZH-L16C-GF** models with full helium compartment support (trimix)
- **Gradient factor** configuration (GF low/high)
- **CNS and OTU** oxygen toxicity tracking
- **High-level `plan_dive()` API** for common dive planning
- **Type-annotated**, Python 3.10+ codebase
- Gas mix support: air, nitrox, trimix

## Quick Start

```bash
pip install decodaitengu
```

```python
from decodaitengu import plan_dive, Gas

# Simple air dive
result = plan_dive(depth=35, bottom_time=40, gf=(30, 85))
print(f"Runtime: {result.runtime} min")
print(f"Deco stops: {[(s.depth, s.time) for s in result.stops]}")
print(f"CNS: {result.cns_percent}%")

# Trimix dive with deco gas
result = plan_dive(
    depth=60,
    bottom_time=20,
    back_gas=Gas(21, 35),
    deco_gases=[Gas(50, 0, switch_depth=21), Gas(100, 0, switch_depth=6)],
    gf=(30, 85),
)
print(f"Runtime: {result.runtime} min")

# Segmented ascent profile: 10 m/min to 6m, then 0.5 m/min to surface
result = plan_dive(
    depth=45,
    bottom_time=20,
    ascent_rate=[(6, 10), (0, 0.5)],
)

# Dict form is also supported
result = plan_dive(
    depth=45,
    bottom_time=20,
    ascent_rate={6: 10, 0: 0.5},
)
```

## Ascent Rates

`plan_dive()` accepts `ascent_rate` in three forms:

- Single float (uniform ascent), e.g. `10.0`
- List of `(max_depth_m, rate_m_per_min)`, e.g. `[(6, 10), (0, 0.5)]`
- Dict mapping depth to rate, e.g. `{6: 10, 0: 0.5}`

Rules:

- All rates must be positive finite numbers.
- Segment depths must be non-negative.
- Profile input must include a segment at depth `0` (surface).

## Models

```python
from decodaitengu import plan_dive
from decodaitengu.models import ZHL16C, ZHL16B

# ZHL-16C is the default (recommended for dive computers)
result = plan_dive(depth=40, bottom_time=25, model=ZHL16C)

# ZHL-16B available for backward compatibility
result = plan_dive(depth=40, bottom_time=25, model=ZHL16B)
```

## Legacy API

The original DecoTengu Engine-based API has been removed. Calling
`decodaitengu.create()` raises `RuntimeError` with migration instructions.

Migration from old `decotengu`:

```python
# OLD (decotengu v0.x):
#   import decotengu
#   engine = decotengu.create()
#   engine.add_gas(0, 21)
#   profile = engine.calculate(35, 40)
#   list(profile)
#   print(engine.deco_table.total)

# NEW (decodaitengu v1.x):
from decodaitengu import plan_dive, Gas

result = plan_dive(depth=35, bottom_time=40, back_gas=Gas(21, 0), gf=(30, 85))
print(result.total_deco_time)
```

## Known Differences from Other Planners

This library uses the analytically-exact Schreiner equation for tissue loading,
whereas Subsurface (and many dive computers) use the Haldane equation with
discrete 1-second steps. The two approaches are equivalent at constant depth
but produce slightly different results during ascent/descent phases.

Key divergences from Subsurface 6.0 (ZHL-16C, GF 50/70):

| Factor | Effect | Typical magnitude |
|--------|--------|-------------------|
| Schreiner vs Haldane 1s steps | Less conservative during ascent | ±1–4 min at shallow stops |
| Gas switch timing (free ascent) | May be more conservative | +2–4 min at 3m for multi-gas |
| Helium off-gassing | Extra shallow stops for trimix | +1 stop at 18m |

Per-stop divergence is bounded at ≤5 minutes in integration tests. See
[`tests/integration/reference_data.json`](decodaitengu/tests/integration/reference_data.json)
for exact Subsurface reference values.

**This library is not a certified dive planning tool. Always validate plans
against established software and never dive beyond your training.**

## Documentation

The legacy Sphinx docs (referencing the old `decotengu` namespace) have been
removed. API documentation will be rebuilt from the current `decodaitengu`
package in a future release.

## Development

```bash
pip install -e ".[dev]"
pre-commit install
pre-commit run --all-files
pytest
ruff check .
```

The pre-commit hooks intentionally run check-only commands matching CI:

```bash
ruff check decodaitengu/
ruff format --check decodaitengu/
```

## Release Process

- Add or update release notes in RELEASE_NOTES.md with a heading that matches the tag,
  for example `## v1.2.1`.
- The publish workflow enforces this and will fail if the section is missing.

## License

GPL-3.0-or-later. See [COPYING](COPYING) for details.

**WARNING:** This software is provided as-is with no warranty. Any diving
using data provided by this library is at the diver's own risk.

![Ukiyoe print by Utagawa Kuniyoshi. The poem (substituting hentaigana and adding punctuation) reads, 競れば､長し短し､むつかしや。我慢の鼻の､を(置)き所なし Kurabureba, nagashi mijikashi, mutsukashiya. Gamanno hanano, okidokoro nashi and means something like, "If you compete, long or short, it's a problem. With a boast-worthy? nose, there's no place to put it."](https://upload.wikimedia.org/wikipedia/commons/4/48/Elephant_and_a_flying_tengu.jpg)
