Metadata-Version: 2.4
Name: resilience-memory-utac
Version: 0.1.0
Summary: Critical slowing down (early-warning statistics) and post-perturbation resilience-debt tracking for climate and ecological systems
Author: Römer, Johann
License: MIT
License-File: LICENSE
Requires-Python: >=3.11
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

# resilience-memory-utac

[![GenesisAeon](https://img.shields.io/badge/GenesisAeon-P97-blue)](https://github.com/GenesisAeon)
[![CI](https://github.com/GenesisAeon/resilience-memory-utac/actions/workflows/ci.yml/badge.svg)](https://github.com/GenesisAeon/resilience-memory-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 97 — real critical-slowing-down statistics and
post-perturbation resilience-debt tracking. **Deliberately has no
UTAC/CREP/AFET bridge** — see [DISCLAIMER.md](DISCLAIMER.md).

## What's real here

- Dakos et al. (2012, *PLOS ONE*): the generic early-warning-signal
  workflow — detrend a time series, compute rolling variance / lag-1
  autocorrelation / skewness, test each for a trend with Kendall's tau.
- Scheffer et al. (2009, *Nature*): the underlying concept — recovery
  rate from small perturbations declines as a system nears a critical
  transition ("critical slowing down").
- van Nes & Scheffer (2007, *American Naturalist*): slow recovery from
  perturbations, tracked here as an explicit "resilience-debt" — if a
  system hasn't recovered before the next shock, it carries the deficit
  forward.
- A live, verified illustration (not calibration input): Rhine at Kaub
  (24 cm, 2026-08-04, matching the 2018 record), Danube at Paks (-144 cm,
  below the 2018 record of -98 cm, triggering Hungary's first-ever full
  reactor shutdown), and Cernavoda NPP (Romania, reactor shutdown +
  emergency underwater demolition to redirect cooling water) — see
  [DISCLAIMER.md](DISCLAIMER.md) for exactly what this case study is and
  is not used for.

## Quickstart

```bash
pip install resilience-memory-utac
```

```python
from resilience_memory_utac import compute_early_warning_report

# any real time series you supply -- river discharge, coral cover, ...
report = compute_early_warning_report(my_series)
print(f"Variance trend: tau={report.variance_tau:.2f} (p={report.variance_p:.3f})")
print(f"Autocorrelation trend: tau={report.autocorrelation_tau:.2f}")
```

```python
from resilience_memory_utac import PerturbationEvent, compute_resilience_debt

events = [
    PerturbationEvent(label="2018 low-water", time=0, magnitude=8.0, tau=365.0),
    PerturbationEvent(label="2026 low-water", time=2800, magnitude=10.0, tau=365.0),
]
states = compute_resilience_debt(events)
print(states[-1].fully_recovered)  # False if the 2018 event hadn't fully decayed away
```

## Development

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

## Citation

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