fram-core 0.0.0__py3-none-any.whl → 0.1.0__py3-none-any.whl

framcore/aggregators/WindSolarAggregator.py

@@ -0,0 +1,315 @@
+from __future__ import annotations
+
+from collections import defaultdict
+from typing import TYPE_CHECKING
+
+from framcore.aggregators._utils import (
+    _aggregate_costs,
+    _aggregate_result_volumes,
+    _aggregate_weighted_expressions,
+    _all_detailed_exprs_in_sum_expr,
+)
+from framcore.aggregators.Aggregator import Aggregator  # full import path so inheritance works
+from framcore.attributes import AvgFlowVolume, Cost
+from framcore.components import Component, Solar, Wind
+from framcore.curves import Curve
+from framcore.expressions import Expr, get_level_value
+from framcore.timeindexes import FixedFrequencyTimeIndex, SinglePeriodTimeIndex
+from framcore.timevectors import ConstantTimeVector, TimeVector
+
+if TYPE_CHECKING:
+    from framcore import Model
+
+
+class _WindSolarAggregator(Aggregator):
+    """
+    Aggregate Wind and Solar components into groups based on their power nodes.
+
+    Aggregation steps (self._aggregate):
+
+    1. Group components based on their power nodes (self._group_by_power_node):
+    2. Aggregate grouped components into a single aggregated component for each group (self._aggregate_groups):
+        - Max_capacity is calculated as the sum of the maximum capacity levels with weighted profiles.
+        - Variable operational costs (voc) are aggregated using weighted averages based on the weighting method (now only max_capacity supported).
+        - TODO: Add support for additional weighting methods (e.g. production instead of capacity).
+        - Production is aggregated as the sum of production levels with weighted profiles. TODO: Add possibility to skip results aggregation.
+    2a. Make new hydro module and delete original components from model data.
+    3. Add mapping from detailed to aggregated components to self._aggregation_map.
+
+
+    Disaggregation steps (self._disaggregate):
+
+    1. Restore original components from self._original_data. NB! Changes to aggregated modules are lost except for results (TODO)
+    2. Distribute production from aggregated components back to the original components:
+        - Results are weighted based on the weighting method (now only max_capacity supported).
+    3. Delete aggregated components from the model.
+
+    See Aggregator for general design notes and rules to follow when using Aggregators.
+
+    Attributes:
+        _data_dim (SinglePeriodTimeIndex | None): Data dimension for eager evaluation.
+        _scen_dim (FixedFrequencyTimeIndex | None): Scenario dimension for eager evaluation.
+        _grouped_components (dict[str, set[str]]): Mapping of aggregated components to their detailed components.  agg to detailed
+
+    Parent Attributes (see framcore.aggregators.Aggregator):
+
+        _is_last_call_aggregate (bool | None): Tracks whether the last operation was an aggregation.
+        _original_data (dict[str, Component | TimeVector | Curve | Expr] | None): Original detailed data before aggregation.
+        _aggregation_map (dict[str, set[str]] | None): Maps aggregated components to their detailed components. detailed to agg
+
+    """
+
+    def __init__(
+        self,
+        data_dim: SinglePeriodTimeIndex | None = None,
+        scen_dim: FixedFrequencyTimeIndex | None = None,
+    ) -> None:
+        """
+        Initialize Aggregator.
+
+        Args:
+            data_dim (SinglePeriodTimeIndex): Data dimension for eager evalutation.
+            scen_dim (FixedFrequencyTimeIndex): Scenario dimension for eager evalutation.
+
+        """
+        super().__init__()
+        self._data_dim = data_dim
+        self._scen_dim = scen_dim
+        self._grouped_components: dict[str, set[str]] = defaultdict(set)
+
+    def _aggregate(self, model: Model) -> None:
+        data = model.get_data()
+
+        # Group components by power node and remove groups of size 1
+        self._group_by_power_node(data)
+
+        # Aggregate the grouped components
+        self._aggregate_groups(model)
+
+        # Remove the original components from the model
+        for group_id in self._grouped_components:
+            for component_id in self._grouped_components[group_id]:
+                del data[component_id]
+
+        # Add mapping to self._aggregation_map
+        self._aggregation_map = {member_id: {group_id} for group_id, member_ids in self._grouped_components.items() for member_id in member_ids}
+
+    def _group_by_power_node(self, data: dict[str, Component | TimeVector | Curve | Expr]) -> None:
+        """Group components by their power node and remove groups with only one member."""
+        self._grouped_components.clear()
+        for name, obj in data.items():
+            if isinstance(obj, self._component_type):
+                power_node = obj.get_power_node()
+                if power_node is None:
+                    message = f"Component {name} has no power node defined. Cannot group by power node."
+                    raise ValueError(message)
+                group_id = f"Aggregated{self._component_type.__name__}{power_node}"
+                self._grouped_components[group_id].add(name)
+
+        for group_id in list(self._grouped_components.keys()):
+            if len(self._grouped_components[group_id]) == 1:
+                del self._grouped_components[group_id]
+
+    def _aggregate_groups(self, model: Model) -> None:
+        """Aggregate each group of components into a single component."""
+        for group_id, member_ids in self._grouped_components.items():
+            self._aggregate_group(model, group_id, member_ids)
+
+    def _aggregate_group(self, model: Model, group_id: str, member_ids: list[str]) -> None:
+        """Aggregate a group of components into a single component."""
+        self.send_info_event(f"{group_id} from {len(member_ids)} components.")
+        data = model.get_data()
+        members = [data[member_id] for member_id in member_ids]
+
+        # Weights
+        capacity_levels = [member.get_max_capacity().get_level() for member in members]
+        capacity_profiles = [member.get_max_capacity().get_profile() for member in members]
+        vocs = [member.get_voc() for member in members]
+        if any(capacity_profiles) or any(vocs):  # only calc capacity weights if needed
+            capacity_level_values = [get_level_value(cl, model, "MW", self._data_dim, self._scen_dim, True) for cl in capacity_levels]
+            if sum(capacity_level_values) == 0.0:
+                message = "All grouped components do not contribute to weights (capacity = 0). Simplified aggregation."
+                self.send_warning_event(message)
+
+        # Production capacity
+        capacity_levels = [member.get_max_capacity().get_level() for member in members]
+        capacity_level = sum(capacity_levels)
+
+        capacity_profile = None
+        if any(capacity_profiles) and (sum(capacity_level_values) != 0.0):
+            one_profile = Expr(src=ConstantTimeVector(1.0, is_zero_one_profile=False), is_profile=True)
+            capacity_profiles = [profile if profile else one_profile for profile in capacity_profiles]
+            capacity_profile = _aggregate_weighted_expressions(capacity_profiles, capacity_level_values)
+
+        sum_capacity = AvgFlowVolume(capacity_level, capacity_profile)
+
+        # Power node
+        power_node = members[0].get_power_node()
+
+        # Production
+        productions = [member.get_production() for member in members]
+        production = _aggregate_result_volumes(model, productions, "MW", self._data_dim, self._scen_dim, group_id, member_ids)
+
+        # Variable operational cost
+        voc = None
+        if any(vocs) and (sum(capacity_level_values) != 0.0):
+            voc_level, voc_profile, voc_intercept = _aggregate_costs(model, vocs, outside_weights=capacity_level_values, weight_unit="EUR/MWh")
+            voc = Cost(voc_level, voc_profile, voc_intercept)
+
+        new_wind = Wind(
+            power_node=power_node,
+            max_capacity=sum_capacity,
+            voc=voc,
+            production=production,
+        )
+
+        data[group_id] = new_wind
+
+    def _disaggregate(
+        self,
+        model: Model,
+        original_data: dict[str, Component | TimeVector | Curve | Expr],
+    ) -> None:
+        new_data = model.get_data()
+
+        deleted_group_names = self._get_deleted_group_components(new_data)
+        agg_components = {key: new_data.pop(key) for key in self._grouped_components if key not in deleted_group_names}  # isolate agg modules out of new_data
+
+        # Reinstate original detailed components that are not fully deleted
+        for detailed_key, agg_keys in self._aggregation_map.items():
+            if agg_keys and all(key in deleted_group_names for key in agg_keys):
+                continue
+            new_data[detailed_key] = original_data[detailed_key]
+
+        # Set production results in detailed modules
+        for agg_key, detailed_keys in self._grouped_components.items():
+            if agg_key in deleted_group_names:
+                continue
+
+            agg_production_level = agg_components[agg_key].get_production().get_level()
+            if agg_production_level is None:  # keep original production if agg has no production defined
+                continue
+            if len(detailed_keys) == 1:  # only one detailed module, set production directly
+                new_data[detailed_key].get_production().set_level(agg_production_level)
+                continue
+            detailed_production_levels = [new_data[detailed_key].get_production().get_level() for detailed_key in detailed_keys]
+            if any(detailed_production_levels) and not all(
+                detailed_production_levels,
+            ):  # if some but not all detailed components have production defined, skip setting production
+                missing = [detailed_key for detailed_key, level in zip(detailed_keys, detailed_production_levels, strict=False) if not level]
+                message = f"Some but not all grouped components have production defined. Production not disaggregated for {agg_key}, missing for {missing}."
+                self.send_warning_event(message)
+                continue
+            if _all_detailed_exprs_in_sum_expr(agg_production_level, detailed_production_levels):  # if agg production is sum of detailed levels,  keep original
+                continue
+            capacity_levels = [new_data[detailed_key].get_max_capacity().get_level() for detailed_key in detailed_keys]
+            capacity_level_values = [get_level_value(cl, model, "MW", self._data_dim, self._scen_dim, True) for cl in capacity_levels]
+            capacity_level_value_weights = [cl / sum(capacity_level_values) for cl in capacity_level_values]
+            production_weights = {detailed_key: weight for detailed_key, weight in zip(detailed_keys, capacity_level_value_weights, strict=False)}
+            for detailed_key in detailed_keys:
+                self._set_weighted_production(new_data[detailed_key], agg_components[agg_key], production_weights[detailed_key])  # default
+
+    def _get_deleted_group_components(self, new_data: dict[str, Component | TimeVector | Curve | Expr]) -> set[str]:
+        """Identify which aggregated components have been deleted from the model."""
+        deleted_group_names: set[str] = set()
+
+        for group_name in self._grouped_components:
+            if group_name not in new_data:
+                deleted_group_names.add(group_name)
+                continue
+
+        return deleted_group_names
+
+    def _set_weighted_production(self, detailed_component: Component, agg_component: Component, production_weight: float) -> None:
+        """Set production level and profile for detailed components based on aggregated component."""
+        agg_production_level = agg_component.get_production().get_level()
+        agg_production_profile = agg_component.get_production().get_profile()
+        production_level = production_weight * agg_production_level
+        detailed_component.get_production().set_level(production_level)
+        detailed_component.get_production().set_profile(agg_production_profile)
+
+
+class WindAggregator(_WindSolarAggregator):
+    """
+    Aggregate Wind components into groups based on their power nodes.
+
+    Aggregation steps (self._aggregate):
+
+    1. Group components based on their power nodes (self._group_by_power_node):
+    2. Aggregate grouped components into a single aggregated component for each group (self._aggregate_groups):
+        - Max_capacity is calculated as the sum of the maximum capacity levels with weighted profiles.
+        - Variable operation costs (voc) are aggregated using weighted averages based on the weighting method (now ony max_capacity supported).
+        - TODO: Add support for additional weighting methods (e.g. production instead of capacity).
+        - Production is aggregated as the sum of production levels with weighted profiles.
+    2a. Make new hydro module and delete original components from model data.
+    3. Add mapping from detailed to aggregated components to self._aggregation_map.
+
+
+    Disaggregation steps (self._disaggregate):
+
+    1. Restore original components from self._original_data. NB! Changes to aggregated modules are lost except for results.
+    2. Distribute production from aggregated components back to the original components:
+        - Results are weighted based on the weighting method (now ony max_capacity supported).
+    3. Delete aggregated components from the model.
+
+
+    See Aggregator for general design notes and rules to follow when using Aggregators.
+
+    Attributes:
+        _data_dim (SinglePeriodTimeIndex | None): Data dimension for eager evaluation.
+        _scen_dim (FixedFrequencyTimeIndex | None): Scenario dimension for eager evaluation.
+        _grouped_components (dict[str, set[str]]): Mapping of aggregated components to their detailed components.  agg to detailed
+
+
+    Parent Attributes (see framcore.aggregators.Aggregator):
+
+        _is_last_call_aggregate (bool | None): Tracks whether the last operation was an aggregation.
+        _original_data (dict[str, Component | TimeVector | Curve | Expr] | None): Original detailed data before aggregation.
+        _aggregation_map (dict[str, set[str]] | None): Maps aggregated components to their detailed components. detailed to agg
+
+    """
+
+    _component_type = Wind
+
+
+class SolarAggregator(_WindSolarAggregator):
+    """
+    Aggregate Solar components into groups based on their power nodes.
+
+    Aggregation steps (self._aggregate):
+
+    1. Group components based on their power nodes (self._group_by_power_node):
+    2. Aggregate grouped components into a single aggregated component for each group (self._aggregate_groups):
+        - Max_capacity is calculated as the sum of the maximum capacity levels with weighted profiles.
+        - Variable operation costs (voc) are aggregated using weighted averages based on the weighting method (now ony max_capacity supported).
+        - TODO: Add support for additional weighting methods (e.g. production instead of capacity).
+        - Production is aggregated as the sum of production levels with weighted profiles.
+    2a. Make new hydro module and delete original components from model data.
+    3. Add mapping from detailed to aggregated components to self._aggregation_map.
+
+
+    Disaggregation steps (self._disaggregate):
+
+    1. Restore original components from self._original_data. NB! Changes to aggregated modules are lost except for results.
+    2. Distribute production from aggregated components back to the original components:
+        - Results are weighted based on the weighting method (now ony max_capacity supported).
+    3. Delete aggregated components from the model.
+
+
+    See Aggregator for general design notes and rules to follow when using Aggregators.
+
+    Attributes:
+        _data_dim (SinglePeriodTimeIndex | None): Data dimension for eager evaluation.
+        _scen_dim (FixedFrequencyTimeIndex | None): Scenario dimension for eager evaluation.
+        _grouped_components (dict[str, set[str]]): Mapping of aggregated components to their detailed components.  agg to detailed
+
+
+    Parent Attributes (see framcore.aggregators.Aggregator):
+
+        _is_last_call_aggregate (bool | None): Tracks whether the last operation was an aggregation.
+        _original_data (dict[str, Component | TimeVector | Curve | Expr] | None): Original detailed data before aggregation.
+        _aggregation_map (dict[str, set[str]] | None): Maps aggregated components to their detailed components. detailed to agg
+
+    """
+
+    _component_type = Solar

framcore/aggregators/__init__.py

@@ -0,0 +1,13 @@
+# framcore/aggregators/__init__.py
+from framcore.aggregators.Aggregator import Aggregator
+from framcore.aggregators.HydroAggregator import HydroAggregator
+from framcore.aggregators.NodeAggregator import NodeAggregator
+from framcore.aggregators.WindSolarAggregator import WindAggregator, SolarAggregator
+
+__all__ = [
+    "Aggregator",
+    "HydroAggregator",
+    "NodeAggregator",
+    "SolarAggregator",
+    "WindAggregator",
+]

framcore/aggregators/_utils.py

@@ -0,0 +1,184 @@
+"""Utility functions for aggregation and disaggregation of model attributes."""
+
+from math import isclose
+
+from framcore.attributes import AvgFlowVolume, Cost, LevelProfile
+from framcore.expressions import Expr, get_level_value
+from framcore.Model import Model
+from framcore.timeindexes import FixedFrequencyTimeIndex, SinglePeriodTimeIndex
+from framcore.timevectors import ConstantTimeVector
+
+
+# Aggregation util functions ---------------------------------------------------------------------
+# Only for results
+def _aggregate_result_volumes(
+    model: Model,
+    volumes: list[AvgFlowVolume],
+    weight_unit: str,
+    data_dim: SinglePeriodTimeIndex,
+    scen_dim: FixedFrequencyTimeIndex,
+    group_id: str,
+    grouped_ids: list[str],
+) -> AvgFlowVolume | None:
+    """Aggregate result volumes for grouped components. If some but not all grouped components have volume defined, send warning and return None."""
+    sum_volume = None
+    if all(volume.get_level() for volume in volumes):
+        level, profiles, weights = _get_level_profile_weights_volumes_from_results(model, volumes, weight_unit, data_dim, scen_dim)
+        profile = _aggregate_weighted_expressions(profiles, weights)
+        sum_volume = AvgFlowVolume(level=level, profile=profile)
+    elif any(volume.get_level() for volume in volumes):
+        missing = [grouped_id for grouped_id, volume in zip(grouped_ids, volumes, strict=False) if not volume.get_level()]
+        message = f"Some but not all grouped components have volume defined. Volume not aggregated for {group_id}, missing volume for {missing}."
+        model.send_warning_event(message)
+    return sum_volume
+
+
+def _get_level_profile_weights_volumes_from_results(
+    model: Model,
+    volumes: list[AvgFlowVolume],
+    weight_unit: str,
+    data_dim: SinglePeriodTimeIndex,
+    scen_dim: FixedFrequencyTimeIndex,
+) -> tuple[Expr, list[Expr], list[float]]:
+    """
+    Get aggregated level, and profiles with weights from list of volumes.
+
+    Two cases:
+    1. All volumes have previously been disaggregated (levels are weight * LevelExpr). Can be aggregated more efficiently.
+    2. Default: sum levels and get weights from level values.
+    """
+    levels = [volume.get_level() for volume in volumes]
+    if all(_is_weight_flow_expr(level) for level in levels):
+        return _get_level_profile_weights_from_disagg_levelprofiles(model, volumes, data_dim, scen_dim)
+    level = sum(levels)
+    profiles = [volume.get_profile() for volume in volumes]
+    weights = [get_level_value(level, model, weight_unit, data_dim, scen_dim, False) for level in levels]
+    return level, profiles, weights
+
+
+def _get_level_profile_weights_from_disagg_levelprofiles(
+    model: Model,
+    objs: list[LevelProfile],
+    data_dim: SinglePeriodTimeIndex,
+    scen_dim: FixedFrequencyTimeIndex,
+) -> tuple[Expr, list[Expr], list[float]]:
+    """
+    Get aggregated level, and profiles with weights from disaggregated LevelProfiles with Level = weight * LevelExpr.
+
+    Two cases:
+    - If all sum weights are 1, return sum of levels and profiles with weights 1.
+    - Otherwise, return weighted sum of levels, and profiles with weights from level expressions.
+    """
+    weights = _get_weights_from_levelprofiles(model, objs, data_dim, scen_dim)
+    if all(isclose(weight, 1.0, rel_tol=1e-6) for weight in weights.values()):
+        level = sum([obj[0] for obj in weights])  # all weights 1, return sum of objs
+        profiles = [obj[1] for obj in weights]
+        weights = [1.0 for _ in weights]
+        return level, profiles, weights
+    level = sum([weight * obj[0] for obj, weight in weights.items()])  # return weighted sum of objs
+    profiles = [obj[1] for obj in weights]
+    weights = [weight for weight in weights.values()]
+    return level, profiles, weights
+
+
+# Generic
+def _aggregate_weighted_expressions(exprs: list[Expr], weights: list[float]) -> Expr:
+    """Calculate weighted average of expressions with sum of weights = 1. If all profiles are identical, return that expr."""
+    if any(e is None for e in exprs):
+        message = f"Cannot aggregate profiles if some profiles are None: {exprs}."
+        raise ValueError(message)
+    if all(exprs[0] == e for e in exprs):
+        return exprs[0]
+    weights_dict = dict()
+    for e, w in zip(exprs, weights, strict=True):
+        if e not in weights_dict:
+            weights_dict[e] = 0.0
+        weights_dict[e] += w / sum(weights)
+    return sum([w * e for e, w in weights_dict.items()])
+
+
+def _is_weight_flow_expr(expr: Expr) -> bool:
+    """Check if expr is weight * FlowExpr, which indicates it comes from disaggregation."""
+    if expr.is_leaf():
+        return False
+    ops, args = expr.get_operations(expect_ops=True, copy_list=False)
+    if ops != "*" or len(args) != 2 or not args[0].is_leaf():  # noqa E501
+        return False
+    if not (not args[0].is_level() and not args[0].is_profile()):
+        return False
+    return args[1].is_flow()
+
+
+def _get_weights_from_levelprofiles(
+    model: Model,
+    objs: list[LevelProfile],
+    data_dim: SinglePeriodTimeIndex,
+    scen_dim: FixedFrequencyTimeIndex,
+) -> dict[tuple[Expr, Expr], float]:
+    """Get sum of weights for each unique (level, profile) pair from disaggregated LevelProfiles with Level = weight * LevelExpr."""
+    weights = dict()
+    for obj in objs:
+        ops, args = obj.get_level().get_operations(expect_ops=True, copy_list=False)
+        key = (args[1], obj.get_profile())
+        if key not in weights:
+            weights[key] = 0.0
+        weights[key] += get_level_value(args[0], model, unit=None, data_dim=data_dim, scen_dim=scen_dim, is_max=False)
+
+    for key in weights:  # noqa: PLC0206
+        if isclose(weights[key], 1.0, rel_tol=1e-6):
+            weights[key] = 1.0
+
+    if any(weight > 1.0 for weight in weights.values()):
+        message = f"Sum of weights are over 1 for some level/profile combinations: {weights}."
+        raise ValueError(message)
+
+    return weights
+
+
+def _aggregate_costs(
+    model: Model,
+    costs: list[Cost],
+    weights: list[float],
+    weight_unit: str,
+    data_dim: SinglePeriodTimeIndex,
+    scen_dim: FixedFrequencyTimeIndex,
+) -> tuple[Expr, Expr | None, Expr | None]:
+    """Aggregate a list of costs with weights. Aggregated cost has weighted level, profile and intercept."""
+    # Initialize default values
+    aggregated_level = None
+    aggregated_profile = None
+    aggregated_intercept = None
+
+    # Handle levels
+    zero_level = Expr(ConstantTimeVector(0.0, is_max_level=False), is_level=True)
+    cost_levels = [cost.get_level() if cost.get_level() else zero_level for cost in costs]
+    aggregated_level = _aggregate_weighted_expressions(cost_levels, weights)
+
+    # Handle profiles
+    cost_profiles = [cost.get_profile() for cost in costs]
+    if any(cost_profiles):
+        one_profile = Expr(src=ConstantTimeVector(1.0, is_zero_one_profile=False), is_profile=True)
+        cost_profiles = [profile if profile else one_profile for profile in cost_profiles]
+        cost_level_values = [get_level_value(level, model, weight_unit, data_dim, scen_dim, False) for level in cost_levels]
+        profile_weights = [clv * weight for clv, weight in zip(cost_level_values, weights, strict=True)]
+        aggregated_profile = _aggregate_weighted_expressions(cost_profiles, profile_weights)
+
+    # Handle intercepts
+    cost_intercepts = [cost.get_intercept() for cost in costs]
+    if any(cost_intercepts):
+        one_profile = Expr(src=ConstantTimeVector(1.0, is_zero_one_profile=False), is_profile=True)
+        cost_intercepts = [intercept if intercept else one_profile for intercept in cost_intercepts]
+        aggregated_intercept = _aggregate_weighted_expressions(cost_intercepts, weights)
+
+    return aggregated_level, aggregated_profile, aggregated_intercept
+
+
+# Disaggregation util functions ---------------------------------------------------------------------
+def _all_detailed_exprs_in_sum_expr(expr: Expr, detailed_exprs: list[Expr]) -> bool:
+    """Check if expr is sum of detailed exprs. Does not handle the case where len(exprs) == 1."""
+    if expr.is_leaf():
+        return False
+    ops, args = expr.get_operations(expect_ops=True, copy_list=False)
+    if ops != "+" or len(args) != len(detailed_exprs):
+        return False
+    return all(arg in detailed_exprs for arg in args)