fram-core 0.1.0a1__py3-none-any.whl → 0.1.1__py3-none-any.whl

framcore/aggregators/NodeAggregator.py

@@ -7,24 +7,55 @@ from typing import TYPE_CHECKING
 from framcore.aggregators import Aggregator
 from framcore.aggregators._utils import _aggregate_costs
 from framcore.attributes import MaxFlowVolume, Price
-from framcore.components import Component, Demand, Node, Transmission, Flow
+from framcore.components import Component, Demand, Flow, Node, Transmission
 from framcore.curves import Curve
 from framcore.expressions import Expr
 from framcore.metadata import Member, Meta
 from framcore.timeindexes import FixedFrequencyTimeIndex, SinglePeriodTimeIndex
 from framcore.timevectors import TimeVector
-from framcore.utils import get_component_to_nodes, get_transports_by_commodity, get_supported_components, get_flow_infos, get_node_to_commodity
-
-# TODO: Support internal loss demand
-# TODO: Document method appropriate place (which docstring? module? class? __init__? _aggregate?)
-# TODO: transfer member metadata to internal loss Demand
+from framcore.utils import get_component_to_nodes, get_flow_infos, get_node_to_commodity, get_supported_components, get_transports_by_commodity
 
 if TYPE_CHECKING:
     from framcore import Model
 
 
 class NodeAggregator(Aggregator):
-    """Aggregate groups of nodes for a commodity. Subclass of Aggregator."""
+    """
+    Aggregate groups of Nodes for a commodity. Subclass of Aggregator.
+
+    Aggregation steps (self._aggregate):
+
+    1. Map all Components to their Nodes of the correct commodity if they are referencing any. This is important to redirect all references to the
+        new Nodes after aggregation.
+    2. Create mapping of what members the new Nodes will be aggregated from. This step also does alot of error handling and checks the validity of the
+        metadata and groupings. Raises error if:
+        - Nodes do not have any metadata for the meta key.
+        - Nodes have the wrong metadata object type for the meta key (must be Member).
+        - Exogenous Nodes are grouped together for aggregation with endogenous Nodes.
+    3. Initialize new Node objects and set prices and exogenous status. Prices are calculated as a weighted average of all the member Node prices.
+    4. Old Nodes are deleted from the Model data, after which the aggregated Node is added, and references in the rest of the system are updated to point to
+        the new Node.
+    5. Handling of transports: All Components which transport the same commodity as the aggregated Nodes are analysed. If the two Nodes they connect is now
+        the same aggregated Node, the transpart is 'internal' meaning it is now operating within a Node. If the transport Component is lossy, it is replaced
+        by a Demand Component representing the commodity consumption caused by the loss. All internal transports are afterwards deleted.
+
+
+    Disaggregation steps (self._aggregate):
+
+    1. Collect set of Nodes group keys for which have been either removed from the Model data or changed to reference something other than Nodes.
+    2. Validate that IDs of Nodes to be restored have not been used to reference something else in the meantime.
+    3. Delete the aggregated Nodes and restore the old Nodes to the Model. Also copy shadow price results from the aggregated Nodes to the disaggregated.
+        NB! This will overwrite the possible previous shadow prices of the original disaggregated Nodes.
+    4. Restore the references in all objects to the disaggregated Nodes. A mapping created during aggregation is used for this.
+    5. Validate that no restorable internal transports has a name conflict with existing objects in the Model.
+        NB! an internal transport is not restorable if one or both of its referenced Nodes have been removed from the Model or is now referencing another
+        object. See step 1.
+    6. Restore all the restorable internal transports from the original data.
+    7. Delete the aggregation-created Demand objects representing internal transports.
+
+    See Aggregator for general design notes and rules to follow when using Aggregators.
+
+    """
 
     def __init__(
         self,
@@ -125,16 +156,16 @@ class NodeAggregator(Aggregator):
         out: set[str] = set()
         nodes_and_flows = get_supported_components(components, supported_types=(Node, Flow), forbidden_types=tuple())
         node_to_commodity = get_node_to_commodity(nodes_and_flows)
-        for flow in nodes_and_flows.values():            
+        for flow in nodes_and_flows.values():
             if not isinstance(flow, Flow):
                 continue
             flow_infos = get_flow_infos(flow, node_to_commodity)
-            if not len(flow_infos) == 1:
+            if len(flow_infos) != 1:
                 continue
             flow_info = flow_infos[0]
             if flow_info.category != "direct_out":
                 continue
-            if flow_info.commodity_out != self._commodity: 
+            if flow_info.commodity_out != self._commodity:
                 continue
             demand = flow
             for key in demand.get_meta_keys():
@@ -142,7 +173,6 @@ class NodeAggregator(Aggregator):
                 if isinstance(meta, Member):
                     out.add(key)
         return out
-                
 
     def _add_internal_transport_demands(
         self,
@@ -163,7 +193,9 @@ class NodeAggregator(Aggregator):
         for key in self._internal_transports:
             transport = components[key]
             from_node, to_node = transports[key]
-            assert from_node == to_node, f"{from_node}, {to_node}"
+            assert from_node == to_node, (
+                f"Transport {key} added to internal transport when it should not. Source node {from_node}, and destination node {to_node} are not the same."
+            )
             node = from_node
 
             transport: Transmission
@@ -192,13 +224,15 @@ class NodeAggregator(Aggregator):
                     ),
                 )
 
-                for meta_key in demand_member_meta_keys:
+                for meta_key in demand_member_meta_keys:  # transfer member metadata to internal loss Demand
                     internal_losses_demand.add_meta(meta_key, Member("InternalTransportLossFromNodeAggregator"))
 
                 demand_key = key + "_InternalTransportLossDemand_" + node
 
                 self._internal_transport_demands.add(demand_key)
-                assert demand_key not in data, f"{demand_key}"
+                if demand_key in data:
+                    msg = f"Could not use key {demand_key} for internal transport demand because it already exists in the Model."
+                    raise KeyError(msg)
                 data[demand_key] = internal_losses_demand
 
     def _delete_internal_transports(
@@ -227,6 +261,13 @@ class NodeAggregator(Aggregator):
         data = model.get_data()
         weights = [1.0 / len(member_node_names)] * len(member_node_names)
         prices = [data[key].get_price() for key in member_node_names]
+
+        exogenous = [data[key].is_exogenous() for key in member_node_names]
+        if all(exogenous):
+            group_node.set_exogenous()
+        elif any(exogenous):
+            message = f"Only some member Nodes of group {group_node} are exogenous. This is ambiguous. Either all or none must be exogenous."
+            raise ValueError(message)
         if all(prices):
             level, profile, intercept = _aggregate_costs(
                 model=model,
@@ -241,7 +282,7 @@ class NodeAggregator(Aggregator):
             group_node.get_price().set_intercept(intercept)
         elif any(prices):
             missing = [key for key in member_node_names if data[key].get_price() is None]
-            self.send_warning_event(f"Only some member nodes of group {group_node} have a Price, skip aggregate prices. Missing: {missing}")
+            self.send_warning_event(f"Only some member Nodes of group {group_node} have a Price, skip aggregate prices. Missing: {missing}")
 
     def _replace_node(
         self,
@@ -316,17 +357,11 @@ class NodeAggregator(Aggregator):
 
         for group_name in exogenous_groups:  # Check exogenous groups.
             node_keys = grouped_nodes[group_name]
-            if len(node_keys) != 1:  # allow unchanged or renamed exogenous Nodes.
-                self._errors.add(
-                    f"Group {group_name} contains an exogenous Node and must therefore contain only one Node."
-                    " Exogenous Nodes cannot be grouped together with other Nodes.",
-                )
-                # For if we want to allow pure exogenous groups.
-                # for node_key in node_keys:
-                #     node: Node = components[node_key]
-                #     if not node.is_exogenous():
-                #         self._errors.add(f"Group {group_name} contains both exogenous and endogenous Nodes. This is not allowed.")
-                #         break
+            if len(node_keys) > 1:  # allow unchanged or renamed exogenous Nodes.
+                # We allow pure exogenous groups.
+                exogenous = [components[node_key].is_exogenous() for node_key in node_keys]
+                if (not all(exogenous)) and any(exogenous):
+                    self._errors.add(f"Group {group_name} contains both exogenous and endogenous Nodes. This is ambiguous and therefore not allowed.")
 
         # remove single groups with unchanged names and check for duplicated names
         for group_name, node_keys in grouped_nodes.items():
@@ -359,7 +394,7 @@ class NodeAggregator(Aggregator):
                 flipped[member].add(group)
         for k, v in flipped.items():
             if len(v) > 1:
-                self._errors.add(f"Node {k} belong to more than one group {v}")
+                self._errors.add(f"Node {k} belongs to more than one group {v}")
 
     def _disaggregate(
         self,
@@ -393,7 +428,7 @@ class NodeAggregator(Aggregator):
 
             group_node = new_data[group_name]
 
-            if not isinstance(group_node, Node):
+            if not (isinstance(group_node, Node) and group_node.get_commodity() == self._commodity):
                 deleted_group_names.add(group_name)
 
         return deleted_group_names
@@ -409,7 +444,7 @@ class NodeAggregator(Aggregator):
             for key in member_node_names:
                 if key in new_data:
                     obj = new_data[key]
-                    if not isinstance(obj, Node) and obj.get_commodity() == self._commodity:
+                    if not (isinstance(obj, Node) and obj.get_commodity() == self._commodity):
                         typ = type(obj).__name__
                         message = f"Restoring node {key} from group node {group_name} failed because model already stores object of {typ} with that name."
                         self._errors.add(message)
@@ -463,7 +498,7 @@ class NodeAggregator(Aggregator):
             if key in new_data:
                 obj = new_data[key]
                 typ = type(obj).__name__
-                message = f"Restoring deleted transport {key} from group node {group_name} failed becausemodel already stores object of {typ} with that name."
+                message = f"Restoring deleted transport {key} from group node {group_name} failed because model already stores object of {typ} with that name."
                 self._errors.add(message)
 
         self._report_errors(self._errors)

framcore/aggregators/WindSolarAggregator.py

@@ -23,9 +23,10 @@ if TYPE_CHECKING:
 
 class _WindSolarAggregator(Aggregator):
     """
-    Aggregate components into groups based on their power nodes.
+    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.
@@ -35,21 +36,15 @@ class _WindSolarAggregator(Aggregator):
     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.
 
-    Comments:
-        - It is recommended to only use the same aggregator type once on the same components of a model. If you want to go from one aggregation level to
-        another, it is better to use model.disaggregate first and then aggregate again. This is to keep the logic simple and avoid complex expressions.
-        We have also logic that recognises if result expressions come from aggregations or disaggregations. When aggregating or disaggregating these,
-        we can go back to the original results rather than setting up complex expressions that for examples aggregates the disaggregated results.
-        - Levels and profiles are aggregated separately, and then combined into attributes.
-        - We have chosen to eagerly evaluate weights for aggregation and disaggregation of levels and profiles. This is a balance between eagerly evaluating
-        everything, and setting up complex expressions. Eagerly evaluating everything would require setting up new timevectors after eager evaluation, which
-        is not ideal. While setting up complex expressions gives expressions that are harder to work with and slower to query from.
+    See Aggregator for general design notes and rules to follow when using Aggregators.
 
     Attributes:
         _data_dim (SinglePeriodTimeIndex | None): Data dimension for eager evaluation.
@@ -57,6 +52,7 @@ class _WindSolarAggregator(Aggregator):
         _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
@@ -235,9 +231,10 @@ class _WindSolarAggregator(Aggregator):
 
 class WindAggregator(_WindSolarAggregator):
     """
-    Aggregate components into groups based on their power nodes.
+    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.
@@ -247,28 +244,25 @@ class WindAggregator(_WindSolarAggregator):
     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.
 
-    Comments:
-        - It is recommended to only use the same aggregator type once on the same components of a model. If you want to go from one aggregation level to
-        another, it is better to use model.disaggregate first and then aggregate again. This is to keep the logic simple and avoid complex expressions.
-        We have also logic that recognises if result expressions come from aggregations or disaggregations. When aggregating or disaggregating these,
-        we can go back to the original results rather than setting up complex expressions that for examples aggregates the disaggregated results.
-        - Levels and profiles are aggregated separately, and then combined into attributes.
-        - We have chosen to eagerly evaluate weights for aggregation of levels and profiles, and disaggregation. This is a balance between eagerly evaluating
-        everything, and setting up complex expressions. Eagerly evaluating everything would require setting up new timevectors after eager evaluation, which
-        is not ideal. While setting up complex expressions gives expressions that are harder to work with and slower to query from.
+
+    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
@@ -280,9 +274,10 @@ class WindAggregator(_WindSolarAggregator):
 
 class SolarAggregator(_WindSolarAggregator):
     """
-    Aggregate components into groups based on their power nodes.
+    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.
@@ -292,28 +287,25 @@ class SolarAggregator(_WindSolarAggregator):
     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.
 
-    Comments:
-        - It is recommended to only use the same aggregator type once on the same components of a model. If you want to go from one aggregation level to
-        another, it is better to use model.disaggregate first and then aggregate again. This is to keep the logic simple and avoid complex expressions.
-        We have also logic that recognises if result expressions come from aggregations or disaggregations. When aggregating or disaggregating these,
-        we can go back to the original results rather than setting up complex expressions that for examples aggregates the disaggregated results.
-        - Levels and profiles are aggregated separately, and then combined into attributes.
-        - We have chosen to eagerly evaluate weights for aggregation of levels and profiles, and disaggregation. This is a balance between eagerly evaluating
-        everything, and setting up complex expressions. Eagerly evaluating everything would require setting up new timevectors after eager evaluation, which
-        is not ideal. While setting up complex expressions gives expressions that are harder to work with and slower to query from.
+
+    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

framcore/attributes/Arrow.py

@@ -19,7 +19,9 @@ class Arrow(Base):
     """
     Arrow class is used by Flows to represent contribution of its commodity to Nodes.
 
-    coefficient = conversion * (1 / efficiency) * (1 - loss)
+    The Arrow has direction to determine input or output (is_ingoing), and parameters for the contribution of the Flow to the Node.
+    The main parameters are conversion, efficiency and loss which together form the coefficient = conversion * (1 / efficiency) * (1 - loss)
+    Arrow has its own implementation of get_scenario_vector and get_data_value to calculate the coefficient shown above.
     """
 
     def __init__(
@@ -102,7 +104,7 @@ class Arrow(Base):
         """Get set of units behind conversion level expr (if any)."""
         if self._conversion is None:
             return set()
-        return self._conversion.get_level_unit_set()
+        return self._conversion.get_level_unit_set(db)
 
     def get_profile_timeindex_set(
         self,
@@ -125,7 +127,7 @@ class Arrow(Base):
             s.update(self._efficiency.get_profile_timeindex_set(db))
         return s
 
-    def get_scenario_vector(
+    def get_scenario_vector(  # noqa: C901, PLR0915
         self,
         db: QueryDB | Model,
         scenario_horizon: FixedFrequencyTimeIndex,
@@ -298,7 +300,7 @@ class Arrow(Base):
 
     def add_loaders(self, loaders: set[Loader]) -> None:
         """Add all loaders stored in attributes to loaders."""
-        from framcore.utils import add_loaders_if  # noqa: PLC0415
+        from framcore.utils import add_loaders_if
 
         add_loaders_if(loaders, self.get_conversion())
         add_loaders_if(loaders, self.get_loss())

framcore/attributes/ElasticDemand.py

@@ -14,17 +14,7 @@ if TYPE_CHECKING:
 
 
 class ElasticDemand(Base):
-    """
-    ElasticDemand class representing the price elasticity of a demand Component.
-
-    Attributes:
-        _price_elasticity: The price elasticity factor of the demand consumer.
-        _min_price: Lower limit for price elasticity.
-        _normal_price: Price for which the demand is inelastic. If it deviates from this price, the consumer will adjust
-                       it's consumption according to the _price_elasticity factor.
-        _max_price: Upper limit for price elasticity / reservation price level.
-
-    """
+    """ElasticDemand class representing the price elasticity of a demand Component."""
 
     def __init__(
         self,
@@ -33,7 +23,17 @@ class ElasticDemand(Base):
         normal_price: Price,
         max_price: Price,
     ) -> None:
-        """Initialize the ElasticDemand class."""
+        """
+        Initialize the ElasticDemand class.
+
+        Args:
+            price_elasticity (Elasticity): The price elasticity factor of the demand consumer.
+            min_price (Price): Lower limit for price elasticity.
+            normal_price (Price): Price for which the demand is inelastic. If it deviates from this price, the consumer will adjust
+                                  it's consumption according to the _price_elasticity factor.
+            max_price (Price): Upper limit for price elasticity / reservation price level.
+
+        """
         self._check_type(price_elasticity, Elasticity)
         self._check_type(min_price, Price)
         self._check_type(normal_price, Price)
@@ -82,7 +82,7 @@ class ElasticDemand(Base):
 
     def add_loaders(self, loaders: set[Loader]) -> None:
         """Add all loaders stored in attributes to loaders."""
-        from framcore.utils import add_loaders_if  # noqa: PLC0415
+        from framcore.utils import add_loaders_if
 
         add_loaders_if(loaders, self._normal_price)
         add_loaders_if(loaders, self._price_elasticity)

framcore/attributes/ReservoirCurve.py

@@ -9,26 +9,12 @@ if TYPE_CHECKING:
 
 
 class ReservoirCurve(Base):
-    """
-    Represents a reservoir curve attribute.
+    """Water level elevation to water volume characteristics for HydroStorage."""
 
-    Attributes
-    ----------
-    _value : str | None
-        The value representing the reservoir curve.
-
-    """
+    # TODO: Implement and comment, also too generic name
 
     def __init__(self, value: str | None) -> None:
-        """
-        Initialize a ReservoirCurve instance.
-
-        Parameters
-        ----------
-        value : str | None
-            The value representing the reservoir curve.
-
-        """
+        """Initialize a ReservoirCurve instance."""
         self._check_type(value, (str, type(None)))
         self._value = value
 

framcore/attributes/SoftBound.py

@@ -7,12 +7,9 @@ if TYPE_CHECKING:
 
 
 class SoftBound:
-    """
-    Represents a soft bound attribute.
+    """Represents a soft bound attribute. Penalty applied if the bound is violated."""
 
-    This class can be extended to define soft bounds for various parameters.
-
-    """
+    # TODO: Implement and comment
 
     def add_loaders(self, loaders: set[Loader]) -> None:
         """Add all loaders stored in attributes to loaders."""

framcore/attributes/StartUpCost.py

@@ -11,7 +11,9 @@ if TYPE_CHECKING:
 
 
 class StartUpCost(Base):
-    """StartUpCost class representing the startup cost of a Component."""
+    """Represent the costs associated with starting up the operation of a Component."""
+
+    # TODO: Complete description
 
     def __init__(
         self,
@@ -20,7 +22,16 @@ class StartUpCost(Base):
         start_hours: Hours,
         part_load_efficiency: Efficiency,
     ) -> None:
-        """Initialize the StartUpCost class."""
+        """
+        Initialize the StartUpCost class.
+
+        Args:
+            startup_cost (Cost): _description_
+            min_stable_load (Proportion): _description_
+            start_hours (Hours): _description_
+            part_load_efficiency (Efficiency): _description_
+
+        """
         self._check_type(startup_cost, Cost)
         self._check_type(min_stable_load, Proportion)
         self._check_type(start_hours, Hours)
@@ -46,7 +57,7 @@ class StartUpCost(Base):
 
     def add_loaders(self, loaders: set[Loader]) -> None:
         """Get all loaders stored in attributes."""
-        from framcore.utils import add_loaders_if  # noqa: PLC0415
+        from framcore.utils import add_loaders_if
 
         add_loaders_if(loaders, self.get_startupcost())
         add_loaders_if(loaders, self._start_hours)

framcore/attributes/Storage.py

@@ -13,22 +13,34 @@ class Storage(Base):
     """
     Represents all types of storage this system supports.
 
-    Subclasses are supposed to restrict which attributes that are
-    used, not add more.
+    Subclasses are supposed to restrict which attributes that are used, not add more.
     """
 
     def __init__(
         self,
         capacity: StockVolume,
         volume: StockVolume | None = None,
-        loss: Loss | None = None,
+        loss: Loss | None = None,  # TODO: Should be loss percentage per time.
         reservoir_curve: ReservoirCurve | None = None,
         max_soft_bound: SoftBound | None = None,
         min_soft_bound: SoftBound | None = None,
         target_bound: TargetBound | None = None,
         initial_storage_percentage: float | None = None,
     ) -> None:
-        """Create new storage."""
+        """
+        Create new storage.
+
+        Args:
+            capacity (StockVolume): Storage capacity.
+            volume (StockVolume | None, optional): Storage filling (actual/result). Defaults to None.
+            loss (Loss | None, optional): Loss percentage per time. Defaults to None.
+            reservoir_curve (ReservoirCurve | None, optional): Water level elevation to water volume for HydroStorage. Defaults to None.
+            max_soft_bound (SoftBound | None, optional): Upper soft boundary that is penalized if broken. Defaults to None.
+            min_soft_bound (SoftBound | None, optional): Lower soft boundary that is penalized if broken. Defaults to None.
+            target_bound (TargetBound | None, optional): Target filling, can be penalized if deviation. Defaults to None.
+            initial_storage_percentage (float | None, optional): Initial storage filling percentage at start of simulation. Defaults to None.
+
+        """
         super().__init__()
 
         self._check_type(capacity, StockVolume)
@@ -132,7 +144,7 @@ class Storage(Base):
 
     def add_loaders(self, loaders: set[Loader]) -> None:
         """Add all loaders stored in attributes to loaders."""
-        from framcore.utils import add_loaders_if  # noqa: PLC0415
+        from framcore.utils import add_loaders_if
 
         add_loaders_if(loaders, self.get_capacity())
         add_loaders_if(loaders, self.get_loss())

framcore/attributes/TargetBound.py

@@ -7,11 +7,9 @@ if TYPE_CHECKING:
 
 
 class TargetBound:
-    """
-    Represents a target bound attribute.
+    """Target boundary attribute. Can be penalized if deviation from target."""
 
-    This class can be extended to define specific bounds for targets in the energy model.
-    """
+    # TODO: Implement and comment
 
     def add_loaders(self, loaders: set[Loader]) -> None:
         """Add all loaders stored in attributes to loaders."""

framcore/attributes/__init__.py

@@ -1,5 +1,3 @@
-# ruff: noqa: I001
-
 from framcore.attributes.level_profile_attributes import (
     AvgFlowVolume,
     Coefficient,
@@ -16,7 +14,7 @@ from framcore.attributes.level_profile_attributes import (
     Price,
     Proportion,
     ReservePrice,
-    ShaddowPrice,
+    ShadowPrice,
     StockVolume,
     WaterValue,
 )
@@ -55,7 +53,7 @@ __all__ = [
     "Proportion",
     "ReservePrice",
     "ReservoirCurve",
-    "ShaddowPrice",
+    "ShadowPrice",
     "SoftBound",
     "StartUpCost",
     "StockVolume",

framcore/attributes/hydro/HydroBypass.py

@@ -4,14 +4,21 @@ from framcore.fingerprints import Fingerprint
 
 
 class HydroBypass(Base):
-    """Bypass class representing a hydro bypass attribute."""
+    """HydroBypass represents a controlled water way from a HydroModule. Used to bypass main release of the HydroModule."""
 
     def __init__(
         self,
         to_module: str | None,
         capacity: FlowVolume | None = None,
     ) -> None:
-        """Initialize Bypass."""
+        """
+        Initialize object.
+
+        Args:
+            to_module (str | None): Name of the HydroModule the water is released to.
+            capacity (FlowVolume | None, optional): Restrictions on the volume of water which can pass through the bypass at a given moment. Defaults to None.
+
+        """
         super().__init__()
 
         self._check_type(to_module, (str, type(None)))