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

framcore/solvers/Solver.py

@@ -1,5 +1,3 @@
-"""Definition of Solver interface."""
-
 import pickle
 from abc import ABC, abstractmethod
 from copy import deepcopy
@@ -10,20 +8,37 @@ from framcore.solvers import SolverConfig
 
 
 class Solver(Base, ABC):
-    """Solver inteface class."""
+    """
+    Solver inteface class.
+
+    In FRAM we call energy market models for Solvers. They take a populated Model and configurations from a SolverConfig,
+    and transfers this to the solver software. Then it solves the energy market model, and writes results back to the Model.
+    """
 
     _FILENAME_MODEL = "model.pickle"
     _FILENAME_SOLVER = "solver.pickle"
 
     def solve(self, model: Model) -> None:
-        """Solve the models. Use folder to write results."""
+        """
+        Inititiate the solve.
+
+        It takes the populated Model and configurations from self.SolverConfig, and transfers this to the solver software.
+        Then it solves the energy market model, and writes results back to the Model.
+
+        At the end of the solve, the Model (now with results) and the Solver object (with configurations) are pickled to the solve folder.
+        - model.pickle can be used to inspect results later.
+        - solver.pickle allows reuse of the same solver configurations (with solve_folder set to None to avoid overwriting).
+        TODO: Could also pickle the Model before solving, to have a record of the input model.
+
+        """
         self._check_type(model, Model)
 
         config = self.get_config()
 
         folder = config.get_solve_folder()
 
-        assert folder is not None, "use Solver.get_config().set_solve_folder(folder)"
+        if folder is None:
+            raise ValueError("A folder for the Solver has not been set yet. Use Solver.get_config().set_solve_folder(folder)")
 
         Path.mkdir(folder, parents=True, exist_ok=True)
 
@@ -44,5 +59,5 @@ class Solver(Base, ABC):
 
     @abstractmethod
     def _solve(self, folder: Path, model: Model) -> None:
-        """Solve the model inplace. Write to folder."""
+        """Solve the model inplace. Write to folder. Must be implemented by specific solvers."""
         pass

framcore/solvers/SolverConfig.py

@@ -149,11 +149,11 @@ class SolverConfig(Base, ABC):
             self.send_warning_event(message)
 
     def get_num_cpu_cores(self) -> int:
-        """Return number of cpu cores JulES can use."""
+        """Return number of cpu cores the Solver can use."""
         return self._num_cpu_cores
 
     def set_num_cpu_cores(self, n: int) -> int:
-        """Set number of cpu cores JulES can use."""
+        """Set number of cpu cores the Solver can use."""
         self._num_cpu_cores = n
 
     def set_currency(self, currency: str) -> None:
@@ -166,11 +166,11 @@ class SolverConfig(Base, ABC):
         return self._currency
 
     def set_screen_output_on(self) -> None:
-        """Print output from JulES to stdout and logfile."""
+        """Print output from Solver to stdout and logfile."""
         self._show_screen_output = True
 
     def set_screen_output_off(self) -> None:
-        """Only print output from JulES to logfile."""
+        """Only print output from Solver to logfile."""
         self._show_screen_output = False
 
     def show_screen_output(self) -> bool:

framcore/timeindexes/AverageYearRange.py

@@ -4,10 +4,17 @@ from framcore.timeindexes.SinglePeriodTimeIndex import SinglePeriodTimeIndex  #
 
 
 class AverageYearRange(SinglePeriodTimeIndex):
-    """AverageYearRange represents an average over a range of years."""
+    """AverageYearRange represents a period over a range of years. No extrapolation and represents full iso calendar years."""
 
     def __init__(self, start_year: int, num_years: int) -> None:
-        """Initialize AverageYearRange with a year range."""
+        """
+        Initialize AverageYearRange with a year range. No extrapolation and represents full iso calendar years.
+
+        Args:
+            start_year (int): First year in the range.
+            num_years (int): Number of years in the range.
+
+        """
         start_time = datetime.fromisocalendar(start_year, 1, 1)
         end_time = datetime.fromisocalendar(start_year + num_years, 1, 1)
         period_duration = end_time - start_time

framcore/timeindexes/ConstantTimeIndex.py

@@ -4,10 +4,15 @@ from framcore.timeindexes.SinglePeriodTimeIndex import SinglePeriodTimeIndex  #
 
 
 class ConstantTimeIndex(SinglePeriodTimeIndex):
-    """Used in ConstantTimeVector."""
+    """
+    ConstantTimeIndex that is constant over time. For use in ConstantTimeVector.
+
+    Represents a period of 52 weeks starting from the iso calendar week 1 of 1985. Extrapolates both first and last point.
+
+    """
 
     def __init__(self) -> None:
-        """Represent a specified year."""
+        """Initialize ConstantTimeIndex."""
         super().__init__(
             start_time=datetime.fromisocalendar(1985, 1, 1),
             period_duration=timedelta(weeks=52),

framcore/timeindexes/DailyIndex.py

@@ -4,7 +4,11 @@ from framcore.timeindexes.ProfileTimeIndex import ProfileTimeIndex  # NB! full i
 
 
 class DailyIndex(ProfileTimeIndex):
-    """One or more whole years with daily resolution."""
+    """
+    ProfileTimeIndex with one or more whole years with daily resolution. Either years with 52 weeks or full iso calendar years.
+
+    No extrapolation inherited from ProfileTimeIndex.
+    """
 
     def __init__(
         self,
@@ -12,7 +16,15 @@ class DailyIndex(ProfileTimeIndex):
         num_years: int,
         is_52_week_years: bool = True,
     ) -> None:
-        """One or more whole years with daily resolution."""
+        """
+        Initialize DailyIndex over a number of years. Either years with 52 weeks or full iso calendar years.
+
+        Args:
+            start_year (int): First year in the index.
+            num_years (int): Number of years in the index.
+            is_52_week_years (bool, optional): Whether to use 52-week years. If False, full iso calendar years are used. Defaults to True.
+
+        """
         super().__init__(
             start_year=start_year,
             num_years=num_years,

framcore/timeindexes/FixedFrequencyTimeIndex.py

@@ -6,7 +6,7 @@ from datetime import datetime, timedelta, tzinfo
 import numpy as np
 from numpy.typing import NDArray
 
-import framcore.expressions._time_vector_operations as v_ops
+import framcore.timeindexes._time_vector_operations as v_ops
 from framcore.fingerprints import Fingerprint
 from framcore.timeindexes.TimeIndex import TimeIndex  # NB! full import path needed for inheritance to work
 from framcore.timevectors import ReferencePeriod
@@ -27,32 +27,25 @@ class FixedFrequencyTimeIndex(TimeIndex):
         """
         Initialize a FixedFrequencyTimeIndex.
 
-        Parameters
-        ----------
-        start_time : datetime
-            The starting datetime of the time index.
-        period_duration : timedelta
-            The duration of each period.
-        num_periods : int
-            The number of periods in the time index.
-        is_52_week_years : bool
-            Whether to use 52-week years.
-        extrapolate_first_point : bool
-            Whether to allow extrapolation of the first point.
-        extrapolate_last_point : bool
-            Whether to allow extrapolation of the last point.
+        Args:
+            start_time (datetime): The starting datetime of the time index.
+            period_duration (timedelta): The duration of each period.
+            num_periods (int): The number of periods in the time index. Must be greater than 0.
+            is_52_week_years (bool): Whether to use 52-week years.
+            extrapolate_first_point (bool): Whether to allow extrapolation of the first point.
+            extrapolate_last_point (bool): Whether to allow extrapolation of the last point.
 
         """
-        if num_periods < 0:
-            message = f"num_periods must be a positive integer. Got {num_periods}."
-            raise ValueError(message)
+        if num_periods <= 0:
+            msg = f"num_periods must be a positive integer. Got {num_periods}."
+            raise ValueError(msg)
         if period_duration < timedelta(seconds=1):
-            message = f"period_duration must be at least one second. Got {period_duration}."
-            raise ValueError(message)
+            msg = f"period_duration must be at least one second. Got {period_duration}."
+            raise ValueError(msg)
         if not period_duration.total_seconds().is_integer():
-            message = f"period_duration must be a whole number of seconds, got {period_duration.total_seconds()} s"
-            raise ValueError(message)
-        if is_52_week_years and start_time.isocalendar().week == 53:  #  original: assert start_time.isocalendar().week != 53  # noqa: PLR2004
+            msg = f"period_duration must be a whole number of seconds, got {period_duration.total_seconds()} s"
+            raise ValueError(msg)
+        if is_52_week_years and start_time.isocalendar().week == 53:  # noqa: PLR2004
             raise ValueError("Week of start_time must not be 53 when is_52_week_years is True.")
         self._check_type(num_periods, int)
         self._start_time = start_time
@@ -91,7 +84,7 @@ class FixedFrequencyTimeIndex(TimeIndex):
     def __repr__(self) -> str:
         """Return a string representation of the FixedFrequencyTimeIndex."""
         return (
-            f"FixedFrequencyTimeIndex("
+            f"{type(self).__name__}("
             f"start_time={self._start_time}, "
             f"period_duration={self._period_duration}, "
             f"num_periods={self._num_periods}, "
@@ -133,7 +126,13 @@ class FixedFrequencyTimeIndex(TimeIndex):
         return self._num_periods == 1 and self._extrapolate_first_point == self._extrapolate_last_point is True
 
     def is_whole_years(self) -> bool:
-        """Return True if index covers one or more full years."""
+        """
+        Return True if index covers one or more full years.
+
+        The start_time must be the first week and weekday of a year. For real ISO time,
+        the stop_time must also be the first week and weekday of a year. For 52-week years,
+        the total duration must be an integer number of 52-week years.
+        """
         start_time = self.get_start_time()
         start_year, start_week, start_weekday = start_time.isocalendar()
         if not start_week == start_weekday == 1:
@@ -144,7 +143,9 @@ class FixedFrequencyTimeIndex(TimeIndex):
             num_periods = self.get_num_periods()
             stop_time = start_time + num_periods * period_duration
             stop_year, stop_week, stop_weekday = stop_time.isocalendar()
-            assert stop_year >= start_year
+            if stop_year < start_year:
+                msg = f"Stop year must be after start year. Current stop year: {stop_year} and start year: {start_year}"
+                raise ValueError(msg)
             return stop_week == stop_weekday == 1
 
         period_duration = self.get_period_duration()
@@ -157,7 +158,6 @@ class FixedFrequencyTimeIndex(TimeIndex):
         """Get the reference period (only if is_whole_years() is True)."""
         if self.is_whole_years():
             start_year = self.get_start_time().isocalendar().year
-
             if self._is_52_week_years:
                 num_years = (self.get_num_periods() * self.get_period_duration()) // timedelta(weeks=52)
             else:
@@ -202,7 +202,14 @@ class FixedFrequencyTimeIndex(TimeIndex):
 
     def get_period_average(self, vector: NDArray, start_time: datetime, duration: timedelta, is_52_week_years: bool) -> float:
         """Get the average over the period from the vector."""
-        assert vector.shape == (self.get_num_periods(),)
+        self._check_type(vector, np.ndarray)
+        self._check_type(start_time, datetime)
+        self._check_type(duration, timedelta)
+        self._check_type(is_52_week_years, bool)
+
+        if vector.shape != (self.get_num_periods(),):
+            msg = f"Vector shape {vector.shape} does not match number of periods {self.get_num_periods()} of timeindex ({self})."
+            raise ValueError(msg)
         target_timeindex = FixedFrequencyTimeIndex(
             start_time=start_time,
             period_duration=duration,
@@ -443,7 +450,14 @@ class FixedFrequencyTimeIndex(TimeIndex):
 
     def get_stop_time(self) -> datetime:
         """Get the stop time of the TimeIndex."""
-        return self._start_time + self._period_duration * self._num_periods
+        if not self._is_52_week_years:
+            return self._start_time + self._period_duration * self._num_periods
+
+        return v_ops.calculate_52_week_years_stop_time(
+            start_time=self._start_time,
+            period_duration=self._period_duration,
+            num_periods=self._num_periods,
+        )
 
     def slice(
         self,
@@ -469,6 +483,7 @@ class FixedFrequencyTimeIndex(TimeIndex):
             self._start_time,
             target_index.get_start_time(),
             self._period_duration,
+            self._is_52_week_years,
         )
         transformed_timeindex = self.copy_with(
             start_time=target_index.get_start_time(),
@@ -489,6 +504,7 @@ class FixedFrequencyTimeIndex(TimeIndex):
             self.get_stop_time(),
             target_index.get_stop_time(),
             self._period_duration,
+            self._is_52_week_years,
         )
         transformed_timeindex = self.copy_with(num_periods=self._num_periods - num_periods_to_slice)
         transformed_vector = input_vector[:-num_periods_to_slice]
@@ -512,7 +528,12 @@ class FixedFrequencyTimeIndex(TimeIndex):
         if not self._extrapolate_first_point:
             raise ValueError("Cannot extend start without extrapolation.")
 
-        num_periods_to_extend = self._periods_between(self._start_time, target_timeindex.get_start_time(), self._period_duration)
+        num_periods_to_extend = self._periods_between(
+            self._start_time,
+            target_timeindex.get_start_time(),
+            self._period_duration,
+            self._is_52_week_years,
+        )
         extended_vector = np.concatenate((np.full(num_periods_to_extend, input_vector[0]), input_vector))
 
         transformed_timeindex = self.copy_with(
@@ -534,6 +555,7 @@ class FixedFrequencyTimeIndex(TimeIndex):
             self.get_stop_time(),
             target_timeindex.get_stop_time(),
             self._period_duration,
+            self._is_52_week_years,
         )
         extended_vector = np.concatenate((input_vector, np.full(num_periods_to_extend, input_vector[-1])))
         target_timeindex = self.copy_with(num_periods=self._num_periods + num_periods_to_extend)
@@ -634,27 +656,25 @@ class FixedFrequencyTimeIndex(TimeIndex):
         if target_timeindex.get_start_time() < self._start_time:
             if self._extrapolate_first_point:
                 return self._extend_start(input_vector, target_timeindex)
-            raise ValueError(
-                (
-                    "Cannot write into fixed frequency: incompatible time indices. "
-                    "Start time of the target index is before the start time of the source index "
-                    "and extrapolate_first_point is False.\n"
-                    f"Input timeindex: {self}\n"
-                    f"Target timeindex: {target_timeindex}"
-                ),
+            msg = (
+                "Cannot write into fixed frequency: incompatible time indices. "
+                "Start time of the target index is before the start time of the source index "
+                "and extrapolate_first_point is False.\n"
+                f"Input timeindex: {self}\n"
+                f"Target timeindex: {target_timeindex}"
             )
+            raise ValueError(msg)
         if target_timeindex.get_stop_time() > self.get_stop_time():
             if self._extrapolate_last_point:
                 return self._extend_end(input_vector, target_timeindex)
-            raise ValueError(
-                (
-                    "Cannot write into fixed frequency: incompatible time indices. " 
-                    "'stop_time' of the target index is after the 'stop_time' of the source index "
-                    "and 'extrapolate_last_point' is False.\n"
-                    f"Input timeindex: {self}\n"
-                    f"Target timeindex: {target_timeindex}"
-                ),
+            msg = (
+                "Cannot write into fixed frequency: incompatible time indices. "
+                "'stop_time' of the target index is after the 'stop_time' of the source index "
+                "and 'extrapolate_last_point' is False.\n"
+                f"Input timeindex: {self}\n"
+                f"Target timeindex: {target_timeindex}"
             )
+            raise ValueError(msg)
         if target_timeindex.get_start_time() > self.get_start_time():
             return self._slice_start(input_vector, target_timeindex)
 
@@ -662,7 +682,7 @@ class FixedFrequencyTimeIndex(TimeIndex):
             return self._slice_end(input_vector, target_timeindex)
         return target_timeindex, input_vector
 
-    def _periods_between(self, first_time: datetime, second_time: datetime, period_duration: timedelta) -> int:
+    def _periods_between(self, first_time: datetime, second_time: datetime, period_duration: timedelta, is_52_week_years: bool) -> int:
         """
         Calculate the number of periods between two times.
 
@@ -674,6 +694,8 @@ class FixedFrequencyTimeIndex(TimeIndex):
             The second time point.
         period_duration : timedelta
             The duration of each period.
+        is_52_week_years : bool
+            Whether to use 52-week years.
 
         Returns
         -------
@@ -681,7 +703,15 @@ class FixedFrequencyTimeIndex(TimeIndex):
             The number of periods between the two times.
 
         """
-        return abs(first_time - second_time) // period_duration
+        start = min(first_time, second_time)
+        end = max(first_time, second_time)
+        total_period = end - start
+
+        if is_52_week_years:
+            weeks_53 = v_ops._find_all_week_53_periods(start, end)  # noqa: SLF001
+            total_period -= timedelta(weeks=len(weeks_53))
+
+        return abs(total_period) // period_duration
 
     def copy_with(
         self,
@@ -740,9 +770,13 @@ class FixedFrequencyTimeIndex(TimeIndex):
             A new instance with the updated attributes.
 
         """
+        if reference_period is None:
+            raise ValueError("Cannot copy as reference period when provided reference_period is None.")
+
         start_year = reference_period.get_start_year()
         num_years = reference_period.get_num_years()
         start_time = datetime.fromisocalendar(start_year, 1, 1)
+
         if self.is_52_week_years():
             period_duration = timedelta(weeks=52 * num_years)
         else:
@@ -755,8 +789,26 @@ class FixedFrequencyTimeIndex(TimeIndex):
         )
 
     def get_datetime_list(self) -> list[datetime]:
-        """Return list of datetime including stop time."""
-        t = self.get_start_time()
-        n = self.get_num_periods()
-        d = self.get_period_duration()
-        return [t + i * d for i in range(n + 1)]
+        """
+        Return list of datetime including stop time.
+
+        Note: When `is_52_week_years` is True, the returned list will skip any datetimes that fall in week 53.
+        """
+        start_time = self.get_start_time()
+        num_periods = self.get_num_periods()
+        period_duration = self.get_period_duration()
+
+        if not self._is_52_week_years:
+            return [start_time + i * period_duration for i in range(num_periods + 1)]
+
+        datetime_list = []
+        i = 0
+        count = 0
+        while count <= num_periods:
+            current = start_time + i * period_duration
+            if current.isocalendar().week != 53:  # noqa: PLR2004
+                datetime_list.append(current)
+                count += 1
+            i += 1
+
+        return datetime_list

framcore/timeindexes/HourlyIndex.py

@@ -4,7 +4,11 @@ from framcore.timeindexes.ProfileTimeIndex import ProfileTimeIndex  # NB! full i
 
 
 class HourlyIndex(ProfileTimeIndex):
-    """One or more whole years with hourly resolution."""
+    """
+    ProfileTimeIndex with one or more whole years with hourly resolution. Either years with 52 weeks or full iso calendar years.
+
+    No extrapolation inherited from ProfileTimeIndex.
+    """
 
     def __init__(
         self,
@@ -12,7 +16,15 @@ class HourlyIndex(ProfileTimeIndex):
         num_years: int,
         is_52_week_years: bool = True,
     ) -> None:
-        """One or more whole years with hourly resolution."""
+        """
+        Initialize HourlyIndex over a number of years. Either years with 52 weeks or full iso calendar years.
+
+        Args:
+            start_year (int): First year in the index.
+            num_years (int): Number of years in the index.
+            is_52_week_years (bool, optional): Whether to use 52-week years. If False, full iso calendar years are used. Defaults to True.
+
+        """
         super().__init__(
             start_year=start_year,
             num_years=num_years,

framcore/timeindexes/IsoCalendarDay.py

@@ -16,11 +16,13 @@ class IsoCalendarDay(SinglePeriodTimeIndex):
         """
         IsoCalendarDay represent a day from datetime.fromisocalendar(year, week, day).
 
-        No extrapolation.
+        No extrapolation and is_52_week_years=False. Useful for testing.
 
-        is_52_week_years=False
+        Args:
+            year (int): The ISO year.
+            week (int): The ISO week number (1-53).
+            day (int): The ISO weekday (1=Monday, 7=Sunday).
 
-        Useful for testing.
         """
         super().__init__(
             start_time=datetime.fromisocalendar(year, week, day),