Models and variants (model)

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

class message_ix_models.model.Config(regions: str = 'R14', relations: str = 'A', 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, relations, years.

regions: str = 'R14'

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

relations: str = 'A'

The ‘relations’ codelist to use. Must be one of the lists of relations described at Relations (relation/*.yaml).

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()