SAMBA

Systems Advisor for Microgrids & Building Analysis — optimal sizing and techno-economic analysis of hybrid energy systems.

Describe a system in a YAML file; SAMBA formulates and solves a linear program (oemof-solph + HiGHS) for the least-cost component sizing and hourly dispatch, then writes a structured directory of result artifacts.

Features

• Provably-optimal sizing (LP/MILP) — PV, wind, battery, diesel, inverter, grid, EV/V2G
• Thermal domain — heat pump, thermal storage, and gas boiler with merit-order dispatch
• 8 tariff structures — flat, TOU, tiered, seasonal, monthly (and combinations), plus demand charges and NEM/net-billing
• Multi-objective cost + CO₂ with epsilon-constraint Pareto fronts
• Real-world data — NSRDB weather fetch, bifacial PV, battery degradation, load-profile templates
• Four ways to use it — Python API, CLI, REST service, and a Vue 3 + Tauri desktop/web UI
• Standardised artifacts — kpis.json, dispatch.parquet, economics.json, sizing.csv

Quick start

pip install samba-core[cli]
samba run examples/base_scenario.yaml -o results/

import samba
from samba.scenario import load_scenario
from samba.input_resolver import resolve_arrays
from pathlib import Path

scenario = load_scenario("examples/base_scenario.yaml")
load_kw, pv_per_kwp, wind_power_kw = resolve_arrays(scenario, Path("examples"))
result = samba.run(scenario, load_kw=load_kw, pv_per_kwp=pv_per_kwp, output_dir="results/")
print(f"NPC ${result.kpis['npc']:,.0f}  ·  LCOE ${result.kpis['lcoe']:.3f}/kWh")

The default solver is HiGHS (installed via highspy); CBC also works (--solver cbc).

Desktop & Web UI

A Vue 3 + Tauri front-end talks to the samba serve REST API and runs in the browser or as a native desktop app:

samba serve --data-dir examples       # REST API on http://127.0.0.1:8000
cd ui && npm install && npm run dev    # UI on http://localhost:1420

Documentation

Contributing

See CONTRIBUTING.md. Development uses uv:

git clone https://github.com/sambaenergies/samba.git
cd samba && uv sync --all-extras

License

Mozilla Public License 2.0. See Acknowledgements.