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
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file samba_core-6.0.0.tar.gz.
File metadata
- Download URL: samba_core-6.0.0.tar.gz
- Upload date:
- Size: 1.5 MB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
9076446b3b9f12afadd0f77dbe0504535ba4c62f5c2dc4c2ef696599cc89538f
|
|
| MD5 |
f4bb441f197883662dd731a7aadb54ac
|
|
| BLAKE2b-256 |
8f281f1091b6dbf7d3b3a8f116864bf97d193021cf501f34777110e2a7f0ce37
|
Provenance
The following attestation bundles were made for samba_core-6.0.0.tar.gz:
Publisher:
release.yml on sambaenergies/samba
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
samba_core-6.0.0.tar.gz -
Subject digest:
9076446b3b9f12afadd0f77dbe0504535ba4c62f5c2dc4c2ef696599cc89538f - Sigstore transparency entry: 2581784161
- Sigstore integration time:
-
Permalink:
sambaenergies/samba@05c8961efc5db889cc9cd607434f38e653c79844 -
Branch / Tag:
refs/tags/v6.0.0 - Owner: https://github.com/sambaenergies
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@05c8961efc5db889cc9cd607434f38e653c79844 -
Trigger Event:
push
-
Statement type:
File details
Details for the file samba_core-6.0.0-py3-none-any.whl.
File metadata
- Download URL: samba_core-6.0.0-py3-none-any.whl
- Upload date:
- Size: 220.6 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
bc38f2e4206ae8eb7dc5a5850e86b09393b3068371d60cf25ca286c2610739fd
|
|
| MD5 |
ba5c44dfd134b93ed7b423e1221940b8
|
|
| BLAKE2b-256 |
866ea4bee3040d935abd775642a6e4953323567713b37284800f19de0a842a29
|
Provenance
The following attestation bundles were made for samba_core-6.0.0-py3-none-any.whl:
Publisher:
release.yml on sambaenergies/samba
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
samba_core-6.0.0-py3-none-any.whl -
Subject digest:
bc38f2e4206ae8eb7dc5a5850e86b09393b3068371d60cf25ca286c2610739fd - Sigstore transparency entry: 2581784166
- Sigstore integration time:
-
Permalink:
sambaenergies/samba@05c8961efc5db889cc9cd607434f38e653c79844 -
Branch / Tag:
refs/tags/v6.0.0 - Owner: https://github.com/sambaenergies
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@05c8961efc5db889cc9cd607434f38e653c79844 -
Trigger Event:
push
-
Statement type:
