detquantlib 3.14.0__tar.gz → 3.15.0__tar.gz

{detquantlib-3.14.0 → detquantlib-3.15.0}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: detquantlib
-Version: 3.14.0
+Version: 3.15.0
 Summary: An internal library containing functions and classes that can be used across Quant models.
 License-File: LICENSE.txt
-Author: DET
+Author: Dynamic Energy Trading
 Requires-Python: >=3.10,<4.0
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
@@ -19,9 +19,9 @@ Requires-Dist: plotly (>=6.3.1,<7.0.0)
 Requires-Dist: pyarrow (>=21.0.0,<22.0.0)
 Requires-Dist: pyodbc (>=5.2.0,<6.0.0)
 Requires-Dist: python-dotenv (>=1.1.0,<2.0.0)
+Requires-Dist: redis (>=7.4.0,<8.0.0)
 Requires-Dist: scipy (>=1.15.2,<2.0.0)
 Requires-Dist: sqlalchemy (>=2.0.43,<3.0.0)
-Project-URL: Repository, https://github.com/Dynamic-Energy-Trading/detquantlib
 Description-Content-Type: text/markdown
 
 # DET Quant Library

detquantlib-3.15.0/detquantlib/assets/__init__.py

@@ -0,0 +1,4 @@
+from .battery import Battery
+from .wind_turbine import WindTurbine
+
+__all__ = ["Battery", "WindTurbine"]

detquantlib-3.15.0/detquantlib/assets/battery.py

@@ -0,0 +1,174 @@
+# Python built-in packages
+import json
+import os
+
+# Third-party packages
+import pandas as pd
+import redis
+
+# Internal modules
+from detquantlib.utils import list_to_str
+
+
+class Battery:
+    """A class containing the characteristics of a battery."""
+
+    def __init__(
+        self,
+        capacity_mwh: float = None,
+        power_mw: float = None,
+        state_of_charge_mwh: float = None,
+        roundtrip_eff: float = None,
+        group_id: int = None,
+    ):
+        """
+        Constructor method.
+
+        Args:
+            capacity_mwh: Battery capacity in MWh
+            power_mw: Battery power in MW
+            state_of_charge_mwh: Current state of charge in MWh
+            roundtrip_eff: Roundtrip efficiency
+            group_id: Group ID (used to differentiate batteries with different characteristics
+        """
+        # Assign inputs
+        self.capacity_mwh = capacity_mwh
+        self.power_mw = power_mw
+        self.state_of_charge_mwh = state_of_charge_mwh
+        self.roundtrip_eff = roundtrip_eff
+        self.group_id = group_id
+
+        # Calculate power-to-capacity ratio
+        if self.capacity_mwh and self.power_mw:
+            self.capacity_power_ratio = round(self.capacity_mwh / self.power_mw, 0)
+
+    @staticmethod
+    def build_from_redis() -> (list["Battery"], str):
+        """
+        Builds Battery objects from the individual battery units found in the redis cache.
+
+        Returns:
+            Tuple:
+                - List of Battery objects
+                - Message listing all the batteries whose information could not be retrieved
+                    from the redis cache
+        """
+        # Load individual battery units
+        battery_units, missing_units = Battery.load_battery_units_from_redis()
+
+        # Print missing battery units
+        msg_missing_units = ""
+        nr_found, nr_miss = len(battery_units), len(missing_units)
+        if nr_miss > 0:
+            msg_missing_units = (
+                f"Failed to retrieve the battery storage data of {nr_miss}/{nr_found + nr_miss} "
+                f"batteries. Details:"
+            )
+            for mb in missing_units:
+                msg_missing_units += (
+                    f"\n- Site node ID: {mb['site_node_id']}. Error message: '{mb['error_msg']}'."
+                )
+
+        if nr_found == 0:
+            return list(), msg_missing_units
+
+        # Set battery groups based on capacity:power ratio
+        battery_units = pd.DataFrame(battery_units)
+        battery_units.sort_values("cp_ratio", ignore_index=True, inplace=True)
+        battery_units["cp_group"] = battery_units["cp_ratio"].round(0)
+
+        # Calculate aggregated virtual batteries
+        agg_units = (
+            battery_units[["capacity_mwh", "power_mw", "state_of_charge_mwh", "cp_group"]]
+            .groupby("cp_group", as_index=False)
+            .agg({"capacity_mwh": "sum", "power_mw": "sum", "state_of_charge_mwh": "sum"})
+            .reset_index(drop=True)
+        )
+        agg_units["group_id"] = agg_units["cp_group"].rank(method="dense")
+        agg_units.drop(columns="cp_group", inplace=True)
+
+        # Round to avoid machine precision issues caused by 'group by'
+        agg_units = agg_units.round(9)
+
+        # Create battery objects
+        batteries = [Battery(**agg_units.loc[i, :].to_dict()) for i in agg_units.index]
+
+        return batteries, msg_missing_units
+
+    @staticmethod
+    def load_battery_units_from_redis() -> (list[dict], list[dict]):
+        """
+        Loads individual battery units from the redis cache.
+
+        Returns:
+            Tuple:
+                - Individual battery units whose information could be found
+                - Individual battery units whose information could not be found
+
+        Raises:
+            ConnectionError: Raises an error if environment variables are not defined.
+        """
+        # Check mandatory environment variables to connect to Redis cache
+        mandatory_vars = ["DET_REDIS_HOST", "DET_REDIS_PORT", "DET_REDIS_PASSWORD", "DET_REDIS_DB"]
+        for mv in mandatory_vars:
+            if mv not in os.environ:
+                raise ConnectionError(
+                    f"Environment variable '{mv}' not found. Connection to Redis cache requires "
+                    f"the following environment variables: {list_to_str(mandatory_vars)}."
+                )
+
+        # Connect to redis cache
+        r = redis.Redis(
+            host=os.environ["DET_REDIS_HOST"],
+            port=int(os.environ["DET_REDIS_PORT"]),
+            password=os.environ["DET_REDIS_PASSWORD"],
+            ssl=True,
+            db=int(os.environ["DET_REDIS_DB"]),
+        )
+
+        # Loop over cache data
+        battery_units = []
+        missing_units = []
+        for key in r.scan_iter("*"):
+            # Parse data
+            raw = r.get(key)
+            data = json.loads(raw)
+
+            try:
+                storage = data["data"]["state"]["storage"]
+            except KeyError:
+                # Skip battery if info cannot be found
+                missing_units.append(
+                    dict(site_node_id=data["siteNodeId"], error_msg=data["data"].get("errors", ""))
+                )
+                continue
+
+            # Convert settings
+            capacity_mwh = storage["energy_capacity_Wh"] / 1e6
+            state_of_charge_mwh = storage["energy_stored_Wh"] / 1e6
+            charge_rate_mw = storage["max_charge_power_W"] / 1e6
+            discharge_rate_mw = storage["max_discharge_power_W"] / 1e6
+
+            # Set (dis)charge rate
+            power_mw = max(charge_rate_mw, -discharge_rate_mw)
+
+            # Calculate capacity:power ratio
+            cp_ratio = capacity_mwh / power_mw
+
+            # Get BESS group data
+            timestamp = data["time"]
+            site_node_id = data["siteNodeId"]
+
+            # Store characteristics
+            battery_units.append(
+                dict(
+                    capacity_mwh=capacity_mwh,
+                    power_mw=power_mw,
+                    state_of_charge_mwh=state_of_charge_mwh,
+                    cp_ratio=cp_ratio,
+                    timestamp=timestamp,
+                    site_node_id=site_node_id,
+                )
+            )
+
+        return battery_units, missing_units

detquantlib-3.15.0/detquantlib/assets/wind_turbine.py

@@ -0,0 +1,92 @@
+# Third-party packages
+import numpy as np
+import pandas as pd
+from scipy.interpolate import CubicSpline
+
+
+class WindTurbine:
+    """A class to store wind turbine information and perform wind turbine-related calculations."""
+
+    def __init__(
+        self, rated_power: float, cut_in: float, cut_out: float, power_curve: CubicSpline = None
+    ):
+        """
+        Constructor method.
+
+        Args:
+            rated_power: Rated power
+            cut_in: Cut-in wind speed
+            cut_out: Cut-out wind speed
+            power_curve: Power curve, stored as a cubic spline object. If not provided, can be
+                set via the 'fit_power_curve()' method below.
+        """
+        self.rated_power = rated_power
+        self.cut_in = cut_in
+        self.cut_out = cut_out
+        self.power_curve = power_curve
+
+    def fit_power_curve(
+        self, wind_speed: list | np.ndarray | pd.Series, power: list | np.ndarray | pd.Series
+    ):
+        """
+        Fits the wind turbine's power curve with a cubic spline, and stores the resulting spline
+        object in attribute self.power_curve.
+
+        Args:
+            wind_speed: Wind speeds
+            power: Corresponding power
+        """
+        # Make sure input data is stored as numpy array
+        wind_speed, power = np.array(wind_speed), np.array(power)
+
+        # Trim data to cut-in - cut-out interval
+        idx = (wind_speed >= self.cut_in) & (wind_speed <= self.cut_out)
+        wind_speed_trim, power_trim = wind_speed[idx], power[idx]
+
+        # Add data point with power=0.0 before cut-in to ensure smooth behaviour of spline
+        # interpolation
+        w0 = wind_speed_trim[0] - np.diff(wind_speed_trim[:2])
+        p0 = [0]
+        wind_speed_trim, power_trim = np.concat([w0, wind_speed_trim]), np.concat([p0, power_trim])
+
+        # Fit cubic spline
+        cs = CubicSpline(wind_speed_trim, power_trim)
+
+        # Store spline object
+        self.power_curve = cs
+
+    def wind_to_power(self, wind_speed: list | np.ndarray | pd.Series) -> np.ndarray:
+        """
+        Converts wind speeds to wind turbine power.
+
+        Args:
+            wind_speed: Wind speeds
+
+        Returns:
+            Corresponding power
+
+        Raises:
+            ValueError: Raises an error if self.power_curve is None.
+        """
+        # Check that power curve attribute is defined
+        if self.power_curve is None:
+            raise ValueError(
+                "Cannot execute method self.wind_to_power() if attribute self.power_curve is "
+                "None. Use method self.fit_power_curve() to set self.power_curve based on power "
+                "curve data."
+            )
+
+        # Make sure input data is stored as numpy array
+        wind_speed = np.array(wind_speed)
+
+        # Cubic spline interpolation
+        power = self.power_curve(wind_speed)
+
+        # Cap to rated power
+        power = np.minimum(power, self.rated_power)
+
+        # Adjust values outside of cut-in - cut-out bounds
+        idx = (wind_speed < self.cut_in) | (wind_speed > self.cut_out)
+        power[idx] = 0.0
+
+        return power

{detquantlib-3.14.0 → detquantlib-3.15.0}/detquantlib/data/databases/detdatabase.py

@@ -51,7 +51,7 @@ class DetDatabase:
         Checks if environment variables needed by the class are defined.
 
         Raises:
-            EnvironmentError: Raises an error if environment variables are not defined
+            ConnectionError: Raises an error if environment variables are not defined.
         """
         required_env_vars = [
             dict(name="DET_DB_NAME", value=None, description="Database name"),
@@ -64,7 +64,7 @@ class DetDatabase:
             if d["name"] not in available_env_vars:
                 required_env_vars_names = [x["name"] for x in required_env_vars]
                 required_env_vars_str = list_to_str(required_env_vars_names)
-                raise EnvironmentError(
+                raise ConnectionError(
                     f"The DetDatabase class requires the following environment variables: "
                     f"{required_env_vars_str}. Environment variable '{d['name']}' "
                     f"(description: '{d['description']}') not found."
@@ -104,11 +104,11 @@ class DetDatabase:
             Dataframe containing the queried data
 
         Raises:
-            Exception: Raises an error if the SQL query fails
+            Exception: Raises an error if the SQL query fails.
         """
         try:
             df = pd.read_sql_query(query, con=self.engine)
-        except Exception as e:
+        except Exception:
             # If query fails, close connection before raising the error
             self.terminate_engine()
             raise
@@ -171,10 +171,10 @@ class DetDatabase:
 
         Raises:
             ValueError: Raises an error if input arguments 'columns' and 'process_data' are not
-                compatible
+                compatible.
             ValueError: Raises an error if the combination of trading dates and delivery dates
                 is not valid.
-            ValueError: Raises an error if no price data is found for user inputs
+            ValueError: Raises an error if no price data is found for user inputs.
         """
         # Input validation
         if process_data and columns is not None:
@@ -385,10 +385,10 @@ class DetDatabase:
 
         Raises:
             ValueError: Raises an error if input arguments 'columns' and 'process_data' are not
-                compatible
+                compatible.
             ValueError: Raises an error if the combination of trading dates and delivery dates
                 is not valid.
-            ValueError: Raises an error if no price data is found for user inputs
+            ValueError: Raises an error if no price data is found for user inputs.
         """
         # Input validation
         if process_data and columns is not None:
@@ -569,7 +569,7 @@ class DetDatabase:
             Dataframe containing futures end-of-day settlement prices
 
         Raises:
-            ValueError: Raises an error if no price data is found for user inputs
+            ValueError: Raises an error if no price data is found for user inputs.
         """
         # Set default column values
         if columns is None:
@@ -669,8 +669,8 @@ class DetDatabase:
             A dictionary containing the requested information
 
         Raises:
-            ValueError: Raises an error if match with input filter value is not unique
-            ValueError: Raises an error if the input filter value is not found
+            ValueError: Raises an error if match with input filter value is not unique.
+            ValueError: Raises an error if the input filter value is not found.
         """
         # Get commodity information for user-defined filtering criteria
         condition = f"WHERE {filter_column}='{filter_value}'"
@@ -1000,7 +1000,7 @@ class DetDatabase:
             Dataframe containing customer day-ahead auction bids
 
         Raises:
-            ValueError: Raises an error if no data is found for user inputs
+            ValueError: Raises an error if no data is found for user inputs.
         """
         # Convert start delivery date from local timezone to UTC and string
         start_delivery_date = start_delivery_date.replace(tzinfo=ZoneInfo(local_timezone))
@@ -1104,8 +1104,8 @@ class DetDatabase:
             A dictionary containing the requested information
 
         Raises:
-            ValueError: Raises an error if match with input filter value is not unique
-            ValueError: Raises an error if the input filter value is not found
+            ValueError: Raises an error if match with input filter value is not unique.
+            ValueError: Raises an error if the input filter value is not found.
         """
         # Get client information for user-defined filtering criteria
         condition = f"WHERE {filter_column}='{filter_value}'"

{detquantlib-3.14.0 → detquantlib-3.15.0}/pyproject.toml

@@ -1,10 +1,9 @@
 [tool.poetry]
 name = "detquantlib"
-version = "3.14.0"
+version = "3.15.0"
 description = "An internal library containing functions and classes that can be used across Quant models."
-authors = ["DET"]
+authors = ["Dynamic Energy Trading"]
 readme = "README.md"
-repository = "https://github.com/Dynamic-Energy-Trading/detquantlib"
 packages = [
     { include = "detquantlib" }, # Specifies the location of the package
 ]
@@ -21,6 +20,7 @@ pandas = "^2.3.3"
 pyarrow = "^21.0.0"
 scipy = "^1.15.2"
 colorlog = "^6.10.1"
+redis = "^7.4.0"
 
 [tool.poetry.group.dev.dependencies]
 toml = "^0.10.2"
@@ -30,6 +30,7 @@ pytest-cov = "^7.0.0"
 black = "^25.9.0"
 darglint = "^1.8.1"
 isort = "^6.1.0"
+ruff = "^0.15.4"
 colorama = "^0.4.6"
 pymarkdownlnt = "^0.9.32"
 md-toc = "^9.0.0"
@@ -53,6 +54,10 @@ known_third_party = ["invoke"]
 [tool.black]
 line-length = 99
 
+[tool.ruff.lint]
+select = ["B", "F"]  # "B"=flake8-bugbear, "F"=Pyflakes
+ignore = ["F403", "F405"]
+
 [tool.pymarkdown]
 plugins.md013.enabled = false # Disable line length requirements
 plugins.md040.enabled = false # Disable fenced code blocks language requirements