Metadata-Version: 2.4
Name: climate-lama-engine
Version: 0.4.0
Summary: Lean probabilistic climate risk calculation engine
Author: CortoMaltese3
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/CortoMaltese3/climate-lama-engine
Project-URL: Repository, https://github.com/CortoMaltese3/climate-lama-engine
Project-URL: Bug Tracker, https://github.com/CortoMaltese3/climate-lama-engine/issues
Keywords: climate,risk,impact,hazard,exposure,probabilistic
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.11
Provides-Extra: pandas
Requires-Dist: pandas>=2.0; extra == "pandas"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: pandas>=2.0; extra == "dev"
Dynamic: license-file

# climate-lama-engine

Lean probabilistic climate risk calculation engine. Clean-room reimplementation of CLIMADA's core math — no geospatial dependencies, no I/O, just numpy and scipy.

**Runtime deps**: `numpy>=1.24`, `scipy>=1.11`
**Python**: >=3.10

---

## Install

```bash
uv sync --group dev
```

Or with pip:

```bash
pip install -e ".[dev]"
```

---

## Run tests

```bash
uv run pytest
```

---

## Use on another machine

Clone the repo and sync the environment — the lockfile guarantees identical versions:

```bash
git clone <repo-url>
cd climate-lama-core
uv sync --group notebooks
```

Then open VS Code, create or open any notebook, and select the `.venv` inside
`climate-lama-core/` as the kernel. `import climate_lama_engine as cc` will work
from any notebook on the machine, not just the ones in this repo.

To update later:

```bash
git pull
uv sync --group notebooks
```

---

## Notebooks

Documentation and manual testing notebooks live in [`notebooks/`](notebooks/).

### Setup

```bash
uv sync --group notebooks
uv run jupyter notebook
```

Or with pip:

```bash
pip install -e .
pip install -r notebooks/requirements.txt
jupyter notebook
```

Then open any notebook from the `notebooks/` folder in your browser.

### Notebook overview

| Notebook | Description |
|----------|-------------|
| [00_quickstart.ipynb](notebooks/00_quickstart.ipynb) | 10-minute end-to-end walkthrough: hazard to EAD to measure |
| [01_hazard.ipynb](notebooks/01_hazard.ipynb) | Hazard deep dive: marginal frequencies, sparse matrix internals |
| [02_exposures.ipynb](notebooks/02_exposures.ipynb) | Exposures: centroid assignment, insurance parameters |
| [03_impact_functions.ipynb](notebooks/03_impact_functions.ipynb) | MDR, MDD, PAA -- why they are separate, JRC flood function |
| [04_impact_calculation.ipynb](notebooks/04_impact_calculation.ipynb) | Core engine: all output attributes, identity checks, spatial risk map |
| [05_measures.ipynb](notebooks/05_measures.ipynb) | Adaptation measures: intensity reduction, retrofits, early warning |
| [06_cost_benefit.ipynb](notebooks/06_cost_benefit.ipynb) | Cost-benefit analysis: BCR, discount rates, risk metric sensitivity |
| [07_flood_greece_pattern.ipynb](notebooks/07_flood_greece_pattern.ipynb) | Realistic JRC flood scenario on a 50x50 Greece grid |
| [08_climada_comparison.ipynb](notebooks/08_climada_comparison.ipynb) | Side-by-side verification against upstream CLIMADA |

---

## Quick example

```python
import numpy as np
from scipy import sparse
import climate_lama_engine as cc

rps = np.array([10, 100, 500])
intensity = sparse.csr_matrix(np.array([
    [0.0, 0.5, 1.0, 0.0, 0.2],
    [0.0, 1.2, 2.5, 0.5, 0.8],
    [0.0, 2.0, 4.0, 1.0, 1.5],
]))
hazard = cc.Hazard.from_rp_maps(
    haz_type="RF", intensity_unit="m",
    return_periods=rps, intensity=intensity,
    centroid_lat=np.array([37.9, 38.0, 38.1, 38.2, 38.3]),
    centroid_lon=np.array([23.7, 23.8, 23.9, 24.0, 24.1]),
)

impf = cc.ImpactFunc(
    id=1, haz_type="RF",
    intensity=np.array([0.0, 0.5, 1.0, 2.0, 3.0, 5.0]),
    mdd=np.array([0.0, 0.02, 0.07, 0.25, 0.50, 0.80]),
    paa=np.array([0.0, 0.20, 0.40, 0.70, 0.90, 1.00]),
)
impfset = cc.ImpactFuncSet([impf])

exposures = cc.Exposures(
    value=np.array([500_000, 1_200_000, 800_000, 300_000]),
    centroid_idx=np.array([1, 2, 3, 4]),
    impf_id=np.array([1, 1, 1, 1]),
    value_unit="EUR",
)

result = cc.ImpactCalc(hazard, exposures, impfset).impact()
print(f"EAD: EUR {result.aai_agg:,.0f}")

levee = cc.Measure(name="Flood Levee", haz_type="RF", haz_inten_a=0.8, cost=2_000_000)
mod_haz, mod_impf = levee.apply(hazard, impfset)
result_with_levee = cc.ImpactCalc(mod_haz, exposures, mod_impf).impact()
print(f"EAD with levee: EUR {result_with_levee.aai_agg:,.0f}")
```

---

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for a full history of releases.

---

## License & Legal

Apache 2.0 — see [LICENSE](LICENSE).

`climate-lama-engine` is a clean-room reimplementation of well-known probabilistic
climate risk mathematics. No GPL-licensed source code was used during implementation.
See [CLEAN_ROOM.md](CLEAN_ROOM.md) for the full implementation statement.
