Rens Roosloot

Battery Simulation URS

Volledige gerenderde weergave van URS.md.

Laatst gesynchroniseerd: 13 april 2026

URS - Battery Simulation Tool

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

1. Purpose

This document captures the user requirements for a static-site battery simulation tool that estimates how a home battery could have performed on historical household energy data.

The tool must run locally in the browser for the core workflow.

2. MVP Scope

In scope:

  • upload and parse one HomeWizard-oriented CSV workflow
  • detect and map the minimum required columns
  • configure one battery scenario
  • simulate battery behavior per 15-minute interval
  • show a compact KPI summary and a limited chart set
  • estimate indicative savings from manual import/export prices

Out of scope for MVP:

  • live device integration
  • cloud storage
  • guaranteed savings predictions
  • advanced degradation modeling
  • external price APIs
  • multiple scenario comparison
  • user preset storage
  • advanced strategy modes such as peak shaving optimization

3. Primary User

A household user who wants to evaluate whether a home battery might have reduced grid import/export and improved self-consumption, based on historical data.

4. Functional Requirements

4.1 CSV Upload and Mapping

  • FR-001 The system shall allow the user to upload a CSV file from a local device.
  • FR-002 The system shall parse the uploaded CSV in the browser.
  • FR-003 The system shall attempt to detect relevant columns, including timestamp, import, export, and tariff-related fields where present.
  • FR-004 The system shall show which columns were detected.
  • FR-005 The system shall warn the user when required fields are missing or ambiguous.
  • FR-006 The system shall allow manual column mapping when automatic detection is insufficient.
  • FR-007 The system shall support at least one year of 15-minute interval data in the browser.
  • FR-008 The MVP shall support a common HomeWizard-oriented CSV structure with cumulative import/export meter columns, including multiple tariff columns that must be combined into one total import/export series.
  • FR-009 The MVP may ignore per-phase behavior for simulation decisions, provided the total connection-level import/export result is used.

4.2 Battery Inputs

  • FR-010 The system shall provide user-configurable battery parameters.
  • FR-011 The system shall allow the user to enter battery capacity in kWh.
  • FR-012 The system shall allow the user to enter maximum charging power in kW.
  • FR-013 The system shall allow the user to enter maximum discharging power in kW.
  • FR-014 The system shall allow the user to enter efficiency assumptions.
  • FR-015 The system shall allow the user to define minimum and maximum usable state of charge.
  • FR-016 The system shall allow the user to define initial state of charge.
  • FR-017 The system shall allow the user to choose whether charging from the grid is allowed.
  • FR-018 The system shall allow the user to reserve part of the battery capacity from use.
  • FR-019 The interface shall clearly separate basic inputs from any advanced inputs.
  • FR-020 The interface shall provide concise inline help for battery settings.
  • FR-021 The system shall allow the user to enter an indicative acquisition cost for the battery setup.
  • FR-022 After a valid dataset is loaded, the prototype shall rerun when relevant inputs change.

4.3 Simulation Logic

  • FR-030 The system shall simulate battery behavior for each 15-minute interval.
  • FR-031 The system shall calculate surplus and deficit energy per interval from the total connection result, not from individual phases.
  • FR-032 The system shall apply charging limits based on battery space, power limits, and efficiencies.
  • FR-033 The system shall apply discharging limits based on available battery energy, power limits, efficiencies, and state-of-charge boundaries.
  • FR-034 The system shall update the battery state of charge after every interval.
  • FR-035 The system shall calculate resulting grid import and grid export after battery action.
  • FR-036 The system shall retain the baseline case without battery for comparison.
  • FR-037 The system shall produce identical results for identical inputs and datasets.
  • FR-038 The MVP shall simulate one scenario at a time.

4.4 Financial Summary

  • FR-040 The system shall calculate estimated electricity cost without battery.
  • FR-041 The system shall calculate estimated electricity cost with battery.
  • FR-042 The system shall calculate avoided import costs.
  • FR-043 The system shall calculate reduced or deferred export/feed-in revenue.
  • FR-044 The system shall calculate net estimated savings from user-entered prices.
  • FR-045 The system shall clearly indicate which pricing basis is used.
  • FR-046 The MVP shall use manual pricing only.
  • FR-047 The system shall estimate an indicative payback period when acquisition cost and positive annualized savings are available.

4.5 Visualization and Output

  • FR-060 The system shall present outputs as interactive plots.
  • FR-061 The system shall support zooming, panning, and hover inspection.
  • FR-062 The system shall show at least:
    • battery state of charge over time
    • cumulative charged/discharged battery energy over time
    • grid import/export or net exchange over time
    • indicative savings versus battery capacity from 0 to 30 kWh
    • a baseline versus simulated comparison view
  • FR-063 The system shall show summary metrics for import, export, battery charged/discharged energy, savings, and self-consumption improvement.
  • FR-064 The system shall support aggregated daily or monthly summaries for at least one output view.
  • FR-065 The system shall allow export of key result summaries as CSV or JSON.
  • FR-066 The MVP shall limit the default chart set to 2 or 3 charts.

4.6 Privacy

  • FR-080 The system shall process the uploaded CSV locally in the browser for the base simulation.
  • FR-081 The system shall clearly indicate that uploaded usage data is not sent to the server in normal operation.
  • FR-082 The system shall not require user registration.

5. Non-Functional Requirements

  • NFR-001 The system shall remain deployable as a static website.
  • NFR-002 The system shall remain usable with annual 15-minute datasets in a modern desktop browser.
  • NFR-003 The interface shall be understandable for non-technical users.
  • NFR-004 The interface shall separate basic settings from advanced settings when advanced options exist.
  • NFR-005 The simulation shall validate inputs and fail gracefully on incomplete or inconsistent CSV data.
  • NFR-006 The tool shall clearly communicate assumptions and limitations.
  • NFR-007 The solution should be modular so parser, simulation, KPI, and visualization logic can evolve independently.
  • NFR-008 The page should remain desktop-first, with acceptable use on tablets.

6. Acceptance Criteria

The first release is acceptable when:

  1. A user can upload a HomeWizard-oriented CSV file.
  2. The tool can detect or map the required columns.
  3. The user can configure core battery size, power, efficiency, and state-of-charge limits.
  4. The simulation runs fully in the browser.
  5. The tool shows KPI cards and interactive charts.
  6. The tool calculates an indicative savings result using manual import/export pricing.
  7. The page clearly states that the result is indicative and not a real-world guarantee.
  8. The MVP remains limited to one scenario and one reliable CSV-oriented flow.

7. Post-MVP Direction

After the MVP is proven useful, later phases may add:

  • multiple scenario comparison
  • local presets
  • external dynamic price integration
  • richer aggregation modes
  • smarter strategy modes
Terug naar home