Power Forecast

Jua's Power Forecast is an end-to-end model trained directly on actual generation data, delivering renewable energy generation forecasts in MW for power trading and grid management.

Power forecasts can be queried directly through the Jua Python SDK using the client.power_forecast interface. Forecasts are returned as an xarray.Dataset with dimensions (zone_key, psr_type, time) and a value data variable in MW.

Power Forecast support requires jua >= 0.22.0. See Installation to upgrade.

Example

As an introduction to power forecasts in the SDK, see this simple example. For more examples, please see our GitHub repository.

import matplotlib.pyplot as plt
from jua import JuaClient

client = JuaClient()
pf = client.power_forecast

# Fetch the latest German Solar forecast, up to 48h ahead (2880 minutes)
ds = pf.get_data(
    zone_keys=["DE"],
    psr_types=["Solar"],
    init_time="latest",
    max_prediction_timedelta=2880,
    debias=True,
)

# The result is an xarray.Dataset; select the single zone/PSR slice and plot it
series = ds["value"].sel(zone_key="DE", psr_type="Solar")

fig, ax = plt.subplots(figsize=(15, 5))
series.plot(ax=ax, x="time")
ax.set_title("Germany — Solar Power Forecast (latest run)")
ax.set_ylabel("Power [MW]")
plt.show()

Documentation

The PowerForecast interface is available as client.power_forecast. It exposes metadata helpers (get_zones, get_psr_types, get_init_times), the main get_data query method, and a get_day_ahead_timeseries helper for stitching a continuous day-ahead series across runs.

Zones and PSR Types

Power Forecast covers a set of market zones, each serving one or more PSR types (Production Source types, e.g. Solar, Wind Onshore). The available zones and PSR types differ per zone, so query them before building requests.

List zones and PSR types

from jua import JuaClient

client = JuaClient()
pf = client.power_forecast

# All available zones
zones = pf.get_zones()
print("Zones:", zones)

# All PSR types across all zones
print("All PSR types:", pf.get_psr_types())

# PSR types served for a specific zone
print("DE PSR types:", pf.get_psr_types(zone_key="DE"))

Output

Zones: ['BE', 'DE', 'FR', 'GB', 'NL']
All PSR types: ['Load', 'Solar', 'Wind', 'Wind Embedded', 'Wind Offshore', 'Wind Onshore', 'Wind Transmission']
DE PSR types: ['Load', 'Solar', 'Wind Offshore', 'Wind Onshore']

Requesting a PSR type that a zone does not serve raises a ValueError listing the available types. For predicted demand in zones without a fitted Load model, use Market Aggregates with weighting=population and unit=mw, which returns a load_mw column.

Init Times

get_init_times lists the available forecast runs (init times), newest first. Use count mode for the most recent runs, or time-window mode to retrieve every run in a date range. Pass version and regime to list runs for a specific serving selection (same semantics as get_data).

from datetime import datetime, timezone

# Count mode: the 5 most recent German runs
for it in pf.get_init_times(zone_key="DE", limit=5):
    print(it.init_time, "max horizon (min):", it.max_prediction_timedelta)

# Time-window mode: every run in January 2025 (can exceed 1000)
init_times = pf.get_init_times(
    zone_key="DE",
    start_time=datetime(2025, 1, 1, tzinfo=timezone.utc),
    end_time=datetime(2025, 2, 1, tzinfo=timezone.utc),
)
print(f"{len(init_times)} runs in January 2025")

Each entry is an InitTimeInfo with an init_time (timezone-aware datetime) and max_prediction_timedelta (forecast horizon in minutes).

Querying Data

get_data supports two mutually exclusive query modes.

Horizon mode is init-time-centric. Specify init_time as a datetime, an integer offset (0 = latest), or a relative token ("latest", "latest-N"), and optionally cap the horizon with max_prediction_timedelta (in minutes). Relative tokens resolve to the most recent run where all requested zone/PSR-type combinations have data.

# Latest run, 48h horizon, German Solar
ds = pf.get_data(
    zone_keys=["DE"],
    psr_types=["Solar"],
    init_time="latest",
    max_prediction_timedelta=2880,
    debias=True,
)

# The two most recent runs for several zones, all PSR types, localized times
ds = pf.get_data(
    zone_keys=["DE", "FR"],
    init_time=[0, 1],
    max_prediction_timedelta=1440,
    time_zone="Europe/Berlin",
    debias=True,
)

Time range mode is valid-time-centric. Specify start_time and/or end_time to filter by the forecast's valid time instead of by run.

from datetime import datetime

ds = pf.get_data(
    zone_keys=["DE"],
    psr_types=["Solar", "Wind Onshore"],
    start_time=datetime(2025, 12, 1),
    end_time=datetime(2025, 12, 3),
    debias=True,
)

The two modes cannot be combined; passing both horizon and time-range parameters raises a ValueError.

Examples pass debias=True to apply the same walk-forward MW bias correction as the HTTP API. Wind uses eight weeks of history and solar and load use four weeks to estimate the bias for each init time and lead; that bias is subtracted from the current forecast, then the window moves ahead. The API default is still raw: omit debias or pass debias=False only when you need the unadjusted forecast. debias=True cannot be combined with regime="uncurtailed" — uncurtailed queries stay raw.

Model version and regime

version and regime are independent. Omit version (or pass "stable") to follow Jua's stable model; "latest" follows the newest model; a version hash from get_versions() keeps using that exact model after Jua updates. regime selects which product "stable" and "latest" refer to: "curtailed" (actual production, default) or "uncurtailed" (potential). A version hash ignores regime.

# Uncurtailed German Solar (potential). Debias is not available.
ds = pf.get_data(
    zone_keys=["DE"],
    psr_types=["Solar"],
    init_time="latest",
    max_prediction_timedelta=2880,
    regime="uncurtailed",
)

# Freeze today's uncurtailed stable run
versions = pf.get_versions(zone_key="DE", psr_type="Solar")
uncurtailed = next(v for v in versions if v.is_stable_uncurtailed)
ds = pf.get_data(
    zone_keys=["DE"],
    psr_types=["Solar"],
    init_time="latest",
    version=uncurtailed.model_version,
)

Uncurtailed currently covers Germany Solar / Wind Onshore / Wind Offshore and Great Britain Wind Transmission. Other zone and generation-type combinations raise rather than falling back to the curtailed product.

Attributes:
    zone_keys: list[str] | None
        Zone codes to query (e.g. ["DE", "FR"]).
    psr_types: list[str] | None
        PSR types to query (e.g. ["Solar", "Wind Onshore"]).
        If None, returns all available types.
    init_time: str | int | datetime | list | None
        Horizon-mode run selection: "latest", "latest-N", a datetime,
        an integer offset (0 = latest), or a list of these.
    max_prediction_timedelta: int | None
        Horizon-mode maximum forecast horizon in minutes.
    start_time: datetime | None
        Time-range-mode lower bound on valid time (inclusive).
    end_time: datetime | None
        Time-range-mode upper bound on valid time (exclusive).
    time_zone: str | None
        IANA time zone name for time formatting (e.g. "Europe/Berlin").
    version: str | None
        `"stable"`, `"latest"`, or a version hash.
        `"stable"` and `"latest"` are looked up for the
        chosen regime.
    regime: "curtailed" | "uncurtailed" | None
        Product `"stable"` / `"latest"` refer to. Default
        (omitted) is curtailed / actual production.
        Uncurtailed is potential and only available for
        some zones and generation types. A version hash
        ignores regime.
    version_pins: list[dict] | None
        Per-(zone_key, psr_type) overrides. Each mapping needs
        zone_key, psr_type, and version; optional regime inherits
        the request regime when omitted.
    debias: bool
        Apply walk-forward additive MW debiasing. Wind uses eight weeks
        and solar and load use four weeks to estimate the bias, then the
        window moves ahead. Defaults to False. Not available with
        regime="uncurtailed". See the Power Forecast product page.

Returns:
    xarray.Dataset with dimensions (zone_key, psr_type, time) and the
    data variable `value` in MW.

Day-Ahead Time Series

get_day_ahead_timeseries stitches a continuous day-ahead series from the runs whose local init-time hour matches init_hour. For each matching run it takes the day-ahead window and concatenates the results onto a single time axis — useful for plotting or backtesting a consistent day-ahead product over a long history.

from datetime import datetime, timedelta, timezone

# Last year of German Solar day-ahead generation from the 09:00 UTC run
end = datetime.now(timezone.utc)
start = end - timedelta(days=365)

ds = pf.get_day_ahead_timeseries(
    zone_keys=["DE"],
    psr_types=["Solar"],
    init_hour=9,
    time_zone="UTC",
    start_date=start,
    end_date=end,
    debias=True,
)

# Plot the stitched series
df = ds.to_dataframe().reset_index().dropna(subset=["value"])
df.plot(x="time", y="value", figsize=(16, 6), title="DE Solar — day-ahead (09:00 UTC run)")

When start_date/end_date are given (date-range mode), one init run per day is constructed over the range, bypassing the init-times listing limit so arbitrarily long histories can be stitched. When no dates are given (latest mode), the most recent matching runs are discovered automatically (bounded by max_init_times). version, regime, and version_pins are forwarded to every fetched run. The optional debias flag defaults to False and uses the same walk-forward windows as get_data; it cannot be combined with regime="uncurtailed".