Models and variants (model)

Code for constructing models/scenarios in the MESSAGEix-GLOBIOM model family.

class message_ix_models.model.Config(regions: str = 'R14', years: str = 'B', res_with_dummies: bool = False)

Settings and valid values for message_ix_models.model and submodules.

check()

Check the validity of regions and years.

regions: str = 'R14'

The ‘node’ codelist (regional aggregation) to use. Must be one of the lists of nodes described at Node code lists.

res_with_dummies: bool = False

Create the reference energy system with dummy commodities and technologies. See bare.get_spec().

years: str = 'B'

The ‘year’ codelist (time periods) to use, Must be one of the lists of periods described at Years or time periods (year/*.yaml).

model.structure: Model structure information

codelists(kind)	Return a valid IDs for code lists of kind.
generate_product(data, name, template)	Generates codes using a template by Cartesian product along ≥1 dimensions.
generate_set_elements(data, name)	Generate elements for set name.
get_codes(name)	Return codes for the dimension/set name in MESSAGE-GLOBIOM scenarios.
get_region_codes(codelist)	Return the codes that are children of "World" in the specified codelist.
process_units_anno(set_name, code[, quiet])	Process an annotation on code with id="units".
process_commodity_codes(codes)	Process a list of codes for commodity.
process_technology_codes(codes)	Process a list of codes for technology.

message_ix_models.model.structure.codelists(kind: str) → List[str]

Return a valid IDs for code lists of kind.

Parameters

kind (str) – “node” or “year”.

message_ix_models.model.structure.generate_product(data: Mapping, name: str, template: Code) → Tuple[List[Code], Dict[str, DataArray]]

Generates codes using a template by Cartesian product along ≥1 dimensions.

generate_set_elements() is called for each of the dims, and these values are used to format base.

Parameters

• data – Mapping from dimension IDs to lists of codes.

• name (str) – Name of the set.

• template (.Code) – Must have Python format strings for its its id and name attributes.

message_ix_models.model.structure.generate_set_elements(data: MutableMapping, name) → None

Generate elements for set name.

This function converts lists of codes in data, calling generate_product() and process_units_anno() as appropriate.

Parameters

• data – Mapping from dimension IDs to lists of codes.

• name (str) – Name of the set for which to generate elements e.g. “commodity” or “technology”.

message_ix_models.model.structure.get_region_codes(codelist: str) → List[Code]

Return the codes that are children of “World” in the specified codelist.

message_ix_models.model.structure.process_commodity_codes(codes)

Process a list of codes for commodity.

The function warns for commodities missing units or with non-pint-compatible units.

message_ix_models.model.structure.process_technology_codes(codes)

Process a list of codes for technology.

This function ensures every code has an annotation with id “vintaged”, default False.

message_ix_models.model.structure.process_units_anno(set_name: str, code: Code, quiet: bool = False) → None

Process an annotation on code with id=”units”.

The annotation text is wrapped as 'registry.Unit("{text}")', such that it can be retrieved with eval_anno() or ScenarioInfo.units_for(). If code has direct children, the annotation is also copied to those codes.

Parameters

• set_name (str) – Used in logged messages when quiet is False.

• quiet (bool, optional) –

  If False (the default), log on level WARNING if:

  • the annotation is missing, or

  • its text is not parseable with the pint application registry, i.e. iam_units.registry.

  Otherwise, log on DEBUG.

message_ix_models.model.structure.get_codes(name: str) → List[Code]

Return codes for the dimension/set name in MESSAGE-GLOBIOM scenarios.

The information is read from data/name.yaml, e.g. data/technology.yaml.

When name includes “node”, then child codes are automatically populated from the ISO 3166 database via pycountry. For instance:

myregion:
  name: Custom region
  child: [AUT, SCG]

…results in a region with child codes for Austria (a current country) and the formerly-existing country Serbia and Montenegro.

Parameters

name (str) – Any .yaml file in the folder message_ix_models/data/.

Returns

Every Code has id, name, description, and annotations attributes. Calling str() on a code returns its id.

Return type

list of Code

The available code lists are reproduced as part of this documentation. The returned code objects have annotations that vary by set. See:

• Other code lists

• Node code lists

Also available is cd_links/unit.yaml. This is a project-specific list of units appearing in CD-LINKS scenarios.

Example:

>>> from message_ix_models.model.structure import get_codes
>>> codes = get_codes("node/R14")

# Show the codes
>>> codes
[<Code ABW: Aruba>,
 <Code AFG: Afghanistan>,
 <Code AGO: Angola>,
 ...
 <Code ZWE: Zimbabwe>,
 <Code World: World>,
 ...
 <Code R11_PAS: Other Pacific Asia>,
 <Code R11_SAS: South Asia>,
 <Code R11_WEU: Western Europe>]

# Retrieve one code matching a certain ID
>>> world = codes[codes.index("World")]

# Get its children's IDs strings, e.g. for a "node" dimension
>>> [str(c) for c in world.child]
['R11_AFR',
 'R11_CPA',
 'R11_EEU',
 'R11_FSU',
 'R11_LAM',
 'R11_MEA',
 'R11_NAM',
 'R11_PAO',
 'R11_PAS',
 'R11_SAS',
 'R11_WEU']

# Navigate from one ISO 3166-3 country code to its parent
>>> AUT = codes[codes.index("AUT")]
>>> AUT.parent
<Code R11_WEU: Western Europe>

See also

adapt_R11_R14()