From d22f5ec15cfae10b695ace0e442f6f07a0cb4bd3 Mon Sep 17 00:00:00 2001 From: Paul Natsuo Kishimoto Date: Mon, 15 Aug 2022 17:41:48 +0200 Subject: [PATCH] Add #451 to release notes --- RELEASE_NOTES.rst | 4 ++++ doc/api-model.rst | 16 +++++++++++----- ixmp/model/base.py | 15 ++++++++++----- 3 files changed, 25 insertions(+), 10 deletions(-) diff --git a/RELEASE_NOTES.rst b/RELEASE_NOTES.rst index d6f44844a..658a943ce 100644 --- a/RELEASE_NOTES.rst +++ b/RELEASE_NOTES.rst @@ -4,6 +4,10 @@ Next release All changes ----------- +- Optionally tolerate failures to add individual items in :func:`.store_ts` reporting computation (:pull:`451`); use ``timeseries_only=True`` in check-out to function with :class:`.Scenario` with solution data stored. +- Bugfix: :class:`.Config` squashed configuration values read from :file:`config.json`, if the respective keys were registered in downstream packages, e.g. :mod:`message_ix`. + Allow the values loaded from file to persist (:pull:`451`). +- Adjust to genno 1.12 and set this as the minimum required version (:pull:`451`). - Add :meth:`.enforce` to the :class:`~.base.Model` API for enforcing structure/data consistency before :meth:`.Model.solve` (:pull:`450`). .. _v3.5.0: diff --git a/doc/api-model.rst b/doc/api-model.rst index 85f653175..94a2cfa26 100644 --- a/doc/api-model.rst +++ b/doc/api-model.rst @@ -32,16 +32,22 @@ Model API .. currentmodule:: ixmp.model.base .. autoclass:: ixmp.model.base.Model - :members: name, __init__, initialize, initialize_items, run + :members: name, __init__, run, initialize, initialize_items, enforce In the following, the words **required**, **optional**, etc. have specific meanings as described in `IETF RFC 2119 `_. - Model is an **abstract** class; this means it MUST be subclassed. - It has two REQURIED methods that MUST be overridden by subclasses: + Model is an *abstract* class; this means it **must** be subclassed. + It has two **required** methods that **must** be overridden by subclasses: .. autosummary:: - name __init__ + run + + The following attributes and methods are **optional** in subclasses. + The default implementations are either empty or implement reasonable default behaviour. + + .. autosummary:: + enforce initialize initialize_items - run + name diff --git a/ixmp/model/base.py b/ixmp/model/base.py index c5a07aad1..cce58b88b 100644 --- a/ixmp/model/base.py +++ b/ixmp/model/base.py @@ -14,12 +14,14 @@ class ModelError(Exception): class Model(ABC): #: Name of the model. - name = "base" + name: str = "base" @abstractmethod def __init__(self, name, **kwargs): """Constructor. + **Required.** + Parameters ---------- kwargs : @@ -38,12 +40,13 @@ def clean_path(cls, value: str) -> str: def enforce(scenario): """Enforce data consistency in `scenario`. - Optional. Implementations of :meth:`enforce`: + **Optional**; the default implementation does nothing. Subclass implementations + of :meth:`enforce`: - **should** modify the contents of sets and parameters so that `scenario` contains structure and data that is consistent with the underlying model. - **must not** add or remove sets or parameters; for that, use - :meth:`initiatize`. + :meth:`initialize`. :meth:`enforce` is always called by :meth:`run` before the model is run or solved; it **may** be called manually at other times. @@ -58,7 +61,8 @@ def enforce(scenario): def initialize(cls, scenario): """Set up *scenario* with required items. - Implementations of :meth:`initialize`: + **Optional**; the default implementation does nothing. Subclass implementations + of :meth:`initialize`: - **may** add sets, set elements, and/or parameter values. - **may** accept any number of keyword arguments to control behaviour. @@ -180,10 +184,11 @@ def initialize_items(cls, scenario, items): def run(self, scenario): """Execute the model. - Implementations of :meth:`run`: + **Required.** Implementations of :meth:`run`: - **must** call :meth:`enforce`. + Parameters ---------- scenario : .Scenario