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

fram_core-0.1.0a1/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.0a1/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.4
+Name: fram-core
+Version: 0.1.0a1
+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
+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: 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 **FRAM** modelling framework. The package contains essential features, interfaces and components for running energy market models in FRAM.
+
+For package documentation see [fram-core](https://nve.github.io/fram-core){:target="_blank"}. 
+
+For FRAM documentation see [FRAM mainpage](https://nve.github.io/fram){:target="_blank"}.
+
+## Installation
+
+To add the package to your project use:
+
+    pip install fram-core
+
+With poetry:
+
+    poetry add fram-core
+

fram_core-0.1.0a1/README.md

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

fram_core-0.1.0a1/framcore/Base.py

@@ -0,0 +1,142 @@
+import contextlib
+import inspect
+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
+        if not isinstance(value, class_or_tuple):
+            message = f"Expected {class_or_tuple} for {self}, got {type(value).__name__}"
+            raise TypeError(message)
+
+    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__

fram_core-0.1.0a1/framcore/Model.py

@@ -0,0 +1,73 @@
+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, value):
+        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):
+    """Definition of the Model class."""
+
+    def __init__(self) -> None:
+        """Create a new model instance."""
+        self._data = ModelDict()
+        self._aggregators: list[Aggregator] = []
+
+    def disaggregate(self) -> None:
+        """Undo all aggregations 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()
+        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.0a1/framcore/__init__.py

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

fram_core-0.1.0a1/framcore/aggregators/Aggregator.py

@@ -0,0 +1,153 @@
+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.
+
+    Public API is the aggregate and disaggregate methods.
+
+    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:
+        """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 = f"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)