Agents

`polars_ts.energy_agents.agents`

Agents for hierarchical energy/demand forecasting.

:class:DemandForecastAgent — per-node seasonal demand forecasting.
:class:WeatherContextAgent — weather-driven demand adjustment (degree-day).
:class:RenewableAgent — net demand after intermittent renewable generation.
:class:DemandResponseAgent — peak-shaving / load-shifting optimisation.

`DemandForecastAgent`

Seasonal-naive demand forecaster for a single node.

Repeats the most recent seasonal cycle; falls back to the historical mean when history is shorter than one season.

Parameters

season Seasonal period in steps (e.g. 24 for hourly-with-daily-cycle).

`forecast(history, horizon)`

Return an horizon-step demand forecast for one node.

`WeatherContextAgent`

Adjust a base demand forecast for weather via a degree-day response.

Demand rises with both heating (cold) and cooling (hot) load relative to a comfort temperature.

Parameters

comfort_temp Temperature (deg C) of minimal weather-driven load. cooling_coef, heating_coef Additional demand per degree above / below comfort_temp.

`adjust(base_forecast, temperature)`

Return the weather-adjusted forecast for the given temperature path.

`RenewableAgent`

Compute net demand after subtracting intermittent renewable generation.

Parameters

curtail When True, net demand is floored at zero (excess generation is curtailed rather than exported).

`net_demand(demand, generation)`

Return demand - generation (floored at 0 when curtail).

`DemandResponseAgent`

Peak-shaving / load-shifting optimiser over a demand profile.

Energy above capacity is shed from peak periods and shifted into the lowest-demand troughs, conserving total energy while flattening peaks.

Parameters

capacity Maximum demand target; peaks above it are shifted to troughs.

`optimize(profile)`

Return (shifted_profile, energy_shifted).

Total energy is always preserved. When the profile can fit under capacity (total energy <= capacity * n), peaks are clipped to capacity and the shed energy is water-filled into the lowest periods without exceeding capacity. When it cannot (an inherently over-loaded window), the profile is flattened to its mean — the closest feasible approximation.