samba-core 5.3.1

Systems Advisor for Microgrids & Building Analysis

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

Document	Description
Getting Started	Install and run your first scenario
Scenario Reference	Complete YAML schema reference
Thermal Components	Heat pump, thermal storage, gas supply
CLI Reference	run, validate, info, serve, …
API Reference	Python API
Deployment	REST service (Docker, persistence, CI)
Desktop / Web UI	Running and developing the front-end
Known Limitations	What SAMBA does and does not model

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.