Merge pull request #433 from iiasa/bmt_dev

Add BMT workflows and update functions to build Buildings module

Author: khaeru

doc/api/model-bmt.rst

@@ -0,0 +1,35 @@
+BMT workflow (:mod:`.model.bmt`)
+********************************
+
+The acronym **“BMT”** refers to a configuration of MESSAGEix-GLOBIOM
+that combines all 3 of the
+:doc:`/buildings/index` (**B**),
+:doc:`MESSAGEix-Materials </material/index>` (**M**), and
+:doc:`MESSAGEix-Transport </transport/index>` (**T**)
+model variants.
+
+The current module :mod:`.model.bmt` includes:
+
+- :func:`.bmt.workflow.generate` —generates a :class:`.Workflow`
+  that chains steps to build all 3 variants on a base scenario.
+  See the function documentation for complete details.
+- :mod:`.bmt.cli` —the :program:`mix-models bmt run` CLI subcommand
+  used to invoke the workflow.
+  For example::
+
+    mix-models bmt run --from="base" "glasgow+" --dry-run
+
+  See :program:`mix-models bmt run --help` for options.
+- :mod:`.bmt.config` —handling for configuration,
+  which is read from a file :file:`data/bmt/config.yaml`.
+  See the module documentation for a description of the file format.
+
+Code reference
+==============
+
+.. autosummary::
+   :toctree: _autosummary
+   :template: autosummary-module.rst
+   :recursive:
+
+   message_ix_models.model.bmt

doc/buildings/index.rst

@@ -45,6 +45,18 @@ These are handled by :func:`.buildings.build_and_solve`.
 
    These steps are handled by :func:`.buildings.pre_solve`.
 
+   When the buildings module is run as part of the :doc:`/bmt/index` workflow,
+   it calls :func:`.buildings.build.build_B`,
+   which loads inputs (prices, STURM outputs, static demand) specified in :attr:`context.buildings`
+   or from :file:`data/bmt/config.yaml`,
+   calls :func:`.buildings.build.prepare_data_B`
+   to derive parameter data from the base scenario and those inputs,
+   then applies the buildings spec to the scenario.
+   :func:`.buildings.build.prepare_data_B` produces demand and technology parameters
+   (input, output, capacity factor, etc.)
+   for buildings commodities and the residual AFOFIO representation.
+   It can also add materials linkage when :attr:`with_materials` is :any:`True`.
+
 2. **Solve.**
    Because prices are endogenous in MESSAGE, solving the MESSAGE scenario produced by (1.4) can result in prices that are *different* from the ones provided to ACCESS and STURM in steps (1.2) and (1.3).
 
@@ -56,7 +68,6 @@ These are handled by :func:`.buildings.build_and_solve`.
    .. note:: As of 2023-01-10, this is not in active use; the models are run in a once-through fashion with :attr:`.max_iterations` set to 1.
       See also the :ref:`NAVIGATE workflow <navigate-workflow>`, wherein a second iteration is run manually after a policy scenario is solved.
 
-
 Report
 ------
 
@@ -180,7 +191,8 @@ The following corresponds to :file:`reporting_EFC.py`:
 Configuration
 =============
 
-The class :class:`.buildings.Config` defines all the options to which the code responds, as well as default values.
+The class :class:`.buildings.Config` defines all the options to which the code responds,
+as well as default values.
 Values given in code or on the command line will override these.
 
 .. autoclass:: message_ix_models.model.buildings.Config
@@ -196,4 +208,4 @@ Code reference
    :template: autosummary-module.rst
    :recursive:
 
-   buildings
+   message_ix_models.model.buildings

doc/index.rst

@@ -93,6 +93,7 @@ Other submodules are documented on their respective pages:
 
    api/model
    api/model-bare
+   api/model-bmt
    api/model-build
    api/model-emissions
    api/model-snapshot

doc/whatsnew.rst

@@ -5,6 +5,15 @@ Next release
 ============
 
 - Add IAMC code list :class:`~.iamc.structure.CL_SCENARIO_DIAGNOSTIC` (:pull:`501`).
+- Add :doc:`/api/model-bmt` (:pull:`433`).
+
+  - Add
+    :data:`.buildings.config.DEFAULT_DATA_PATHS`,
+    :class:`~.buildings.config.METHOD`,
+    :attr:`.buildings.Config.data_paths`, and
+    :attr:`~.buildings.Config.method`.
+  - Add :func:`.buildings.build.prepare_data_B`;
+    rename :py:`prepare_data()` to :func:`~.buildings.build.prepare_data_A`.
 
 v2026.4.17
 ==========

message_ix_models/cli.py

@@ -172,6 +172,7 @@ def _log_threads(k: int, n: int):
     "message_ix_models.testing.cli",
     "message_ix_models.util.pooch",
     "message_ix_models.util.slurm",
+    "message_ix_models.model.bmt.cli",
 ]
 
 try:

message_ix_models/data/bmt/config.yaml

@@ -0,0 +1,17 @@
+# BMT workflow configuration.
+# Top-level keys are energy demand sectors; each is loaded into context (e.g. context.buildings).
+# Paths under a sector are relative to private_data_path(sector) unless redefined.
+
+buildings:
+  data_paths:
+      # Input file names under private_data_path("buildings")
+      prices: "input_prices_R12.csv"
+      sturm_r: "report_MESSAGE_resid_SSP2_nopol_post.csv"
+      sturm_c: "report_MESSAGE_comm_SSP2_nopol_post.csv"
+      demand_static: "static_20251227.csv"
+  # Whether to include materials (steel, cement, aluminum) in the buildings spec
+  with_materials: true
+
+# transport: {}
+# materials: {}
+# others: {}

message_ix_models/data/buildings/commodity.yaml

@@ -0,0 +1,78 @@
+# biomass_rc
+resid_cook_biomass:
+  description: Biomass demand for residential cooking
+resid_heat_biomass:
+  description: Biomass demand for residential heating
+resid_hotwater_biomass:
+  description: Biomass demand for residential hotwater
+comm_heat_biomass:
+  description: Biomass demand for commercial heating
+comm_hotwater_biomass:
+  description: Biomass demand for commercial hotwater
+
+# coal_rc
+resid_heat_coal:
+  description: Coal demand for residential heating
+resid_hotwater_coal:
+  description: Coal demand for residential hotwater
+comm_heat_coal:
+  description: Coal demand for commercial heating
+comm_hotwater_coal:
+  description: Coal demand for commercial hotwater
+
+# heat_rc
+resid_heat_d_heat:
+  description: District heat demand for residential heating
+resid_hotwater_d_heat:
+  description: District heat demand for residential hotwater
+comm_heat_d_heat:
+  description: District heat demand for commercial heating
+comm_hotwater_d_heat:
+  description: District heat demand for commercial hotwater
+
+# elec_rc
+resid_cook_electr:
+  description: Electricity demand for residential cooking
+resid_heat_electr:
+  description: Electricity demand for residential heating
+resid_hotwater_electr:
+  description: Electricity demand for residential hotwater
+comm_heat_electr:
+  description: Electricity demand for commercial heating
+comm_hotwater_electr:
+  description: Electricity demand for commercial hotwater
+
+# sp_el_RC
+resid_cool_electr:
+  description: Electricity demand for residential cooling
+comm_cool_electr:
+  description: Electricity demand for commercial cooling
+resid_apps_electr:
+  description: Electricity demand for residential appliances
+resid_other_uses_electr:
+  description: Electricity demand for residential other uses
+comm_other_uses_electr:
+  description: Electricity demand for commercial other uses
+
+# gas_rc
+resid_heat_gas:
+  description: Gas demand for residential heating
+resid_hotwater_gas:
+  description: Gas demand for residential hotwater
+comm_heat_gas:
+  description: Gas demand for commercial heating
+comm_hotwater_gas:
+  description: Gas demand for commercial hotwater
+
+# loil_rc
+resid_cook_lightoil:
+resid_cook_lightoil:
+  description: Light oil demand for residential cooking
+resid_hotwater_lightoil:
+  description: Light oil demand for residential hotwater
+comm_hotwater_lightoil:
+  description: Light oil demand for commercial hotwater
+resid_heat_lightoil:
+  description: Light oil demand for residential heating
+comm_heat_lightoil:
+  description: Light oil demand for commercial heating

message_ix_models/data/buildings/set.yaml

@@ -7,9 +7,9 @@
 # NB this cannot be "sector", as it collides with the MACRO set of the same name
 buildings_sector:
   add:
-    afofi:
-      name: Agriculture, forestry, and fisheries
-      report: AFOFI
+    afofio:
+      name: Agriculture, forestry, fisheries, and others
+      report: AFOFIO
     comm:
       name: Commercial buildings
       report: Commercial
@@ -100,25 +100,27 @@ relation:
   # Relations for which data should be adapted
   require:
   - BCA_Emission
-  - CH4_Emission
+  # - CH4_Emission
   - CO2_r_c
   - CO_Emission
   - HFC_Emission
   - HFC_foam_red
   - HFC_rescom_red
-  - N2O_Emission
+  #- N2O_Emission
   - NH3_Emission
   - NOx_Emission
   - OCA_Emission
   - SO2_Emission
   - VOC_Emission
   - oper_res
   - solar_th_pot
-
+  - gas_mix_lim
+  # - share_low_lim_NFPE
+  # - share_low_lim_REPE
 
 technology:
   add:
-    # NB some others like meth_afofi are generated in .buildings.build
+    # NB some others like meth_afofio are generated in .buildings.build
     "{commodity.id}_{buildings_sector.id}_{enduse.id}":
       # name: "{commodity.name}-powered {enduse.name.lower()} in {buildings_sector.name.lower()}"
       name: "{commodity.name}-powered {enduse.name} in {buildings_sector.name}"

message_ix_models/data/technology.yaml

@@ -2896,6 +2896,14 @@ sp_el_RC:
   input: [electr, final]
   output: [rc_spec, useful]
 
+sp_el_RC_RT:
+  name: sp_el_RC_RT
+  description: Specific use of electricity in residential/commercial from rooftop PV
+  type: useful
+  sector: residential/commercial
+  input: [electr, final]
+  output: [rc_spec, useful]
+
 h2_fc_RC:
   name: h2_fc_RC
   description: Specific use of hydrogen fuel cell cogeneration system in res/comm

message_ix_models/model/bmt/__init__.py

@@ -0,0 +1,8 @@
+"""Buildings-Materials-Transport workflow."""
+
+from .utils import build_PM, subtract_material_demand
+
+__all__ = [
+    "build_PM",
+    "subtract_material_demand",
+]