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

framcore/timevectors/LinearTransformTimeVector.py

@@ -0,0 +1,114 @@
+import numpy as np
+from numpy.typing import NDArray
+
+from framcore.fingerprints import Fingerprint
+from framcore.loaders import TimeVectorLoader
+from framcore.timeindexes import ConstantTimeIndex
+from framcore.timevectors import ReferencePeriod
+from framcore.timevectors.TimeVector import TimeVector  # NB! full import path needed for inheritance to work
+
+
+class LinearTransformTimeVector(TimeVector):
+    """LinearTransformTimeVector(TimeVector). Immutable."""
+
+    def __init__(
+        self,
+        timevector: TimeVector,
+        scale: float,
+        shift: float,
+        unit: str | None,
+        is_max_level: bool | None = None,
+        is_zero_one_profile: bool | None = None,
+        reference_period: ReferencePeriod | None = None,
+    ) -> None:
+        """
+        Transform timevector into scale * timevector + shift.
+
+        May also override unit, is_max_level,  is_zero_one_profile and reference_period.
+        """
+        self._check_type(timevector, TimeVector)
+        self._check_type(scale, float)
+        self._check_type(shift, float)
+        self._check_type(unit, (str, type(None)))
+        self._check_type(is_max_level, (bool, type(None)))
+        self._check_type(is_zero_one_profile, (bool, type(None)))
+        self._check_type(reference_period, (ReferencePeriod, type(None)))
+        self._timevector = timevector
+        self._scale = scale
+        self._shift = shift
+        self._unit = unit
+        self._is_max_level = is_max_level
+        self._is_zero_one_profile = is_zero_one_profile
+        self._reference_period = reference_period
+
+    def get_vector(self, is_float32: bool) -> NDArray:
+        """Get the values of the TimeVector."""
+        vector = self._timevector.get_vector(is_float32)
+        if self._scale == 1.0 and self._shift == 0.0:
+            return vector
+        out = vector.copy()
+        if self._scale != 1.0:
+            np.multiply(out, self._scale, out=out)
+        if self._shift != 0.0:
+            np.add(out, self._shift, out=out)
+        return out
+
+    def get_fingerprint(self) -> Fingerprint:
+        """Get the Fingerprint of the TimeVector."""
+        return self.get_fingerprint_default()
+
+    def get_timeindex(self) -> ConstantTimeIndex:
+        """Get the TimeIndex of the TimeVector."""
+        return self._timevector.get_timeindex()
+
+    def is_constant(self) -> bool:
+        """Check if the TimeVector is constant."""
+        return self._timevector.is_constant()
+
+    def is_max_level(self) -> bool | None:
+        """Check if TimeVector is a level representing maximum Volume/Capacity."""
+        return self._is_max_level
+
+    def is_zero_one_profile(self) -> bool | None:
+        """Check if TimeVector is a profile with values between zero and one."""
+        return self._is_zero_one_profile
+
+    def get_unit(self) -> str | None:
+        """Get the unit of the TimeVector."""
+        return self._unit
+
+    def get_reference_period(self) -> ReferencePeriod | None:
+        """Get the reference period of the TimeVector."""
+        return self._reference_period
+
+    def get_loader(self) -> TimeVectorLoader | None:
+        """Call get_loader on underlying time vector."""
+        return self._timevector.get_loader()
+
+    def __eq__(self, other) -> bool:  # noqa: ANN001
+        """Check if self and other are equal."""
+        if not isinstance(other, type(self)):
+            return False
+        return (
+            self._timevector == other._timevector
+            and self._scale == other._scale
+            and self._shift == other._shift
+            and self._unit == other._unit
+            and self._is_max_level == other._is_max_level
+            and self._is_zero_one_profile == other._is_zero_one_profile
+            and self._reference_period == other._reference_period
+        )
+
+    def __hash__(self) -> int:
+        """Compute the hash of the LinearTransformTimeVector."""
+        return hash(
+            (
+                self._timevector,
+                self._scale,
+                self._shift,
+                self._unit,
+                self._is_max_level,
+                self._is_zero_one_profile,
+                self._reference_period,
+            ),
+        )

framcore/timevectors/ListTimeVector.py

@@ -0,0 +1,123 @@
+import numpy as np
+from numpy.typing import NDArray
+
+from framcore.fingerprints import Fingerprint
+from framcore.timeindexes import TimeIndex
+from framcore.timevectors import ReferencePeriod
+from framcore.timevectors.TimeVector import TimeVector  # NB! full import path needed for inheritance to work
+
+
+class ListTimeVector(TimeVector):
+    """ListTimeVector class for TimeVectors with a numpy array of values. Subclass of TimeVector."""
+
+    def __init__(
+        self,
+        timeindex: TimeIndex,
+        vector: NDArray,
+        unit: str | None,
+        is_max_level: bool | None,
+        is_zero_one_profile: bool | None,
+        reference_period: ReferencePeriod | None = None,
+    ) -> None:
+        """
+        Initialize the ListTimeVector class.
+
+        Args:
+            timeindex (TimeIndex): Index of timestamps for the vector.
+            vector (NDArray): Array of vector values.
+            unit (str | None): Unit of the values in the vector.
+            is_max_level (bool | None): Whether the vector represents the maximum level, average level given a
+                                        reference period, or not a level at all.
+            is_zero_one_profile (bool | None): Whether the vector represents aprofile with values between 0 and 1, a
+                                               profile with values averaging to 1 over a given reference period, or is
+                                               not a profile.
+            reference_period (ReferencePeriod | None, optional): Given reference period if the vector represents average
+                                                                 level or mean one profile. Defaults to None.
+
+        Raises:
+            ValueError: When both is_max_level and is_zero_one_profile is not None. This would mean the TimeVector
+                        represents both a level and a profile, which is not allowed.
+
+        """
+        if (is_max_level is not None and is_zero_one_profile is not None) or (is_max_level is None and is_zero_one_profile is None):
+            message = (
+                f"Input arguments for {self}: Must have exactly one 'non-None'"
+                "value for is_max_level and is_zero_one_profile. "
+                "A TimeVector is either a level or a profile."
+            )
+            raise ValueError(message)
+        # assert vector.shape == (timeindex.get_num_periods(),), (
+        #     f"Vector shape {vector.shape} does not match timeindex num_periods {timeindex.get_num_periods()}"
+        # )
+        self._timeindex = timeindex
+        self._vector = vector
+        self._unit = unit
+        self._reference_period = reference_period
+        self._is_max_level = is_max_level
+        self._is_zero_one_profile = is_zero_one_profile
+
+    def __eq__(self, other):
+        """Check equality between two ListTimeVector objects."""
+        if not isinstance(other, ListTimeVector):
+            return NotImplemented
+        return (
+            (self._timeindex == other._timeindex)
+            and np.array_equal(self._vector, other._vector)
+            and (self._unit == other._unit)
+            and (self._is_max_level == other._is_max_level)
+            and (self._is_zero_one_profile == other._is_zero_one_profile)
+            and (self._reference_period == other._reference_period)
+        )
+
+    def __hash__(self) -> int:
+        """Return hash of ListTimeVector object."""
+        return hash((self._timeindex, self._vector.tobytes(), self._unit, self._is_max_level, self._is_zero_one_profile, self._reference_period))
+
+    def __repr__(self) -> str:  # TODO: Also timeindex and reference_period
+        """Return the string representation of the ListTimeVector."""
+        return f"ListTimeVector(timeindex={self._timeindex}, vector={self._vector}, unit={self._unit})"
+
+    def get_vector(self, is_float32: bool) -> NDArray:
+        """Get the vector of the TimeVector as a numpy array."""
+        if is_float32:
+            return self._vector.astype(dtype=np.float32)
+        return self._vector
+
+    def get_timeindex(self) -> TimeIndex:
+        """Get the TimeIndex of the TimeVector."""
+        return self._timeindex
+
+    def is_constant(self) -> bool:
+        """Check if the TimeVector is constant."""
+        return False
+
+    def is_max_level(self) -> bool:
+        """Check if TimeVector is a level representing maximum Volume/Capacity."""
+        return self._is_max_level
+
+    def is_zero_one_profile(self) -> bool:
+        """Check if TimeVector is a profile with vector between zero and one."""
+        return self._is_zero_one_profile
+
+    def get_unit(self) -> str | None:
+        """Get the unit of the TimeVector."""
+        return self._unit
+
+    def get_reference_period(self) -> ReferencePeriod | None:
+        """Get the reference period of the TimeVector."""
+        return self._reference_period
+
+    def get_fingerprint(self) -> Fingerprint:
+        """
+        Get the fingerprint of the ListTimeVector.
+
+        Returns:
+            Fingerprint: The fingerprint of the ListTimeVector, excluding the reference period.
+
+        """
+        excludes = {"_reference_period"}
+        return self.get_fingerprint_default(excludes=excludes)
+
+    def get_loader(self) -> None:
+        """Interface method Not applicable for this type. Return None."""
+        return

framcore/timevectors/LoadedTimeVector.py

@@ -0,0 +1,104 @@
+import numpy as np
+from numpy.typing import NDArray
+
+from framcore.fingerprints import Fingerprint
+from framcore.loaders import TimeVectorLoader
+from framcore.timeindexes import TimeIndex
+from framcore.timevectors import ReferencePeriod
+from framcore.timevectors.TimeVector import TimeVector  # NB! full import path needed for inheritance to work
+
+
+class LoadedTimeVector(TimeVector):
+    """TimeVector which gets its data from a data source via a TimeVectorLoader. Subclass of TimeVector."""
+
+    def __init__(self, vector_id: str, loader: TimeVectorLoader) -> None:
+        """
+        Store vector id and loader in instance variables, get unit from loader.
+
+        Args:
+            vector_id (str): Unique name of this vector.
+            loader (TimeVectorLoader): Object connected to a data source where vector_id is associated with a time
+                                       vector. The Loader object must also implement the TimeVectorLoader API.
+
+        Raises:
+            ValueError: When metadata in the TimeVectorLoader for both is_max_level and is_zero_one_profile for the
+                        given vector_id is not None. This would mean the TimeVector represents both a level and a
+                        profile, which is not allowed.
+
+        """
+        self._vector_id = vector_id
+        self._loader = loader
+        self._check_type(self._vector_id, str)
+        self._check_type(self._loader, TimeVectorLoader)
+
+        self._is_max_level = self._loader.is_max_level(self._vector_id)
+        self._is_zero_one_profile = self._loader.is_zero_one_profile(self._vector_id)
+        self._unit = self._loader.get_unit(self._vector_id)
+        self._reference_period = self._loader.get_reference_period(self._vector_id)
+
+        if (self._is_max_level is not None and self._is_zero_one_profile is not None) or (self._is_max_level is None and self._is_zero_one_profile is None):
+            message = (
+                f"Values for {self._loader} is_max_level ({self._is_max_level}) and is_zero_one_profile"
+                f" ({self._is_zero_one_profile}) with time vector {self} Must have exactly one 'non-None' value."
+                " A TimeVector is either a level or a profile."
+            )
+            raise ValueError(message)
+
+    def __repr__(self) -> str:
+        """Overwrite string representation of LoadedTimeVector objects."""
+        return f"{type(self).__name__}(vector_id={self._vector_id},loader={self._loader},unit={self._unit})"
+
+    def __eq__(self, other: object) -> bool:
+        """Check equality between two LoadedTimeVector objects."""
+        if not isinstance(other, LoadedTimeVector):
+            return NotImplemented
+        return (self._vector_id == other._vector_id) and (self._loader == other._loader)
+
+    def __hash__(self) -> int:
+        """Return hash of LoadedTimeVector object."""
+        return hash((self._vector_id, self._loader))
+
+    def get_vector(self, is_float32: bool) -> NDArray:
+        """Get the vector of the TimeVector as a numpy array."""
+        vector = self._loader.get_values(self._vector_id)
+        if is_float32:
+            return vector.astype(np.float32)
+        return vector
+
+    def get_timeindex(self) -> TimeIndex:
+        """
+        Get this time vectors index.
+
+        Returns:
+            TimeIndex: Object describing the index.
+
+        """
+        return self._loader.get_index(self._vector_id)
+
+    def is_constant(self) -> bool:
+        """Signify if this TimeVector is constant."""
+        return False
+
+    def get_unit(self) -> str:
+        """Get the unit of this TimeVector."""
+        return self._unit
+
+    def get_loader(self) -> TimeVectorLoader:
+        """Get the Loader this TimeVector retrieves its data from."""
+        return self._loader
+
+    def get_reference_period(self) -> ReferencePeriod | None:
+        """Get the reference period which the data of this TimeVector is from."""
+        return self._reference_period
+
+    def is_max_level(self) -> bool | None:
+        """Check if TimeVector is a level representing maximum Volume/Capacity."""
+        return self._loader.is_max_level(self._vector_id)
+
+    def is_zero_one_profile(self) -> bool | None:
+        """Check if TimeVector is a profile with values between zero and one."""
+        return self._loader.is_zero_one_profile(self._vector_id)
+
+    def get_fingerprint(self) -> Fingerprint:
+        """Get the Fingerprint of this TimeVector."""
+        return self._loader.get_fingerprint(self._vector_id)

framcore/timevectors/ReferencePeriod.py

@@ -0,0 +1,41 @@
+from framcore import Base
+
+
+class ReferencePeriod(Base):
+    """ReferencePeriod class represents a period of one or more years."""
+
+    def __init__(self, start_year: int, num_years: int) -> None:
+        """Initialize a ReferencePeriod with the start year and number of years."""
+        self._check_type(start_year, int)
+        self._check_type(num_years, int)
+        if start_year < 0:
+            message = f"start_year must be a positive integer. Got {start_year}."
+            raise ValueError(message)
+        if num_years < 0:
+            message = f"num_years must be a positive integer. Got {num_years}."
+            raise ValueError(message)
+        self._start_year = start_year
+        self._num_years = num_years
+
+    def get_start_year(self) -> int:
+        """Get the start_year from a ReferencePeriod instance."""
+        return self._start_year
+
+    def get_num_years(self) -> int:
+        """Get the number of years in the ReferencePeriod."""
+        return self._num_years
+
+    def __eq__(self, other) -> bool:  # noqa: ANN001
+        """Check if self and other are equal."""
+        if not isinstance(other, type(self)):
+            return False
+        return self._start_year == other._start_year and self._num_years == other._num_years
+
+    def __hash__(self) -> int:
+        """Compute hash value.."""
+        return hash(
+            (
+                self._start_year,
+                self._num_years,
+            ),
+        )

framcore/timevectors/TimeVector.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+from numpy.typing import NDArray
+
+from framcore import Base
+from framcore.fingerprints import Fingerprint
+from framcore.timeindexes import TimeIndex
+from framcore.timevectors import ReferencePeriod
+
+if TYPE_CHECKING:
+    from framcore.loaders import TimeVectorLoader
+
+
+# TODO: Floating point precision
+class TimeVector(Base, ABC):
+    """TimeVector interface class."""
+
+    def __init__(self) -> None:
+        """Initialize the TimeVector class."""
+        super().__init__()
+
+    @abstractmethod
+    def __eq__(self, other) -> bool:  # noqa: ANN001
+        """Check if two TimeVectors are equal."""
+        pass
+
+    @abstractmethod
+    def __hash__(self) -> int:
+        """Compute hash value."""
+        pass
+
+    @abstractmethod
+    def get_vector(self, is_float32: bool) -> NDArray:
+        """Get the values of the TimeVector."""
+        pass
+
+    @abstractmethod
+    def get_timeindex(self) -> TimeIndex | None:
+        """Get the TimeIndex of the TimeVector."""
+        pass
+
+    @abstractmethod
+    def is_constant(self) -> bool:
+        """Check if the TimeVector is constant."""
+        pass
+
+    @abstractmethod
+    def is_max_level(self) -> bool | None:
+        """
+        Check if TimeVector is a level representing max Volume/Capacity.
+
+        Returns:
+            True - vector is a level representing max Volume/Capacity.
+            False - vector is a level representing average Volume/Capacity over a given reference period.
+            None - vector is not a level.
+
+        """
+        pass
+
+    @abstractmethod
+    def is_zero_one_profile(self) -> bool | None:
+        """
+        Check if TimeVector is a profile with values between zero and one.
+
+        Returns:
+            True - vector is a profile with values between zero and one.
+            False - vector is a profile where the mean value is 1 given a reference period.
+            None - vector is not a profile.
+
+        """
+        pass
+
+    @abstractmethod
+    def get_unit(self) -> str | None:
+        """Get the unit of the TimeVector."""
+        pass
+
+    @abstractmethod
+    def get_fingerprint(self) -> Fingerprint:
+        """Get the fingerprint of the TimeVector."""
+        pass
+
+    @abstractmethod
+    def get_reference_period(self) -> ReferencePeriod | None:
+        """Get the reference period of the TimeVector."""
+        pass
+
+    @abstractmethod
+    def get_loader(self) -> TimeVectorLoader | None:
+        """Get the TimeVectorLoader of the TimeVector if self has one."""
+        pass

framcore/timevectors/__init__.py

@@ -0,0 +1,17 @@
+# framcore/timevectors/__init__.py
+
+from framcore.timevectors.ReferencePeriod import ReferencePeriod
+from framcore.timevectors.TimeVector import TimeVector
+from framcore.timevectors.ConstantTimeVector import ConstantTimeVector
+from framcore.timevectors.LinearTransformTimeVector import LinearTransformTimeVector
+from framcore.timevectors.ListTimeVector import ListTimeVector
+from framcore.timevectors.LoadedTimeVector import LoadedTimeVector
+
+__all__ = [
+    "ConstantTimeVector",
+    "LinearTransformTimeVector",
+    "ListTimeVector",
+    "LoadedTimeVector",
+    "ReferencePeriod",
+    "TimeVector",
+]

framcore/utils/__init__.py

@@ -0,0 +1,36 @@
+# framcore/lib/__init__.py
+
+
+from framcore.utils.get_supported_components import get_supported_components
+from framcore.utils.node_flow_utils import (
+    FlowInfo,
+    get_component_to_nodes,
+    get_flow_infos,
+    get_node_to_commodity,
+    get_transports_by_commodity,
+    is_transport_by_commodity,
+)
+from framcore.utils.global_energy_equivalent import get_hydro_downstream_energy_equivalent, set_global_energy_equivalent
+from framcore.utils.storage_subsystems import get_one_commodity_storage_subsystems
+from framcore.utils.isolate_subnodes import isolate_subnodes
+from framcore.utils.get_regional_volumes import get_regional_volumes, RegionalVolumes
+from framcore.utils.loaders import add_loaders_if, add_loaders, replace_loader_path
+
+__all__ = [
+    "FlowInfo",
+    "RegionalVolumes",
+    "add_loaders",
+    "add_loaders_if",
+    "get_component_to_nodes",
+    "get_flow_infos",
+    "get_hydro_downstream_energy_equivalent",
+    "get_node_to_commodity",
+    "get_one_commodity_storage_subsystems",
+    "get_regional_volumes",
+    "get_supported_components",
+    "get_transports_by_commodity",
+    "is_transport_by_commodity",
+    "isolate_subnodes",
+    "replace_loader_path",
+    "set_global_energy_equivalent",
+]