Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

34 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

BESS-Opt — Parametric Layout & Cabling Optimization Engine for Battery Energy Storage Systems

Python Streamlit Shapely SciPy Status

Overview

BESS-Opt is a spatial optimization engine for utility-scale Battery Energy Storage System (BESS) plant design. It automates the placement of battery containers and their Medium-Voltage Stations (MVS) inside an arbitrary site polygon, honouring safety setbacks, non-buildable corridors, equipment clearances, and cable-length constraints — and then performs a global cable-routing reassignment to minimize copper.

What is traditionally a manual, multi-day CAD exercise is reduced to a parametric, repeatable run that produces engineering-grade KPIs (cluster count, total cable length, area saturation, plant power, plant energy) and an interactive layout that can be hand-tuned and exported.

Repository Layout

The project is split into a headless core, a rendering layer, and two thin front-ends (notebook + app) that share the core verbatim — no duplicated logic.

core/         layout & calculations (no UI, no plotting deps)
viz/          matplotlib + plotly + text rendering (imports core)
app/          Streamlit UI wrapper (imports core + viz)
Layout.ipynb  engineering notebook at the repo root (imports core + viz)
tests/        invariant tests
Path Role
core/config.py Single source of truth: DEFAULT_EQUIPMENT + build_config(). Both modes build CONFIG here so they can never diverge.
core/geometry.py Polygon handling (shapely), candidate grids, clearance generation, rotation, placement validity.
core/placement.py Shared placement helpers (cluster growth, straggler fill, Hungarian cable reassignment) used by the packer and the co-located engine.
core/colocation.py Co-located / paired-MVS hub engine (facility-location + hub-balanced assignment).
core/metrics.py Layout KPIs and hub/civil-works metrics.
core/sizing.py System sizing: total MW / MWh and 2H / 3H / 4H duration classification.
core/site_io.py save_site / load_site: site boundary + zones as JSON files under sites/.
core/serialization.py Layout ⇄ DataFrame round-trip and non-corrupting CSV export.
core/packing.py Row/shelf packing engine (run_row_packing) — the primary layout optimizer.
core/optimize.py run_colocated_optimization (co-located / paired-MVS scenario).
viz/ matplotlib_plots, plotly_plots, compare (text table).
app/app.py Streamlit UI — three-phase workflow; widgets → build_config → core → viz.
Layout.ipynb Standalone engineering notebook at the repo root, no app dependency.
tests/test_engine.py Invariant tests (no overlaps, capacity, in-bounds, sizing).

Algorithmic Highlights

  1. Back-to-Back Row Packing — the engine places containers flush at the exact per-side clearance (not on a lattice), so adjacent rows touch on their small back clearance (e.g. 0.15 m), with a centred MVS row every max_bess_per_mvs rows for short cable.
  2. Full 0/90/180/270 Rotation — every container evaluates all four orientations, with asymmetric clearances remapped accordingly; 180°/270° are what enable back-to-back packing on the small clearance side.
  3. Row-Alignment Penalty — a configurable cost term coerces BESS units to inherit their parent MVS orientation and X/Y axis, producing clean architectural rows when uniformity matters.
  4. Global Min-Cost Layout Selection — a Hungarian solver finds the maximum number of BESS that can be served under the cable and per-MVS caps; then, across every packing, the final layout is chosen with a convex cable cost (d²/4 m per BESS: 4 m → 4, 5 m → 6.25, so every BESS stays close to its station rather than saving total length by pushing one far away), each MVS centred in its cluster (2+2 rather than 1+3), and LV cables kept inside one buildable zone unless crossing non-buildable land is the only way to reach the maximum (then with as few crossings as possible). Reported cable KPIs stay in real metres.
  5. Collision-Aware Editing — manual edits in the UI re-run the placement validator so any out-of-bounds or overlapping component is flagged immediately.

Engines

Engine What it does
Row Pack (core/packing.py, run_row_packing) Primary optimizer. Analytic back-to-back shelf packing adaptive to arbitrary concave polygons, evaluating all 4 rotations, with interleaved MVS rows and cable-cap-aware Hungarian assignment. Runs in ~1-3 s.
Target Sizing (extra) (core/packing.py, run_target_packing) Optional study on top of the main (max-BESS) design. Sizes the plant to an energy target (MWh) at one or more chosen system durations (h): BESS = ⌈MWh / bess_unit_mwh⌉, MVS = ⌈MW / mvs_station_mw⌉ with MW = MWh / duration (never fewer than ⌈BESS / max_bess_per_mvs⌉ — the per-MVS cap is always respected), BESS split evenly across MVS. It can never place more BESS than the max-fill Row Pack. Uses the same layout selection as Row Pack (convex LV cable cost + MV cable as MST between MVS), with each MVS centred among its BESS (MVS rows tried at every offset of the shelf cycle) and every BESS on an MVS of its own buildable zone (crossing non-buildable land only as a last resort, allow_cross_zone). If the target does not fit, returns the largest plant that fits at the same duration and reports the shortfall.
Co-Located (core/optimize.py, run_colocated_optimization) Optional scenario that seeds MVS onto shared foundation pads (paired / hub) via facility-location before packing BESS, then balances cable across each hub.

Installation

Python 3.12 is recommended. Core runtime dependencies:

pip install numpy shapely scipy matplotlib plotly streamlit pandas

Usage

1. Programmatic — the engine in a script or notebook

build_config is the single config constructor (equipment defaults to the mandated DEFAULT_EQUIPMENT); the notebook and the app both use it.

from core import build_config, run_row_packing, size_system
from viz import plot_individual, print_comparison

CONFIG = build_config(
    site_vertices=[(0, 0), (53.3, 0), (53.3, 90.4), (0, 90.4)],
    non_buildable=[],
    restricted=[],
    max_bess_per_mvs=4,
    max_cable_length=25,
    grid_resolution=2.0,
    bess_unit_mwh=5.0,
    mvs_station_mw=2.5,
)

result = run_row_packing(CONFIG, verbose=True)
plot_individual(result, CONFIG)

# System sizing: total MW / MWh and 2H / 3H / 4H duration class.
m = result["metrics"]
print(size_system(m["bess_count"], m["mvs_count"],
                  CONFIG["bess_unit_mwh"], CONFIG["mvs_station_mw"]))

Extra — size to an energy target at a chosen system duration (the main objective stays run_row_packing, maximum BESS):

from core import run_target_packing

out = run_target_packing(CONFIG, target_mwh=200, durations=[4, 3, 2], verbose=True)
for h, res in out.items():
    t = res["target"]   # achieved_bess/_mvs/_mwh/_mw, achieved_duration_h, met, shortfall_mwh
    print(f"{h}H", t["achieved_bess"], t["achieved_mvs"], t["met"], t["shortfall_mwh"])

Keep a site's hand-traced vertices in their own file so they are never lost (sites/ holds one JSON per site; the notebook's SITE_FILE / SAVE_SITE_AS switches between loading a file and typing vertices inline):

from core import save_site, load_site

save_site("sites/my_site.json", site_vertices=[...], non_buildable=[...], restricted=[...])
CONFIG = build_config(**load_site("sites/my_site.json"), max_bess_per_mvs=4)

Print the metrics table for a run:

print_comparison(CONFIG, result)

The standalone notebook lives at Layout.ipynb (repo root) and depends only on core + viz (no app).

2. Interactive — the Streamlit application

streamlit run app/app.py

The app exposes a three-phase workflow:

  1. Site definition — paste the property boundary, non-buildable corridors and restricted zones as vertex lists; tune BESS / MVS clearances, max BESS per MVS, and commercial MWh / MW scaling factors.
  2. Row-Pack optimization — the back-to-back packing engine maximises the number of BESS and reports BESS / MVS count, plant energy, plant power, storage duration, total cable length, and area saturation.
  3. Deep-dive editor — click a unit on the interactive Plotly canvas (or pick from the dropdown) to nudge its X/Y coordinates, change orientation (0/90/180/270), reassign its MVS network, or delete it. Collisions are validated live. Layouts can be exported as a 1920×1080 PNG and the bill of quantities as a CSV report.

An extra 🎯 Target Sizing tab (last tab) sizes the plant to an energy target at the chosen system duration(s), one column per duration, with layout preview and CSV export.

Benchmark results are cached per input hash, so re-entering Phase 2 with unchanged parameters is instantaneous.

Configuration Reference

Key Meaning
site_vertices Ordered list of (x, y) tuples defining the outer property boundary.
setback Inward buffer applied to the site before placement (metres).
zones.non_buildable List of polygons where equipment may not be placed (access roads, cable corridors).
zones.restricted List of polygons entirely excluded from the usable area.
equipment.{BESS,MVS}.width/height Container footprint in metres.
equipment.{BESS,MVS}.clearance Per-side clearance dictionary (front, back, left, right).
max_bess_per_mvs Capacity cap for each MVS cluster.
max_cable_length Maximum Euclidean BESS-to-MVS distance (set to 0 to disable).
grid_resolution Coarse seeding grid spacing (metres).
mvs_scoring_radius Radius used to score candidate MVS positions by nearby demand.
min_mvs_spacing Minimum centre-to-centre spacing between MVS stations.
bess_unit_mwh / mvs_station_mw Per-unit ratings used by core.sizing.size_system.
colocation Co-located/hub parameters (group_size, pad_gap, balance_tolerance, hub_search_radius, target_hub_count).

Output

run_row_packing returns a dictionary containing the prepared site polygon, the non-buildable polygons, the lists of placed MVS and BESS objects (with footprint, clearance zone, rotation flag and assignment), and a metrics dictionary:

  • mvs_count, bess_count, full_mvs
  • total_cable, avg_cable, max_cable_used
  • buildable_area, equipment_area
  • area_saturation_pct, capacity_saturation_pct

Tests

python -m pytest tests/ -q        # or: python tests/test_engine.py

The suite runs every mode (plus the co-located engine) end-to-end on the default site and asserts the invariants any valid layout must satisfy: no footprint/clearance overlaps, per-MVS capacity respected, all equipment inside the site and out of non-buildable zones, and sane 2H/3H/4H sizing.

Roadmap

  • Topographical awareness — Z-axis elevation tiering for sloped sites.
  • Thermal heat-map overlays — ambient HVAC clearance scoring.
  • DXF / GeoJSON export — direct hand-off to CAD and GIS pipelines.
  • Multi-vendor equipment library — pluggable container catalogue.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages