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

framcore/components/HydroModule.py

@@ -3,7 +3,25 @@ from framcore.components import Component, Flow, Node
 
 
 class HydroModule(Component):
-    """HydroModule class representing a hydro module component."""
+    """
+    HydroModules represents a physical element in a river system, with its topology and other attributes.
+
+    The hydromodule can contain a HydroReservoir, HydroGenerator, HydroPump, HydroBypass and local inflow, aswell as the topological attributes release_to
+    and spill_to:
+
+    - HydroGenerator uses the release pathway of the HydroModule to generate power, while HydroPump has its own water way that consumes
+      power. Both HydroGenerator and HydroPump connects to power nodes.
+    - HydroBypass also have attributes that define the topology of the river system.
+    - HydroReservoir represents the water storage of the HydroModule.
+    - The hydraulic_coupling attribute is used to identify which HydroModules have hydraulic coupled reservoirs.
+
+
+    Results for the release volume, spill volume and the water value are stored directly in the HydroModule, while the production, pumping,
+    reservoir volume and bypass volume are stored in the attributes.
+
+    HydroModule is compatible with HydroAggregator for aggregation of multiple HydroModules into one.
+
+    """
 
     # We add this to module name to get corresponding node name
     _NODE_NAME_POSTFIX = "_node"
@@ -24,7 +42,28 @@ class HydroModule(Component):
         release_volume: AvgFlowVolume | None = None,
         spill_volume: AvgFlowVolume | None = None,
     ) -> None:
-        """Initialize the HydroModule with its parameters."""
+        """
+        Initialize the HydroModule with its parameters.
+
+        Args:
+            release_to (str | None, optional): Reference to another HydroModule which recieves the water releases through the main release. Defaults to None.
+            release_capacity (FlowVolume | None): Amount of water which can be released via main release at a given moment. Defaults to None.
+            generator (HydroGenerator | None, optional): Represents generation of electricity from the movement of water through the Modules main release
+                                                        pathway. Defaults to None.
+            pump (HydroPump | None): Pump associated with this Module. Can move water to another using power. Defaults to None.
+            inflow (AvgFlowVolume | None, optional): The local inflow of the HydroModule. Defaults to None.
+            reservoir (HydroReservoir | None, optional): The Modules water storage. Defaults to None.
+            hydraulic_coupling (int): Number other than 0 if the HydroModules reservoir is hydraulic coupled to another reservoir. Defaults to 0.
+                                                        TODO: Replace with HydraulicCoupling class
+            bypass (HydroBypass | None, optional): Bypass water way. Defaults to None.
+            spill_to (str | None): Reference to another Module recieving this ones spill volume. Defaults to None.
+            commodity (str, optional): Commodity of the hydro node. Defaults to "Hydro".
+            water_value (WaterValue | None, optional): Water value of the reservoir in currency per water volume. Defaults to None.
+                                                        TODO: Allow water values with multiple demimensions?
+            release_volume (AvgFlowVolume | None, optional): Volume of water released via main waterway. Defaults to None.
+            spill_volume (AvgFlowVolume | None, optional): Volume of water spilled. Defaults to None.
+
+        """
         super().__init__()
         self._check_type(release_to, (str, type(None)))
         self._check_type(release_capacity, (FlowVolume, type(None)))
@@ -187,6 +226,7 @@ class HydroModule(Component):
             arrow_volumes=None,
             is_exogenous=False,
         )
+
         arrow_volumes = flow.get_arrow_volumes()
 
         outgoing_arrow = Arrow(
@@ -194,6 +234,7 @@ class HydroModule(Component):
             is_ingoing=False,
             conversion=Conversion(value=1),
         )
+
         flow.add_arrow(outgoing_arrow)
 
         if self._release_to:
@@ -209,7 +250,7 @@ class HydroModule(Component):
             production_arrow = Arrow(
                 node=self._generator.get_power_node(),
                 is_ingoing=True,
-                conversion=self._generator.get_energy_eq(),
+                conversion=self._generator.get_energy_equivalent(),
             )
             flow.add_arrow(production_arrow)
             arrow_volumes[production_arrow] = self._generator.get_production()
@@ -322,7 +363,7 @@ class HydroModule(Component):
         pump_arrow = Arrow(
             node=self._pump.get_power_node(),
             is_ingoing=False,
-            conversion=self._pump.get_energy_eq(),
+            conversion=self._pump.get_energy_equivalent(),
         )
         flow.add_arrow(pump_arrow)
         arrow_volumes[pump_arrow] = self._pump.get_power_consumption()

framcore/components/Node.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING
 
-from framcore.attributes import Price, ShaddowPrice, Storage
+from framcore.attributes import Price, ShadowPrice, Storage
 from framcore.components import Component
 
 if TYPE_CHECKING:
@@ -10,20 +10,43 @@ if TYPE_CHECKING:
 
 
 class Node(Component):
-    """Node class. Subclass of Component."""
+    """
+    Represents a point in the energy system where a commodity can possibly be traded, stored or pass through.
+
+    A node is characterized by the commodity it handles, its price, and optionally storage capabilities. If the
+    node is exogenous, the commodity can be bought and sold at a fixed price determined by the user.
+    If the node is endogenous, the price is determined by the market dynamics at the Node.
+
+    Nodes, Flows and Arrows are the main building blocks in FRAM's low-level representation of energy systems.
+    Movement between Nodes is represented by Flows and Arrows. Flows represent a commodity flow,
+    and can have Arrows that each describe contribution of the Flow into a Node.
+    The Arrows have direction to determine input or output,
+    and parameters for the contribution of the Flow to the Node (conversion, efficiency and loss).
+
+    """
 
     def __init__(
         self,
         commodity: str,
         is_exogenous: bool = False,  # TODO
-        price: ShaddowPrice | None = None,
+        price: ShadowPrice | None = None,
         storage: Storage | None = None,
     ) -> None:
-        """Initialize the Node class."""
+        """
+        Initialize the Node class.
+
+        Args:
+            commodity (str): Commodity at the Node. Power/electricity, gas, heat, etc.
+            is_exogenous (bool, optional): Flag used to signal Solvers whether they should simulate the node endogenously or use the pre-set price.
+                                           Defaults to False.
+            price (ShadowPrice | None): Actual, calculated price of Commodity in this Node for each moment of simulation. Defaulta to None.
+            storage (Storage | None, optional): The amount of the Commodity stored on this Node. Defaults to None.
+
+        """
         super().__init__()
         self._check_type(commodity, str)
         self._check_type(is_exogenous, bool)
-        self._check_type(price, (ShaddowPrice, type(None)))
+        self._check_type(price, (ShadowPrice, type(None)))
         self._check_type(storage, (Storage, type(None)))
 
         self._commodity = commodity
@@ -37,12 +60,12 @@ class Node(Component):
         self._price: Price = price
 
     def set_exogenous(self) -> None:
-        """Set internal is_exogenous flag to True."""
+        """Set the Node to be exogenous."""
         self._check_type(self._is_exogenous, bool)
         self._is_exogenous = True
 
     def set_endogenous(self) -> None:
-        """Set internal is_exogenous flag to False."""
+        """Set the Node to be endogenous."""
         self._check_type(self._is_exogenous, bool)
         self._is_exogenous = False
 
@@ -50,7 +73,7 @@ class Node(Component):
         """Return True if Node is exogenous (i.e. has fixed prices determined outside the model) else False."""
         return self._is_exogenous
 
-    def get_price(self) -> ShaddowPrice:
+    def get_price(self) -> ShadowPrice:
         """Return price."""
         return self._price
 
@@ -64,7 +87,7 @@ class Node(Component):
 
     def add_loaders(self, loaders: set[Loader]) -> None:
         """Add 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_price())
         add_loaders_if(loaders, self.get_storage())

framcore/components/Thermal.py

@@ -2,10 +2,6 @@ from framcore.attributes import Arrow, AvgFlowVolume, Conversion, Cost, Efficien
 from framcore.components import Component, Flow
 from framcore.components._PowerPlant import _PowerPlant
 
-# TODO
-# refactor to use _ensure_flow and _ensure_coeff by using check_type, and possibly other methods
-# add exception to replace_nodes (see implementation in Demand)
-
 
 class Thermal(_PowerPlant):
     """
@@ -13,12 +9,14 @@ class Thermal(_PowerPlant):
 
     This class models a thermal power plant with attributes inherited from PowerPlant.
     Additionally, it includes specific attributes such as:
+
     - fuel node
     - efficiency
     - emission node
     - emission coefficient
     - startup costs
 
+
     This class is compatible with ThermalAggregator.
     """
 
@@ -27,10 +25,10 @@ class Thermal(_PowerPlant):
         power_node: str,
         fuel_node: str,
         efficiency: Efficiency,
+        max_capacity: FlowVolume,
         emission_node: str | None = None,
         emission_coefficient: Conversion | None = None,
         startupcost: StartUpCost | None = None,
-        max_capacity: FlowVolume | None = None,
         min_capacity: FlowVolume | None = None,
         voc: Cost | None = None,
         production: AvgFlowVolume | None = None,
@@ -46,9 +44,9 @@ class Thermal(_PowerPlant):
             efficiency (Efficiency): Efficiency of the plant.
             emission_node (str | None, optional): Emission node.
             emission_coefficient (Conversion | None, optional): Emission coefficient.
-            startupcost (StartUpCost | None, optional): Startup cost.
-            max_capacity (FlowVolume | None, optional): Maximum capacity.
-            min_capacity (FlowVolume | None, optional): Minimum capacity.
+            startupcost (StartUpCost | None, optional): Cost associated with starting up the Plant.
+            max_capacity (FlowVolume | None, optional): Maximum production capacity.
+            min_capacity (FlowVolume | None, optional): Minimum production capacity.
             voc (Cost | None, optional): Variable operating cost.
             production (AvgFlowVolume | None, optional): Production volume.
             fuel_demand (AvgFlowVolume | None, optional): Fuel demand.
@@ -149,6 +147,12 @@ class Thermal(_PowerPlant):
         return {base_name + "_Flow": self._create_flow()}
 
     def _replace_node(self, old: str, new: str) -> None:
+        existing_nodes = [self._power_node, self._fuel_node]
+        existing_nodes = existing_nodes if self._emission_node is None else [*existing_nodes, self._emission_node]
+        if old not in existing_nodes:
+            message = f"{old} not found in {self}. Expected one of the existing nodes {existing_nodes}."
+            raise ValueError(message)
+
         if self._power_node == old:
             self._power_node = new
         if self._fuel_node == old:

framcore/components/Transmission.py

@@ -6,7 +6,7 @@ from framcore.components import Component, Flow
 
 class Transmission(Component):
     """
-    Transmission component representing a transmission line. Subclass of Component.
+    Transmission component representing a one directional transmission line. Subclass of Component.
 
     An object of this class represents one transmission line where power flows one direction (the other direction is
     represented by another Transmission object). However, the actual measured power being sent can be higher than the
@@ -28,7 +28,22 @@ class Transmission(Component):
         ingoing_volume: AvgFlowVolume | None = None,
         outgoing_volume: AvgFlowVolume | None = None,
     ) -> None:
-        """Initialize object of the Transmission class. Perform type checks and convert arguments to expressions."""
+        """
+        Initialize object of the Transmission class. Perform type checks and convert arguments to expressions.
+
+        Args:
+            from_node (str): Node which power is transported from.
+            to_node (str): Destination Node.
+            max_capacity (FlowVolume, optional): Maximum transmission capacity. Defaults to None.
+            min_capacity (FlowVolume | None, optional): Minimum transmission capacity. Defaults to None.
+            loss (Loss | None, optional): Amount of power lost while transmitting. Defaults to None.
+            tariff (Cost | None, optional): Costs associated with operating this transmission line. Defaults to None.
+            ramp_up (Proportion | None, optional): Max upwards change in transmission per time. Defaults to None.
+            ramp_down (Proportion | None, optional): Max downwards change in transmission per time. Defaults to None.
+            ingoing_volume (AvgFlowVolume | None, optional): Volume of power recieved by to_node. Defaults to None.
+            outgoing_volume (AvgFlowVolume | None, optional): Volume of power sent by from_node. Defaults to None.
+
+        """
         super().__init__()
 
         self._check_type(from_node, str)

framcore/components/wind_solar.py

@@ -7,13 +7,7 @@ class _WindSolar(_PowerPlant):
     """
     Wind and Solar class component representing a wind and solar power plant. Subclass of PowerPlant.
 
-    This class models a wind or solarpower plant with various attributes inherited from the parent class PowerPlant.
-
-    Capacity can be provided directly or as parts (level or profile). Max and min capacity profiles are set
-    to be equal as the capacity_profile for these technologytypes since it does not have a max or min.
-
-    The functions _get_fingerprints, _get_nodes og _get_flow are defines in this
-    subclass since other subclases are dependent on fuel and emission nodes.
+    This class models a wind or solar power plant with various attributes inherited from the parent class PowerPlant.
     """
 
     def __init__(
@@ -23,7 +17,16 @@ class _WindSolar(_PowerPlant):
         voc: Cost | None = None,
         production: AvgFlowVolume | None = None,
     ) -> None:
-        """Initialize the Wind and Solar class."""
+        """
+        Initialize the Wind and Solar class.
+
+        Args:
+            power_node (str): Reference to a power Node to produce to.
+            max_capacity (FlowVolume): Maximum capacity.
+            voc (Cost | None, optional): Variable operational costs. Defaults to None.
+            production (AvgFlowVolume | None, optional): Actual production. Defaults to None.
+
+        """
         super().__init__(
             power_node=power_node,
             max_capacity=max_capacity,
@@ -56,12 +59,24 @@ class _WindSolar(_PowerPlant):
 
 
 class Wind(_WindSolar):
-    """Wind power component."""
+    """
+    Wind power component.
+
+    Has attributes for power node, capacity, variable operation cost, and production.
+
+    Compatible with WindSolarAggregator.
+    """
 
     pass
 
 
 class Solar(_WindSolar):
-    """Solar power component."""
+    """
+    Solar power component.
+
+    Has attributes for power node, capacity, variable operation cost, and production.
+
+    Compatible with WindSolarAggregator.
+    """
 
     pass

framcore/curves/LoadedCurve.py

@@ -16,15 +16,6 @@ class LoadedCurve(Curve):
     """
     Represents a curve loaded from a CurveLoader.
 
-    Attributes
-    ----------
-    _curve_id : str
-        Identifier for the curve.
-    _loader : CurveLoader
-        Loader instance used to retrieve curve data.
-    _reference_period : Any
-        Reference period for the curve (currently not set).
-
     Methods
     -------
     get_unique_name()

framcore/expressions/Expr.py

@@ -4,6 +4,7 @@ from copy import copy
 from typing import TYPE_CHECKING
 
 from framcore import Base
+from framcore.curves import Curve, LoadedCurve
 from framcore.fingerprints import Fingerprint, FingerprintRef
 from framcore.timevectors import ConstantTimeVector, TimeVector
 
@@ -13,11 +14,44 @@ if TYPE_CHECKING:
 
 # TODO: Add Expr.add_many to support faster aggregation expressions.
 class Expr(Base):
-    """Expressions for data manipulation of curves and timevectors."""
+    """
+    Mathematical expression with TimeVectors and Curves to represent Levels and Profiles in LevelProfiles.
+
+    The simplest Expr is a single TimeVector, while a more complicated expression could be a weighted average of several TimeVectors or Expressions.
+    Expr can also have string references to Expr, TimeVector or Curve in a database (often Model).
+
+    Expr are classified as Stock, Flow or None of them. See https://en.wikipedia.org/wiki/Stock_and_flow. In FRAM we only support Flow data as a rate of change.
+    So, for example, a production timeseries has to be in MW, and not in MWh. Converting between the two versions of Flow would add another
+    level of complexity both in Expr and in TimeVector operations.
+
+    Expr are also classified as Level, Profile or none of them. This classification, together with Stock or Flow,
+    is used to check if the built Expr are legal operations.
+    - Expr that are Level can contain its connected Profile Expr. This is used in the queries to evaluate Levels according to their ReferencePeriod, and
+        convert between Level formats (max level or average level, see LevelProfile for more details).
+
+    Calculations using Expr are evaluated lazily, reducing unnecessary numerical operations during data manipulation.
+    Computations involving values and units occur only when the Expr is queried.
+
+    We only support calculations using +, -, *, and / in Expr, and we have no plans to change this.
+    Expanding beyond these would turn Expr into a complex programming language rather than keeping it as a simple
+    and efficient system for common time-series calculations. More advanced operations are still possible through eager evaluation, so this is not a limitation.
+    It simply distributes responsibilities across system components in a way that is practical from a maintenance perspective.
+
+    We use SymPy to support unit conversions. Already computed unit conversion factors are cached to minimize redundant calculations.
+
+    At the moment we support these queries for Expr (see Aggregators for more about how they are used):
+    - get_level_value(expr, db, unit, data_dim, scen_dim, is_max)
+        - Supports all expressions. Will evaluate level Exprs at data_dim (with reference period of scen_dim),
+            and profile Exprs as an average over scen_dim (both as constants).
+        - Has optimized fastpath methods for sums, products and aggregations. The rest uses a fallback method with SymPy.
+    - get_profile_vector(expr, db, data_dim, scen_dim, is_zero_one, is_float32)
+        - Supports expr = sum(weight[i] * profile[i]) where weight[i] is a unitless constant Expr with value >= 0, and profile[i] is a unitless profile Expr.
+
+    """
 
     def __init__(
         self,
-        src: str | TimeVector | None = None,
+        src: str | Curve | TimeVector | None = None,
         is_stock: bool = False,
         is_flow: bool = False,
         is_profile: bool = False,
@@ -26,19 +60,33 @@ class Expr(Base):
         operations: tuple[str, list[Expr]] | None = None,
     ) -> None:
         """
-        Create new (immutable) expression.
+        Create new (immutable) Expression.
 
         Args:
-            src (str | None, optional): _description_. Defaults to None.
-            is_stock (bool, optional): _description_. Defaults to False.
-            is_flow (bool, optional): _description_. Defaults to False.
-            is_profile (bool, optional): _description_. Defaults to False.
-            is_level (bool, optional): _description_. Defaults to False.
-            profile (Expr | None, optional): _description_. Defaults to None.
+            src (str | Curve | TimeVector | None, optional): Source of the values to be used in the Expression. Either a Curve or TimeVector object,
+              or a reference to one of them. Defaults to None.
+            is_stock (bool, optional): Flag to signify if the Expr represents a stock type variable. Defaults to False.
+            is_flow (bool, optional): Flag to signify if the Expr represents a flow type variable. Defaults to False.
+            is_profile (bool, optional): Flag to signify if the Expr represents a profile. Defaults to False.
+            is_level (bool, optional): Flag to signify if the Expr represents a level. Defaults to False.
+            profile (Expr | None, optional): Expr that are Level can contain its connected Profile Expr. This is used in the queries to evaluate
+                Levels according to their ReferencePeriod, and convert between Level formats (max level or average level, see LevelProfile for more details).
             operations (tuple[str, list[Expr]] | None, optional): Operations to apply to the expression. Defaults to None.
 
-        """  # TODO: write detailed description of what the labels of Expr means (level, profile, flow, stock)
-        self._src: str | TimeVector | None = src
+        """
+        if is_level and is_profile:
+            message = "Expr cannot be both level and a profile. Set either is_level or is_profile True or both False."
+            raise ValueError(message)
+
+        if is_flow and is_stock:
+            message = "Expr cannot be both flow and stock. Set either is_flow or is_stock True or both False."
+            raise ValueError(message)
+
+        if is_profile and (is_flow or is_stock):
+            message = "Expr cannot be both a profile and a flow/stock. Profiles must be coefficients."
+            raise ValueError(message)
+
+        self._src: str | Curve | TimeVector | None = src
         self._is_stock = is_stock
         self._is_flow = is_flow
         self._is_profile = is_profile
@@ -49,7 +97,7 @@ class Expr(Base):
         # because fields are used to create
         # error messages e.g. in __repr__
 
-        self._check_type(src, (str, TimeVector, type(None)))
+        self._check_type(src, (str, Curve, TimeVector, type(None)))
         self._check_type(is_stock, (bool, type(None)))
         self._check_type(is_flow, (bool, type(None)))
         self._check_type(is_level, (bool, type(None)))
@@ -80,7 +128,7 @@ class Expr(Base):
                 raise ValueError(message)
             return
         if len(ops) != len(args) - 1:
-            message = f"Expected len(ops) == len(args). Got {operations}"
+            message = f"Expected len(ops) == len(args) - 1. Got {operations}"
             raise ValueError(message)
         for op in ops:
             if op not in "+-/*":
@@ -106,8 +154,8 @@ class Expr(Base):
         """Return True if self is not an operation expression."""
         return self._src is not None
 
-    def get_src(self) -> str | TimeVector | None:
-        """Return str (either usercode or key in model) or None if self is an operation expression."""
+    def get_src(self) -> str | Curve | TimeVector | None:
+        """Return str, Curve or TimeVector (either reference to Curve/TimeVector or Curve/TimeVector itself) or None if self is an operation expression."""
         return self._src
 
     def get_operations(self, expect_ops: bool, copy_list: bool) -> tuple[str, list[Expr]]:
@@ -122,23 +170,28 @@ class Expr(Base):
     def _verify_operations(self, expect_ops: bool = False) -> None:
         self._check_operations(self._operations, expect_ops)
         ops = self._operations[0]
+
         if not ops:
             return
+
         has_add = "+" in ops
         has_sub = "-" in ops
         has_mul = "*" in ops
         has_div = "/" in ops
+
         if (has_add or has_sub) and (has_mul or has_div):
-            message = f"+- in same operation level as */ in operations {self._operations} "
+            message = f"Found +- in same operation level as */ in operations {self._operations} "
             raise ValueError(message)
+
         if has_div:
             seen_div = False
             for op in ops:
                 if op == "/":
                     seen_div = True
-                    break
+                    continue
                 if seen_div and op != "/":
-                    message = f"+-* after / in operations {self._operations}"
+                    message = f"Found +-* after / in operations {self._operations}"
+                    raise ValueError(message)
 
     def is_flow(self) -> bool:
         """Return True if flow. Cannot be stock and flow."""
@@ -258,7 +311,7 @@ class Expr(Base):
     def _create_op_expr(  # noqa: C901
         self,
         op: str,
-        other: object,
+        other: Expr | int | float,
         is_rhs: bool,
     ) -> Expr:
         if isinstance(other, Expr):
@@ -377,12 +430,12 @@ class Expr(Base):
     def __repr__(self) -> str:
         """Represent Expr as str."""
         if self._src is not None:
-            return f"{self._src}"
+            return f"Expr({self._src})"
         ops, args = self.get_operations(expect_ops=True, copy_list=False)
         out = f"{args[0]}"
         for op, arg in zip(ops, args[1:], strict=True):
             out = f"{out} {op} {arg}"
-        return f"({out})"
+        return f"Expr({out})"
 
     def __eq__(self, other) -> bool:  # noqa: ANN001
         """Check if self and other are equal."""
@@ -397,7 +450,7 @@ class Expr(Base):
             and self._profile == other._profile
             and self._operations[0] == other._operations[0]
             and len(self._operations[1]) == len(other._operations[1])
-            and all([self._operations[1][i] == other._operations[1][i] for i in range(len(self._operations[1]))])
+            and all([self._operations[1][i] == other._operations[1][i] for i in range(len(self._operations[1]))])  # noqa: SLF001
         )
 
     def __hash__(self) -> int:
@@ -417,11 +470,9 @@ class Expr(Base):
 
     def add_loaders(self, loaders: set[Loader]) -> None:
         """Add all loaders stored in TimeVector or Curve within Expr to loaders."""
-        from framcore.curves import Curve
-
         if self.is_leaf():
             src = self.get_src()
-            if isinstance(src, TimeVector | Curve):
+            if isinstance(src, TimeVector | LoadedCurve):
                 loader = src.get_loader()
                 if loader is not None:
                     loaders.add(loader)
@@ -433,7 +484,7 @@ class Expr(Base):
 
 # Proposed new way of creating Expr in classes.
 def ensure_expr(
-    value: Expr | str | TimeVector | None,  # technically anything that can be converted to float. Typehint for this?
+    value: Expr | str | Curve | TimeVector | None,  # technically anything that can be converted to float. Typehint for this?
     is_flow: bool = False,
     is_stock: bool = False,
     is_level: bool = False,
@@ -455,21 +506,15 @@ def ensure_expr(
         value (Expr | str): The value as an expression of the expected type or None.
 
     """
-    # Following checks could be moved to Expr.
-    if is_level and is_profile:
-        message = "Expr cannot be both level and a profile. Set either is_level or is_profile True or both False."
-        raise ValueError(message)
-    if is_flow and is_stock:
-        message = "Expr cannot be both flow and stock. Set either is_flow or is_stock True or both False."
-        raise ValueError(message)
-    if is_profile and (is_flow or is_stock):
-        message = "Expr cannot be both a profile and a flow/stock. Profiles must be coefficients."
+    if not isinstance(value, (str, Expr, Curve, TimeVector)) and value is not None:
+        msg = f"Expected value to be of type Expr, str, Curve, TimeVector or None. Got {type(value).__name__}."
+        raise TypeError(msg)
 
     if value is None:
         return None
+
     if isinstance(value, Expr):
         # Check wether given Expr matches expected flow, stock, profile and level status.
-        # Alternatively we could just create a new Expr with updated status.
         if value.is_flow() != is_flow or value.is_stock() != is_stock or value.is_level() != is_level or value.is_profile() != is_profile:
             message = (
                 "Given Expr has a mismatch between expected and actual flow/stock or level/profile status:\nExpected: "
@@ -488,3 +533,59 @@ def ensure_expr(
         is_profile=is_profile,
         profile=profile,
     )
+
+
+def get_profile_exprs_from_leaf_levels(expr: Expr) -> list[Expr]:
+    """
+    Get all profile expressions from leaf-level Expr objects that are marked as levels.
+
+    Args:
+        expr (Expr): The starting Expr object.
+
+    Returns:
+        list[Expr]: A list of profile expressions from leaf-level Expr objects.
+
+    """
+    profile_exprs = []
+
+    def _traverse(expr: Expr) -> None:
+        if expr.is_leaf():
+            if expr.is_level() and expr.get_profile() is not None:
+                profile_exprs.append(expr.get_profile())
+            return
+
+        # Recursively traverse the arguments of the expression
+        _, args = expr.get_operations(expect_ops=False, copy_list=False)
+        for arg in args:
+            _traverse(arg)
+
+    _traverse(expr)
+    return profile_exprs
+
+
+def get_leaf_profiles(expr: Expr) -> list[Expr]:
+    """
+    Get all leaf profile expressions from an Expr object.
+
+    Args:
+        expr (Expr): The starting Expr object.
+
+    Returns:
+        list[Expr]: A list of leaf profile expressions.
+
+    """
+    leaf_profiles = []
+
+    def _traverse(expr: Expr) -> None:
+        if expr.is_leaf():
+            if expr.is_profile():
+                leaf_profiles.append(expr)
+            return
+
+        # Recursively traverse the arguments of the expression
+        _, args = expr.get_operations(expect_ops=False, copy_list=False)
+        for arg in args:
+            _traverse(arg)
+
+    _traverse(expr)
+    return leaf_profiles

framcore/expressions/__init__.py

@@ -1,6 +1,6 @@
 # framcore/expressions/__init__.py
 
-from framcore.expressions.Expr import Expr, ensure_expr
+from framcore.expressions.Expr import Expr, ensure_expr, get_leaf_profiles, get_profile_exprs_from_leaf_levels
 
 from framcore.expressions.units import (
     get_unit_conversion_factor,
@@ -18,7 +18,9 @@ from framcore.expressions.queries import (
 __all__ = [
     "Expr",
     "ensure_expr",
+    "get_leaf_profiles",
     "get_level_value",
+    "get_profile_exprs_from_leaf_levels",
     "get_profile_vector",
     "get_timeindexes_from_expr",
     "get_unit_conversion_factor",