Energy Simulation

The EnergySimulator class provides a realistic simulation of utility consumption (power, gas, and hot water) for a typical household or building. It models a continuous, cyclical daily pattern with added randomization to mimic real-world usage fluctuations.

This class is designed to run as a background process. You create an instance with your desired annual consumption targets, start the simulation, and then you can query it at any time to get the live consumption rate or the total accumulated consumption.

How It Works: The Simulation Model

The simulator's logic is based on a few key principles to achieve realism:

• Annual Baseline: You provide the total annual consumption for power, gas, and water. The simulator uses this to calculate an average consumption rate per second.

• Daily Cycles (Sine Wave): Consumption is not constant. It follows a daily rhythm. The simulator uses a sine wave to model this, creating natural peaks and troughs in usage. For example, power usage peaks in the evening, while hot water usage peaks in the morning. This is controlled by a phaseShift.

• Randomization: To avoid a perfectly predictable pattern, a small amount of random "noise" is added to the calculation every second, making the live consumption values fluctuate slightly, just as they would in reality.

create

Creates a new energy simulator instance based on total annual consumption figures. The simulation starts automatically upon creation.

Parameters

• config: An object specifying the total annual consumption for each utility.

  • power: Total annual power consumption in kilowatt-hours (kWh).

  • gas: Total annual gas consumption in cubic meters (m³).

  • water: Total annual hot water consumption in cubic meters (m³).

Example

# config
power: 4500  // kWh per year
gas: 1200    // m³ per year
water: 90      // m³ per year

start

Starts the simulation loop. Once started, the internal state of the simulator will be updated every second. Note: The simulation starts automatically when the instance is created.

Output

Returns true when the simulation has been started.

stop

Stops and pauses the simulation loop. The internal consumption values will no longer be updated until start() is called again.

Output

Returns true when the simulation has been stopped.

getLiveValue

Gets the current, instantaneous consumption rate for a specific utility.

Parameters

• mediaType: The type of utility to query. Must be one of 'power', 'gas', or 'water'.

Example

# mediaType
power

Output

A number representing the live consumption rate. The units are:

• Power: kilowatts (kW)

• Gas: cubic meters per hour (m³/h)

• Water: cubic meters per hour (m³/h)

getAggregatedValue

Gets the total accumulated consumption for a specific utility since the simulator instance was started.

Parameters

• mediaType: The type of utility to query. Must be one of 'power', 'gas', or 'water'.

Example

# mediaType
gas

Output

A number representing the total accumulated consumption. The units are:

• Power: kilowatt-hours (kWh)

• Gas: cubic meters (m³)

• Water: cubic meters (m³)

Complete Usage Example

Here’s a step-by-step example showing how to use the EnergySimulator.

Step 1: Create a simulator instance

This will immediately start the simulation in the background.

# (Call create)
# config
power: 3000
gas: 800
water: 50

Step 2: Periodically read live data

You can use another function, like a timer, to periodically query the live values from the simulator.

// Inside another function that runs every 5 seconds...
// const livePower = simulator.getLiveValue('power')
// const liveGas = simulator.getLiveValue('gas')
// console.log(`Current Power Draw: ${livePower.toFixed(2)} kW`)

Step 3: Check total consumption after some time

After the simulation has been running for a while, you can check the total accumulated values.

// After an hour...
// const totalWaterUsed = simulator.getAggregatedValue('water')
// console.log(`Total hot water used so far: ${totalWaterUsed.toFixed(3)} m³`)

Step 4: Stop the simulation

When you no longer need the data, stop the simulation to free up resources.

# (Call stop)