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 (Rit et al., Applied Energy 2024) as a vectorized multidimensional multiple-choice knapsack problem (MMCKP) — a binary MILP built with linopy and solved by default with the open-source HiGHS 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

pip install batipathway

Or from source:

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

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/ 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:

See 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, and a complete synthetic example lives in tests/fixtures.py:make_synthetic_dataset.

Documentation

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

• installation.md — install instructions
• theory.md — mathematical formulation and SHAPE mapping
• input_schema.md — normative input schema reference
• tutorial.md — end-to-end walkthrough
• api.md — API reference

Development

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
• Hofmann, F. (2023). Linopy: Linear optimization with n-dimensional labeled variables. Journal of Open Source Software, 8(84), 4823.

License

MIT — see LICENSE.