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.
Example Usage
Section titled “Example Usage”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))Constructor
Section titled “Constructor”HistoricalMetadata
Section titled “HistoricalMetadata”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,): HistoricalMetadataDescriptor and path resolver for NPY-backed historical weather data.
Parameters
Section titled “Parameters”-
Filename of the NPY artifact (also used as cache key).npy_basenamestr -
Resolver from artifact basename to executor-local path.path_resolverCallable[[str], str] -
Earliest datetime represented in the artifact.data_limit_leftDateTimeLike -
Latest datetime represented in the artifact.data_limit_rightDateTimeLike -
Artifact column names/identifiers.columnsSequence[str] -
Prefix histogram block size when available.hours_per_blockint|None
Returns HistoricalMetadata
WeatherData
Section titled “WeatherData”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,): WeatherDataIntermittent weather sampler supporting raw bucketed sampling and optional inverse-CDF resampling against desired averages.
Parameters
Section titled “Parameters”-
Manifest-backed metadata descriptor.metadataHistoricalMetadata -
Earliest historical date considered for sampling.historical_start_dateDateTimeLike -
Latest historical date considered for sampling.historical_end_dateDateTimeLike -
Target average mapping for transformed columns.desired_averagesdict[int, list[float]] -
Optional prefix-histogram artifact for fast histogram queries.prefix_histogramsNDArray[np.uint32]|None -
Optional historical data matrix/memmap.historical_dataNDArray[np.floating]|None -
If True, histogram and resampling logic operate on non-zero values only.ignore_zerosbool
Returns WeatherData
Raises
ValueError: If desired averages are supplied without historical data and prefix histograms.
Methods
Section titled “Methods”HistoricalMetadata.from_manifest
Section titled “HistoricalMetadata.from_manifest”from_manifest(manifest: dict[str, Any], path_resolver: Callable[[str], str]) -> HistoricalMetadataBuilds metadata from manifest payload and runtime path resolver.
Parameters
Section titled “Parameters”-
manifestdict[str, Any] -
path_resolverCallable[[str], str]
Returns HistoricalMetadata
WeatherData.get_or_mmap_historical
Section titled “WeatherData.get_or_mmap_historical”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]
WeatherData.random_sample
Section titled “WeatherData.random_sample”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.
Parameters
Section titled “Parameters”-
future_start_dateDateTimeLike -
future_end_dateDateTimeLike -
python_rngrandom.Random -
numpy_rngnumpy.random.Generator
Returns VersionedColumnsNDArray
Note Output shape is (n_hours_in_horizon, n_output_columns).
Properties
Section titled “Properties”WeatherData.draw_period
Section titled “WeatherData.draw_period”Draw period in days used for chunk stitching.
Type int

