Simulation Spec - Battery Simulation Tool

Version: 0.2.0
Date: 2026-03-08
Status: Active planning

1. Purpose

Define the initial simulation rules for the browser-based battery model.

2. Interval Model

• simulation runs on each source interval in chronological order
• MVP assumes 15-minute intervals
• each interval is evaluated deterministically
• interval duration should be derived from timestamps where possible, but the MVP is optimized for 15-minute data

3. Baseline

For every interval, keep the original total connection-level:

• import energy
• export energy

This baseline remains unchanged and is used for comparison against the simulated case.

4. Core Derived Values

For each interval:

• surplus energy = total exported energy available for charging
• deficit energy = total imported energy that could potentially be offset by discharge

If the uploaded format requires derivation, normalization should calculate equivalent values before simulation starts.

For HomeWizard-style cumulative import/export meters:

• convert cumulative readings to interval deltas before simulation
• combine tariff-split columns such as Import T1 and Import T2 into one total import value
• combine tariff-split export columns into one total export value
• ignore per-phase balancing in the MVP; only the total connection result determines whether the battery may charge or discharge

5. Charging Rules

Charging per interval is limited by:

• available surplus energy or optional grid energy when grid charging is enabled
• remaining usable battery space
• max charging power converted to interval energy
• charging efficiency derived from the configured round-trip efficiency model used in the MVP

6. Discharging Rules

Discharging per interval is limited by:

• current usable battery energy above reserve/minimum SOC
• interval deficit energy
• max discharging power converted to interval energy
• discharging efficiency derived from the configured round-trip efficiency model used in the MVP

7. State of Charge Update

After charge and discharge are evaluated:

• update SOC
• clamp to configured minimum and maximum usable bounds
• persist the result for the next interval

The interval order shall be:

1. determine baseline import/export
2. determine charge opportunity
3. apply charge limits
4. determine discharge opportunity
5. apply discharge limits
6. update SOC
7. calculate simulated import/export

8. Output Calculation

For every interval calculate:

• simulated import
• simulated export
• charge energy
• discharge energy
• SOC

9. Financial Layer

Use the post-simulation totals to calculate:

• baseline import cost
• simulated import cost
• baseline export revenue
• simulated export revenue
• indicative net savings

The MVP pricing layer uses manual import and export tariffs only.

10. Explicit MVP Limits

The MVP does not model:

• battery degradation over lifetime
• temperature effects
• inverter clipping beyond a simple configurable loss assumption
• demand charges
• smart forecast-based charging
• dynamic tariff optimization