openenergyid 0.1.21__py3-none-any.whl

openenergyid/dyntar/main.py

@@ -0,0 +1,312 @@
+"""Main module of the DynTar package."""
+
+from typing import cast
+import pandas as pd
+
+from openenergyid.const import (
+    ELECTRICITY_DELIVERED,
+    ELECTRICITY_EXPORTED,
+    PRICE_ELECTRICITY_DELIVERED,
+    PRICE_ELECTRICITY_EXPORTED,
+    RLP,
+    SPP,
+)
+
+from .const import (
+    ELECTRICITY_DELIVERED_SMR3,
+    ELECTRICITY_EXPORTED_SMR3,
+    ELECTRICITY_DELIVERED_SMR2,
+    ELECTRICITY_EXPORTED_SMR2,
+    COST_ELECTRICITY_DELIVERED_SMR2,
+    COST_ELECTRICITY_EXPORTED_SMR2,
+    COST_ELECTRICITY_DELIVERED_SMR3,
+    COST_ELECTRICITY_EXPORTED_SMR3,
+    RLP_WEIGHTED_PRICE_DELIVERED,
+    SPP_WEIGHTED_PRICE_EXPORTED,
+    HEATMAP_DELIVERED,
+    HEATMAP_EXPORTED,
+    HEATMAP_TOTAL,
+    HEATMAP_DELIVERED_DESCRIPTION,
+    HEATMAP_EXPORTED_DESCRIPTION,
+    HEATMAP_TOTAL_DESCRIPTION,
+    Register,
+)
+
+
+def weigh_by_monthly_profile(df: pd.DataFrame, series_name, profile_name) -> pd.Series:
+    """Weigh a time series by a monthly profile."""
+    grouped = df.groupby(pd.Grouper(freq="MS"))
+    return grouped[series_name].transform("sum") * grouped[profile_name].transform(
+        lambda x: x / x.sum()
+    )
+
+
+def extend_dataframe_with_smr2(
+    df: pd.DataFrame,
+    inplace: bool = False,
+    registers: list[Register] | None = None,
+) -> pd.DataFrame | None:
+    """Extend a DataFrame with the SMR2 columns."""
+    if not inplace:
+        result_df = df.copy()
+    else:
+        result_df = df
+
+    if registers is None:
+        registers = [Register.DELIVERY, Register.EXPORT]
+
+    if Register.DELIVERY in registers:
+        result_df[ELECTRICITY_DELIVERED_SMR2] = weigh_by_monthly_profile(
+            df, ELECTRICITY_DELIVERED, RLP
+        )
+    if Register.EXPORT in registers:
+        result_df[ELECTRICITY_EXPORTED_SMR2] = weigh_by_monthly_profile(
+            df, ELECTRICITY_EXPORTED, SPP
+        )
+
+    result_df.rename(
+        columns={
+            ELECTRICITY_DELIVERED: ELECTRICITY_DELIVERED_SMR3,
+            ELECTRICITY_EXPORTED: ELECTRICITY_EXPORTED_SMR3,
+        },
+        inplace=True,
+        errors="ignore",
+    )
+
+    if not inplace:
+        return result_df
+    return None
+
+
+def extend_dataframe_with_costs(
+    df: pd.DataFrame, inplace: bool = False, registers: list[Register] | None = None
+) -> pd.DataFrame | None:
+    """Extend a DataFrame with the cost columns."""
+    if not inplace:
+        result_df = df.copy()
+    else:
+        result_df = df
+
+    if registers is None:
+        registers = [Register.DELIVERY, Register.EXPORT]
+
+    if Register.DELIVERY in registers:
+        result_df[COST_ELECTRICITY_DELIVERED_SMR2] = (
+            df[ELECTRICITY_DELIVERED_SMR2] * df[PRICE_ELECTRICITY_DELIVERED]
+        )
+        result_df[COST_ELECTRICITY_DELIVERED_SMR3] = (
+            df[ELECTRICITY_DELIVERED_SMR3] * df[PRICE_ELECTRICITY_DELIVERED]
+        )
+
+    if Register.EXPORT in registers:
+        result_df[COST_ELECTRICITY_EXPORTED_SMR2] = (
+            df[ELECTRICITY_EXPORTED_SMR2] * df[PRICE_ELECTRICITY_EXPORTED] * -1
+        )
+        result_df[COST_ELECTRICITY_EXPORTED_SMR3] = (
+            df[ELECTRICITY_EXPORTED_SMR3] * df[PRICE_ELECTRICITY_EXPORTED] * -1
+        )
+
+    if not inplace:
+        return result_df
+    return None
+
+
+def extend_dataframe_with_weighted_prices(
+    df: pd.DataFrame, inplace: bool = False, registers: list[Register] | None = None
+) -> pd.DataFrame | None:
+    """Extend a DataFrame with the weighted price columns."""
+    if not inplace:
+        df = df.copy()
+
+    if registers is None:
+        registers = [Register.DELIVERY, Register.EXPORT]
+
+    if Register.DELIVERY in registers:
+        rlp_weighted_price_delivered = (df[PRICE_ELECTRICITY_DELIVERED] * df[RLP]).resample(
+            "MS"
+        ).sum() / df[RLP].resample("MS").sum()
+        df[RLP_WEIGHTED_PRICE_DELIVERED] = rlp_weighted_price_delivered.reindex_like(
+            df[RLP], method="ffill"
+        )
+
+    if Register.EXPORT in registers:
+        spp_weighted_price_exported = (df[PRICE_ELECTRICITY_EXPORTED] * df[SPP]).resample(
+            "MS"
+        ).sum() / df[SPP].resample("MS").sum()
+        df[SPP_WEIGHTED_PRICE_EXPORTED] = spp_weighted_price_exported.reindex_like(
+            df[SPP], method="ffill"
+        )
+
+    if not inplace:
+        return df
+    return None
+
+
+def extend_dataframe_with_heatmap(
+    df: pd.DataFrame, inplace: bool = False, registers: list[Register] | None = None
+) -> pd.DataFrame | None:
+    """Extend a DataFrame with the heatmap columns."""
+    if not inplace:
+        df = df.copy()
+
+    if registers is None:
+        registers = [Register.DELIVERY, Register.EXPORT]
+
+    if Register.DELIVERY in registers:
+        energy_delta_delivered = df[ELECTRICITY_DELIVERED_SMR2] - df[ELECTRICITY_DELIVERED_SMR3]
+        price_delta_delivered = df[RLP_WEIGHTED_PRICE_DELIVERED] - df[PRICE_ELECTRICITY_DELIVERED]
+        heatmap_score_delivered = energy_delta_delivered * price_delta_delivered
+        heatmap_score_delivered.fillna(0, inplace=True)
+        # Invert score so that positive values indicate a positive impact
+        heatmap_score_delivered = -heatmap_score_delivered
+        df[HEATMAP_DELIVERED] = heatmap_score_delivered
+
+    if Register.EXPORT in registers:
+        energy_delta_exported = df[ELECTRICITY_EXPORTED_SMR2] - df[ELECTRICITY_EXPORTED_SMR3]
+        price_delta_exported = df[SPP_WEIGHTED_PRICE_EXPORTED] - df[PRICE_ELECTRICITY_EXPORTED]
+        heatmap_score_exported = energy_delta_exported * price_delta_exported
+        heatmap_score_exported.fillna(0, inplace=True)
+        df[HEATMAP_EXPORTED] = heatmap_score_exported
+
+    if Register.DELIVERY in registers and Register.EXPORT in registers:
+        heatmap_score_delivered = cast(pd.Series, df[HEATMAP_DELIVERED])
+        heatmap_score_exported = cast(pd.Series, df[HEATMAP_EXPORTED])
+        heatmap_score_combined = heatmap_score_delivered + heatmap_score_exported
+    elif Register.DELIVERY in registers:
+        heatmap_score_combined = heatmap_score_delivered
+    else:
+        heatmap_score_combined = heatmap_score_exported
+    df[HEATMAP_TOTAL] = heatmap_score_combined
+
+    if not inplace:
+        return df
+    return None
+
+
+def map_delivery_description(
+    price_delivered, price_rlp, electricity_delivered_smr3, electricity_delivered_smr2
+):
+    """Map the delivery description."""
+    if price_delivered > price_rlp and electricity_delivered_smr3 > electricity_delivered_smr2:
+        return 1
+    if price_delivered > price_rlp and electricity_delivered_smr3 < electricity_delivered_smr2:
+        return 2
+    if price_delivered < price_rlp and electricity_delivered_smr3 > electricity_delivered_smr2:
+        return 3
+    if price_delivered < price_rlp and electricity_delivered_smr3 < electricity_delivered_smr2:
+        return 4
+    return 0
+
+
+def map_export_description(
+    price_exported, price_spp, electricity_exported_smr3, electricity_exported_smr2
+):
+    """Map the export description."""
+    if price_exported > price_spp and electricity_exported_smr3 > electricity_exported_smr2:
+        return 5
+    if price_exported > price_spp and electricity_exported_smr3 < electricity_exported_smr2:
+        return 6
+    if price_exported < price_spp and electricity_exported_smr3 > electricity_exported_smr2:
+        return 7
+    if price_exported < price_spp and electricity_exported_smr3 < electricity_exported_smr2:
+        return 8
+    return 0
+
+
+def map_total_description(
+    abs_heatmap_delivered, abs_heatmap_exported, delivered_description, exported_description
+):
+    """Map the total description."""
+    if abs_heatmap_delivered > abs_heatmap_exported:
+        return delivered_description
+    return exported_description
+
+
+def extend_dataframe_with_heatmap_description(
+    df: pd.DataFrame, inplace: bool = False, registers: list[Register] | None = None
+) -> pd.DataFrame | None:
+    """Extend a DataFrame with the heatmap description columns."""
+    if not inplace:
+        df = df.copy()
+
+    if registers is None:
+        registers = [Register.DELIVERY, Register.EXPORT]
+
+    if Register.DELIVERY in registers:
+        df[HEATMAP_DELIVERED_DESCRIPTION] = list(
+            map(
+                map_delivery_description,
+                df[PRICE_ELECTRICITY_DELIVERED],
+                df[RLP_WEIGHTED_PRICE_DELIVERED],
+                df[ELECTRICITY_DELIVERED_SMR3],
+                df[ELECTRICITY_DELIVERED_SMR2],
+            )
+        )
+
+    if Register.EXPORT in registers:
+        df[HEATMAP_EXPORTED_DESCRIPTION] = list(
+            map(
+                map_export_description,
+                df[PRICE_ELECTRICITY_EXPORTED],
+                df[SPP_WEIGHTED_PRICE_EXPORTED],
+                df[ELECTRICITY_EXPORTED_SMR3],
+                df[ELECTRICITY_EXPORTED_SMR2],
+            )
+        )
+
+    if Register.DELIVERY in registers and Register.EXPORT in registers:
+        df[HEATMAP_TOTAL_DESCRIPTION] = list(
+            map(
+                map_total_description,
+                df[HEATMAP_DELIVERED].abs(),
+                df[HEATMAP_EXPORTED].abs(),
+                df[HEATMAP_DELIVERED_DESCRIPTION],
+                df[HEATMAP_EXPORTED_DESCRIPTION],
+            )
+        )
+    elif Register.DELIVERY in registers:
+        df[HEATMAP_TOTAL_DESCRIPTION] = df[HEATMAP_DELIVERED_DESCRIPTION]
+    else:
+        df[HEATMAP_TOTAL_DESCRIPTION] = df[HEATMAP_EXPORTED_DESCRIPTION]
+
+    if not inplace:
+        return df
+
+
+def calculate_dyntar_columns(
+    df: pd.DataFrame,
+    inplace: bool = False,
+    registers: list[Register] | None = None,
+) -> pd.DataFrame | None:
+    """Calculate all columns required for the dynamic tariff analysis."""
+    if not inplace:
+        df = df.copy()
+
+    if registers is None:
+        registers = [Register.DELIVERY, Register.EXPORT]
+
+    extend_dataframe_with_smr2(df, inplace=True, registers=registers)
+    extend_dataframe_with_costs(df, inplace=True, registers=registers)
+    extend_dataframe_with_weighted_prices(df, inplace=True, registers=registers)
+    extend_dataframe_with_heatmap(df, inplace=True, registers=registers)
+    extend_dataframe_with_heatmap_description(df, inplace=True, registers=registers)
+
+    if not inplace:
+        return df
+    return None
+
+
+def summarize_result(df: pd.DataFrame) -> pd.Series:
+    """Summarize the dynamic tariff analysis result."""
+    summary = df.filter(like="cost").sum()
+
+    abs_smr2 = summary.filter(like="smr2").abs().sum()
+
+    summary["cost_electricity_total_smr2"] = summary.filter(like="smr2").sum()
+    summary["cost_electricity_total_smr3"] = summary.filter(like="smr3").sum()
+
+    summary["ratio"] = (
+        summary["cost_electricity_total_smr3"] - summary["cost_electricity_total_smr2"]
+    ) / abs_smr2
+
+    return summary

openenergyid/dyntar/models.py

@@ -0,0 +1,110 @@
+"""Models for dynamic tariff analysis."""
+
+from typing import Literal
+from pydantic import Field, conlist, confloat, BaseModel
+
+from openenergyid.models import TimeDataFrame
+from .const import Register
+
+
+RequiredColumns = Literal[
+    "electricity_delivered",
+    "electricity_exported",
+    "price_electricity_delivered",
+    "price_electricity_exported",
+    "RLP",
+    "SPP",
+]
+
+OutputColumns = Literal[
+    "electricity_delivered_smr3",
+    "electricity_exported_smr3",
+    "price_electricity_delivered",
+    "price_electricity_exported",
+    "RLP",
+    "SPP",
+    "electricity_delivered_smr2",
+    "electricity_exported_smr2",
+    "cost_electricity_delivered_smr2",
+    "cost_electricity_exported_smr2",
+    "cost_electricity_delivered_smr3",
+    "cost_electricity_exported_smr3",
+    "rlp_weighted_price_delivered",
+    "spp_weighted_price_exported",
+    "heatmap_delivered",
+    "heatmap_exported",
+    "heatmap_total",
+    "heatmap_delivered_description",
+    "heatmap_exported_description",
+    "heatmap_total_description",
+]
+
+
+class DynamicTariffAnalysisInput(TimeDataFrame):
+    """Input frame for dynamic tariff analysis."""
+
+    columns: list[RequiredColumns] = Field(
+        min_length=3,
+        max_length=len(RequiredColumns.__args__),
+        examples=[RequiredColumns.__args__],
+    )
+    data: list[
+        conlist(
+            item_type=confloat(allow_inf_nan=True),
+            min_length=3,
+            max_length=len(RequiredColumns.__args__),
+        )  # type: ignore
+    ] = Field(examples=[[0.0] * len(RequiredColumns.__args__)])
+
+    @property
+    def registers(self) -> list[Register]:
+        """Check which registers are present in the input data."""
+        registers = []
+        columns = list(self.columns)
+        # if "electricity_delivered", "price_electricity_delivered" and "RLP" are present
+        if all(
+            column in columns
+            for column in [
+                "electricity_delivered",
+                "price_electricity_delivered",
+                "RLP",
+            ]
+        ):
+            registers.append(Register.DELIVERY)
+        # if "electricity_exported", "price_electricity_exported" and "SPP" are present
+        if all(
+            column in columns
+            for column in ["electricity_exported", "price_electricity_exported", "SPP"]
+        ):
+            registers.append(Register.EXPORT)
+        return registers
+
+
+class DynamicTariffAnalysisOutputSummary(BaseModel):
+    """Summary of the dynamic tariff analysis output."""
+
+    cost_electricity_delivered_smr2: float | None = None
+    cost_electricity_delivered_smr3: float | None = None
+    cost_electricity_exported_smr2: float | None = None
+    cost_electricity_exported_smr3: float | None = None
+    cost_electricity_total_smr2: float | None = None
+    cost_electricity_total_smr3: float | None = None
+    ratio: float | None = None
+
+
+class DynamicTariffAnalysisOutput(TimeDataFrame):
+    """Output frame for dynamic tariff analysis."""
+
+    columns: list[OutputColumns] = Field(
+        min_length=1,
+        max_length=len(OutputColumns.__args__),
+        examples=[OutputColumns.__args__],
+    )
+    data: list[
+        conlist(
+            item_type=confloat(allow_inf_nan=True),
+            min_length=1,
+            max_length=len(OutputColumns.__args__),
+        )  # type: ignore
+    ] = Field(examples=[[0.0] * len(OutputColumns.__args__)])
+    summary: DynamicTariffAnalysisOutputSummary | None = None

openenergyid/energysharing/__init__.py

@@ -0,0 +1,12 @@
+"""Energy Sharing package."""
+
+from .main import calculate
+from .models import CalculationMethod, EnergySharingInput, EnergySharingOutput, KeyInput
+
+__all__ = [
+    "calculate",
+    "CalculationMethod",
+    "EnergySharingInput",
+    "EnergySharingOutput",
+    "KeyInput",
+]

openenergyid/energysharing/const.py

@@ -0,0 +1,8 @@
+"""Constants for the energysharing module."""
+
+GROSS_INJECTION = "Gross Injection"
+NET_INJECTION = "Net Injection"
+GROSS_OFFTAKE = "Gross Offtake"
+NET_OFFTAKE = "Net Offtake"
+KEY = "Key"
+SHARED_ENERGY = "Shared Energy"

openenergyid/energysharing/data_formatting.py

@@ -0,0 +1,69 @@
+"""Functions to create multi-indexed DataFrames for input and output data for energy sharing."""
+
+import pandas as pd
+from .const import GROSS_INJECTION, GROSS_OFFTAKE, KEY, NET_INJECTION, NET_OFFTAKE, SHARED_ENERGY
+
+
+def create_multi_index_input_frame(
+    gross_injection: pd.DataFrame,
+    gross_offtake: pd.DataFrame,
+    key: pd.DataFrame,
+) -> pd.DataFrame:
+    """Create a multi-indexed DataFrame with the input data for energy sharing."""
+    gross_injection = gross_injection.copy()
+    gross_offtake = gross_offtake.copy()
+    key = key.copy()
+
+    gross_injection.columns = pd.MultiIndex.from_product(
+        [[GROSS_INJECTION], gross_injection.columns]
+    )
+    gross_offtake.columns = pd.MultiIndex.from_product([[GROSS_OFFTAKE], gross_offtake.columns])
+    key.columns = pd.MultiIndex.from_product([[KEY], key.columns])
+
+    df = pd.concat([gross_injection, gross_offtake, key], axis=1)
+
+    return df
+
+
+def create_multi_index_output_frame(
+    net_injection: pd.DataFrame,
+    net_offtake: pd.DataFrame,
+    shared_energy: pd.DataFrame,
+) -> pd.DataFrame:
+    """Create a multi-indexed DataFrame with the output data for energy sharing."""
+    net_injection = net_injection.copy()
+    net_offtake = net_offtake.copy()
+    shared_energy = shared_energy.copy()
+
+    net_injection.columns = pd.MultiIndex.from_product([[NET_INJECTION], net_injection.columns])
+    net_offtake.columns = pd.MultiIndex.from_product([[NET_OFFTAKE], net_offtake.columns])
+    shared_energy.columns = pd.MultiIndex.from_product([[SHARED_ENERGY], shared_energy.columns])
+
+    df = pd.concat([net_injection, net_offtake, shared_energy], axis=1)
+
+    return df
+
+
+def result_to_input_for_reiteration(result: pd.DataFrame, key: pd.DataFrame) -> pd.DataFrame:
+    """Create a multi-indexed DataFrame with the input data for energy sharing after the first iteration."""
+    # We iterate again. The net injection of the previous result is taken as gross injection input
+    # And the net offtake is taken as the gross offtake input
+    # When a user's net offtake is 0, the key is set to 0; and the keys are re-normalized
+
+    gross_injection = result[NET_INJECTION].copy()
+    gross_offtake = result[NET_OFFTAKE].copy()
+
+    # Take the original key, but replace the value with 0.0 if result[NET_OFFTAKE] is 0.0
+
+    key = key.copy()
+    key = key.where(~result[NET_OFFTAKE].eq(0), 0)
+
+    # Re-normalize the keys
+
+    key = key.div(key.sum(axis=1), axis=0)
+
+    df = create_multi_index_input_frame(
+        gross_injection=gross_injection, gross_offtake=gross_offtake, key=key
+    )
+
+    return df

openenergyid/energysharing/main.py

@@ -0,0 +1,111 @@
+"""Main Calcuation Module for Energy Sharing."""
+
+import pandas as pd
+from .models import CalculationMethod
+from .const import GROSS_INJECTION, GROSS_OFFTAKE, KEY, NET_INJECTION, NET_OFFTAKE, SHARED_ENERGY
+from .data_formatting import create_multi_index_output_frame, result_to_input_for_reiteration
+
+
+def _calculate(df: pd.DataFrame, method: CalculationMethod) -> pd.DataFrame:
+    """Calculate the energy sharing for the given input data. This function is not iterative."""
+    # Step 1: Calculate the maximum available gross injection that can be shared
+    # A participant cannot share their injection with themselves
+
+    # Take the injection of P1, and divide it per participant as per their key
+
+    injections_to_share = []
+    rest = {}
+
+    for participant in df[GROSS_INJECTION].columns:
+        injection_to_share = df[GROSS_INJECTION][participant].copy()
+
+        key = df[KEY].copy()
+        if method == CalculationMethod.RELATIVE or method == CalculationMethod.OPTIMAL:
+            # Set the key of the current participant to 0
+            # Re-normalize the keys for the other participants
+            if participant in df[KEY].columns:
+                key.loc[:, participant] = 0
+                key = key.div(key.sum(axis=1), axis=0)
+
+        # Multiply injection_to_share with the key of each participant
+        shared_by_participant = (injection_to_share * key.T).T
+        shared_by_participant.fillna(0, inplace=True)
+
+        # Set the value for the current participant to 0
+        if participant in shared_by_participant.columns:
+            shared_by_participant.loc[:, participant] = 0
+
+        # Put the not shared injection in the rest
+        rest[participant] = injection_to_share - shared_by_participant.sum(axis=1)
+
+        injections_to_share.append(shared_by_participant)
+
+    # Sum the injections to share
+    max_allocated_injection = sum(injections_to_share)
+
+    # Concat the rest
+    injection_that_cannot_be_shared = pd.concat(rest, axis=1)
+
+    # Step 2: Calculate the Net Offtake, by assigning the injections to each participant
+    # But, a participant cannot receive more than their offtake
+
+    net_offtake = df[GROSS_OFFTAKE] - max_allocated_injection
+
+    # Sum all negative values into a column "Not Shared"
+    not_shared_after_assignment = net_offtake.clip(upper=0).sum(axis=1).abs()
+
+    # Clip the values to 0
+    net_offtake = net_offtake.clip(lower=0)
+
+    # Calculate the amount of actual shared energy
+    # This is the difference between the gross offtake and the net offtake
+    shared_energy = df[GROSS_OFFTAKE] - net_offtake
+
+    # Step 3: Assign the Rests back to the original injectors
+
+    # The energy that is not shared after assignment
+    # should be divided back to the original injectors
+    # A ratio of the original injection should be used
+
+    re_distributed_not_shared = (
+        (df[GROSS_INJECTION].T / df[GROSS_INJECTION].sum(axis=1)) * not_shared_after_assignment
+    ).T
+    re_distributed_not_shared.fillna(0, inplace=True)
+
+    # The nett injection is the sum of:
+    # the injection that cannot be shared to begin with
+    # (because participants cannot share with themselves)
+    # and the injection that cannot be shared after assignment
+    # (because participants cannot receive more than their offtake)
+
+    net_injection = injection_that_cannot_be_shared + re_distributed_not_shared
+
+    result = create_multi_index_output_frame(
+        net_injection=net_injection, net_offtake=net_offtake, shared_energy=shared_energy
+    )
+
+    return result
+
+
+def calculate(df: pd.DataFrame, method: CalculationMethod) -> pd.DataFrame:
+    """Calculate the energy sharing for the given input data.
+
+    This function is iterative if the method is optimal."""
+    result = _calculate(df, method)
+
+    if method in [CalculationMethod.FIXED, CalculationMethod.RELATIVE]:
+        return result
+
+    # Optimal method, we iterate until the amount of shared energy is 0
+    final_result = result.copy()
+    while not result[SHARED_ENERGY].eq(0).all().all():
+        df = result_to_input_for_reiteration(result, df[KEY])
+        result = _calculate(df, method)
+
+        # Add the result to the final result
+        # Overwrite NET_INJECTION and NET_OFFTAKE, Sum SHARED_ENERGY
+        final_result[NET_INJECTION] = result[NET_INJECTION]
+        final_result[NET_OFFTAKE] = result[NET_OFFTAKE]
+        final_result[SHARED_ENERGY] += result[SHARED_ENERGY]
+
+    return final_result