ha-helios-optimizer

Helios Optimizer - Documentation

Helios Optimizer README - Doc - Why LP - Install - Release Notes

Table of Content

Intro

The HELIOS Optimizer Service is a Home Assistant PyScript application designed to calculate an Optimal Energy Plan for your house for typically 2 days.

To find the financially Optimal Energy Management Strategy for charging, discharging and solar production, it looks at dynamic electricity prices, solar forecasts, battery storage and expected household energy usage.

For each step (of an hour or 15 minutes) it will determine the best Battery Strategy (Sell/Discharge, Charge/Buy, Charge PV, Self-consumption (NOM), Zero import or Standby). It will take into account: energy import and export prices, maximum and minimum state of charge (SoC) of the battery, target SoC at the end of the optimization period, efficiency of battery charging and discharging, prediction of the solar production during the day(s) and the energy usage distribution over the day. It calculates for each step the costs for import, export and battery discharging and searchs very quickly for a solution with the minimum total cost for all steps while respecting all restrictions specified. A typical optimization period/horizon is from the current time today to the end of the day tomorrow. The Helios Optimizer will run again every 15 minutes so it will adapt automatically to changing circumstances (e.g. different battery SoC due to actual house usage and solar production).

Two graphs are provided that give an insight in the selected strategies per step, the battery state of charge and the power usage. Use the documentation links above each section to get more details (as described below) about the inputs and results.

An important observation is that Helios Optimizer calculates an Energy Plan but does not directly interface with your devices (Batteries and Solar Invertors)! It does provide an interface with Home Battery Control (HBC) and includes a Node-Red Helios Strategy Flow to connect the Helios Energy Plan with the HBC Battery Management. As a result all rules that you define in HBC (e.g. SoC Min/Max, Max Power, Peak shaving, Battery Balancing) will always be followed. The NR Helios Strategy will just read the Helios Strategy and will activate the related HBC Sub-Strategy. Please be aware that due to a restriction in HBC the charging and discharging in HBC is always at maximum power which may not always be equal to the optimal power level calculated by Helios Optimizer. Initially the Battery parameters for Maximum Power and SoC Minimum and Maximum will be copied from HBC but it you change these afterward you need to adapt the Helios Input parameters aswell. Battery SoC and Capacity (Maximum Energy) will be automatically taken from HBC settings.

The optimization is based on a Mathematical Model and uses Linear Programming to determine the Optimal Energy Plan. The Model uses SciPy, a Python Scientific Computing Library, to solve the linear programming calculations.

Overview

Helios Calculator

Why use a Linear Programming Model

See Why use Linear Programming? or Waarom Lineair Programmeren gebruiken?.

If you want to know more about the formulas used in the model and you can read dutch see: Optimale Energie Plan met LP

Description

Helios calculates an optimized energy plan for a specified horizon (typically 2 days) by finding the optimal power setpoints (for battery charge/discharge, grid import/export and solar production) for each step in the optimization period. The most important optimization rule defines that the Total Power Supply (Discharge, Import and Solar Production) and the Total Power Demand (Charge, Export and House Usage) must be equal in each step. The Battery State of Charge (SOC) will be kept between the Minimum and the Maximum SOC Percentages in each step and at the end of the optimization period above the Target SOC. In addition the model will keep the Charge/Discharging Power below the Battery Charge/Discharge Limit values and the Import/Export Power below the Maximum Grid Import/Export values. Solar Production will be equal to the Solar Forecast unless the Solar Inverter can be Modulated (Dimmed) or Turned On and Off.

The planning horizon is defined by the number of steps and the step duration in minutes. For example: 48 steps of 60 minutes or 192 steps of 15 minutes both optimize a 2-day period.

Grid Import and Export Prices, Solar Energy Forecast and House Energy Forecasts are needed as Input Arrays, containing values for every step in the period. HBC Price Data can be used as an alternative source for the Import and Export Price arrays. House Daily Usage and Distribution can be provided as an alternative source for the House Energy Forecast array.

Total Energy Cost is the sum of energy costs per step (calculated for Grid Import and Export Power). To compensate for battery depreciation cost a discharge (default 0.01 euro) and charge cost (default 0.00) is included in the Total Energy Cost. A cost for charging and/or discharging will also prevent the model from charging and discharging at the same time. The optimizer aims to MINIMIZE the Total Energy Cost over the entire horizon. Note: Negative costs may occur when exporting energy to the grid or during negative import prices.

Note: Without a battery or deferrable loads, optimization opportunities are limited since a strict power balance between consumption, import, and export must be met in each step.

The optimization horizon always starts today (and optionally extends to the following days). By default (with a start step of 0), the active start step is calculated based on the current time. Optionally, a specific start step can be defined (e.g., step 1 to start at 00:00) but this is mainly meant for (regression) testing. All input arrays must start at 00:00 today so the optimizer can align prices and forecasts correctly. Again for (regression) testing purposes a specific optimizer timestamp can be provided that runs the optimizer for a specific date and time (instead of for the current date and time).

The resulting Optimized Energy Plan determines the active strategy for the current step (e.g., NOM, Buy, Sell, Charge, Discharge, Disabled) and provides real-time setpoints to steer the Battery Charge/Discharge, the Solar Production and (in the future) the Deferrable Loads.

How It Works: The Energy Model

At the core of the optimizer is a physical and financial Energy Model. For each discrete time step in the optimization period (e.g., 15-minute or 1-hour intervals over 24–48 hours), the model solves a system of linear equations and constraints:

Execution and Architecture

The current version runs as a PyScript Service installed in your pyscript/ folder. Pure Python modules are in the pyscript/helios_python folder. For maximum performance, the calculation (including LinProg) runs asynchronously in a native Python thread, computing a full 48-hour plan in under 500ms without blocking Home Assistant. Testing is done on a Home Assistant Operating System (HAOS) Mini-PC (with NUC: Intel Celeron J4105 CPU @ 1.50Ghz, 8Gb, SSD: 512Gb). Feedback on the performance on other Home Assistant Environments is welcome.

Important Note on Hardware Control: HELIOS Optimizer acts purely as the Planning and Decision Engine. It does not communicate directly with your Inverters, Batteries, or Smart Meters. Instead, it exposes Target State and Power Values back to Home Assistant. Physical control of hardware—such as setting charge/discharge rates or managing safety limits—is handled by external automation frameworks like House Battery Control (HBC), Node-RED flows or other Home Assistant integrations. To maintain high performance the model aggregates all available battery storage into a single virtual battery with combined total capacity (kWh), maximum charge/discharge rates (kW), and average round-trip efficiency. Individual battery management—such as balancing states of charge (SoC) or routing power between multiple physical batteries (e.g., dual Marstek Venus units)—is offloaded to the execution layer (HBC or custom automations), which receives the total target power from Helios and distributes it across the physical units.

Future releases will migrate the PyScript architecture into a standalone Home Assistant Custom Component.

Helios Dashboard (Input and Output)

Helios Calculator At the top of the dashboard a short Overview of the Optimizer Results is displayed. Below that are the Input Parameters and more Detailed Results of the calculated Optimized Energy Plan (e.g. Status Blocks, Graph and Table). The Helios Optimizer Service will typically run every quarter of an hour and can be manually started with the green Start Helios button.

Input Parameters

Optimization Parameters

Advanced Parameters

Enable the ‘Helios Insight Mode’ to make these advanced parameters visible.

Battery Parameters

Why a horizon of 48 hours and a SoC Target

When running an Energy Optimization Model it is important to use a least a 48-hour horizon and a State of Charge (SoC) Target for several mathematical and operational reasons:

  1. Mathematical Boundary Conditions (Preventing Edge Effects): A linear programming (LP) solver optimizes decisions across a finite time window (48 hours). Because the solver’s world abruptly ends at hour 48, it suffers from a “finite horizon effect” at the edge of the window: Without a terminal SoC target, the optimizer treats the final hour of the period as the absolute end of the battery’s lifecycle. To maximize short-term financial gain within the window, the solver might aggressively empty the battery completely by hour 48, leaving you with a depleted battery for hour 49 (which falls outside the current optimization scope).

  2. Ensuring Operational Continuity: Energy optimization is a rolling, continuous process (re-calculated as new price data becomes available). A target SoC at the end of the horizon acts as a vital bridge to the next optimization cycle. It ensures that the battery transitions smoothly into the subsequent hours without unexpected depletion or erratic jumps in state.

  3. Balancing Present Savings Against Future Needs: A 48-hour horizon gives the algorithm the foresight to plan across today and tomorrow’s market peaks and valleys. However, without an end-SoC constraint or target: The model might consume all stored cheap energy today, ignoring that tomorrow morning might feature even higher grid prices or a delayed solar startup. etting a target allows you to dictate the desired energy reserve at the end of the window, ensuring the system leaves enough buffer for upcoming morning loads or reserves capacity for tomorrow midday’s solar surplus.

Summary: While the 48-hour horizon provides the necessary foresight to exploit price fluctuations, the SoC target acts as the anchor. It prevents the optimizer from draining the battery prematurely at the edge of the calculation window and guarantees a safe, predictable transition into the next optimization run.

Derived Parameters

The parameters in this section are retrieved from Helios and cannot be changed by the user. They are displayed only for validation purposes:

The following parameters should represent the (total) values for all HBC batteries and calculated based on HBC Marstek Entities using Helios Templates. They are used as input for the Helios Optimizer:

The following parameters are Helios Entities for HBC which are derived from the Helios Optimal Energy Plan and are used by the Helios Strategy in HBC:

Every time when the Helios Optimizer is run these HA Entities are updated. The Helios Strategy Flow in HBC will pickup these field and makes them available to the Executions section of the flow. The Home Battery Start flow will call this executor (in Call “Link in” node) and will further process the selected Sub-Strategy. The Net Power value is provided to HBC with a value calculated by Helios (for Charge/Buy and Discharge/Sell) but HBC can only charging and discharge at maximum power. For the other Sub-Strategies (e.g. Self-consumption, Zero import, Standby / peak shave and Charge PV) the Net Power value is not applicable/needed.

HBC Settings

The parameters in this section are configured in or calculated by HBC and cannot be changed here. Since they are already compensated for the required minimum and maximum state of charge they cannot be used by Helios. Instead the values calculated using Helios templates based on the Marstek entities (as described in the section above) are used by Helios.


The Max Charge/Discharge and Target SOC-s are copied to the Helios Battery Parameters at installation time.
Warning: When these fields are updated in HBC after installation of Helios they will NOT be copied again to the Helios Battery Parameters!

Output

Results Summary

Actuals for Current Step

Prices and Strategy Graph

Helios Optimizer: Prices and Strategy Graph The Prices and Strategy Graph displays the Import Prices (as columns) and the related Export and Market Prices (as 2 lines). These prices are retrieved from the HBC Price Data (which contains only Import Prices). Export and Market Prices are calculated from the Import Prices using the Energy Tax (Energie Belasting), VAT (BTW) and the Provider Import and Export Markup (Opslag).


TODO: These values will be configurable in the near future, specify a more detailed formula here.

The colors of the Import Price columns represent the selected HBC Sub-Strategy:

Optimal Energy Plan Graph

Helios Optimizer: Optimal Energy Plan Graph The Optimal Energy Plan Graph displays the most important Output of the Helios Optimizer combined into one Graph.
It represents the optimizer results for each step of a two day horizon:

Positive Power values (above the X-as) indicate that power is made available to the House (Battery Discharged, Solar Production or Imported) and Negative Power values (below the X-as) indicate that power is used (Used in the House, Battery Charged or Exported).
The left Y-as is for the Power values (kW) and the right Y-as is for the SOC Percentages (0-100%).
Warning: Occasionally the browser page content with the Helios Energy Plan Graph may need to be manually refreshed (Ctrl-F5) before the graph is updated or is even displayed or is using the full window width. Full Window width problems may also be resolved by resizing the Browser Window or going into Edit of the Dashboard and close without changes. Tips how to fix this issue are welcome.

Optimal Energy Plan Table

The Results Table lists all (power, energy, soc and cost) variables as calculated (or used) by the Optimization Model for every step of the optimization period (horizon):

Insight Details

Enable Helios Insights Mode to make the following outputs visible.

Optimization State

TODO:

Solar and Battery Information

TODO:

Optimization Run

TODO:

Energy Plan Totals

TODO:

Price Calculations

TODO:

Array Operations

Input Arrays with Forecasts for House Usage and Solar Production and Input Price Arrays can have a different horizon than the optimization period and can have a different step size (15 or 60 minutes) than the the optimization step size.
Helios will automatically extend the array with extra days and will repeat the last day one or more times. For example a price array with prices for today (but without prices for tomorrow) will be automatically adapted to an array with prices for 2 days for an optimization horizon of 48 hours. A price array with prices for today and tomorrow can also be used for an optimization period of 24 hours (the prices for tomorrow will be ignored).
Helios will automatically adapt the step size by resampling the values in the array. For example a price array with 15-min prices will be automatically adapted to hour prices for an optimization step size of 60-min (or the otherway around).
For validation purpose (to detect invalid or corrupted arrays) the input array size must contain one or more full days For example an array of 23 or 25 hour values will not be accepted.
An Empty array for prices or solar forecasts (with solar enabled) will also lead to error messages.

Solar Forecast Configuration

There are currently two options to configure the Solar Forecast information. If you already have Forecast.Solar Integration setup then you can use the data available in the Integration. There is not an entity available with the Solar Production Forecast per hour but the data can be retrieved by Helios using a service of the Forecast.Solar Integration.
The alternative (more complex) option is to configure your own REST api in the optional helios_optimizer_forecast.yaml.
Adapt the yaml to your own setup (location, declination (angle), azimuth - 180 (direction) and peak-power) and copy the yaml to the packages folder.
See the Forecast Solar Documentation for details.
A template is included in the yaml file that converts the raw data from the api into the hours data that Helios requires.

The Helios Optimizer requires a Solar Forecast Array that matches the step size and total number of steps specified in the input parameters. If the forecast is only provided for today while you are optimizing a two-day horizon, the array will be automatically extended to two days by repeating the final day’s data. Similarly, if the step size is incorrect (e.g., 60 minutes instead of 15 minutes), the array will be automatically resampled to match the step size.

Fuse Box Limits

The maximum power capacity of your fuse box depends on your connection capacity (the number of phases and the amperage) provided by your grid operator (such as Enexis, Liander, or Stedin). You can roughly calculate the maximum capacity (kW or kVA) using the formula: Amperage × 230 Volts × number of phases. The default value in Helios is 11.0 kW but you can change both the import and the output limit in the Optimization Parameters.
Common connections and their power capacity:

Installation

Helios Optimizer - Installation

Release Notes

Helios Optimizer - Release Notes

License

Helios Optimizer - License

This site is open source. Improve this page.