Skip to content

rencal.simulation.weather_data

rencal.simulation.weather_data defines metadata descriptors and the intermittent weather sampler used to create future hourly load-factor streams from historical artifacts.

WeatherData uses a JSON-parsed HistoricalMetadata descriptor plus a process-scope cache keyed by historical NPY basename to enable safe lazy loading. It supports two sampling modes via ignore_zeros:

  • ignore_zeros = False (wind): all loadfactor values participate in histogram building and resampling.
  • ignore_zeros = True (solar): zero-valued hours (nighttime) are preserved; histograms and inverse-CDF resampling operate only on non-zero values.
import datetime as dt
from rencal.simulation.weather_data import HistoricalMetadata, WeatherData
metadata = HistoricalMetadata(
npy_basename="historic_wind.npy",
path_resolver=lambda basename: f"/mnt/data/{basename}",
data_limit_left=dt.datetime(1980, 1, 1),
data_limit_right=dt.datetime(2026, 1, 1),
columns=["wind_lf"],
hours_per_block=24,
)
weather_data = WeatherData(metadata=metadata, desired_averages={0: [0.38]})
sample = weather_data.random_sample(dt.datetime(2027, 1, 1), dt.datetime(2027, 1, 31))
class HistoricalMetadata(
npy_basename: str,
path_resolver: Callable[[str], str],
data_limit_left: DateTimeLike,
data_limit_right: DateTimeLike,
columns: Sequence[str],
hours_per_block: int | None = None,
): HistoricalMetadata

Descriptor and path resolver for NPY-backed historical weather data.

  • npy_basename str

    Filename of the NPY artifact (also used as cache key).

  • path_resolver Callable[[str], str]

    Resolver from artifact basename to executor-local path.

  • data_limit_left DateTimeLike

    Earliest datetime represented in the artifact.

  • data_limit_right DateTimeLike

    Latest datetime represented in the artifact.

  • columns Sequence[str]

    Artifact column names/identifiers.

  • hours_per_block int | None

    Prefix histogram block size when available.

Returns HistoricalMetadata

class WeatherData(
metadata: HistoricalMetadata,
historical_start_date: DateTimeLike = datetime.datetime(1980, 1, 1),
historical_end_date: DateTimeLike = datetime.datetime(2026, 1, 1),
desired_averages: dict[int, list[float]] | None = None,
prefix_histograms: NDArray[np.uint32] | None = None,
historical_data: NDArray[np.floating] | None = None,
ignore_zeros: bool = False,
): WeatherData

Intermittent weather sampler supporting raw bucketed sampling and optional inverse-CDF resampling against desired averages.

  • metadata HistoricalMetadata

    Manifest-backed metadata descriptor.

  • historical_start_date DateTimeLike

    Earliest historical date considered for sampling.

  • historical_end_date DateTimeLike

    Latest historical date considered for sampling.

  • desired_averages dict[int, list[float]]

    Target average mapping for transformed columns.

  • prefix_histograms NDArray[np.uint32] | None

    Optional prefix-histogram artifact for fast histogram queries.

  • historical_data NDArray[np.floating] | None

    Optional historical data matrix/memmap.

  • ignore_zeros bool

    If True, histogram and resampling logic operate on non-zero values only.

Returns WeatherData

Raises

  • ValueError: If desired averages are supplied without historical data and prefix histograms.
from_manifest(manifest: dict[str, Any], path_resolver: Callable[[str], str]) -> HistoricalMetadata

Builds metadata from manifest payload and runtime path resolver.

  • manifest dict[str, Any]

  • path_resolver Callable[[str], str]

Returns HistoricalMetadata

get_or_mmap_historical() -> NDArray[np.floating]

Lazily loads historical artifact into process-scope cache as a read-only memmap.

The data is memory-mapped in read-only mode for efficient large-array access.

Returns NDArray[np.floating]

random_sample(
future_start_date,
future_end_date,
python_rng=random.Random(40),
numpy_rng=np.random.default_rng(22),
)

Generates future hourly samples by stitching historical draw periods and optionally appending transformed columns.

  • future_start_date DateTimeLike

  • future_end_date DateTimeLike

  • python_rng random.Random

  • numpy_rng numpy.random.Generator

Returns VersionedColumnsNDArray

Note Output shape is (n_hours_in_horizon, n_output_columns).

Draw period in days used for chunk stitching.

Type int