rencal 0.1.1__tar.gz

rencal-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Low Carbon Contracts Company Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rencal-0.1.1/PKG-INFO

@@ -0,0 +1,193 @@
+Metadata-Version: 2.4
+Name: rencal
+Version: 0.1.1
+Summary: Weather-to-power calibration and Monte Carlo load factor simulation for renewable energy applications
+Keywords: weather,forecasting,renewable energy,wind power,solar power,era5,monte carlo,calibration,climate
+Author: Low Carbon Contracts Company Ltd
+Author-email: Low Carbon Contracts Company Ltd <analytics@lowcarboncontracts.uk>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Classifier: Topic :: Utilities
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: pandas>=1.3.0
+Requires-Dist: scipy>=1.7.0
+Requires-Dist: matplotlib>=3.4.0
+Requires-Dist: seaborn>=0.12.0
+Requires-Dist: scikit-learn>=1.0.0
+Requires-Dist: netcdf4>=1.5.0
+Requires-Dist: xarray>=0.19.0
+Requires-Dist: pytz>=2021.1
+Requires-Dist: requests>=2.25.0
+Requires-Dist: polars>=1.8.2
+Requires-Dist: pydantic>=2.10.6
+Requires-Dist: pyodbc>=4.0.0
+Requires-Dist: cdsapi>=0.6.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: openpyxl>=3.1.0
+Requires-Dist: zarr>=2.16.1
+Requires-Dist: tqdm>=4.62.0
+Requires-Dist: pyarrow>=22.0.0
+Maintainer: Low Carbon Contracts Company Ltd
+Maintainer-email: Low Carbon Contracts Company Ltd <analytics@lowcarboncontracts.uk>
+Requires-Python: >=3.12, <3.13
+Project-URL: Homepage, https://github.com/LCCC-Tech/rencal
+Project-URL: Repository, https://github.com/LCCC-Tech/rencal.git
+Project-URL: Bug Tracker, https://github.com/LCCC-Tech/rencal/issues
+Project-URL: Changelog, https://github.com/LCCC-Tech/rencal/blob/main/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+# RenCal
+
+RenCal (Renewable Calibration) is a Python library for calibrating renewable
+energy power curves and generating probabilistic load-factor time series for
+wind and solar plants.
+
+It supports Monte Carlo-based forecasting using weather, generation, and plant
+characteristic data. RenCal is intended for energy analysts, researchers, and
+developers working on renewable-energy modelling.
+
+## Status
+
+RenCal is an experimental pre-1.0 public package. The API and modelling
+approach may change as the project develops. It is not currently a guarantee of
+production suitability or a substitute for independent validation.
+
+## Installation
+
+The first public release will be installed from PyPI with:
+
+```bash
+python -m pip install rencal
+```
+
+Until that release is published, clone the repository and follow the
+[development setup](CONTRIBUTING.md#development-setup) instead.
+
+## Quick start
+
+The primary workflow uses data supplied by the user. RenCal does not distribute
+operational ERA5, generation, or plant datasets.
+
+```python
+from pathlib import Path
+
+from rencal.core.data_loader import LocalDataLoader
+
+loader = LocalDataLoader(data_path=Path("data"))
+plants = loader.load_plant_data()
+generation = loader.load_generation_data()
+
+print(f"Loaded {len(plants.data)} plants")
+print(f"Loaded {len(generation.data)} generation records")
+```
+
+For the full wind-calibration workflow, provide the expected input structure:
+
+```text
+data/
+├── plant/plant_data.csv
+├── generation/generation_data.parquet
+└── era5/*.nc
+```
+
+The ERA5 loader expects suitable NetCDF weather data. Users are responsible for
+obtaining data, checking its provenance and licence, and preparing it for the
+documented schema.
+
+### Calibrate wind power curves
+
+With the plant, generation, and ERA5 inputs in place, run the wind calibration
+workflow and write its outputs to a separate directory:
+
+```python
+from pathlib import Path
+
+from rencal.calibration.wind.wind_calibrator import WindCalibrator
+
+calibrator = WindCalibrator(
+    data_path="data",
+    output_path=Path("outputs/wind-calibration"),
+    visual_output=True,
+    stream_npy_output=True,
+)
+calibrator.calibrate()
+```
+
+The workflow writes the calibration summary, Weibull parameters, extracted wind
+speeds, calibrated wind streams, and optional power-curve plots to the output
+directory. With `stream_npy_output=True`, the generated `Wind Streams.npy` can
+also be used by the weather sampler after its manifest and optional histogram
+artefacts have been prepared.
+
+### Sample calibrated wind streams
+
+`WeatherData` samples future hourly paths from calibrated historical streams
+while preserving the configured time-bucket structure. The local loader expects
+the calibrated NPY file and its manifest under `data/calibrated/`.
+
+```python
+import datetime
+import random
+
+import numpy as np
+
+from rencal.core.data_loader import LocalDataLoader
+from rencal.simulation.weather_data import HistoricalMetadata, WeatherData
+
+loader = LocalDataLoader(data_path="data")
+manifest = loader.check_historical_weather()
+metadata = HistoricalMetadata.from_manifest(
+    manifest,
+    loader.path_resolver_weather_data,
+)
+
+wind_sampler = WeatherData(
+    metadata=metadata,
+    prefix_histograms=loader.get_prefix_histograms(),
+    historical_data=loader.get_historical_weather(),
+)
+
+sample = wind_sampler.random_sample(
+    datetime.datetime(2027, 1, 1),
+    datetime.datetime(2027, 1, 7),
+    python_rng=random.Random(4),
+    numpy_rng=np.random.default_rng(32),
+)
+```
+
+Pass `desired_averages` to `WeatherData` when inverse-distribution resampling is
+required; this also requires historical data or precomputed prefix histograms.
+
+## Main capabilities
+
+- Wind and solar power-curve calibration foundations
+- Probabilistic load-factor forecasting
+- Weather and generation data loading and validation
+- Time-bucketed sampling with geographical correlation support
+- Extensible interfaces for local and external data sources
+
+## Documentation
+
+- [Wind calibration tutorial](docs/tutorials/wind_calibration_tutorial.ipynb)
+- [Contributing](CONTRIBUTING.md)
+- [Code of Conduct](CODE_OF_CONDUCT.md)
+- [Issue tracker](https://github.com/LCCC-Tech/rencal/issues)
+
+Hosted documentation and versioned examples will be linked here once the public
+documentation site is verified.
+
+## Support
+
+Use [GitHub Issues](https://github.com/LCCC-Tech/rencal/issues) for public,
+reproducible bugs and feature requests. Please do not include credentials,
+internal data, or confidential information in issues.
+
+## Licence
+
+RenCal is released under the [MIT Licence](LICENSE).

rencal-0.1.1/README.md

@@ -0,0 +1,149 @@
+# RenCal
+
+RenCal (Renewable Calibration) is a Python library for calibrating renewable
+energy power curves and generating probabilistic load-factor time series for
+wind and solar plants.
+
+It supports Monte Carlo-based forecasting using weather, generation, and plant
+characteristic data. RenCal is intended for energy analysts, researchers, and
+developers working on renewable-energy modelling.
+
+## Status
+
+RenCal is an experimental pre-1.0 public package. The API and modelling
+approach may change as the project develops. It is not currently a guarantee of
+production suitability or a substitute for independent validation.
+
+## Installation
+
+The first public release will be installed from PyPI with:
+
+```bash
+python -m pip install rencal
+```
+
+Until that release is published, clone the repository and follow the
+[development setup](CONTRIBUTING.md#development-setup) instead.
+
+## Quick start
+
+The primary workflow uses data supplied by the user. RenCal does not distribute
+operational ERA5, generation, or plant datasets.
+
+```python
+from pathlib import Path
+
+from rencal.core.data_loader import LocalDataLoader
+
+loader = LocalDataLoader(data_path=Path("data"))
+plants = loader.load_plant_data()
+generation = loader.load_generation_data()
+
+print(f"Loaded {len(plants.data)} plants")
+print(f"Loaded {len(generation.data)} generation records")
+```
+
+For the full wind-calibration workflow, provide the expected input structure:
+
+```text
+data/
+├── plant/plant_data.csv
+├── generation/generation_data.parquet
+└── era5/*.nc
+```
+
+The ERA5 loader expects suitable NetCDF weather data. Users are responsible for
+obtaining data, checking its provenance and licence, and preparing it for the
+documented schema.
+
+### Calibrate wind power curves
+
+With the plant, generation, and ERA5 inputs in place, run the wind calibration
+workflow and write its outputs to a separate directory:
+
+```python
+from pathlib import Path
+
+from rencal.calibration.wind.wind_calibrator import WindCalibrator
+
+calibrator = WindCalibrator(
+    data_path="data",
+    output_path=Path("outputs/wind-calibration"),
+    visual_output=True,
+    stream_npy_output=True,
+)
+calibrator.calibrate()
+```
+
+The workflow writes the calibration summary, Weibull parameters, extracted wind
+speeds, calibrated wind streams, and optional power-curve plots to the output
+directory. With `stream_npy_output=True`, the generated `Wind Streams.npy` can
+also be used by the weather sampler after its manifest and optional histogram
+artefacts have been prepared.
+
+### Sample calibrated wind streams
+
+`WeatherData` samples future hourly paths from calibrated historical streams
+while preserving the configured time-bucket structure. The local loader expects
+the calibrated NPY file and its manifest under `data/calibrated/`.
+
+```python
+import datetime
+import random
+
+import numpy as np
+
+from rencal.core.data_loader import LocalDataLoader
+from rencal.simulation.weather_data import HistoricalMetadata, WeatherData
+
+loader = LocalDataLoader(data_path="data")
+manifest = loader.check_historical_weather()
+metadata = HistoricalMetadata.from_manifest(
+    manifest,
+    loader.path_resolver_weather_data,
+)
+
+wind_sampler = WeatherData(
+    metadata=metadata,
+    prefix_histograms=loader.get_prefix_histograms(),
+    historical_data=loader.get_historical_weather(),
+)
+
+sample = wind_sampler.random_sample(
+    datetime.datetime(2027, 1, 1),
+    datetime.datetime(2027, 1, 7),
+    python_rng=random.Random(4),
+    numpy_rng=np.random.default_rng(32),
+)
+```
+
+Pass `desired_averages` to `WeatherData` when inverse-distribution resampling is
+required; this also requires historical data or precomputed prefix histograms.
+
+## Main capabilities
+
+- Wind and solar power-curve calibration foundations
+- Probabilistic load-factor forecasting
+- Weather and generation data loading and validation
+- Time-bucketed sampling with geographical correlation support
+- Extensible interfaces for local and external data sources
+
+## Documentation
+
+- [Wind calibration tutorial](docs/tutorials/wind_calibration_tutorial.ipynb)
+- [Contributing](CONTRIBUTING.md)
+- [Code of Conduct](CODE_OF_CONDUCT.md)
+- [Issue tracker](https://github.com/LCCC-Tech/rencal/issues)
+
+Hosted documentation and versioned examples will be linked here once the public
+documentation site is verified.
+
+## Support
+
+Use [GitHub Issues](https://github.com/LCCC-Tech/rencal/issues) for public,
+reproducible bugs and feature requests. Please do not include credentials,
+internal data, or confidential information in issues.
+
+## Licence
+
+RenCal is released under the [MIT Licence](LICENSE).

rencal-0.1.1/pyproject.toml

@@ -0,0 +1,190 @@
+[build-system]
+requires = ["uv_build>=0.10.8,<0.11.0"]
+build-backend = "uv_build"
+
+[project]
+name = "rencal"
+version = "0.1.1"
+description = "Weather-to-power calibration and Monte Carlo load factor simulation for renewable energy applications"
+readme = "README.md"
+requires-python = ">=3.12,<3.13"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    {name = "Low Carbon Contracts Company Ltd", email = "analytics@lowcarboncontracts.uk"}
+]
+maintainers = [
+    {name = "Low Carbon Contracts Company Ltd", email = "analytics@lowcarboncontracts.uk"}
+]
+keywords = [
+    "weather",
+    "forecasting",
+    "renewable energy",
+    "wind power",
+    "solar power",
+    "era5",
+    "monte carlo",
+    "calibration",
+    "climate"
+]
+classifiers = [
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Atmospheric Science",
+    "Topic :: Utilities"
+]
+dependencies = [
+    "numpy>=1.20.0",
+    "pandas>=1.3.0",
+    "scipy>=1.7.0",
+    "matplotlib>=3.4.0",
+    "seaborn>=0.12.0",
+    "scikit-learn>=1.0.0",
+    "netCDF4>=1.5.0",
+    "xarray>=0.19.0",
+    "pytz>=2021.1",
+    "requests>=2.25.0",
+    "polars>=1.8.2",
+    "pydantic>=2.10.6",
+    "pyodbc>=4.0.0",
+    "cdsapi>=0.6.0",
+    "python-dotenv>=1.0.0",
+    "openpyxl>=3.1.0",
+    "zarr>=2.16.1",
+    "tqdm>=4.62.0",
+    "pyarrow>=22.0.0",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=6.0",
+    "pytest-cov>=2.0",
+    "ruff>=0.8.0",
+    "basedpyright>=1.0.0",
+    "pre-commit>=2.15.0",
+    "build>=1.0.0"
+]
+docs = [
+    "sphinx>=4.0",
+    "sphinx-rtd-theme>=1.0",
+    "myst-parser>=0.15.0",
+    "sphinx-autoapi>=1.8.0"
+]
+azure = [
+    "azure-storage-blob>=12.0.0",
+    "azure-identity>=1.7.0"
+]
+notebook = [
+    "jupyter>=1.0.0",
+    "ipykernel>=6.0.0",
+    "plotly>=5.0.0"
+]
+
+[project.urls]
+Homepage = "https://github.com/LCCC-Tech/rencal"
+Repository = "https://github.com/LCCC-Tech/rencal.git"
+"Bug Tracker" = "https://github.com/LCCC-Tech/rencal/issues"
+Changelog = "https://github.com/LCCC-Tech/rencal/blob/main/CHANGELOG.md"
+
+[tool.uv.build-backend]
+module-name = "rencal"
+module-root = ""
+
+[tool.basedpyright]
+include = ["rencal"]
+exclude = [".venv", "build", "dist", "rencal/simulation/intermittent_bucketer.py", "rencal/core/bucketed_data.py",]
+venvPath = "."
+venv = ".venv"
+pythonVersion = "3.12"
+typeCheckingMode = "basic"  # Changed from strict to basic to reduce false positives
+reportMissingImports = true
+reportMissingTypeStubs = false
+reportUnusedImport = true
+reportUnusedClass = false  # Reduce noise for now
+reportUnusedFunction = false  # Reduce noise for now
+reportUnusedVariable = true
+# Less strict about third-party library types
+reportUnknownMemberType = false
+reportUnknownVariableType = false
+reportUnknownArgumentType = false
+# Disable overly strict argument type checking for third-party libraries
+reportArgumentType = false
+# Additional settings to help with import resolution
+extraPaths = ["."]
+
+[tool.ruff]
+line-length = 100
+indent-width = 4
+target-version = "py312"
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # pyflakes
+    "I",   # isort
+    "B",   # flake8-bugbear
+    "C4",  # flake8-comprehensions
+    "UP",  # pyupgrade
+]
+ignore = [
+    "E501",  # Line too long (handled by formatter)
+    "B008",  # Do not perform function calls in argument defaults
+]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+line-ending = "auto"
+docstring-code-format = true
+docstring-code-line-length = "dynamic"
+
+[tool.ruff.lint.isort]
+known-first-party = ["rencal"]
+
+# pytest configuration
+[tool.pytest.ini_options]
+minversion = "6.0"
+addopts = "-ra -q --strict-markers --strict-config"
+testpaths = ["tests"]
+python_files = ["test_*.py", "*_test.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+filterwarnings = [
+    "error",
+    "ignore::UserWarning",
+    "ignore::DeprecationWarning",
+    "ignore:numpy.*:RuntimeWarning",
+]
+markers = [
+    "slow: marks tests as slow (deselect with '-m \"not slow\"')",
+    "integration: marks tests as integration tests",
+    "unit: marks tests as unit tests",
+]
+
+# Coverage configuration
+[tool.coverage.run]
+source = ["rencal"]
+omit = [
+    "*/tests/*",
+    "*/test_*",
+    "setup.py",
+]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "if self.debug:",
+    "if settings.DEBUG",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if 0:",
+    "if __name__ == .__main__.:",
+    "class .*\\bProtocol\\):",
+    "@(abc\\.)?abstractmethod",
+]

rencal-0.1.1/rencal/__init__.py

@@ -0,0 +1,13 @@
+"""
+Renewable Calibration (rencal) for renwable energy forecasting.
+
+A Python library for calibrating renewable plant power curves using generalised logistic function
+modules for generating probabilistic load factor time series forecasts using resampling from
+historical ERA5 weather data.
+"""
+
+from importlib.metadata import version
+
+__version__ = version("rencal")
+__author__ = "Low Carbon Contracts Company Ltd"
+__email__ = "analytics@lowcarboncontracts.uk"

rencal-0.1.1/rencal/calibration/calibrator.py

@@ -0,0 +1,99 @@
+"""Abstract base class for the calibration of intermittent generator power curves."""
+
+from abc import ABC, abstractmethod
+
+from ..core.data_loader import DataLoader, LocalDataLoader
+
+
+class Calibrator(ABC):
+    def __init__(
+        self,
+        data_path: str = None,
+        plant_id_col: str = None,
+        loader: DataLoader | None = None,
+    ):
+        """
+        Initialise a calibrator instance.
+
+        The Calibrator is an abstract class that specifies the methods any intermittent
+        generator's calibration should include, as well as setting up and loading input
+        datasets from the configuration file or user-specified paths.
+
+        Args:
+            data_path (str): Path to the directory containing the input data files.
+            plant_id_col (str): Name of the ID column designating a power plant in the input.
+            loader (DataLoader | None): Optional pre-configured data loader. When supplied it
+                is used as-is (overriding ``data_path``), allowing inputs to be read from
+                non-default locations or sources (e.g. a cloud loader reading directly from
+                Blob storage) instead of the default ``LocalDataLoader`` layout.
+        """
+        if loader is not None:
+            self.loader = loader
+        else:
+            self.loader = LocalDataLoader(data_path) if data_path else LocalDataLoader()
+        self.plants = (
+            self.loader.load_plant_data(plant_id_col)
+            if plant_id_col
+            else self.loader.load_plant_data()
+        )
+        self.generation = (
+            self.loader.load_generation_data(plant_id_col)
+            if plant_id_col
+            else self.loader.load_generation_data()
+        )
+        self.resource = self.loader.load_era5_data()
+
+    @abstractmethod
+    def calibrate(self) -> None:
+        """Triggers calibration workflow."""
+        pass
+
+    @abstractmethod
+    def extract_resource_timeseries_for_plants(self) -> None:
+        """Extracts resource time series for plants."""
+        pass
+
+    @abstractmethod
+    def calculate_historical_load_factors(self) -> None:
+        """Calculates historical load factors."""
+        pass
+
+    @abstractmethod
+    def fit_historical_load_factor_distribution(self) -> None:
+        """Fits a distribution to historical load factors."""
+        pass
+
+    @abstractmethod
+    def estimate_load_factors_for_resource(self) -> None:
+        """Estimates load factors based on historical distribution and full resource availability."""
+        pass
+
+    @abstractmethod
+    def generate_resource_streams(self) -> None:
+        """Generates load factor streams for available resource time series for each generator."""
+        pass
+
+    @abstractmethod
+    def output_historical_load_factor_distribution_parameters(self) -> None:
+        """Writes historical load factor parameters to a CSV file."""
+        pass
+
+    @abstractmethod
+    def output_resource_per_plant(self) -> None:
+        """Writes resource time series for each plant to a CSV file."""
+        pass
+
+    @abstractmethod
+    def output_resource_streams(self) -> None:
+        """Writes resource streams to a parquet file."""
+        pass
+
+    @abstractmethod
+    def output_estimated_load_factors_tabular(self) -> None:
+        """Outputs table of estimated load factors."""
+        pass
+
+    @abstractmethod
+    def output_estimated_load_factors_visual(self) -> None:
+        """Outputs a series of plots of estimated load factors and calibrated curves."""
+        pass