Visual Performance Simulator | Knowledge Base

Overview

An interactive simulation tool within the Intelligence Platform that runs a time-series HPWH performance simulation over a user-defined period (1-7 days) and displays results graphically. The user sets operating assumptions (air temperature, draw-off profile, control settings) and receives a visual output showing hot water temperature, heat pump capacity and COP over time, plus summary energy and cost metrics. This feature is the core technical differentiator of the platform. The simulation engine (Python, AS/NZS 4234-based) is already built. the developer’s job is to wrap it in a clean web interface: parameter inputs, API call to the simulation engine, and results visualisation.

User Stories

As a consultant, I want to run a simulation for a specific climate and load profile so I can show a client how the system will perform under their conditions. As a manufacturer, I want to compare performance under different control settings so I can understand the impact of setpoint and boost configuration on energy use. As a user, I want to see energy cost outputs and savings vs gas and resistive electric so I can present a financial case alongside the technical case. As a user, I want to adjust parameters and re-run quickly so I can explore scenarios without friction.

Simulation Inputs

The UI must expose the following parameters. Grouping and labelling on the form is the developer’s to propose, but all fields must be present. System parameters:

Tank volume (litres) - numeric input, typical range 150-400L Heat pump rated capacity (kW) - numeric Heat pump rated COP at test conditions - numeric Resistive boost element size (kW) - numeric Setpoint temperature (°C) - numeric, typical 55-65°C Thermostat cut-in temperature (°C) - numeric

Environmental

Ambient air temperature profile - options: constant value (°C input) or select a pre-defined climate profile (e.g. Christchurch winter, Sydney summer, Melbourne annual average). Climate profiles to be a simple lookup table that Alastair will populate. Simulation duration: 1 / 2 / 3 / 5 / 7 days (segmented control or dropdown)

Draw-off profile

Select from pre-defined load profiles (e.g. AS/NZS 4234 medium household, large household, commercial morning peak) - Alastair to provide profile definitions Or: custom draw-off - user specifies total daily volume (litres) and peak timing (morning / evening / both)

Control settings

HP-only mode vs HP + boost allowed
Boost lockout hours (e.g. no boost 7am-9am for demand response) - optional, can be left blank
Off-peak HP operation only: yes/no toggle

Tariff / cost inputs

Electricity tariff ($/kWh) - numeric, user-entered
Gas tariff ($/MJ) - numeric, for comparison baseline
Gas water heater efficiency assumption (%) - default 85%, editable
Resistive electric tariff ($/kWh) - may differ from HP tariff if on controlled load

Simulation Outputs

Time-series chart (primary visual): Three traces plotted on a shared time axis (x-axis = hours):

Tank temperature (°C) - left y-axis Heat pump capacity (kW) - right y-axis COP (dimensionless) - right y-axis, secondary trace

Chart requirements

Each trace toggleable on/off via legend click
Hover tooltip showing exact values at any time point
X-axis labelled with day markers when duration > 1 day
Zoom and pan enabled
Option to export chart as PNG

Summary metrics panel (alongside or below chart)

Total energy consumed (kWh) - HP compressor Total energy consumed (kWh) - boost element Average COP over simulation period Estimated energy cost ($) based on entered tariffs Estimated cost vs equivalent gas system ($) and % saving Estimated cost vs equivalent resistive electric system ($) and % saving Number of draw-off events where setpoint was not met (cold water delivery events) - if applicable

Scenario comparison (v1 scope, simple)

User can save a simulation run as “Scenario A” Run a second simulation with different parameters Side-by-side summary metrics comparison (not chart overlay in v1) Chart overlay of two scenarios: v2

API Integration with Simulation Engine

The Python simulation engine is a pre-built module. the developer is not to modify its internals. The integration task is:

Define a clean API contract with Alastair before building - what JSON goes in, what JSON comes out Wrap the simulation engine in a FastAPI endpoint Call that endpoint from the frontend on form submission Handle the response and render results

Performance expectation

Simulation should return results within 5 seconds for a 7-day run
If longer, implement a loading state with progress indicator - not a blank screen
Alastair to confirm expected compute time before UI is designed around it

Error handling

If simulation returns an error (e.g. invalid parameter combination), display a clear user-facing message - not a raw stack trace Frontend should validate obviously invalid inputs before submission (e.g. setpoint lower than cut-in, negative values)

UI / UX Direction

Parameter input panel on the left or top; results on the right or below “Run simulation” button is the primary action - clear and prominent Parameters remain visible after running so user can tweak and re-run without re-entering everything Results section should not appear until first simulation is run (no empty chart on load) Loading state while simulation runs - spinner or progress bar Mobile layout: inputs stacked above chart, chart scrollable - acceptable for v1 given likely desktop use the developer to produce wireframe for review before building

V2: Animated System Visualisation

Not in scope for v1 build. Specified here so the developer understands the architecture needs to accommodate it. The v2 visualisation will show an animated schematic of the HPWH system alongside or above the time-series chart. As the simulation plays back:

Tank interior is colour-coded showing thermal stratification (cool blue at bottom graduating to hot red at top, changing over time) Heat pump compressor component visually activates when HP is running Boost element visually activates when resistive heat is on Draw-off events shown as animated flow out of the tank Cold water inlet shown as animated flow in Playback controls: play, pause, scrub to any time point, speed control (1x, 5x, 10x)

Architecture implication for v1: The simulation output data must be stored in a format that supports time-step-by-time-step playback in v2. the developer should confirm the output data structure supports this before finalising the v1 API contract. Do not design the API in a way that only returns summary data.

Out of Scope (v1)

Animated system visualisation (v2 above) Chart overlay of multiple scenarios PDF export of full simulation report (separate feature) Saving simulations to a project or client record Multi-zone or solar pre-heat configurations CO2 emissions calculations (consider v2)

Data Model (indicative)

the developer to propose final schema. Minimum per simulation run:

simulation_id created_at user_id input_parameters (JSON blob of all inputs) output_timeseries (array of time-step objects: timestamp, tank_temp, hp_capacity, cop, boost_active, hp_active) output_summary (JSON: total energy, average COP, cost, savings vs baselines) scenario_label (nullable, set when user saves as named scenario)

Storing the full time-series output per run is required for v2 playback. Do not aggregate or discard step-level data.

Acceptance Criteria

The feature is done when:

Open Questions (resolve before build starts)

What is the actual compute time for a 7-day simulation run? This determines whether a simple spinner is sufficient or whether a more involved async job queue is needed. Alastair to provide: climate profile lookup table, load profile definitions, and a known test case with verified outputs for acceptance testing. Should simulation runs be saved automatically or only when the user explicitly saves a scenario? Are tariff inputs saved per user as defaults, or entered fresh each session? the developer to confirm: does the existing Python engine return per-time-step data, or only summary outputs? If summary only, discuss with Alastair before proceeding.