← Back to the grid

Research — BESS · Live

Battery energy and power arithmetic for grid-scale storage: typed values with provenance, never a verdict.

A compute-only library for stationary grid-scale battery energy storage: usable energy, state of charge, C-rate power limits, charge and discharge duration, and round-trip efficiency loss. Every input is caller-supplied (typically from a manufacturer datasheet) and every result carries its method and source reference. It never decides whether a value is acceptable.

Interactive demos

See harnesses →the toolsets that sit on top of these functions.

What it can do

  • calculate_usable_energy

    Usable kWh = nameplate × depth of discharge × (1 − reserve margin).

  • calculate_state_of_charge

    State of charge as a fraction and percent of usable capacity; raises on an out-of-range reading instead of clamping it.

  • calculate_c_rate_power_limit

    Maximum sustained power = nameplate kWh × C-rate.

  • calculate_charge_duration

    Hours to add a given energy at a charge power, capped at the C-rate limit when one is supplied.

  • calculate_discharge_duration

    Hours to deliver a given energy at a discharge power, with the same cap and an explicit power_was_capped flag.

  • calculate_round_trip_efficiency_loss

    Energy recovered and lost for a given energy in and a round-trip efficiency.

A worked case

Input

Tesla Megapack 2 XL, 4-Hour configuration: 3,916 kWh, 0.25C, 93.7% round-trip efficiency, discharged at 979 kW.

Result

Power limit 979 kW; discharge duration exactly 4.00 h (a 2-Hour configuration, 3,854 kWh at 1,927 kW, gives exactly 2.00 h); energy recovered from a full 3,916 kWh charge is 3,669.292 kWh, so about 246.7 kWh is lost.

Where this stands

Draft/unreviewed as of 2026-08-12: no human power or storage systems engineer has reviewed it. An AI-assisted pre-review found and fixed two issues (a fabricated Powerwall 2 depth-of-discharge validation case, and a basis inconsistency in the standards file). The functions reproduce the Megapack 2 XL durations and power figures exactly, but the Powerwall usable-energy case is trivial (100% depth of discharge) and no ingested product validates a real sub-100% depth of discharge.

Open questions

  • Depth of discharge is stated against different capacities by different manufacturers; the caller must match the convention.
  • The C-rate is a system-level kW per kWh ratio, not a cell-level electrochemical C-rate, so it can mislead where voltage sag matters.
  • Round-trip efficiency has a measurement point (AC to AC vs DC to DC) the caller must keep consistent; it is not enforced.
  • Degradation, thermal derating, economics and EMS scheduling are not built.
All domains →