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

framcore/populators/Populator.py

@@ -0,0 +1,108 @@
+"""Populator API, for creating a system of Components, TimeVectors and Curves (and Expr) for a Model object."""
+
+from abc import ABC, abstractmethod
+
+from framcore import Base, Model
+from framcore.components import Component
+from framcore.curves import Curve
+from framcore.expressions import Expr
+from framcore.timevectors import TimeVector
+
+
+class Populator(Base, ABC):
+    """Populate a model with data from a data source."""
+
+    def __init__(self) -> None:
+        """
+        Set up ID and reference registration containers.
+
+        These are used to check if IDs and references actually exist in the system.
+        """
+        super().__init__()
+
+        self._registered_ids: dict[str, list[object]] = {}
+        self._registered_refs: dict[str, set[str]] = {}
+
+    def populate(self, model: Model) -> None:
+        """
+        Add data objects from a database to an input Model.
+
+        These data objects shall be of class Component, TimeVector, and Curve.
+        The method _populate should be overwritten in a subclass of Populator.
+        In this way, it is used to create objects from any database.
+
+        Args:
+            model (Model): Model which will have the objects added to it.
+
+        """
+        self._check_type(model, Model)
+        new_data = self._populate()
+
+        # check that the new_data dict complies with the type hints of _populate?
+        for existing_id in model.get_data():
+            self._register_id(existing_id, model)
+        errors = list(self._check_duplicate_ids())
+        model.get_data().update(new_data)
+        errors += list(self._check_references(model.get_data()))
+        self._report_errors(errors)
+
+    @abstractmethod
+    def _populate(self) -> dict[str, Component | TimeVector | Curve | Expr]:
+        """Create and return Components, TimeVectors and Curves. Possibly also Exprs."""
+        pass
+
+    def _check_duplicate_ids(self) -> dict[str, list[object]]:
+        """
+        Retrieve dictionary with ids of duplicated objects and their corresponding source.
+
+        Returns:
+            dict[str, list[object]]: keys are ids and values are lists of sources.
+
+        """
+        return {f"Duplicate ID found: '{duplicate_id}' in sources {sources}" for duplicate_id, sources in self._registered_ids.items() if len(sources) > 1}
+
+    def _check_references(self, data: dict[str, Component | TimeVector | Curve | Expr]) -> set:
+        errors = set()
+        for ref, referencers in self._registered_refs.items():
+            if ref not in data:
+                msg = f"References to an invalid ID found. ID '{ref}' is not connected to any data."
+                try:
+                    sources = {source_id: data[source_id] for source_id in referencers}
+                except KeyError:
+                    errors.add(
+                        msg + f" Sub Components referencing the faulty ID: {referencers}",
+                    )
+                else:
+                    errors.add(
+                        msg + f" Components referencing the faulty ID: {sources}",
+                    )
+        return errors
+
+    def _report_errors(self, errors: list[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 _register_id(self, new_id: str, source: object) -> None:
+        """
+        Register an id and its source.
+
+        Args:
+            new_id (str): New id to be registered.
+            source (object): Source of the new id.
+
+        """
+        if new_id in self._registered_ids:
+            self._registered_ids[new_id].append(source)
+        else:
+            self._registered_ids[new_id] = [source]
+
+    def _register_references(self, component_id: str, references: set) -> None:
+        for ref in references:
+            if ref in self._registered_refs:
+                self._registered_refs[ref].add(component_id)
+            else:
+                self._registered_refs[ref] = {component_id}

framcore/populators/__init__.py

@@ -0,0 +1,7 @@
+# framcore/populators/__init__.py
+
+from framcore.populators.Populator import Populator
+
+__all__ = [
+    "Populator",
+]

framcore/querydbs/CacheDB.py

@@ -0,0 +1,50 @@
+from framcore import Model
+from framcore.querydbs import QueryDB
+
+
+class CacheDB(QueryDB):
+    """Stores models and precomputed values."""
+
+    def __init__(self, model: Model, *models: tuple[Model]) -> None:
+        """
+        Initialize CacheDB with one or more Model instances.
+
+        Args:
+            model (Model): The primary Model instance.
+            *models (tuple[Model]): Additional Model instances.
+
+        """
+        self._models: tuple[Model] = (model, *models)
+        self._cache = dict()
+        self._min_elapsed_seconds = 0.01
+
+    def set_min_elapsed_seconds(self, value: float) -> None:
+        """Values that takes below this threshold to compute, does not get cached."""
+        self._check_type(value, float)
+        self._check_float(lower_bound=0.0)
+        self._min_elapsed_seconds = value
+
+    def get_min_elapsed_seconds(self) -> float:
+        """Values that takes below this threshold to compute, does not get cached."""
+        return self._min_elapsed_seconds
+
+    def _get(self, key: object) -> object:
+        if key in self._cache:
+            return self._cache[key]
+        for m in self._models:
+            data = m.get_data()
+            if key in data:
+                return data[key]
+        message = f"Key '{key}' not found."
+        raise KeyError(message)
+
+    def _has_key(self, key: object) -> bool:
+        return key in self._cache or any(key in m.get_data() for m in self._models)
+
+    def _put(self, key: object, value: object, elapsed_seconds: float) -> None:
+        if elapsed_seconds < self._min_elapsed_seconds:
+            return
+        self._cache[key] = value
+
+    def _get_data(self) -> dict:
+        return self._models[0].get_data()

framcore/querydbs/ModelDB.py

@@ -0,0 +1,34 @@
+from framcore import Model
+from framcore.querydbs import QueryDB
+
+
+class ModelDB(QueryDB):
+    """A database-like interface for querying multiple Model instances."""
+
+    def __init__(self, model: Model, *models: tuple[Model]) -> None:
+        """
+        Initialize ModelDB with one or more Model instances.
+
+        Args:
+            model (Model): The primary Model instance.
+            *models (tuple[Model]): Additional Model instances.
+
+        """
+        self._models: tuple[Model] = (model, *models)
+
+    def _get(self, key: object) -> object:
+        for m in self._models:
+            data = m.get_data()
+            if key in data:
+                return data[key]
+        message = f"Key '{key}' not found."
+        raise KeyError(message)
+
+    def _has_key(self, key: object) -> bool:
+        return any(key in m.get_data() for m in self._models)
+
+    def _put(self, key: object, value: object, elapsed_seconds: float) -> None:
+        return None
+
+    def _get_data(self) -> dict:
+        return self._models[0].get_data()

framcore/querydbs/QueryDB.py

@@ -0,0 +1,45 @@
+from abc import ABC, abstractmethod
+
+from framcore import Base
+
+
+class QueryDB(Base, ABC):
+    """
+    Abstract base class for database queries.
+
+    Provides an interface for getting, putting, and checking keys in a database.
+    Subclasses must implement the _get, _put, and _has_key methods.
+
+    """
+
+    def get(self, key: object) -> object:
+        """Get value behind key from db."""
+        return self._get(key)
+
+    def put(self, key: object, value: object, elapsed_seconds: float) -> None:
+        """Put value in db behind key (maybe, depending on implementation)."""
+        self._put(key, value, elapsed_seconds)
+
+    def has_key(self, key: str) -> bool:
+        """Return True if db has value behind key."""
+        return self._has_key(key)
+
+    def get_data(self) -> dict:
+        """Return output of get_data called on first underlying model."""
+        return self._get_data()
+
+    @abstractmethod
+    def _get(self, key: object) -> object:
+        pass
+
+    @abstractmethod
+    def _put(self, key: object, value: object, elapsed_seconds: float) -> None:
+        pass
+
+    @abstractmethod
+    def _has_key(self, key: object) -> bool:
+        pass
+
+    @abstractmethod
+    def _get_data(self) -> dict:
+        pass

framcore/querydbs/__init__.py

@@ -0,0 +1,11 @@
+# framcore/querydbs/__init__.py
+
+from framcore.querydbs.QueryDB import QueryDB
+from framcore.querydbs.ModelDB import ModelDB
+from framcore.querydbs.CacheDB import CacheDB
+
+__all__ = [
+    "CacheDB",
+    "ModelDB",
+    "QueryDB",
+]

framcore/solvers/Solver.py

@@ -0,0 +1,48 @@
+"""Definition of Solver interface."""
+
+import pickle
+from abc import ABC, abstractmethod
+from copy import deepcopy
+from pathlib import Path
+
+from framcore import Base, Model
+from framcore.solvers import SolverConfig
+
+
+class Solver(Base, ABC):
+    """Solver inteface class."""
+
+    _FILENAME_MODEL = "model.pickle"
+    _FILENAME_SOLVER = "solver.pickle"
+
+    def solve(self, model: Model) -> None:
+        """Solve the models. Use folder to write results."""
+        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)"
+
+        Path.mkdir(folder, parents=True, exist_ok=True)
+
+        self._solve(folder, model)
+
+        with Path.open(folder / self._FILENAME_MODEL, "wb") as f:
+            pickle.dump(model, f)
+
+        c = deepcopy(self)
+        c.get_config().set_solve_folder(None)
+        with Path.open(folder / self._FILENAME_SOLVER, "wb") as f:
+            pickle.dump(c, f)
+
+    @abstractmethod
+    def get_config(self) -> SolverConfig:
+        """Return the solver's config object."""
+        pass
+
+    @abstractmethod
+    def _solve(self, folder: Path, model: Model) -> None:
+        """Solve the model inplace. Write to folder."""
+        pass

framcore/solvers/SolverConfig.py

@@ -0,0 +1,272 @@
+"""Definition of SolverConfig interface."""
+
+from __future__ import annotations
+
+from abc import ABC
+from pathlib import Path
+
+from framcore import Base
+from framcore.expressions import is_convertable
+from framcore.timeindexes import TimeIndex
+
+
+class SolverConfig(Base, ABC):
+    """SolverConfig inteface class."""
+
+    _SIMULATION_MODE_SERIAL = "serial"
+    _SIMULATION_MODE_FORECAST = "forecast"
+
+    _DIFF_POLICY_ERROR = "error"
+    _DIFF_POLICY_IGNORE = "ignore"
+    _DIFF_POLICY_BACKUP = "backup"
+
+    def __init__(self) -> None:
+        """Create internal variables with default values."""
+        self._simulation_mode: str | None = None
+        self._diff_policy: str = self._DIFF_POLICY_ERROR
+        self._show_screen_output: bool = False
+        self._currency: str | None = None
+        self._num_cpu_cores: int = 1
+        self._is_float32 = True
+        self._first_weather_year: int | None = None
+        self._num_weather_years: int | None = None
+        self._first_simulation_year: int | None = None
+        self._num_simulation_years: int | None = None
+        self._data_period: TimeIndex | None = None
+        self._commodity_unit_flow_default: str | None = None
+        self._commodity_unit_stock_default: str | None = None
+        self._commodity_unit_flows: dict[str, str] = {}
+        self._commodity_unit_stocks: dict[str, str] = {}
+        self._solve_folder: Path | None = None
+
+    def set_solve_folder(self, folder: Path | str | None) -> None:
+        """Set folder where solve related files will be written."""
+        self._check_type(folder, (str, Path, type(None)))
+        if isinstance(folder, str):
+            folder = Path(folder)
+        self._solve_folder = folder
+
+    def get_solve_folder(self) -> Path | None:
+        """Get folder where solve related files will be written."""
+        return self._solve_folder
+
+    def set_commodity_units(
+        self,
+        commodity: str,
+        stock_unit: str,
+        flow_unit: str | None = None,
+        is_default: bool | None = None,
+    ) -> None:
+        """
+        Set the stock and flow units for a commodity.
+
+        Parameters
+        ----------
+        commodity : str
+            The name of the commodity.
+        stock_unit : str
+            The unit for the commodity stock.
+        flow_unit : str or None, optional
+            The unit for the commodity flow, representing the rate of change of the stock unit over time.
+        is_default : bool or None, optional
+            If True, set these units as the default for all commodities.
+
+        Raises
+        ------
+        ValueError
+            If the flow unit is incompatible with the stock unit.
+
+        """
+        self._check_type(commodity, str)
+        self._check_type(stock_unit, str)
+        self._check_type(flow_unit, (str, type(None)))
+        self._check_type(is_default, (bool, type(None)))
+        if flow_unit:
+            candidate = f"{stock_unit}/s"
+            if not is_convertable(candidate, flow_unit):
+                message = (
+                    f"Incompatible units for commodity '{commodity}': stock_unit '{stock_unit}' flow_unit '{flow_unit}'"
+                    "The flow_unit must represent the rate of change of the stock_unit over time."
+                )
+                raise ValueError(message)
+        if is_default:
+            self._warn_if_changed_defaults(stock_unit, flow_unit)
+            self._commodity_unit_stock_default = stock_unit
+            if flow_unit:
+                self._commodity_unit_flow_default = flow_unit
+        else:
+            self._commodity_unit_stocks[commodity] = stock_unit
+            self._commodity_unit_flows[commodity] = flow_unit
+
+    def get_unit_stock(self, commodity: str) -> str:
+        """
+        Get the stock unit for a given commodity.
+
+        Parameters
+        ----------
+        commodity : str
+            The name of the commodity.
+
+        Returns
+        -------
+        str
+            The stock unit for the commodity.
+
+        Raises
+        ------
+        ValueError
+            If no stock unit is set for the commodity.
+
+        """
+        if commodity not in self._commodity_unit_stocks and not self._commodity_unit_stock_default:
+            message = f"No stock unit set for '{commodity}'."
+            raise ValueError(message)
+        return self._commodity_unit_stocks.get(commodity, self._commodity_unit_stock_default)
+
+    def get_unit_flow(self, commodity: str) -> str | None:
+        """
+        Get the flow unit for a given commodity.
+
+        Parameters
+        ----------
+        commodity : str
+            The name of the commodity.
+
+        Returns
+        -------
+        str or None
+            The flow unit for the commodity, or None if not set.
+
+        """
+        return self._commodity_unit_flows.get(commodity, self._commodity_unit_flow_default)
+
+    def _warn_if_changed_defaults(self, stock_unit: str, flow_unit: str) -> None:
+        if self._commodity_unit_flow_default and flow_unit != self._commodity_unit_flow_default:
+            message = f"Replacing flow default from {self._commodity_unit_flow_default} to {flow_unit}. Usually default is only set once."
+            self.send_warning_event(message)
+        if self._commodity_unit_stock_default and stock_unit != self._commodity_unit_stock_default:
+            message = f"Replacing stock default from {self._commodity_unit_stock_default} to {stock_unit}. Usually default is only set once."
+            self.send_warning_event(message)
+
+    def get_num_cpu_cores(self) -> int:
+        """Return number of cpu cores JulES can use."""
+        return self._num_cpu_cores
+
+    def set_num_cpu_cores(self, n: int) -> int:
+        """Set number of cpu cores JulES can use."""
+        self._num_cpu_cores = n
+
+    def set_currency(self, currency: str) -> None:
+        """Set currency."""
+        self._check_type(currency, str)
+        self._currency = currency
+
+    def get_currency(self) -> str | None:
+        """Get currency."""
+        return self._currency
+
+    def set_screen_output_on(self) -> None:
+        """Print output from JulES to stdout and logfile."""
+        self._show_screen_output = True
+
+    def set_screen_output_off(self) -> None:
+        """Only print output from JulES to logfile."""
+        self._show_screen_output = False
+
+    def show_screen_output(self) -> bool:
+        """Return True if screen output is set to be shown."""
+        return self._show_screen_output
+
+    def set_diff_policy_error(self) -> None:
+        """Error if non-empty diff during solve."""
+        self._diff_policy = self._DIFF_POLICY_ERROR
+
+    def set_diff_policy_ignore(self) -> None:
+        """Ignore if non-empty diff during solve."""
+        self._diff_policy = self._DIFF_POLICY_IGNORE
+
+    def set_diff_policy_backup(self) -> None:
+        """Copy existing folder to folder/backup_[timestamp] folder if non-empty diff during solve."""
+        self._diff_policy = self._DIFF_POLICY_BACKUP
+
+    def is_diff_policy_error(self) -> bool:
+        """Return True if error diff policy."""
+        return self._diff_policy == self._DIFF_POLICY_ERROR
+
+    def is_diff_policy_ignore(self) -> bool:
+        """Return True if ignore diff policy."""
+        return self._diff_policy == self._DIFF_POLICY_IGNORE
+
+    def is_diff_policy_backup(self) -> bool:
+        """Return True if backup diff policy."""
+        return self._diff_policy == self._DIFF_POLICY_BACKUP
+
+    def set_simulation_mode_serial(self) -> None:
+        """Activate serial simulation mode."""
+        self._simulation_mode = self._SIMULATION_MODE_SERIAL
+
+    def is_simulation_mode_serial(self) -> bool:
+        """Return True if serial simulation mode."""
+        return self._simulation_mode == self._SIMULATION_MODE_SERIAL
+
+    def set_data_period(self, period: TimeIndex) -> None:
+        """Set period used in level value queries."""
+        self._check_type(period, TimeIndex)
+        self._data_period = period
+
+    def get_data_period(self) -> TimeIndex | None:
+        """Get period used in level value queries."""
+        return self._data_period
+
+    def set_simulation_years(self, first_year: int, num_years: int) -> None:
+        """Set subset of scenario years. For serial simulation."""
+        self._check_type(first_year, int)
+        self._check_type(num_years, int)
+        self._check_int(first_year, lower_bound=0, upper_bound=None)
+        self._check_int(num_years, lower_bound=1, upper_bound=None)
+        self._first_simulation_year = first_year
+        self._num_simulation_years = num_years
+
+    def get_simulation_years(self) -> tuple[int, int]:
+        """
+        Get simulation years (first_year, num_years).
+
+        Return weather years as fallback if serial simulation.
+        """
+        if (self._first_simulation_year is None or self._num_simulation_years is None) and self.is_simulation_mode_serial():
+            first_weather_year, num_weather_years = self.get_weather_years()
+            if first_weather_year is not None and num_weather_years is not None:
+                return first_weather_year, num_weather_years
+
+        if self._first_simulation_year is None or self._num_simulation_years is None:
+            message = "Simulation years not set."
+            raise ValueError(message)
+        return (self._first_simulation_year, self._num_simulation_years)
+
+    def set_weather_years(self, first_year: int, num_years: int) -> None:
+        """Set weather scenario period used in profiles."""
+        self._check_type(first_year, int)
+        self._check_type(num_years, int)
+        self._check_int(first_year, lower_bound=0, upper_bound=None)
+        self._check_int(num_years, lower_bound=1, upper_bound=None)
+        self._first_weather_year = first_year
+        self._num_weather_years = num_years
+
+    def get_weather_years(self) -> tuple[int, int]:
+        """Get weather scenario period (first_year, num_years) used in profiles."""
+        if self._first_weather_year < 0 or self._num_weather_years < 0:
+            message = "Scenario years not set."
+            raise ValueError(message)
+        return (self._first_weather_year, self._num_weather_years)
+
+    def use_float32(self) -> None:
+        """Use single precision floating point numbers in data management."""
+        self._is_float32 = True
+
+    def use_float64(self) -> None:
+        """Use double precision floating point numbers in data management."""
+        self._is_float32 = False
+
+    def is_float32(self) -> bool:
+        """Return if single precision in data management, else double precision."""
+        return self._is_float32

framcore/solvers/__init__.py

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

framcore/timeindexes/AverageYearRange.py

@@ -0,0 +1,20 @@
+from datetime import datetime
+
+from framcore.timeindexes.SinglePeriodTimeIndex import SinglePeriodTimeIndex  # NB! full import path needed for inheritance to work
+
+
+class AverageYearRange(SinglePeriodTimeIndex):
+    """AverageYearRange represents an average over a range of years."""
+
+    def __init__(self, start_year: int, num_years: int) -> None:
+        """Initialize AverageYearRange with a year 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
+        super().__init__(
+            start_time=start_time,
+            period_duration=period_duration,
+            is_52_week_years=False,
+            extrapolate_first_point=False,
+            extrapolate_last_point=False,
+        )

framcore/timeindexes/ConstantTimeIndex.py

@@ -0,0 +1,17 @@
+from datetime import datetime, timedelta
+
+from framcore.timeindexes.SinglePeriodTimeIndex import SinglePeriodTimeIndex  # NB! full import path needed for inheritance to work
+
+
+class ConstantTimeIndex(SinglePeriodTimeIndex):
+    """Used in ConstantTimeVector."""
+
+    def __init__(self) -> None:
+        """Represent a specified year."""
+        super().__init__(
+            start_time=datetime.fromisocalendar(1985, 1, 1),
+            period_duration=timedelta(weeks=52),
+            is_52_week_years=True,
+            extrapolate_first_point=True,
+            extrapolate_last_point=True,
+        )

framcore/timeindexes/DailyIndex.py

@@ -0,0 +1,21 @@
+from datetime import timedelta
+
+from framcore.timeindexes.ProfileTimeIndex import ProfileTimeIndex  # NB! full import path needed for inheritance to work
+
+
+class DailyIndex(ProfileTimeIndex):
+    """One or more whole years with daily resolution."""
+
+    def __init__(
+        self,
+        start_year: int,
+        num_years: int,
+        is_52_week_years: bool = True,
+    ) -> None:
+        """One or more whole years with daily resolution."""
+        super().__init__(
+            start_year=start_year,
+            num_years=num_years,
+            period_duration=timedelta(days=1),
+            is_52_week_years=is_52_week_years,
+        )