Building models (model.build)

apply_spec() can be used to be build (compose, assemble, construct, …) models given three pieces of information:

• A message_ix.Scenario to be used as a base. This scenario may be empty.

• A specification, or Spec, which is trio of ScenarioInfo objects; see below.

• An optional function that adds or produces data to add to the scenario.

The spec is applied as follows:

1. For each ixmp set that exists in scenario:

   1. Required elements from Spec.require, if any, are checked.

      If they are missing, apply_spec() raises ValueError. This indicates that spec is not compatible with the given scenario.

   2. Elements from Spec.remove, if any, are removed.

      Any parameter values which reference these set elements are also removed, using strip_par_data().

   3. New set elements from Spec.add, if any, are added.

2. Elements in spec.add.set["unit"] are added to the Platform on which scenario is stored.

3. The data argument, a function, is called with scenario as the first argument, and a keyword argument dry_run from apply_spec(). data may either add to scenario directly (by calling Scenario.add_par() and similar methods); or it can return a dict that can be passed to add_par_data().

The following modules use this workflow and can be examples for developing similar code:

• model.bare

• model.disutility

• message_data.model.transport

Code reference

message_ix_models.model.build.apply_spec(scenario: Scenario, spec: Spec | Mapping[str, ScenarioInfo], data: Callable | None = None, **options)

Apply spec to scenario.

Parameters:

• spec (Spec) – Specification of changes to make to scenario.

• data (callable, optional) – Function to add data to scenario. data can either manipulate the scenario directly, or return a dict compatible with add_par_data().

• dry_run (bool) – Don’t modify scenario; only show what would be done. Default False. Exceptions will still be raised if the elements from spec['required'] are missing; this serves as a check that the scenario has the required features for applying the spec.

• fast (bool) – Do not remove existing parameter data; increases speed on large scenarios.

• quiet (bool) – Only show log messages at level ERROR and higher. If False (default), show log messages at level DEBUG and higher.

• message (str) – Commit message.

See also

add_par_data, strip_par_data, Code, ScenarioInfo

message_ix_models.model.build.ellipsize(elements: list) → str

Generate a short string representation of elements.

If the list has more than 5 elements, only the first two and last two are shown, with “…” between.