Orchestrator

polars_ts.energy_agents.orchestrator

EnergyGridOrchestrator: hierarchical demand forecasting + reconciliation.

EnergyForecastResult dataclass

Output of an :class:EnergyGridOrchestrator run.

Attributes

reconciled Long-format DataFrame of coherent per-node forecasts (unique_id, ds, y_hat). base_forecasts Per-node incoherent base forecasts before reconciliation. region_net_demand Region-level demand after subtracting renewable generation. demand_response Peak-shaving outcome: {"shifted_profile", "energy_shifted"} or None when no capacity limit was supplied. history Diagnostic records per node.

EnergyGridOrchestrator

Hierarchical multi-agent energy/demand forecasting.

Each node (household, grid, region) is forecast independently, optionally adjusted for weather; the incoherent forecasts are then reconciled to sum coherently across the hierarchy. Renewable generation and demand-response optimisation are applied at the region level.

Parameters

season Seasonal period for the demand forecasters. reconcile_method Reconciliation method passed to :func:polars_ts.reconciliation.reconcile.

run(household_histories, hierarchy, horizon, weather=None, generation=None, capacity=None)

Forecast, reconcile, and optimise demand across the grid hierarchy.

Parameters

household_histories Mapping household_id -> 1D demand history. Must cover every household in hierarchy. hierarchy The region -> grid -> household topology. horizon Forecast horizon in steps. weather Optional region-wide temperature path of length horizon used to adjust every node's forecast. generation Optional region-level renewable generation path of length horizon subtracted from the reconciled region demand. capacity Optional region demand cap enabling peak-shaving demand response.

Returns

EnergyForecastResult

_node_series(reconciled, node, horizon)

Extract a node's reconciled forecast ordered by ds.