data.synthetic

data.synthetic

Deterministic synthetic load-series generator for demos and documentation.

The generator composes a strictly positive hourly electric-load series from four simple components: a linear trend, a daily sinusoid peaking at noon, a weekday uplift, and seeded Gaussian noise. It exists so that executable documentation never has to hand-roll simulation code: the same seeded call yields a byte-identical series on every run (code rule CR-2, determinism).

Functions

Name	Description
make_synthetic_load	Generate a deterministic synthetic hourly electric-load series.

make_synthetic_load

data.synthetic.make_synthetic_load(
    start='2025-01-01',
    end='2025-03-31 23:00',
    *,
    base_level=50.0,
    trend_total=2.0,
    daily_amplitude=4.0,
    weekday_uplift=1.5,
    noise_std=0.5,
    seed=2026,
    tz='UTC',
    name='load',
)

Generate a deterministic synthetic hourly electric-load series.

The series is the sum of a base level, a linear trend rising from zero to trend_total over the full range, a daily sinusoid of amplitude daily_amplitude peaking at 12:00, a constant weekday_uplift added on Monday through Friday, and Gaussian noise with standard deviation noise_std drawn from a generator seeded with seed. Repeated calls with identical arguments return byte-identical values.

Parameters

Name	Type	Description	Default
start	str	First timestamp of the hourly index (inclusive).	`'2025-01-01'`
end	str	Last timestamp of the hourly index (inclusive).	`'2025-03-31 23:00'`
base_level	float	Constant offset of the series.	`50.0`
trend_total	float	Total linear increase over the whole range.	`2.0`
daily_amplitude	float	Amplitude of the daily sinusoid (peak at 12:00).	`4.0`
weekday_uplift	float	Constant added on weekdays (Monday to Friday).	`1.5`
noise_std	float	Standard deviation of the Gaussian noise term.	`0.5`
seed	int	Seed for `numpy.random.default_rng`.	`2026`
tz	str	Time zone of the index.	`'UTC'`
name	str	Name of the returned series.	`'load'`

Returns

Name	Type	Description
	pd.Series	Hourly, time-zone-aware series of strictly positive load values.

Raises

Name	Type	Description
	ValueError	If the requested range is empty, or if the chosen parameters produce non-positive values (which would make percentage errors such as MAPE undefined).

Examples

Default demo series (deterministic, seed 2026):

from spotforecast2_safe.data import make_synthetic_load

y = make_synthetic_load()
print(len(y), y.index.tz, y.name)
print(y.head(3).round(3))

2160 UTC load
2025-01-01 00:00:00+00:00    47.103
2025-01-01 01:00:00+00:00    47.758
2025-01-01 02:00:00+00:00    47.090
Freq: h, Name: load, dtype: float64

Determinism: two calls with the same seed are byte-identical:

a = make_synthetic_load(seed=7)
b = make_synthetic_load(seed=7)
assert a.equals(b)
print("identical:", a.equals(b))

identical: True

Non-positive parameter combinations fail explicitly instead of producing MAPE-hostile values:

try:
    make_synthetic_load(base_level=0.0)
except ValueError as err:
    print(type(err).__name__)

ValueError