FS - Battery Simulation Tool

Version: 0.3.0
Date: 2026-03-08
Status: Active prototype

1. Purpose

This Functional Specification translates the MVP URS into explicit, implementable page behavior.

2. Functional Behavior

FS-01 Upload Flow

• The page shall provide a file-upload control for CSV input.
• The page shall show parsing status and basic file-read feedback.
• The page shall keep uploaded household data in client memory only for the normal workflow.

FS-02 Column Detection

• The parser shall attempt to detect timestamp, import, export, and tariff-like columns.
• The page shall show the detected mapping to the user.
• If the minimum required mapping is unclear, the page shall expose manual mapping controls.
• The MVP shall support a HomeWizard-style CSV path where import/export may be split over multiple tariff columns and must be combined into one total interval series.

FS-03 Scenario Inputs

• The page shall provide fields for:
  • battery capacity
  • max charge power
  • max discharge power
  • round-trip efficiency
  • min/max usable state of charge
  • initial state of charge
  • grid charging permission
  • reserve capacity
  • manual import tariff
  • manual export tariff
  • acquisition cost
• The current prototype defaults shall open with 2.7 kWh capacity and 0.8 kW max charge/discharge power.
• The current prototype defaults shall open with 8% minimum SOC and 8% initial SOC.
• The settings fields shall expose inline ? help affordances with short explanations.

FS-04 Simulation Run

• The page shall expose a run action for explicit reruns and recovery after invalid input.
• Relevant mapping and settings changes shall automatically trigger a rerun in the prototype.
• The engine shall evaluate the dataset interval by interval.
• The engine shall make charge/discharge decisions from the total connection-level import/export result, not per individual phase.
• The baseline and simulated case shall both be retained for result comparison.
• The MVP shall run one scenario at a time.

FS-05 KPI Summary

• After a successful run, the page shall display KPI cards for:
  • imported energy without battery
  • imported energy with battery
  • exported energy without battery
  • exported energy with battery
  • battery charged energy
  • battery discharged energy
  • indicative savings
  • indicative payback time
  • self-consumption improvement
• The page shall also show the pricing basis used for the KPI calculation.

FS-06 Charts

• The page shall render interactive Plotly charts for:
  • battery state of charge over time
  • battery charged/discharged energy over time
  • cumulative charged/discharged battery energy over time
  • grid import/export or net exchange over time
  • indicative savings over a 0 to 30 kWh capacity sweep
  • aggregated daily comparison totals
• The time-based charts shall keep a synchronized visible time range when the user zooms or pans one of them.
• The default chart set shall remain limited to 2 to 3 charts for responsiveness.

FS-07 Result Export

• The page shall allow export of summary outputs in CSV or JSON form.
• The export shall be derived from the currently active scenario only.

FS-08 Local-Only Processing

• Core parsing, simulation, and chart data preparation shall run locally in the browser.
• The page shall state that uploaded household data stays local in the normal workflow.

FS-09 Validation and Errors

• The tool shall reject obviously invalid or incomplete input combinations.
• The page shall show actionable validation errors instead of silent failure.
• The tool shall show a clear warning when the CSV does not contain a reliable minimum column set.

3. Functional Traceability

• FR-001 to FR-008 -> FS-01, FS-02
• FR-010 to FR-019 -> FS-03
• FR-030 to FR-038 -> FS-04
• FR-040 to FR-046 -> FS-05
• FR-060 to FR-066 -> FS-06, FS-07
• FR-080 to FR-082 -> FS-08

4. MVP Boundary

The MVP stops at one scenario per run, one reliable CSV-oriented workflow, manual pricing, and a limited chart set.