fram-core 0.0.0__tar.gz → 0.1.0__tar.gz

fram_core-0.1.0/LICENSE.md

@@ -0,0 +1,8 @@
+The MIT License (MIT)
+Copyright © 2025 NVE
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

fram_core-0.1.0/PKG-INFO

@@ -0,0 +1,42 @@
+Metadata-Version: 2.4
+Name: fram-core
+Version: 0.1.0
+Summary: 
+License: LICENSE.md
+License-File: LICENSE.md
+Author: The Norwegian Water Resources and Energy Directorate
+Author-email: fram@nve.no
+Requires-Python: >=3.11,<4
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: juliacall (>=0.9.28,<0.10.0)
+Requires-Dist: numexpr (>=2.10.2)
+Requires-Dist: numpy (>=2.2.2)
+Requires-Dist: pandas (>=2.2.3)
+Requires-Dist: sympy (>=1.13.3)
+Description-Content-Type: text/markdown
+
+# fram-core
+
+## About
+
+**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). 
+
+For FRAM documentation see [FRAM mainpage](https://nve.github.io/fram).
+
+## Installation
+
+To add the package to your project use:
+
+    pip install fram-core
+
+With poetry:
+
+    poetry add fram-core
+

fram_core-0.1.0/README.md

@@ -0,0 +1,19 @@
+# fram-core
+
+## About
+
+**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). 
+
+For FRAM documentation see [FRAM mainpage](https://nve.github.io/fram).
+
+## Installation
+
+To add the package to your project use:
+
+    pip install fram-core
+
+With poetry:
+
+    poetry add fram-core

fram_core-0.1.0/framcore/Base.py

@@ -0,0 +1,161 @@
+import contextlib
+import inspect
+from collections.abc import Callable
+from typing import Any
+
+from framcore.events import (
+    send_debug_event,
+    send_error_event,
+    send_event,
+    send_info_event,
+    send_warning_event,
+)
+from framcore.fingerprints import Fingerprint
+
+# TODO: Consider context dict | None in event-methods to support more info (e.g. process id)
+
+
+class Base:
+    """Core base class to share methods."""
+
+    def _check_type(self, value, class_or_tuple) -> None:  # noqa: ANN001
+        check_type(value, class_or_tuple, caller=self)
+
+    def _ensure_float(self, value: object) -> float:
+        with contextlib.suppress(Exception):
+            return float(value)
+        message = f"Unable to convert {value} to float."
+        raise ValueError(message)
+
+    def _check_int(self, value: int, lower_bound: int | None, upper_bound: int | None) -> None:
+        if lower_bound is not None and value < lower_bound:
+            message = f"Value {value} is less than lower_bound {lower_bound}."
+            raise ValueError(message)
+        if upper_bound is not None and value > upper_bound:
+            message = f"Value {value} is greater than upper_bound {upper_bound}."
+            raise ValueError(message)
+
+    def _check_float(self, value: float, lower_bound: float | None, upper_bound: float | None) -> None:
+        if lower_bound is not None and value < lower_bound:
+            message = f"Value {value} is less than lower_bound {lower_bound}."
+            raise ValueError(message)
+        if upper_bound is not None and value > upper_bound:
+            message = f"Value {value} is greater than upper_bound {upper_bound}."
+            raise ValueError(message)
+
+    def _report_errors(self, errors: set[str]) -> None:
+        if errors:
+            n = len(errors)
+            s = "s" if n > 1 else ""
+            error_str = "\n".join(errors)
+            message = f"Found {n} error{s}:\n{error_str}"
+            raise RuntimeError(message)
+
+    def send_event(self, event_type: str, **kwargs: dict[str, Any]) -> None:
+        """All events in core should use this."""
+        send_event(sender=self, event_type=event_type, **kwargs)
+
+    def send_warning_event(self, message: str) -> None:
+        """Use this to send warning event."""
+        send_warning_event(sender=self, message=message)
+
+    def send_error_event(self, message: str, exception_type_name: str, traceback: str) -> None:
+        """Use this to send error event."""
+        send_error_event(sender=self, message=message, exception_type_name=exception_type_name, traceback=traceback)
+
+    def send_info_event(self, message: str) -> None:
+        """Use this to send info event."""
+        send_info_event(sender=self, message=message)
+
+    def send_debug_event(self, message: str) -> None:
+        """Use this to send debug event."""
+        send_debug_event(sender=self, message=message)
+
+    def get_fingerprint_default(
+        self,
+        refs: dict[str, str] | None = None,
+        excludes: set[str] | None = None,
+    ) -> Fingerprint:
+        """
+        Generate a Fingerprint for the object, optionally including references and excluding specified properties.
+
+        Parameters
+        ----------
+        refs : dict[str, str] | None, optional
+            Dictionary mapping property names to reference keys to include as references in the fingerprint.
+        excludes : set[str] | None, optional
+            Set of property names to exclude from the fingerprint.
+
+        Returns
+        -------
+        Fingerprint
+            The generated fingerprint for the object.
+
+        """
+        fingerprint = Fingerprint(source=self)
+
+        if refs:
+            for ref_prop, ref_key in refs.items():
+                if ref_key is not None:
+                    fingerprint.add_ref(ref_prop, ref_key)
+
+        default_excludes = {"_parent"}
+
+        for prop_name, prop_value in self.__dict__.items():
+            if callable(prop_value) or (refs and prop_name in refs) or (excludes and prop_name in excludes) or prop_name in default_excludes:
+                continue
+
+            if prop_value is None:
+                continue
+
+            fingerprint.add(prop_name, prop_value)
+
+        return fingerprint
+
+    def _get_property_name(self, property_reference) -> str | None:  # noqa: ANN001
+        for name, value in inspect.getmembers(self):
+            if value is property_reference:
+                return name
+        return None
+
+    def __repr__(self) -> str:
+        """Display type and non-None fields."""
+        type_name = type(self).__name__
+        value_fields = []
+        for k, v in vars(self).items():
+            display_value = self._get_attr_str(k, v)
+            if display_value is not None:
+                value_fields.append(f"{k}={display_value}")
+        value_fields = ", ".join(value_fields)
+        return f"{type_name}({value_fields})"
+
+    def _get_attr_str(self, key: str, value: object) -> str | None:
+        if value is None:
+            return None
+        if isinstance(value, int | float | str | bool):
+            return value
+        try:
+            return value._get_attr_str()  # noqa: SLF001
+        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)

fram_core-0.1.0/framcore/Model.py

@@ -0,0 +1,90 @@
+from collections import Counter
+from typing import TYPE_CHECKING
+
+from framcore import Base
+from framcore.components import Component
+from framcore.curves import Curve
+from framcore.expressions import Expr
+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: 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)
+        if not isinstance(value, Component | Expr | TimeVector | Curve):
+            message = f"Expected Component | Expr | TimeVector | Curve for key {key}, got {type(value).__name__}"
+            raise TypeError(message)
+        return super().__setitem__(key, value)
+
+
+class Model(Base):
+    """
+    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 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 applied to Model in LIFO order."""
+        while self._aggregators:
+            aggregator = self._aggregators.pop(-1)  # last item
+            aggregator.disaggregate(self)
+
+    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()
+        counts = {
+            "components": Counter(),
+            "timevectors": Counter(),
+            "curves": Counter(),
+            "expressions": Counter(),
+        }
+        for obj in data_values:
+            if isinstance(obj, Component):
+                key = "components"
+            elif isinstance(obj, TimeVector):
+                key = "timevectors"
+            elif isinstance(obj, Curve):
+                key = "curves"
+            elif isinstance(obj, Expr):
+                key = "expressions"
+            else:
+                key = "unexpected"
+                if key not in counts:
+                    counts[key] = Counter()
+            counts[key][type(obj).__name__] += 1
+
+        assert len(data_values) == sum(c.total() for c in counts.values())
+
+        counts["aggregators"] = Counter()
+        for a in self._aggregators:
+            counts["aggregators"][type(a).__name__] += 1
+
+        return counts

fram_core-0.1.0/framcore/__init__.py

@@ -0,0 +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",
+]

fram_core-0.1.0/framcore/aggregators/Aggregator.py

@@ -0,0 +1,172 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections import defaultdict
+from collections.abc import Iterable
+from copy import deepcopy
+
+from framcore.Base import Base
+from framcore.components import Component
+from framcore.curves import Curve
+from framcore.expressions import Expr
+from framcore.metadata import Member
+from framcore.Model import Model
+from framcore.timevectors import TimeVector
+
+
+class Aggregator(Base, ABC):
+    """
+    Aggregator interface class.
+
+    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.
+
+    """
+
+    def __init__(self) -> None:
+        """Initialize the Aggregator with default state for aggregation tracking and data storage."""
+        self._is_last_call_aggregate = None
+        self._original_data: dict[str, Component | TimeVector | Curve | Expr] | None = None
+        self._aggregation_map: dict[str, set[str]] = None
+
+    def aggregate(self, model: Model) -> None:
+        """Aggregate model. Keep original data in case disaggregate is called."""
+        self._check_type(model, Model)
+
+        if self._is_last_call_aggregate is True:
+            message = "Will overwrite existing aggregation."
+            self.send_warning_event(message)
+
+        self._original_data = deepcopy(model.get_data())
+        self._aggregate(model)
+        self._is_last_call_aggregate = True
+        if self in model._aggregators:  # noqa: SLF001
+            message = f"{model} has already been aggregated with {self}. Cannot perform the same Aggregation more than once on a Model object."
+            raise ValueError(message)
+
+        # transfer_unambigous_memberships to aggregated components to support further aggregation
+        mapping = self.get_aggregation_map()
+        reversed_mapping = defaultdict(set)
+        new_data = model.get_data()
+        for member_id, group_ids in mapping.items():
+            self._check_type(group_ids, set)
+            for group_id in group_ids:
+                self._check_type(group_id, str)
+                member_component = self._original_data[member_id]
+                group_component = new_data[group_id]
+                reversed_mapping[group_component].add(member_component)
+        for group_component, member_components in reversed_mapping.items():
+            transfer_unambigous_memberships(group_component, member_components)
+
+        model._aggregators.append(deepcopy(self))  # noqa: SLF001
+
+    def disaggregate(self, model: Model) -> None:
+        """Disaggregate model back to pre-aggregate form. Move results into the disaggregated objects."""
+        self._check_type(model, Model)
+        self._check_is_aggregated()
+        self._disaggregate(model, self._original_data)
+        self._is_last_call_aggregate = False
+        self._original_data = None
+        self._aggregation_map = None
+
+    def get_aggregation_map(self) -> dict[str, set[str]]:
+        """
+        Return dictionary mapping from disaggregated to aggregated Component IDs.
+
+        The mapping should tell you which of the original Components were aggregated into which new Components.
+        Components which are left as is should not be in the mapping.
+        Components which are deleted without being aggregated are mapped to an empty set.
+        """
+        if self._aggregation_map is None:
+            message = f"{self} has not yet performed an aggregation or the aggregation map was not created during aggregation."
+            raise ValueError(message)
+        return self._aggregation_map
+
+    @abstractmethod
+    def _aggregate(self, model: Model) -> None:
+        """Modify model inplace. Replace components with aggregated components according to some method."""
+        pass
+
+    @abstractmethod
+    def _disaggregate(
+        self,
+        model: Model,
+        original_data: dict[str, Component | TimeVector | Curve | Expr],
+    ) -> None:
+        """
+        Modify model inplace. Restore from aggregated to original components.
+
+        Transfer any results from aggregated components to restored (disaggregated) components.
+
+        Implementers should document and handle changes in model instance between aggregation and disaggregation.
+        E.g. what to do if an aggregated component has been deleted prior to disaggregate call.
+        """
+        pass
+
+    def _check_is_aggregated(self) -> None:
+        if self._is_last_call_aggregate in [False, None]:
+            message = "Not aggregated. Must call aggregate and disaggregate in pairs."
+            raise RuntimeError(message)
+
+
+def transfer_unambigous_memberships(group_component: Component, member_components: Iterable[Component]) -> None:
+    """
+    Transfer unambiguous membership metadata from member components to a group component.
+
+    Parameters
+    ----------
+    group_component : Component
+        The component to which unambiguous membership metadata will be transferred.
+    member_components : Iterable[Component]
+        The components from which membership metadata is collected.
+
+    Notes
+    -----
+    Only metadata keys with a single unique Member value among all member components are transferred.
+    Existing metadata on the group component is not overwritten.
+
+    """
+    d = defaultdict(set)
+    for member in member_components:
+        for key in member.get_meta_keys():
+            value = member.get_meta(key)
+            if not isinstance(value, Member):
+                continue
+            d[key].add(value)
+    for key, value_set in d.items():
+        test_value = group_component.get_meta(key)
+        if test_value is not None:
+            # don't overwrite if already set
+            continue
+        if len(value_set) != 1:
+            # ambigous membership
+            continue
+        value = next(iter(value_set))
+        group_component.add_meta(key, value)