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

{fram_core-0.1.0a2.dist-info → fram_core-0.1.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fram-core
-Version: 0.1.0a2
+Version: 0.1.1
 Summary: 
 License: LICENSE.md
 License-File: LICENSE.md
@@ -24,11 +24,11 @@ Description-Content-Type: text/markdown
 
 ## About
 
-**fram-core** is the main package in **FRAM** modelling framework. The package contains essential features, interfaces and components for running energy market models in FRAM.
+**fram-core** is the main package in the **FRAM** modelling framework. The package holds the functionality used to describe and manipulate the energy system, handle time series operations, and hold the definition of key interfaces in FRAM.
 
-For package documentation see [fram-core](https://nve.github.io/fram-core){:target="_blank"}. 
+For package documentation see [fram-core](https://nve.github.io/fram-core). 
 
-For FRAM documentation see [FRAM mainpage](https://nve.github.io/fram){:target="_blank"}.
+For FRAM documentation see [FRAM mainpage](https://nve.github.io/fram).
 
 ## Installation
 

fram_core-0.1.1.dist-info/RECORD

@@ -0,0 +1,100 @@
+framcore/Base.py,sha256=WAc8GBeuLxPpLFHbHwyYzd3HCv6RWo17iw0ItCRFXlE,6027
+framcore/Model.py,sha256=S8Tdfl7Ynhhhk1KbOjCl0W4oZRNaroVGwjomwKZi9yU,3654
+framcore/__init__.py,sha256=TvgesX44gH4OCopUSGY05BFK32oafI7ZDhctD6yQ57k,182
+framcore/aggregators/Aggregator.py,sha256=sDlMZyCVwF-NhQPjMwcSm8xHH-SerBqlIP5ckbJ0C5A,8226
+framcore/aggregators/HydroAggregator.py,sha256=XmaLPMe3xD1Vs2s7KsrSEy_zwLmDtCxMsslaCX5aJfg,47321
+framcore/aggregators/NodeAggregator.py,sha256=QUPdXURkRIPymZAxHyavCzo1cGrnBJ3ahZNEmT9kwxE,23651
+framcore/aggregators/WindSolarAggregator.py,sha256=5Fko0-FLRfUPMZQjpkWmpTwqzgW0WGm04zrUZ_-_Ypk,16465
+framcore/aggregators/__init__.py,sha256=ZoBqilfv0XhFkYVROBPQhJHzSY1IcvhJmJ_FOo_Z5Pw,426
+framcore/aggregators/_utils.py,sha256=EoRLeGmPC2ds-egPdvDewtaYbRozi6Psyf9DD1PRajk,8337
+framcore/attributes/Arrow.py,sha256=bodWoKLG3g2bHt6FygwOJP1n3VKfAdrRfYCOveogrmk,11204
+framcore/attributes/ElasticDemand.py,sha256=1sNXLAw1C-pGeQU2kgyoZF_-LTb3NCTOY5hOJwd7mrU,3073
+framcore/attributes/ReservoirCurve.py,sha256=la4bgXNtR0DIdnQ1Iu37ydqr-sWRZN5yOVZ6qJ8rOZY,644
+framcore/attributes/SoftBound.py,sha256=ooScf39EmqyWUIRafGiWEKGIvr6kMbV9JF4CIDARKBM,405
+framcore/attributes/StartUpCost.py,sha256=tKT4hK23yQtjXWvrNz2EPC1oOxBO19SRfecxy77frU4,2107
+framcore/attributes/Storage.py,sha256=c2p5rhaXpjB4PiPi6FCL7SB5X_DAu91bVSsRWE7-h1o,6284
+framcore/attributes/TargetBound.py,sha256=5IcLwi1ciLm7SK3V9ZNzMDBeUKF62LfYr36ARQqJHQk,400
+framcore/attributes/__init__.py,sha256=50viQ-upiArFHZpeUjEh9xqvuh-ZRGtIVwZNEtSGlI8,1530
+framcore/attributes/hydro/HydroBypass.py,sha256=MdF51LNugwZhtpadBjiRI0zPA77Cnku5c8hTn42AJc8,1683
+framcore/attributes/hydro/HydroGenerator.py,sha256=2uohj1QkZl52qNAR8nIywnLW-j_ujnxX-ITV2t9MRrU,4186
+framcore/attributes/hydro/HydroPump.py,sha256=jKeJJk9kzz2dsxXfppqDcVf8_NHtwl6Yzlrv28k6z3M,7506
+framcore/attributes/hydro/HydroReservoir.py,sha256=PEogXuSrdQ08uk5R_Re7G-Ue5N8cphPCEVvQhBIiy_U,879
+framcore/attributes/hydro/__init__.py,sha256=isOSLP2TdHOaPcr16EXIkdtx80LVe8ztFPiuGJPC4ao,381
+framcore/attributes/level_profile_attributes.py,sha256=feyIQ9lSnQGXdo45lU9kPCsKB1SNFrTfRaViFeNxlMI,33636
+framcore/components/Component.py,sha256=z7ApRmaTPIZLwKJdbczrM8buLQnPJhBAgOixTLYG_zc,5581
+framcore/components/Demand.py,sha256=c8N0R_f2GR58zt4pAXVmC-KcqLP5yeAuwQyEYQtHAtA,6241
+framcore/components/Flow.py,sha256=slbVLlZsIxcEgilAJTe3eib4-xi2DTSAGHbpkh3KgFg,7391
+framcore/components/HydroModule.py,sha256=5svph2fVlAYnMqKywdQv9hPsMLbHqSOdFIGwmkf8lMY,14302
+framcore/components/Node.py,sha256=L_CDjjRHyxbiPCTjjj89dNQ9Z7VZjYp_dTHVodJN-DM,3661
+framcore/components/Thermal.py,sha256=mOIIybvIDGhwsWN5ZCIch1Lkz8M1513S6uBI5bOil8s,7895
+framcore/components/Transmission.py,sha256=u5opwBKWGylwDYYBELvGl8omHrBmMk4u4O5rE2hsdkA,7889
+framcore/components/_PowerPlant.py,sha256=zDJ5LtYQN2GLa__BaqCLz54mZJil3dOYjICMPurh-U8,2787
+framcore/components/__init__.py,sha256=0N4UMrYi7cYYaZHMIS6HSOli2jEbtct6LsZ0JcwGz5A,568
+framcore/components/wind_solar.py,sha256=MSKr8MacjhDZLfKgWZf1NVyzurcMrGVjJhXfQzafzjQ,2311
+framcore/curves/Curve.py,sha256=89CsAJpCa_GkQtsBGclUcK8D3ttCyYhs583-_6zE0is,934
+framcore/curves/LoadedCurve.py,sha256=mW4OsG9WPEcm3rgPHZRMnMjqdf_PzYH2rYusN5PNGwQ,3639
+framcore/curves/__init__.py,sha256=BnzdAZVjPwJcjduramRPPX6NJag-g6aKXPho2PwmGco,170
+framcore/events/__init__.py,sha256=O3lOZukd_ixwbkoOmf2ei_--lKJLVXvyhSHjUDfaXEE,401
+framcore/events/events.py,sha256=mNcHUjWraKyb-gwxeKr5ryOtcN8dCKptRWIYgcxM1p4,1683
+framcore/expressions/Expr.py,sha256=qPbRGZxaWpn3y70dENth68DqkF3HP9dN-BVBp87yZWw,25554
+framcore/expressions/__init__.py,sha256=Fn6a9aVCSU-R0QeGmZB7QuHkdLzP7Fvj_prnDLfwsrs,750
+framcore/expressions/_get_constant_from_expr.py,sha256=3891ls8NQzVhTsvzvMsP7TG9Q5bE9jnOlBgA-N_Upjo,16429
+framcore/expressions/_utils.py,sha256=mtruqnHcwpkIufbTFjJvT3iUfN98gN51SQ9e9hS9cUc,2123
+framcore/expressions/queries.py,sha256=Hx3zOQPYR54cwttr1_NoS1i4HQRFpROfeBRqBLUWIF8,18077
+framcore/expressions/units.py,sha256=RAcNTKbkuIs0svkIk6L7hPwA7-G8yHAaByB5BIku1kI,7715
+framcore/fingerprints/__init__.py,sha256=YpIj-t6DRrSOmdidchC4qjLHSoZwsdkf9980nHUsnsw,256
+framcore/fingerprints/fingerprint.py,sha256=GnvzaLquT15lXPGnWe103plCNMNgLzlY0ve1LUY8W5A,9179
+framcore/juliamodels/JuliaModel.py,sha256=7USkw5Y4HKrSZP-Hmm-omoNXHqkow4NQqr0vuZOxIFU,7135
+framcore/juliamodels/__init__.py,sha256=2ia9EGUQAZD0_f2o0NWdhD0d2z80K_bweohnGNfnpGA,124
+framcore/loaders/__init__.py,sha256=iwlnauyXhH_BAuVIKVmX2vMvU94i_bXI57CE82eM7VA,209
+framcore/loaders/loaders.py,sha256=-lMVdp1SDuUJ_kIGaEZTnl-_7keMCk0TOmSX0d-1efI,11118
+framcore/metadata/Div.py,sha256=fIIB9W9fVJEUNzqIWXOJ9ZN3tWE8dB8ap2BdULT2fJw,2428
+framcore/metadata/ExprMeta.py,sha256=nbpEBB2lkwRP1VqD9ohSKfGj99cVIX1g6hdVAocEXXQ,1679
+framcore/metadata/LevelExprMeta.py,sha256=H_sqVFDP2NF6y4e1eq0ANH0Cq7ZdpSBuYaODtfWnO_4,1103
+framcore/metadata/Member.py,sha256=w41UYW97BIXPr_yk514aaHmiYiYS8_Voh0bbE0qCleA,1715
+framcore/metadata/Meta.py,sha256=P9ESFJlrxxhcY9PNSnnccrsLBulu1v3Kir6agzSrv0I,1173
+framcore/metadata/__init__.py,sha256=8GfRSOVEb-051QiMCsgwYgqh-KA8UwSVdKpqtz1a3ZA,350
+framcore/populators/Populator.py,sha256=SraN4QOTsA3yXEVG4z9ohWfPKokssl3uvDJPGh56lrU,4077
+framcore/populators/__init__.py,sha256=jE6tHIvTaPTWcD-yVpBOjDBxI3xFqJh0QASfQexBLCE,119
+framcore/querydbs/CacheDB.py,sha256=VZxNuZ9jX3a0ejDrUqAaZgBmFMTJG64v470-Imtl9i4,1738
+framcore/querydbs/ModelDB.py,sha256=XD4jHlmRQHqF7L2euDIMrPZREhr3SXgv0UnqkADLzRw,1039
+framcore/querydbs/QueryDB.py,sha256=IV96mtslktpJMrdxgrwQetVx4R1HAP1GxtKgx9WLPZA,1233
+framcore/querydbs/__init__.py,sha256=oPX2sqAMoEMxWL9b_sRg4z4Q_b80iDm_jk-W_qmpEME,231
+framcore/solvers/Solver.py,sha256=taiprQFC75pelr2koSmmxnJOeYtl7HsEi-0zFT6SR1k,2255
+framcore/solvers/SolverConfig.py,sha256=QkowQHTfcB2f7v3_8U1zfkSewizzY7BHjT8LhSu8Bx0,10597
+framcore/solvers/__init__.py,sha256=q9HLYJkRdvJeFgAM1NBGIaFI8APmsZCDTy1AkIKw_Zs,179
+framcore/timeindexes/AverageYearRange.py,sha256=EDEkBxQNzTTQ2LtFubsTp9fWtBFWwlDyhPnaN91GJSY,1094
+framcore/timeindexes/ConstantTimeIndex.py,sha256=eg8vsApymy1PkNEtHhx50L0eWFo9DB1xv4YXWbB35JU,787
+framcore/timeindexes/DailyIndex.py,sha256=nORCghZjLvsuObRbC9SbR-NMBTng_DmjqULW2eJKh0M,1127
+framcore/timeindexes/FixedFrequencyTimeIndex.py,sha256=BhIilAo6nG7-UEqPwJLS1T5ONA7g9RLrTIBIVapIk9E,33601
+framcore/timeindexes/HourlyIndex.py,sha256=hdvoXmzzbATxjgO4uSyjo0v_GySkasmvs5_D6HzKrPc,1131
+framcore/timeindexes/IsoCalendarDay.py,sha256=tm9XC5XEn6C_O5vrT94TNIm30XyMBpf7nCTVc0D9i-c,1144
+framcore/timeindexes/ListTimeIndex.py,sha256=UjTTOiwLJ4D_BJPmuROQ6-mp01OV7aJ2sxnkn2iqcZI,11848
+framcore/timeindexes/ModelYear.py,sha256=oq1Ef1gD-j6cteuQzx7eR8Ew9ZBL2QuDF0e1GVnu730,869
+framcore/timeindexes/ModelYears.py,sha256=92UGocvqPtI6I01uJc6PKOInRVmYpZX3FcUnQtM2lxs,958
+framcore/timeindexes/OneYearProfileTimeIndex.py,sha256=yKaan34cHSOypzzt_Q3nzn2ZZFy0R1bg7lChUEu--tQ,1154
+framcore/timeindexes/ProfileTimeIndex.py,sha256=FDXXXEaXoImsiLSWUxYAFFOCzQpUb170sPk9hUuLkMs,1831
+framcore/timeindexes/SinglePeriodTimeIndex.py,sha256=h9lkfIOlXuY-6OHULaVekTbtrSVCYgM5AjW0xTa1b1k,1452
+framcore/timeindexes/TimeIndex.py,sha256=HPcyuJNoBrdvS7jAsQLLUIEYF9WvtT9cPL7dH2QX2a4,3515
+framcore/timeindexes/WeeklyIndex.py,sha256=KiSQouztEW6dwphZwxYa8BsNpFQKs6FMWjrmneYnsz8,1160
+framcore/timeindexes/__init__.py,sha256=2LmQFuMR1DffqHk5O2zd8o9g8QsazxSSykxOE7WGP4o,1351
+framcore/timeindexes/_time_vector_operations.py,sha256=05HqseGkRqwztNk5rEI6p5VXFtXqmwArWuir88OFbnk,31301
+framcore/timevectors/ConstantTimeVector.py,sha256=fp7Bu6nP8iIl0Pn9JLD0sMDMkldZ44d8bQNWWl2RvHQ,5651
+framcore/timevectors/LinearTransformTimeVector.py,sha256=tmPICcT5mlGn60JDpQsQ5p3FXZyRbs5wehAGbH1sj2o,5435
+framcore/timevectors/ListTimeVector.py,sha256=g8v4ym5NzjRJpHW9awbPKGQA4XidYPhBT_u8iSd5744,5429
+framcore/timevectors/LoadedTimeVector.py,sha256=EmCSYwvvjzb7yQae2Y1C_QdY4sHsy4RARQfd06odGmU,4018
+framcore/timevectors/ReferencePeriod.py,sha256=dnstzGIbK6Y2nxZqBEBueIGH44QmWva-HZ7-HTUctis,1712
+framcore/timevectors/TimeVector.py,sha256=D8YOwdNo4TcXHVaTXCc1GiEJXrU85ve-v7QGcFMKeN8,3454
+framcore/timevectors/__init__.py,sha256=Wd3gXGatwpbe2yMKSCq7O9My5wbveuK23iYO2ykkUIk,603
+framcore/utils/__init__.py,sha256=qmmfcTWo6hrNyZn07m-A-6pcHwAUw5Y9It9ihapiiKY,1221
+framcore/utils/get_regional_volumes.py,sha256=gTiXfKBPz4j7t-vyh49jBOQoszrBOMp8ZJViaOSZrA4,16041
+framcore/utils/get_supported_components.py,sha256=yjLMmNwaHT8N9ZueQjw4v6z_rt5_aQVVtb7WAJ1-mzg,1885
+framcore/utils/global_energy_equivalent.py,sha256=2k3PbORz6nwTdCriye7tJf4Ht5v6F1ZIetuSGmkfvnE,3445
+framcore/utils/isolate_subnodes.py,sha256=Em1dc2shtWiF0IqxGj0CVjFF2A_6Ou64lsp88uAEcK8,6917
+framcore/utils/loaders.py,sha256=pWOyRLSV6PikZHuUomKnZOL6c6VzXERysaMC_Q3mvfg,3201
+framcore/utils/node_flow_utils.py,sha256=qnWelrqslc1FDBw-NdkVVQ1nk0l_EEvO8cDgObZnmJQ,7781
+framcore/utils/storage_subsystems.py,sha256=LTKt6j3bCY7rvmOY3dUGcBP711CPXv5PS5XRb2DUmWM,4144
+fram_core-0.1.1.dist-info/METADATA,sha256=7JuS8ef0hHwFatbcxvmbtSKPTmebjofuRj02SAxKnjs,1277
+fram_core-0.1.1.dist-info/WHEEL,sha256=kJCRJT_g0adfAJzTx2GUMmS80rTJIVHRCfG0DQgLq3o,88
+fram_core-0.1.1.dist-info/licenses/LICENSE.md,sha256=fxh4ZxuR8dM2HDs-pIUitPrJdxQ4fEFh1GvEYZA2m1E,1075
+fram_core-0.1.1.dist-info/RECORD,,

{fram_core-0.1.0a2.dist-info → fram_core-0.1.1.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: poetry-core 2.2.1
+Generator: poetry-core 2.3.1
 Root-Is-Purelib: true
 Tag: py3-none-any

framcore/Base.py

@@ -1,5 +1,6 @@
 import contextlib
 import inspect
+from collections.abc import Callable
 from typing import Any
 
 from framcore.events import (
@@ -18,9 +19,7 @@ class Base:
     """Core base class to share methods."""
 
     def _check_type(self, value, class_or_tuple) -> None:  # noqa: ANN001
-        if not isinstance(value, class_or_tuple):
-            message = f"Expected {class_or_tuple} for {self}, got {type(value).__name__}"
-            raise TypeError(message)
+        check_type(value, class_or_tuple, caller=self)
 
     def _ensure_float(self, value: object) -> float:
         with contextlib.suppress(Exception):
@@ -140,3 +139,23 @@ class Base:
         except Exception:
             pass
         return type(value).__name__
+
+
+# could not place this in utils and use __init__ as modules in utils also import queries, if queries then import via utils __init__ we get circular imports.
+def check_type(value: object, expected: type | tuple[type], caller: Callable | None = None) -> None:
+    """
+    Check a value matches expected type(s).
+
+    Args:
+        value (object): value being checked.
+        expected (type | tuple[type]): Expected types.
+        caller (Callable): The origin of the check.
+
+    Raises:
+        TypeError: When value does not match expected types.
+
+    """
+    if not isinstance(value, expected):
+        message = f"{expected}, got {type(value).__name__}"
+        message = "Expected " + message if caller is None else f"{caller} expected " + message
+        raise TypeError(message)

framcore/Model.py

@@ -10,9 +10,12 @@ from framcore.timevectors import TimeVector
 if TYPE_CHECKING:
     from framcore.aggregators import Aggregator
 
+
 class ModelDict(dict):
     """Dict storing only values of type Component | Expr | TimeVector | Curve."""
-    def __setitem__(self, key, value):
+
+    def __setitem__(self, key: str, value: Component | Expr | TimeVector | Curve) -> None:
+        """Set item with type checking."""
         if not isinstance(key, str):
             message = f"Expected str for key {key}, got {type(key).__name__}"
             raise TypeError(message)
@@ -21,24 +24,39 @@ class ModelDict(dict):
             raise TypeError(message)
         return super().__setitem__(key, value)
 
+
 class Model(Base):
-    """Definition of the Model class."""
+    """
+    Model stores the representation of the energy system with Components, TimeVectors, Expression, and the Aggregators applied to the Model.
+
+    - Components describe the main elements in the energy system. Can have additional Attributes.
+    - TimeVector and Curve hold the time series data.
+    - Expressions for data manipulation of TimeVectors and Curves. Can be queried.
+    - Aggregators handle aggregation and disaggregation of Components. Aggregators are added to Model when used (Aggregator.aggregate(model)),
+    and can be undone in LIFO order with disaggregate().
+
+    Methods:
+        get_data(): Get dict of Components, Expressions, TimeVectors and Curves stored in the Model. Can be modified.
+        disaggregate(): Undo all aggregations applied to Model in LIFO order.
+        get_content_counts(): Return number of objects stored in model organized into concepts and types.
+
+    """
 
     def __init__(self) -> None:
-        """Create a new model instance."""
+        """Create a new model instance with empty data and no aggregators."""
         self._data = ModelDict()
         self._aggregators: list[Aggregator] = []
 
+    def get_data(self) -> ModelDict:
+        """Get dict of Components, Expressions, TimeVectors and Curves stored in the Model. Can be modified."""
+        return self._data
+
     def disaggregate(self) -> None:
-        """Undo all aggregations in LIFO order."""
+        """Undo all aggregations applied to Model in LIFO order."""
         while self._aggregators:
             aggregator = self._aggregators.pop(-1)  # last item
             aggregator.disaggregate(self)
 
-    def get_data(self) -> ModelDict:
-        """Get internal data. Modify this with care."""
-        return self._data
-
     def get_content_counts(self) -> dict[str, Counter]:
         """Return number of objects stored in model organized into concepts and types."""
         data_values = self.get_data().values()
@@ -70,4 +88,3 @@ class Model(Base):
             counts["aggregators"][type(a).__name__] += 1
 
         return counts
-

framcore/__init__.py

@@ -1,9 +1,10 @@
 # framcore/__init__.py
-
+from framcore.Base import check_type
 from framcore.Base import Base
 from framcore.Model import Model
 
 __all__ = [
     "Base",
     "Model",
+    "check_type",
 ]

framcore/aggregators/Aggregator.py

@@ -18,17 +18,36 @@ class Aggregator(Base, ABC):
     """
     Aggregator interface class.
 
-    Public API is the aggregate and disaggregate methods.
+    Aggregators handles aggregation and disaggregation of Components.
+    - The general approach for aggregation is to group Components, aggregate Components in the same group to (a) new Component(s),
+    delete the detailed Components, and add the mapping to self._aggregation_map.
+    - The general approach for disaggregation is to restore the detailed Components, move results from aggregated
+    Components to detailed Components, and delete the aggregated Components.
+
+    Concrete Aggregators must implement the abstract methods _aggregate() and _disaggregate().
+
+    Some rules for using Aggregators:
+    1. Disaggragate can only be called after aggregate has been called.
+    2. Not allowed to call aggregate twice. Must call disaggregate before aggregate can be called again.
+    3. Aggregators are stored in Model when aggregate is called. Disaggregate by calling Model.disaggregate(),
+         which will disaggregate all Aggregators in LIFO order.
+    4. At the moment we allow changes to the aggregated Components, which is ignored during disaggregation. TODO: Handle this
+    5. 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.
+
+    Some design notes:
+    - Levels and profiles are aggregated separately and then combined into attributes.
+    - We have chosen to eagerly evaluate weights for aggregation (weighted averages) and disaggregation of levels and profiles.
+        This approach supports any form of aggregation by varying the weights, and complex weights can be created by eagerly evaluating
+        expressions and using the result to compute those weights.
+    - This is a balance between eagerly evaluating everything and setting up complex expressions.
+        Eagerly evaluating everything would require setting up new TimeVectors after evaluation, which is not ideal.
+        While setting up complex expressions gives expressions that are harder to work with and slower to query from.
+    - This trade-off simplifies adding 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.
 
-    These methods come with the folloing calling rules:
-    1. Not allowed to call aggregate twice. Must call disaggregate before aggregate can be called again.
-    2. Disaggragate can only be called after aggregate has been called.
-
-    Implementations should implement _aggregate and _disaggregate.
-    - The general approach for aggregation is to group components, aggregated components in the same group, delete the detailed components,
-    and add the mapping to self._aggregation_map.
-    - The general approach for disaggregation is to restore the detailed components, move results from aggregated components to detailed components,
-    and delete the aggregated components.
     """
 
     def __init__(self) -> None:
@@ -42,7 +61,7 @@ class Aggregator(Base, ABC):
         self._check_type(model, Model)
 
         if self._is_last_call_aggregate is True:
-            message = f"Will overwrite existing aggregation."
+            message = "Will overwrite existing aggregation."
             self.send_warning_event(message)
 
         self._original_data = deepcopy(model.get_data())

framcore/aggregators/HydroAggregator.py

@@ -27,9 +27,10 @@ if TYPE_CHECKING:
 
 class HydroAggregator(Aggregator):
     """
-    Aggregate hydro modules into two equivalent modules based on the regulation factor, into one regulated and one unregulated module per area.
+    Aggregate HydroModules into two equivalent modules based on the regulation factor, into one regulated and one unregulated module per area.
 
     Aggregation steps (self._aggregate):
+
     1. Group modules based on their power nodes (self._group_modules_by_power_node)
         - Modules with generators are grouped based on their power nodes. You can choose to only group modules for certain power nodes by giving
         self._power_node_members alone or together with self._metakey_power_node. NB! Watershed that crosses power nodes should not be aggregated in two
@@ -59,7 +60,9 @@ class HydroAggregator(Aggregator):
     3b. Make new hydro module and delete original modules from model data.
     4. Add mapping from detailed to aggregated modules to self._aggregation_map.
 
+
     Disaggregation steps (self._disaggregate):
+
     1. Restore original modules from self._original_data. NB! Changes to aggregated modules are lost except for results (TODO)
     2. Move production and filling results from aggregated modules to detailed modules, weighted based on production capacity and reservoir capacity.
         - TODO: Water values, spill, bypass and pumping results are currently ignored in the disaggregation.
@@ -69,15 +72,7 @@ class HydroAggregator(Aggregator):
     from the model after the first aggregation. Reservoirs will also be assigned to the power node which has the highest cumulative energy equivalent, so
     this aggregator does not work well for reservoirs that are upstream of multiple power nodes.
 
-    Other 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:
         _metakey_energy_eq_downstream (str): Metadata key for energy equivalent downstream.
@@ -93,6 +88,7 @@ class HydroAggregator(Aggregator):
         _release_capacity_profile (TimeVector | None): If given, use this profile for all aggregated modules' release capacities.
 
     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
@@ -128,13 +124,15 @@ class HydroAggregator(Aggregator):
         super().__init__()
         self._check_type(metakey_energy_eq_downstream, str)
         self._check_type(ror_threshold, float)
-        assert ror_threshold >= 0, ValueError(f"ror_threshold must be non-negative, got {ror_threshold}.")
         self._check_type(data_dim, SinglePeriodTimeIndex)
         self._check_type(scen_dim, FixedFrequencyTimeIndex)
         self._check_type(metakey_power_node, (str, type(None)))
         self._check_type(power_node_members, (list, type(None)))
-        if metakey_power_node is not None:
-            assert len(power_node_members) > 0, ValueError("If metakey_power_node is given, power_node_members must also be given.")
+        if ror_threshold < 0:
+            msg = f"ror_threshold must be non-negative, got {ror_threshold}."
+            raise ValueError(msg)
+        if metakey_power_node is not None and len(power_node_members) <= 0:
+            raise ValueError("If metakey_power_node is given, power_node_members must also be given.")
 
         self._metakey_energy_eq_downstream = metakey_energy_eq_downstream
         self._ror_threshold = ror_threshold
@@ -183,7 +181,7 @@ class HydroAggregator(Aggregator):
             for dd in d:
                 if dd not in self._aggregation_map:
                     self._aggregation_map[dd] = set([a])
-                elif not data[dd].get_reservoir():  # if reservoir module already in map, skip as reservoir mapping is main mapping
+                elif not (data[dd].get_reservoir() and data[a].get_reservoir()):  # reservoir modules can only be mapped to one aggregated reservoir module
                     self._aggregation_map[dd].add(a)
         self.send_debug_event(f"add generator modules to _aggregation_map time: {round(time() - t, 3)} seconds")
 
@@ -450,7 +448,7 @@ class HydroAggregator(Aggregator):
                     (
                         mm,
                         get_level_value(
-                            data[mm].get_generator().get_energy_eq().get_level() * data[mm].get_release_capacity().get_level(),
+                            data[mm].get_generator().get_energy_equivalent().get_level() * data[mm].get_release_capacity().get_level(),
                             model,
                             "MW",
                             self._data_dim,
@@ -466,7 +464,7 @@ class HydroAggregator(Aggregator):
 
         return ignore_production_capacity_modules
 
-    def _aggregate_groups(  # noqa: C901
+    def _aggregate_groups(  # noqa: C901, PLR0915
         self,
         model: Model,
         upstream_topology: dict[str, list[str]],
@@ -487,10 +485,10 @@ class HydroAggregator(Aggregator):
 
             generator = HydroGenerator(
                 power_node=data[generator_module_names[0]].get_generator().get_power_node(),
-                energy_eq=Conversion(level=ConstantTimeVector(1.0, "kWh/m3", is_max_level=True)),
+                energy_equivalent=Conversion(level=ConstantTimeVector(1.0, "kWh/m3", is_max_level=True)),
                 production=sum_production,
             )
-            energy_eq = generator.get_energy_eq().get_level()
+            energy_eq = generator.get_energy_equivalent().get_level()
 
             # Release capacity
             release_capacities = [data[m].get_release_capacity() for m in generator_module_names if m not in ignore_capacity]
@@ -501,9 +499,16 @@ class HydroAggregator(Aggregator):
                 release_capacities = deepcopy(release_capacities)
                 for rc in release_capacities:
                     rc.set_profile(self._release_capacity_profile)
-            generator_energy_eqs = [data[m].get_generator().get_energy_eq() for m in generator_module_names if m not in ignore_capacity]
+            generator_energy_eqs = [data[m].get_generator().get_energy_equivalent() for m in generator_module_names if m not in ignore_capacity]
             release_capacity_levels = [rc.get_level() * ee.get_level() for rc, ee in zip(release_capacities, generator_energy_eqs, strict=True)]
-            release_capacity = MaxFlowVolume(level=sum(release_capacity_levels) / energy_eq, profile=self._release_capacity_profile)
+            
+            release_capacity_profile = None
+            if any(rc.get_profile() for rc in release_capacities):
+                one_profile_max = Expr(src=ConstantTimeVector(1.0, is_zero_one_profile=False), is_profile=True)
+                weights = [get_level_value(rcl, model, "MW", self._data_dim, self._scen_dim, is_max=True) for rcl in release_capacity_levels]
+                profiles = [rc.get_profile() if rc.get_profile() else one_profile_max for rc in release_capacities]
+                release_capacity_profile = _aggregate_weighted_expressions(profiles, weights)
+            release_capacity = MaxFlowVolume(level=sum(release_capacity_levels) / energy_eq, profile=release_capacity_profile)
 
             # Inflow level
             upstream_inflow_levels = defaultdict(list)
@@ -513,7 +518,7 @@ class HydroAggregator(Aggregator):
                     if inflow:
                         upstream_inflow_levels[m].append(inflow.get_level())
             inflow_level_energy = sum(
-                sum(upstream_inflow_levels[m]) * data[m].get_generator().get_energy_eq().get_level()
+                sum(upstream_inflow_levels[m]) * data[m].get_generator().get_energy_equivalent().get_level()
                 for m in generator_module_names
                 if len(upstream_inflow_levels[m]) > 0
             )
@@ -524,7 +529,7 @@ class HydroAggregator(Aggregator):
             inflow_profile_to_energyinflow = defaultdict(list)
             inflow_level_to_value = dict()
             for m in generator_module_names:
-                m_energy_eq = data[m].get_generator().get_energy_eq().get_level()
+                m_energy_eq = data[m].get_generator().get_energy_equivalent().get_level()
                 m_energy_eq_value = get_level_value(
                     m_energy_eq,
                     db=model,
@@ -592,6 +597,13 @@ class HydroAggregator(Aggregator):
         """Aggregate reservoir fillings if all fillings are not None."""
         sum_filling = None
         if all(filling.get_level() for filling in fillings):
+            if any(not filling.get_profile() for filling in fillings):
+                missing = [member for member, filling in zip(members, fillings, strict=False) if not filling.get_profile()]
+                message = (
+                    "Some reservoir fillings in grouped modules have no profile. Cannot aggregate profiles.",
+                    f"Group: '{group_id}', missing profile for {missing}.",
+                )
+                raise ValueError(message)
             level, profiles, weights = self._get_level_profiles_weights_fillings(model, fillings, energy_eq_downstreams, energy_eq, weight_unit)
             profile = _aggregate_weighted_expressions(profiles, weights)
             sum_filling = StockVolume(level=level, profile=profile)
@@ -755,7 +767,7 @@ class HydroAggregator(Aggregator):
         for det in detailed_keys:
             det_module = data[det]
             release_capacity_level = det_module.get_release_capacity().get_level()
-            generator_energy_eq = det_module.get_generator().get_energy_eq().get_level()
+            generator_energy_eq = det_module.get_generator().get_energy_equivalent().get_level()
             production_weight = get_level_value(
                 release_capacity_level * generator_energy_eq,
                 db=model,