diff --git a/doc/api/util.rst b/doc/api/util.rst index cc5cca3759..e4662a4048 100644 --- a/doc/api/util.rst +++ b/doc/api/util.rst @@ -101,9 +101,9 @@ Commonly used: A Context instance always has the following members: - 1. :attr:`core``: an instance of :class:`message_ix_models.Config`. - 2. :attr:`model``: an instance of :class:`message_ix_models.model.Config`. - 3. :attr:`report``: an instance of :class:`message_ix_models.report.Config`. + 1. :attr:`core`: an instance of :class:`message_ix_models.Config`. + 2. :attr:`model`: an instance of :class:`message_ix_models.model.Config`. + 3. :attr:`report`: an instance of :class:`message_ix_models.report.Config`. Attributes of (1) and (2) **may** be accessed by shorthand/aliases. For instance, :py:`context.regions` is an alias for :py:`context.model.regions`. @@ -215,3 +215,11 @@ Commonly used: .. automodule:: message_ix_models.util.sdmx :members: + +:mod:`.types` +============= + +.. currentmodule:: message_ix_models.types + +.. automodule:: message_ix_models.types + :members: diff --git a/doc/pkg-data/codelists.rst b/doc/pkg-data/codelists.rst index 831ac89808..bde8998d54 100644 --- a/doc/pkg-data/codelists.rst +++ b/doc/pkg-data/codelists.rst @@ -25,6 +25,8 @@ These codes have the following annotations: .. literalinclude:: ../../message_ix_models/data/commodity.yaml :language: yaml +.. _emission-yaml: + Emission species (:file:`emission.yaml`) ======================================== diff --git a/doc/whatsnew.rst b/doc/whatsnew.rst index dbe2ec11f8..e8afcfbbd8 100644 --- a/doc/whatsnew.rst +++ b/doc/whatsnew.rst @@ -7,6 +7,7 @@ Next release - :mod:`message_ix_models` is tested and compatible with `Python 3.13 `__ (:pull:`250`). - Support for Python 3.8 is dropped (:pull:`250`), as it has reached end-of-life. - Expand :doc:`repro` with sections on :ref:`repro-doc` and :ref:`versioning`, including :ref:`a list of external model names and ‘versions’ ` like “MESSAGEix-GLOBIOM 2.0” (:issue:`224`, :pull:`226`). +- New code list :ref:`emission-yaml` (:pull:`225`). By topic: @@ -23,7 +24,23 @@ Materials Transport --------- -- Update :doc:`/transport/index` (:pull:`213`). +- Update :doc:`/transport/index` (:pull:`213`, :pull:`225`). +- Rework :mod:`~.transport.freight`, :mod:`~.transport.ldv`, and :mod:`~.transport.non_ldv` to use :mod:`genno` consistently. +- Adopt consistent terms "F RAIL" and "F ROAD" for freight service/modes. +- New technologies: "f rail {electr,lightoil}", "f road electr". +- Extend unit annotations to all transport commodities. +- New input :doc:`files ` :file:`pdt-cap.csv` and :file:`load-factor-ldv.csv`. +- Add :program:`mix-models ssp transport` CLI command to postprocess aviation emissions data. +- New SDMX Codelist ``IIASA:CL_TRANSPORT_SCENARIO`` to distinguish “Low energy demand (LED)” and :doc:`/project/edits` scenarios from :doc:`/project/ssp` baseline scenarios. +- Adjust R12 baseline settings: + + - :file:`mode-share/default.csv`: adjust ``R12_NAM`` values for AIR and LDV. + - :file:`pdt-cap-ref.csv`: adjust ``R12_NAM`` value. +- Implement LED scenarios via :file:`load-factor-ldv.csv` and :file:`pdt-cap.csv`. +- Use y=2019 data from IEA EWEB 2024 edition to align MESSAGEix-Transport with base model calibration. +- New :mod:`genno` operators: :func:`~.transport.operator.broadcast`, :func:`~.transport.operator.broadcast_wildcard`, :func:`~.transport.operator.broadcast_t_c_l`, :func:`~.transport.operator.freight_usage_output`. +- New utility methods :func:`~.transport.config.get_cl_scenario`, :func:`~.transport.util.wildcard`. +- Replace :class:`DataSourceConfig.LDV <.transport.config.DataSourceConfig>` setting with :attr:`Config.dummy_LDV <.transport.config.Config.dummy_LDV>`. Water/Nexus ----------- @@ -51,6 +68,39 @@ Others - Add "LED", "SSP4", and "SSP5" as values for the :program:`--ssp=…` option in :func:`.common_params` (:pull:`233`). - Add :doc:`/project/circeular` project code and documentation (:pull:`232`). +- :mod:`.iea.web` handles the 2024 edition and fixed-width file format published by the IEA directly (:pull:`225`). + + - Code lists for the ``COUNTRY``, ``FLOW``, and ``PRODUCT`` concepts are included with :mod:`message_ix_models`. + - Add :data:`~.iea.web.COUNTRY_NAME` to map particular labels appearing in these data. + - Fuzzed data and tests for this functionality. + +- Add :any:`.types.ParameterData` and :any:`.types.MutableParameterData` to type the common internal data structure in which a :class:`dict` maps from MESSAGE parameter names to :mod:`message_ix`-structured :class:`pandas.DataFrame` (:pull:`225`). +- :class:`message_ix_models.Config`—the “core” configuration class—gains methods specific to its settings (:pull:`225`). + These were formerly on :class:`.Context`. +- :class:`.Context` is no longer a subclass of :class:`dict` (:pull:`225`). + This avoids its mishandling by :mod:`dask` version 2024.11.0 or later when Context is used with :class:`ixmp.Reporter`. + + - Add :data:`.MODULE_WITH_CONFIG_DATACLASS`; + add attributes such as :attr:`.Context.model` that are typed to the respective class such as :class:`.model.Config`. + - Add :meth:`.Context.asdict` for serialization. + - Former methods such as :meth:`.Context.get_scenario` are aliased to their new locations, e.g. :meth:`.Config.get_scenario`. + +- Improve :class:`.ScenarioInfo` (:pull:`225`): + + - Implement the :py:`|` (logical OR/union) operator: `si_a | si_b` is a new ScenarioInfo instance with the union of the contents of the operands. + - New method :meth:`.substitute_codes` to replace string codes (for instance, determined from a Scenario object) with Codes from the corresponding code list, including all annotations. + +- :class:`.MappingAdapter` skips missing labels in the input data without raising an exception (:pull:`225`). +- :meth:`.Workflow.visualize` displays in left-to-right rank direction by default (:pull:`225`). +- :func:`.convert_units` can handle MESSAGE-scheme :class:`pandas.DataFrame` (:pull:`225`). +- :func:`.util.sdmx.make_enum` uses :class:`.URNLookupEnum` by default (:pull:`225`). + This allows to call, for instance, :py:`SSP_2024.by_urn("…Code=ICONICS:SSP(2024).2")` to retrieve an enumeration number. +- :func:`.make_matched_dfs` accepts :class:`dict` for its :py:`par_value` arg, allowing replacement of values for particular dimensions of output data frames (:pull:`225`). +- New reporting operator :func:`.quantity_from_iamc` (:pull:`225`). +- :func:`.same_node` and :func:`.same_time` can handle :any:`.ParameterData` (:pull:`225`). +- :func:`.report.register` becomes :meth:`.report.Config.register` which populates :attr:`.report.Config.callback` (:pull:`225`). + The set of callback functions used to configure a class:`.Reporter` instance is thus now particular to a :class:`.report.Config` instance attached to a :class:`.Context` instance. + This allows better isolation of code/tests that use different sets of callbacks. v2024.8.6 ========= diff --git a/message_ix_models/project/ssp/structure.py b/message_ix_models/project/ssp/structure.py index 0119f3f410..966038c8c5 100644 --- a/message_ix_models/project/ssp/structure.py +++ b/message_ix_models/project/ssp/structure.py @@ -183,5 +183,8 @@ def generate(context: "Context", base_dir: Optional["PathLike"] = None): write(cl, base_dir) +#: Enumeration of codes for SSP 2017 edition. SSP = SSP_2017 = make_enum("ICONICS:SSP(2017)") + +#: Enumeration of codes for SSP 2024 edition. SSP_2024 = make_enum("ICONICS:SSP(2024)") diff --git a/message_ix_models/report/config.py b/message_ix_models/report/config.py index 569ae80e6f..cbc8aedcaf 100644 --- a/message_ix_models/report/config.py +++ b/message_ix_models/report/config.py @@ -59,13 +59,13 @@ class Config(ConfigHelper): #: #: from message_ix.report import Reporter #: from message_ix_models import Context - #: from message_ix_models.report import register #: #: def cb(rep: Reporter, ctx: Context) -> None: #: # Modify `rep` by calling its methods ... #: pass #: - #: context.report.register(cb) + #: # Register this callback on an existing Context instance + #: context.report.register(cb) callback: list[Callback] = field(default_factory=_default_callbacks) #: Path to write reporting outputs when invoked from the command line. diff --git a/message_ix_models/report/operator.py b/message_ix_models/report/operator.py index afaf6a4004..653bad0cfb 100644 --- a/message_ix_models/report/operator.py +++ b/message_ix_models/report/operator.py @@ -38,6 +38,7 @@ "make_output_path", "model_periods", "nodes_ex_world", + "quantity_from_iamc", "remove_ts", "share_curtailment", ] diff --git a/message_ix_models/util/context.py b/message_ix_models/util/context.py index ad6e6d1a28..e7804e1981 100644 --- a/message_ix_models/util/context.py +++ b/message_ix_models/util/context.py @@ -180,14 +180,17 @@ def set(self, key: str, value: Any) -> None: # These SHOULD include all the keys from MODULE_WITH_CONFIG_DATACLASS @property def core(self) -> "message_ix_models.util.config.Config": + """An instance of :class:`.util.config.Config`.""" return self._values["core"] @property def model(self) -> "message_ix_models.model.config.Config": + """An instance of :class:`.model.config.Config`.""" return self._values["model"] @property def report(self) -> "message_ix_models.report.config.Config": + """An instance of :class:`.report.config.Config`.""" return self._values["report"] # Dict-like behaviour