Metadata-Version: 2.4
Name: permafrost-utac
Version: 1.0.0
Summary: Real ESA CCI Permafrost v5.0 data and Schuur et al. 2022 carbon-stock science -- deliberately no UTAC/CREP bridge, per climate-topic convention
Project-URL: Homepage, https://github.com/GenesisAeon/permafrost-utac
Project-URL: Repository, https://github.com/GenesisAeon/permafrost-utac
Author: Römer, Johann
License: MIT
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: numpy>=1.24
Provides-Extra: data
Requires-Dist: netcdf4>=1.6; extra == 'data'
Requires-Dist: xarray>=2023.1; extra == 'data'
Provides-Extra: dev
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pre-commit>=3.7.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.6.0; extra == 'dev'
Description-Content-Type: text/markdown

# permafrost-utac

[![GenesisAeon](https://img.shields.io/badge/GenesisAeon-P60-blue)](https://github.com/GenesisAeon)
[![CI](https://github.com/GenesisAeon/permafrost-utac/actions/workflows/ci.yml/badge.svg)](https://github.com/GenesisAeon/permafrost-utac/actions/workflows/ci.yml)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

GenesisAeon Package 60 — real ESA CCI Permafrost v5.0 data and Schuur et al.
2022 carbon-stock science. **Deliberately has no UTAC/CREP/AFET bridge** —
see [DISCLAIMER.md](DISCLAIMER.md).

## What's real here

- **ESA CCI Permafrost v5.0**: real satellite dataset (University of
  Oslo/CEDA, DOI `10.5285/a6fbedd8ee5b472c8e84e55f746c1704`), 1997-2023,
  1 km resolution, MAGT/active-layer-thickness/extent.
- **Schuur et al. 2022** (*Annual Review of Environment and Resources*,
  47, 343-371): permafrost carbon stock 1460-1600 GtC, and modeled
  emission ranges under 2C/4C warming by 2100.
- An explicit structural note that permafrost thaw is **not** a classical
  bistable tipping element (IPCC AR6) — a gradual, self-amplifying
  feedback with regional abrupt events (thermokarst), not a single global
  bifurcation point.

## Why no UTAC/CREP/AFET bridge

Unlike several other GenesisAeon packages, this one deliberately does not
propose a Gamma/CREP hypothesis for permafrost. Climate-topic packages in
this ecosystem default to presenting real data on its own terms, without a
speculative framework bridge, unless one clearly and genuinely fits — see
[DISCLAIMER.md](DISCLAIMER.md) for the full reasoning.

## Quickstart

```bash
pip install permafrost-utac
# for real ESA CCI NetCDF loading:
pip install "permafrost-utac[data]"
```

```python
from permafrost_utac import SyntheticPermafrostData, carbon_stock_gt

print(f"Permafrost carbon stock: ~{carbon_stock_gt():.0f} GtC")

series = SyntheticPermafrostData.generate_fraction_series()
for year, fraction in list(series.items())[:3]:
    print(year, fraction)
```

## Development

```bash
pip install -e ".[dev,data]"
pre-commit install
ruff check src tests
mypy src
pytest
```

## Citation

See [CITATION.cff](CITATION.cff) and [.zenodo.json](.zenodo.json).
