Metadata-Version: 2.5
Name: batipathway
Version: 0.1.0
Summary: Renovation pathway optimizer for residential building stocks (MMCKP via linopy/HiGHS)
Project-URL: Repository, https://gitlab.com/energytransition/BatiPathway
Project-URL: Changelog, https://gitlab.com/energytransition/BatiPathway/-/blob/main/CHANGELOG.md
Author-email: Seddik Yassine Abdelouadoud <yassine.abdelouadoud@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Seddik Yassine Abdelouadoud
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: MILP,buildings,energy,optimization,renovation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.11
Requires-Dist: highspy
Requires-Dist: linopy>=0.6
Requires-Dist: numpy>=1.26
Requires-Dist: pandas>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: xarray>=2024.1
Provides-Extra: dev
Requires-Dist: hypothesis; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pandas-stubs; extra == 'dev'
Requires-Dist: pre-commit; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Requires-Dist: types-pyyaml; extra == 'dev'
Provides-Extra: docs
Requires-Dist: myst-parser; extra == 'docs'
Requires-Dist: sphinx-autodoc-typehints; extra == 'docs'
Requires-Dist: sphinx-book-theme; extra == 'docs'
Requires-Dist: sphinx-copybutton; extra == 'docs'
Requires-Dist: sphinx>=7.0; extra == 'docs'
Provides-Extra: gurobi
Requires-Dist: gurobipy; extra == 'gurobi'
Provides-Extra: plot
Requires-Dist: matplotlib>=3.8; extra == 'plot'
Requires-Dist: seaborn; extra == 'plot'
Description-Content-Type: text/markdown

# BatiPathway

**Renovation pathway optimizer for residential building stocks.**

BatiPathway decides which renovation combination to apply to each building in a stock so as
to minimize **Net Present Cost (NPC)** subject to policy constraints (GHG caps, energy caps,
primary energy per m², electric peak, renovation-rate caps, minimum EPC class).

It implements the optimization core of [**SHAPE**](https://doi.org/10.1016/j.apenergy.2024.122936)
(Rit et al., *Applied Energy* 2024) as a vectorized **multidimensional multiple-choice
knapsack problem (MMCKP)** — a binary MILP built with [linopy](https://linopy.readthedocs.io)
and solved by default with the open-source [HiGHS](https://highs.dev) solver.

The heavy lifting — enumerating valid renovation combinations and simulating their energy
consumption — happens in an upstream simulation package. BatiPathway consumes that package's
output (a single `xarray.Dataset`) and performs only the selection optimization.

- **Status:** 0.1.0 (Alpha)
- **Python:** ≥ 3.11 (tested on 3.11, 3.12, 3.13)
- **License:** MIT

## Installation

```bash
pip install batipathway
```

Or from source:

```bash
git clone https://gitlab.com/energytransition/BatiPathway.git
cd BatiPathway
pip install -e ".[dev]"
```

Optional extras: `gurobi` (Gurobi solver), `docs` (Sphinx docs), `plot` (seaborn), `dev`
(test/lint tooling).

## Quick start

```python
import batipathway as bp
import xarray as xr

# Dataset produced by the upstream simulation package
ds = xr.open_dataset("renovation_options.nc")

config = bp.ScenarioConfig(
    discount_rate=0.04,
    growth_rate=0.02,
    ghg_cap={2050: 2_000.0},
    pe_per_m2_cap={2050: 80.0},
)

model = bp.build_model(bp.validate_input(ds), config)
bp.solve(model)

decisions = bp.extract_decisions(model, ds)
kpis = bp.compute_kpis(decisions, ds, config)
print(f"Total NPC: {kpis['total_npc']:.2e} €")
```

The typical flow is `validate_input` → `build_model` → `solve` → `extract_decisions` →
`compute_kpis`. See [`examples/`](examples/) for runnable scenarios.

## How it works

For each building `b`, the upstream package enumerates valid renovation combinations `c`
(including the do-nothing baseline). BatiPathway introduces a binary variable
`x[b, c] ∈ {0, 1}` and selects exactly one combination per building to minimize total NPC:

```
min  Σ_{b,c} x[b,c] · npc[b,c]
```

The per-combination NPC coefficient is pre-aggregated into a scalar (discounted investment
plus block-aggregated, annualized energy billing), so the objective is a single inner
product. Policy targets are added as linear constraints, each independently disableable via
`ScenarioConfig`:

| Constraint | Config field | SHAPE ref |
|---|---|---|
| Annual GHG cap | `ghg_cap` | `O_GHG_12` |
| Annual total final-energy cap | `energy_cap` | `O_EC` |
| Average primary energy per m² | `pe_per_m2_cap` | `O_EC_EPC` |
| Electric peak cap | `peak_electric_factor` | `O_PE` |
| Renovation-rate cap | `reno_count_cap` | `O_nb_reno`, Eq. (13) |
| Minimum EPC class | `min_epc_class_by_year` | `O_class_EPC` |

See [`docs/theory.md`](docs/theory.md) for the full formulation and its mapping to the paper.

## Input data

BatiPathway expects a single `xarray.Dataset` with these dimensions: `building`,
`combination`, `year`, `carrier`, `gesture_type`. Required variables are `valid`,
`is_baseline`, `consumption`, `investment`, `is_renovating`, and `area`, plus exogenous
`energy_price` and `emission_factor` on a full annual `year_full` axis. Optional variables
(`peak_electric`, `epc_energy_class`, `pe_factor`) unlock the corresponding constraints.

`validate_input` enforces the schema strictly; pass `coerce=True` for sensible automatic
fixes. The authoritative reference is [`docs/input_schema.md`](docs/input_schema.md), and a
complete synthetic example lives in `tests/fixtures.py:make_synthetic_dataset`.

## Documentation

The full documentation (built with Sphinx) lives in [`docs/`](docs/):

- [`installation.md`](docs/installation.md) — install instructions
- [`theory.md`](docs/theory.md) — mathematical formulation and SHAPE mapping
- [`input_schema.md`](docs/input_schema.md) — normative input schema reference
- [`tutorial.md`](docs/tutorial.md) — end-to-end walkthrough
- [`api.md`](docs/api.md) — API reference

## Development

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

ruff check src/ tests/          # lint
ruff format --check src/ tests/ # format check
mypy src/batipathway/           # type-check (strict)
pytest --cov                    # tests
```

These mirror the CI pipeline (`.github/workflows/ci.yml`), which runs on Python 3.11–3.13.

## References

- Rit, M., Thomas, A., Villot, J., Thorel, M., Garreau, E., & Girard, R. (2024). *SHAPE: A
  temporal optimization model for residential buildings retrofit to discuss policy
  objectives.* Applied Energy, 361, 122936.
  doi:[10.1016/j.apenergy.2024.122936](https://doi.org/10.1016/j.apenergy.2024.122936)
- Hofmann, F. (2023). *Linopy: Linear optimization with n-dimensional labeled variables.*
  Journal of Open Source Software, 8(84), 4823.

## License

MIT — see [LICENSE](LICENSE).
