Migrations

This module contains tools for migrating Scenario data across versions of message_ix. These are applicable when there are changes to the GAMS implementation of MESSAGE:

  • Improvements that allow more efficient or tailored representation of certain phenomena.

  • Fixes to bugs in the implementation that lead to incorrect model solution data, under certain conditions.

  • Changes in the meaning or interpretation of sets or parameters.

Users should call functions like, for instance, v311() that apply migrations appropriate for the MESSAGE GAMS implementation in version v3.11.0 (in other words, changes new since v3.10.x).

These functions call 1 or more atomic migration functions: for example, v311() calls initial_new_capacity_up_v311(). The atomic migration functions use migration_applied() to ensure that the same adjustments are not performed more than once on the same Scenario.

API reference

Tools for migrating Scenario data across versions of message_ix.

message_ix.tools.migrate.initial_new_capacity_up_v311(s: Scenario, *, safety_factor: float = 1.0, debug: bool = False) → None[source]

Adapt values of initial_new_capacity_up.

This function adapts data in line with the revised formulation of NEW_CAPACITY_CONSTRAINT_UP per PR #924. In particular, it:

  • Computes the effective value of the constraint on CAP_NEW under the old formulation.

  • Computes new values for the parameter that give the same effective constraint, using values for growth_new_capacity_up and duration_period in the scenario.

  • Updates initial_new_capacity_up with these values.

All values in initial_new_capacity_up are rewritten in this way.

message_ix.tools.migrate.migration_applied(scenario: Scenario, name: str) → bool[source]

Record and confirm whether migration name has been applied.

If scenario contains a set named “message_ix_migration_applied” with an element name, this indicates the migration has already been applied, and the function returns True. Otherwise, the function creates the set (if necessary), adds the element name, and returns False.

Returns:

True if migration name has been applied. False if not.

Return type:

bool

message_ix.tools.migrate.v311(scenario: Scenario) → None[source]

Adapt data in s for changes between message_ix v3.10.0 and v3.11.0.

This calls initial_new_capacity_up_v311().