Network Optimization Overview¶

HAEO uses linear programming to optimize energy flows across your network. This page explains the high-level architecture and mathematical foundations.

Layered Architecture¶

HAEO separates user configuration from mathematical modeling through a layered architecture:

Device Layer (user-configured): Elements like Battery, Grid, Solar, and Load that users configure through Home Assistant. Each Device Layer element may create multiple Model Layer elements and multiple devices with sensors. See Device Layer.

Model Layer (optimization): The mathematical building blocks that form the linear programming problem. These elements define decision variables, constraints, and cost terms. See Model Layer.

This separation enables composition flexibility—a single Device Layer element can create multiple Model Layer elements to achieve complex behavior (e.g., Battery creates both a battery model for SOC tracking and a connection model for power flow).

Linear Programming Overview¶

Linear programming finds optimal values for decision variables that minimize (or maximize) an objective function subject to linear constraints.

Standard LP form:

Where:

• \(x\): Decision variables (what the optimizer chooses)
• \(c\): Objective coefficients (costs/prices)
• \(A\), \(b\): Inequality constraint matrices
• \(A_{\text{eq}}\), \(b_{\text{eq}}\): Equality constraint matrices
• \(l\), \(u\): Variable bounds

Linearity requirement: All relationships must be linear. No quadratic terms (\(x^2\)), products (\(xy\)), or nonlinear functions (\(\sin(x)\), etc.).

Why linear programming?¶

LP fits home energy systems because power balances, costs, and most device constraints are linear. It delivers a global optimum when a feasible solution exists and scales well as you extend the horizon or add elements.

Mathematical Model Structure¶

HAEO formulates energy system optimization as a network where elements contribute to a unified linear program. Each element defines its own decision variables, constraints, and cost terms. The network aggregates these contributions into a single optimization problem.

Model Aggregation¶

The complete optimization problem is built by combining contributions from all elements:

Decision variables: Each element introduces variables representing its behavior (power flows, energy states, etc.). The complete variable set is the union of all element variables.

Constraints: Each element contributes constraints governing its operation. The complete constraint set is the union of all element constraints plus network-wide power balance constraints.

Objective function: Each element contributes cost terms. The objective minimizes the sum of all element costs.

Solution Process¶

Optimization uses lexicographic multiobjective solving with calibrated blending:

Phase 1: Minimize primary objective

The network minimizes total cost (the primary objective).

Phase 2: Minimize secondary objective

The primary objective is constrained to equal its optimal value, and the solver minimizes the secondary time-preference objective. This breaks ties among cost-equivalent solutions by preferring earlier energy transfers.

Calibration (default mode)

After the first lexicographic solve, a binary search finds the largest blend weight that preserves primary cost optimality. A larger weight gives the secondary objective more influence, producing better tie-breaking in degenerate regions. Subsequent optimizations use this blended objective (primary + weight * secondary) in a single solve, which warm-starts efficiently.

A full three-phase lexicographic mode is also available (mode="lex") that adds a Phase 3 re-minimization of the primary with the secondary constrained. This restores dual values (shadow prices) that reflect pure primary-cost sensitivities, at the cost of an additional solve per optimization.

Solution Outcomes¶

• Optimal solution: Satisfies all constraints with minimum total cost and deterministic tie-breaking
• Infeasible: No solution exists that satisfies all constraints simultaneously

Network Structure¶

HAEO models energy systems as directed graphs:

• Elements: Vertices that produce, consume, or store energy
• Connections: Directed edges that transfer power between elements
• Nodes: Balance points where power flows must sum to zero

graph LR
    Grid((Grid)) <-->|Connection| Node((Node))
    Solar((Solar)) -->|Connection| Node
    Battery((Battery)) <-->|Connection| Node
    Node -->|Connection| Load((Load))

    class Node emphasis

Element Registration¶

When a connection is added to the network, it registers itself with its source and target elements. This allows elements to track their incoming and outgoing connections for constraint generation.

Network Validation¶

Before optimization, the network validates its structure:

• All connection endpoints reference valid elements
• No connection has another connection as an endpoint
• All element dependencies are satisfied

This validation ensures the network forms a valid directed graph before attempting optimization.

Time Discretization¶

The optimization horizon is divided into discrete intervals with variable durations:

• Tiers: Groups of intervals with the same duration (up to 4 tiers)
• Intervals: Individual time steps within each tier
• Duration: Each tier specifies a duration in minutes for its intervals
• Time steps: \(T = \sum_{\text{tier}} \text{count}_{\text{tier}}\)

For example, the default configuration creates:

• Tier 1: 5 intervals × 1 minute = 5 minutes (high resolution near-term)
• Tier 2: 5 intervals × 5 minutes = 25 minutes
• Tier 3: 46 intervals × 30 minutes ≈ 23 hours
• Tier 4: 48 intervals × 60 minutes = 48 hours (low resolution long-term)

This yields \(T = 104\) intervals spanning approximately 72 hours. Each decision variable exists for every time step, but interval durations vary.

Power and Energy Discretization¶

HAEO distinguishes between two types of measurements across the optimization horizon:

Power variables represent average power over each period. These are interval measurements—the "fences" in the fence post analogy. With \(T\) periods, power variables have \(T\) values indexed as \(t \in \{0, 1, \ldots, T-1\}\).

Energy variables represent instantaneous stored energy at time boundaries. These are point measurements—the "posts" in the fence post analogy. With \(T\) periods, energy variables have \(T+1\) values indexed as \(t \in \{0, 1, \ldots, T\}\).

gantt
    title Power and Energy Variable Timing
    dateFormat X
    axisFormat %s
    section Variables
        E0 :milestone, 0, 0s
        P0 :active, 1s
        E1 :milestone,
        P1 :active, 1s
        E2 :milestone,
        P2 :active, 1s
        E3 :milestone,

Energy values (milestones) are measured at 4 time boundaries: \(E(0), E(1), E(2), E(3)\)

Power values (bars) are measured over 3 time intervals: \(P(0), P(1), P(2)\)

This distinction matters for cost calculations. Prices apply to average power over intervals, which is then converted to energy:

Where \(\Delta t_t\) is the duration of interval \(t\) in hours (varies by tier).

Decision Variables and Constraints¶

The complete optimization problem includes decision variables and constraints from all network elements.

Variable Structure¶

Power variables represent average power over each time period. These are interval measurements spanning the optimization horizon with \(T\) values.

Energy variables represent instantaneous stored energy at time boundaries. These are point measurements with \(T+1\) values.

Each element contributes its own variables based on its physical role (power flows, energy storage, curtailment decisions).

Constraint Structure¶

Element constraints govern individual element behavior (capacity limits, efficiency losses, operating bounds).

Network constraints ensure power balance at connection points (Kirchhoff's law).

The complete constraint set ensures physically feasible operation while allowing optimization across the network.

Objective Function¶

The optimization uses a lexicographic two-objective formulation.

Primary objective: minimize cost¶

Where:

• \(T\): Number of time periods
• \(C_{\text{element}}(t)\): Cost contribution from each element at time \(t\)

Each element defines its own cost terms based on its role:

• Elements that interact with external systems (grids) contribute costs based on prices
• Elements with artificial costs (batteries, curtailment) guide optimizer behavior
• Elements without direct costs (loads, nodes) affect costs indirectly through energy balance

See individual element pages for specific cost formulations.

Secondary objective: time preference¶

When multiple solutions achieve the same minimum cost, the optimizer prefers earlier energy transfers. Each connection contributes a time-preference term to the secondary objective:

Where \(p\) is the connection priority derived from endpoint element types, \(w_{p,t} = p \cdot T + (t + 1)\) assigns monotonically increasing weights by priority group and time step, and \(E_c(t)\) is the energy transferred through connection \(c\) at time \(t\). Connections with different priorities receive non-overlapping weight ranges. Connections with the same priority share the same per-period weight sequence.

The secondary objective does not affect the optimal cost. It only selects among cost-equivalent solutions for deterministic, physically intuitive schedules.

Solver¶

HAEO uses HiGHS as its LP solver:

• Open source: MIT licensed
• Fast: State-of-the-art performance
• Robust: Handles large-scale problems reliably
• Alpine Linux compatible: Provides Python wheels that run on Home Assistant's Alpine Linux base
• Actively maintained: Continuous improvements

HiGHS is the only supported solver and cannot be changed via configuration.

Units¶

HAEO uses consistent units for numerical stability:

• Power: kilowatts (kW)
• Energy: kilowatt-hours (kWh)
• Time: hours (h)
• Cost: dollars ($)

This keeps values in similar numerical ranges, improving solver performance. See units documentation for details.

Next steps¶