Configurable timeslice level for sectors

docs/inputs/toml.rst

@@ -319,6 +319,32 @@ A sector accepts these attributes:
    Additional methods can be registered with
    :py:func:`muse.production.register_production`
 
+*technodata*
+   Path to a csv file containing the characterization of the technologies involved in
+   the sector, e.g. lifetime, capital costs, etc... See :ref:`inputs-technodata`.
+
+*technodata_timeslices*
+    Optional. Path to a csv file describing the utilization factor and minimum service
+    factor of each technology in each timeslice.
+    See :ref:`user_guide/inputs/technodata_timeslices`.
+
+*commodities_in*
+   Path to a csv file describing the inputs of each technology involved in the sector.
+   See :ref:`inputs-iocomms`.
+
+*commodities_out*
+   Path to a csv file describing the outputs of each technology involved in the sector.
+   See :ref:`inputs-iocomms`.
+
+*timeslice_level*
+   Optional. This represents the level of timeslice granularity over which commodity
+   flows out of the sector are balanced (e.g. if "day", the sector will aim to meet
+   commodity demands on a daily basis, rather than an hourly basis).
+   If not given, defaults to the finest level defined in the global `timeslices` section.
+   Note: If *technodata_timeslices* is used, the data in this file must match the timeslice
+   level of the sector (e.g. with global timeslice levels "month", "day" and "hour", if a sector has "day" as
+   the timeslice level, then *technodata_timeslices* must have columns "month" and "day", but not "hour")
+
 Sectors contain a number of subsections:
 *interactions*
    Defines interactions between agents. These interactions take place right before new
@@ -372,32 +398,6 @@ Sectors contain a number of subsections:
    "new_to_retro" type of network has been defined but no retro agents are included in
    the sector.
 
-*technodata*
-
-   Defines technologies and their features, in terms of costs, efficiencies, and emissions.
-
-   *technodata* are specified as an inline TOML table, e.g. with single
-   brackets. A technodata section would look like:
-
-   .. code-block:: TOML
-
-      [sectors.residential.technodata]
-        technodata = '{path}/technodata/residential/Technodata.csv'
-        commodities_in = '{path}/technodata/residential/CommIn.csv'
-        commodities_out = '{path}/technodata/residential/CommOut.csv'
-
-   Where:
-   *technodata*
-      Path to a csv file containing the characterization of the technologies involved in
-      the sector, e.g. lifetime, capital costs, etc... See :ref:`inputs-technodata`.
-
-   *commodities_in*
-      Path to a csv file describing the inputs of each technology involved in the sector.
-      See :ref:`inputs-iocomms`.
-
-   *commodities_out*
-      Path to a csv file describing the outputs of each technology involved in the sector.
-      See :ref:`inputs-iocomms`.
 
 *subsectors*
 

src/muse/agents/agent.py

@@ -23,6 +23,7 @@ def __init__(
         interpolation: str = "linear",
         category: Optional[str] = None,
         quantity: Optional[float] = 1,
+        timeslice_level: Optional[str] = None,
     ):
         """Creates a standard MUSE agent.
 
@@ -39,6 +40,9 @@ def __init__(
                 together.
             quantity: optional value to classify different agents' share of the
                 population.
+            timeslice_level: the timeslice level over which investments/production
+                will be optimized (e.g "hour", "day"). If None, the agent will use the
+                finest timeslice level.
         """
         from uuid import uuid4
 
@@ -57,6 +61,8 @@ def __init__(
         """Attribute to classify different sets of agents."""
         self.quantity = quantity
         """Attribute to classify different agents' share of the population."""
+        self.timeslice_level = timeslice_level
+        """Timeslice level for the agent."""
 
     def filter_input(
         self,
@@ -114,6 +120,7 @@ def __init__(
         asset_threshold: float = 1e-4,
         quantity: Optional[float] = 1,
         spend_limit: int = 0,
+        timeslice_level: Optional[str] = None,
         **kwargs,
     ):
         """Creates a standard agent.
@@ -141,6 +148,9 @@ def __init__(
             asset_threshold: Threshold below which assets are not added.
             quantity: different agents' share of the population
             spend_limit: The cost above which agents will not invest
+            timeslice_level: the timeslice level over which the agent invesments will
+                be optimized (e.g "hour", "day"). If None, the agent will use the finest
+                timeslice level.
             **kwargs: Extra arguments
         """
         from muse.decisions import factory as decision_factory
@@ -155,6 +165,7 @@ def __init__(
             interpolation=interpolation,
             category=category,
             quantity=quantity,
+            timeslice_level=timeslice_level,
         )
 
         self.year = year
@@ -331,6 +342,7 @@ def next(
             market,
             technologies,
             year=current_year,
+            timeslice_level=self.timeslice_level,
         )
 
         # Calculate investments
@@ -339,6 +351,7 @@ def next(
             technologies,
             constraints,
             year=current_year,
+            timeslice_level=self.timeslice_level,
         )
 
         # Add investments
@@ -379,7 +392,10 @@ def compute_decision(
 
         # Compute the objectives
         objectives = self.objectives(
-            technologies=techs, demand=reduced_demand, prices=prices
+            technologies=techs,
+            demand=reduced_demand,
+            prices=prices,
+            timeslice_level=self.timeslice_level,
         )
 
         # Compute the decision metric

src/muse/constraints.py

@@ -72,7 +72,7 @@ def constraints(
         search_space: xr.DataArray,
         market: xr.Dataset,
         technologies: xr.Dataset,
-        year: Optional[int] = None,
+        year: int | None = None,
         **kwargs,
     ) -> Constraint:
         pass
@@ -115,7 +115,7 @@ def constraints(
 from mypy_extensions import KwArg
 
 from muse.registration import registrator
-from muse.timeslices import drop_timeslice
+from muse.timeslices import broadcast_timeslice, distribute_timeslice, drop_timeslice
 
 CAPACITY_DIMS = "asset", "replacement", "region"
 """Default dimensions for capacity decision variables."""
@@ -248,11 +248,20 @@ def constraints(
         market: xr.Dataset,
         technologies: xr.Dataset,
         year: int | None = None,
+        timeslice_level: str | None = None,
     ) -> list[Constraint]:
         if year is None:
             year = int(market.year.min())
         constraints = [
-            function(demand, assets, search_space, market, technologies, year=year)
+            function(
+                demand,
+                assets,
+                search_space,
+                market,
+                technologies,
+                year=year,
+                timeslice_level=timeslice_level,
+            )
             for function in constraint_closures
         ]
         return [constraint for constraint in constraints if constraint is not None]
@@ -270,6 +279,7 @@ def max_capacity_expansion(
     year: int | None = None,
     forecast: int | None = None,
     interpolation: str = "linear",
+    **kwargs,
 ) -> Constraint:
     r"""Max-capacity addition, max-capacity growth, and capacity limits constraints.
 
@@ -400,6 +410,7 @@ def demand(
     year: int | None = None,
     forecast: int = 5,
     interpolation: str = "linear",
+    **kwargs,
 ) -> Constraint:
     """Constraints production to meet demand."""
     from muse.commodities import is_enduse
@@ -423,6 +434,7 @@ def search_space(
     technologies: xr.Dataset,
     year: int | None = None,
     forecast: int = 5,
+    **kwargs,
 ) -> Constraint | None:
     """Removes disabled technologies."""
     if search_space.all():
@@ -442,6 +454,8 @@ def max_production(
     market: xr.Dataset,
     technologies: xr.Dataset,
     year: int | None = None,
+    timeslice_level: str | None = None,
+    **kwargs,
 ) -> Constraint:
     """Constructs constraint between capacity and maximum production.
 
@@ -451,7 +465,6 @@ def max_production(
     from xarray import ones_like, zeros_like
 
     from muse.commodities import is_enduse
-    from muse.timeslices import broadcast_timeslice, distribute_timeslice
 
     if year is None:
         year = int(market.year.min())
@@ -470,9 +483,9 @@ def max_production(
         .sel(**kwargs)
         .drop_vars("technology")
     )
-    capacity = distribute_timeslice(techs.fixed_outputs) * broadcast_timeslice(
-        techs.utilization_factor
-    )
+    capacity = distribute_timeslice(
+        techs.fixed_outputs, level=timeslice_level
+    ) * broadcast_timeslice(techs.utilization_factor, level=timeslice_level)
     if "asset" not in capacity.dims and "asset" in search_space.dims:
         capacity = capacity.expand_dims(asset=search_space.asset)
     production = ones_like(capacity)
@@ -489,8 +502,8 @@ def max_production(
         maxadd = maxadd.rename(technology="replacement")
         maxadd = maxadd.where(maxadd == 0, 0.0)
         maxadd = maxadd.where(maxadd > 0, -1.0)
-        capacity = capacity * broadcast_timeslice(maxadd)
-        production = production * broadcast_timeslice(maxadd)
+        capacity = capacity * broadcast_timeslice(maxadd, level=timeslice_level)
+        production = production * broadcast_timeslice(maxadd, level=timeslice_level)
         b = b.rename(region="src_region")
     return xr.Dataset(
         dict(capacity=-cast(np.ndarray, capacity), production=production, b=b),
@@ -506,6 +519,8 @@ def demand_limiting_capacity(
     market: xr.Dataset,
     technologies: xr.Dataset,
     year: int | None = None,
+    timeslice_level: str | None = None,
+    **kwargs,
 ) -> Constraint:
     """Limits the maximum combined capacity to match the demand.
 
@@ -521,7 +536,13 @@ def demand_limiting_capacity(
     """
     # We start with the maximum production constraint and the demand constraint
     capacity_constraint = max_production(
-        demand_, assets, search_space, market, technologies, year=year
+        demand_,
+        assets,
+        search_space,
+        market,
+        technologies,
+        year=year,
+        timeslice_level=timeslice_level,
     )
     demand_constraint = demand(
         demand_, assets, search_space, market, technologies, year=year
@@ -714,12 +735,13 @@ def minimum_service(
     market: xr.Dataset,
     technologies: xr.Dataset,
     year: int | None = None,
+    timeslice_level: str | None = None,
+    **kwargs,
 ) -> Constraint | None:
     """Constructs constraint between capacity and minimum service."""
     from xarray import ones_like, zeros_like
 
     from muse.commodities import is_enduse
-    from muse.timeslices import broadcast_timeslice, distribute_timeslice
 
     if "minimum_service_factor" not in technologies.data_vars:
         return None
@@ -742,9 +764,9 @@ def minimum_service(
         .sel(**kwargs)
         .drop_vars("technology")
     )
-    capacity = distribute_timeslice(techs.fixed_outputs) * broadcast_timeslice(
-        techs.minimum_service_factor
-    )
+    capacity = distribute_timeslice(
+        techs.fixed_outputs, level=timeslice_level
+    ) * broadcast_timeslice(techs.minimum_service_factor, level=timeslice_level)
     if "asset" not in capacity.dims:
         capacity = capacity.expand_dims(asset=search_space.asset)
     production = ones_like(capacity)
@@ -755,7 +777,9 @@ def minimum_service(
     )
 
 
-def lp_costs(technologies: xr.Dataset, costs: xr.DataArray) -> xr.Dataset:
+def lp_costs(
+    technologies: xr.Dataset, costs: xr.DataArray, timeslice_level: str | None = None
+) -> xr.Dataset:
     """Creates costs for solving with scipy's LP solver.
 
     Example:
@@ -805,7 +829,6 @@ def lp_costs(technologies: xr.Dataset, costs: xr.DataArray) -> xr.Dataset:
     from xarray import zeros_like
 
     from muse.commodities import is_enduse
-    from muse.timeslices import broadcast_timeslice, distribute_timeslice
 
     assert "year" not in technologies.dims
 
@@ -818,7 +841,10 @@ def lp_costs(technologies: xr.Dataset, costs: xr.DataArray) -> xr.Dataset:
         selection["region"] = costs.region
     fouts = technologies.fixed_outputs.sel(selection).rename(technology="replacement")
 
-    production = zeros_like(broadcast_timeslice(costs) * distribute_timeslice(fouts))
+    production = zeros_like(
+        broadcast_timeslice(costs, level=timeslice_level)
+        * distribute_timeslice(fouts, level=timeslice_level)
+    )
     for dim in production.dims:
         if isinstance(production.get_index(dim), pd.MultiIndex):
             production = drop_timeslice(production)
@@ -1133,8 +1159,9 @@ def factory(
         technologies: xr.Dataset,
         costs: xr.DataArray,
         *constraints: Constraint,
+        timeslice_level: str | None = None,
     ) -> ScipyAdapter:
-        lpcosts = lp_costs(technologies, costs)
+        lpcosts = lp_costs(technologies, costs, timeslice_level=timeslice_level)
 
         data = cls._unified_dataset(technologies, lpcosts, *constraints)