Runs

class ixmp4.core.run.RunServiceFacade(backend: Backend)

Used to manipulate runs on a platform.

create(model: str, scenario: str) → Run

Creates a run with an incremented version number or version=1 if no versions exist. Will automatically create the models and scenarios if they don’t exist yet.

run = platform.runs.create("Model", "Scenario")
#> <Run 1 model='Model' scenario='Scenario' version=1>
Parameters:

  • model_name (str) – The name of a model.

  • scenario_name (str) – The name of a scenario.

Returns:

The created run.

Return type:

ixmp4.core.run.Run

delete(ref: Run | int) → None

Deletes a run and all associated iamc, optimization and meta data.

platform.runs.delete(1)
Parameters:

ref (ixmp4.core.run.Run | int) – Run object or id.

Raises:

RunNotFound – If the ref does not exist.

get(model: str, scenario: str, version: int | None = None) → Run

Retrieves a run.

default_run = platform.runs.get("Model", "Scenario")
specific_run = platform.runs.get("Model", "Scenario", version=2)
Parameters:

  • model_name (str) – The name of a model.

  • scenario_name (str) – The name of a scenario.

  • version (int | None) – The version number of a run or None to get the default version.

Raises:

RunNotFound – If the run with model_name, scenario_name and optional version does not exist.

Returns:

The retrieved run.

Return type:

ixmp4.core.run.Run

list(**kwargs: Unpack[FacadeRunFilter]) → List[Run]

Lists runs by specified criteria.

platform.runs.list()
#> [<Run 1 model='Model' scenario='Scenario' version=1>]
Parameters:

**kwargs (any) – Any filter parameters as specified in RunFilter.

Returns:

List of runs.

Return type:

list[ixmp4.core.run.Run]

tabulate(include_audit_info: bool = False, include_internal_columns: bool = False, audit_info: bool | None = None, **kwargs: Unpack[FacadeRunFilter]) → DataFrame

Tabulate runs by specified criteria.

platform.runs.tabulate()
#>    id  model  scenario  version  is_default
# 0   1   Model  Scenario  1        True
Parameters:

  • include_audit_info (bool) – Whether or not to include audit info columns in the data frame. Default: False

  • include_internal_columns (bool) – Whether or not to include internal database columns (model__id, scenario__id, lock_transaction). Default: False

  • **kwargs (any) – Any filter parameters as specified in RunFilter.

Returns:

A data frame with the columns:

  • id

  • model

  • scenario

  • version

  • is_default

and if include_internal_columns is True:

  • model__id

  • scenario__id

  • lock_transaction

and if include_audit_info is True:

  • created_by

  • created_at

  • updated_by

  • updated_at

Return type:

pandas.DataFrame

class ixmp4.core.run.Run(backend: Backend, dto: Run)

As a central class to organize data on a platform the Run provides methods and access to Facade instances.

Attribute

Facade Class

meta

RunMetaDescriptor RunMetaDictFacade

checkpoints

RunCheckpoints

iamc

RunIamcData

optimization

RunOptimizationData
Filter

alias of FacadeRunFilter

NotFound

alias of RunNotFound

NotUnique

alias of RunNotUnique

DeletionPrevented

alias of RunDeletionPrevented

IsLocked

alias of RunIsLocked

LockRequired

alias of RunLockRequired

NoDefaultVersion

alias of NoDefaultRunVersion

meta: RunMetaDescriptor

Facade instance to query run meta indicators for a run.

owns_lock: bool = False

Indicated whether this run object has acquired the run’s lock.

iamc: RunIamcData

Facade instance to manager IAMC data for a run.

optimization: RunOptimizationData

Facade instance to manager optimization data for a run.

checkpoints: RunCheckpoints

Facade instance to manage Checkpoint instances for a run.

property id: int

Unique id.

property model: Model

Associated model.

property scenario: Scenario

Associated scenario.

property version: int

Run version.

set_as_default() → None

Sets this run as the default version for its model + scenario combination.

run.set_as_default()
run.is_default
#> True
unset_as_default() → None

Unsets this run as the default version.

run.unset_as_default()
run.is_default
#> False
transact(message: str, timeout: float | None = None, revert_platform_on_error: bool = False) → Generator[None, None, None]

Context manager to lock the run before yielding control back to the caller. The run is unlocked and a checkpoint with the provided message is created after the context manager exits. If an exception occurs, the run is reverted to the last checkpoint or if no checkpoint exists, to the transaction the run was locked at.

If the run is already locked, the context manager will throw Run.IsLocked or if timeout is provided retry until the timeout has passed (and then throw the original Run.IsLocked exception).

with run.transact("My message"):
    # perform operations that require locking the run
    run.meta["new-key"] = 1

#> Checkpoint created and run unlocked
Parameters:

  • messsage (str) – The message for the checkpoint created after conclusion of the context manager.

  • timeout (int, optional) – Timeout in seconds.

  • revert_platform_on_error (bool, optional) – Whether to revert units when encountering an error; default False.

Raises:

ixmp4.core.exceptions.RunIsLocked – If the run is already locked and no timeout is provided or the provided timeout is exceeded.

delete() → None

Delete this run. Tries to acquire a lock in the background.

run.delete()
Raises:

ixmp4.core.exceptions.RunIsLocked – If the run is already locked by this or another object.

clone(model: str | None = None, scenario: str | None = None, keep_solution: bool = True) → Run

Create a copy of this run.

new_run = run.clone(
    model="OtherModel",
    scenario="OtherScenario",
    keep_solution=False
)
#> <Run 2 model='OtherModel' scenario='OtherScenario' version=1>
Parameters:

  • model (str | None) – Optional model name for the cloned run.

  • scenario (str | None) – Optional scenario name for the cloned run.

  • keep_solution (bool) – Whether to keep the solution data in the clone.

Returns:

The cloned run.

Return type:

ixmp4.core.run.Run