Optimization Data

class ixmp4.core.optimization.data.RunOptimizationData(backend: Backend, run: Run)

An optimization data instance, which provides access to optimization data such as IndexSet, Table, Variable, etc.

equations: EquationServiceFacade

Facade instance to manage Equation instances for a run.

indexsets: IndexSetServiceFacade

Facade instance to manage IndexSet instances for a run.

parameters: ParameterServiceFacade

Facade instance to manage Parameter instances for a run.

scalars: ScalarServiceFacade

Facade instance to manage Scalar instances for a run.

tables: TableServiceFacade

Facade instance to manage Table instances for a run.

variables: VariableServiceFacade

Facade instance to manage Variable instances for a run.

remove_solution() → None

Remove solution data from all equations and variables on this run.

run.optimization.remove_solution()
#> None (solution data removed)

has_solution() → bool

Check whether this Run contains a solution.

run.optimization.has_solution()
#> True

Optimization IndexSets

class ixmp4.core.optimization.indexset.IndexSetServiceFacade(backend: Backend, run: ixmp4.core.run.Run)

Used to manage index sets for a specific run.

create(name: str) → IndexSet

Create a new index set for this run.

Requires an active run lock — use with run.transact("message"): before calling this method.

run.optimization.indexsets.create("Years")
#> <IndexSet 1 name='Years'>

Raises:

ixmp4.data.run.exceptions.RunLockRequired – If no run lock is held.

delete(x: IndexSet | int | str) → None

Delete an index set for the run.

Requires an active run lock — use with run.transact("message"): before calling this method.

run.optimization.indexsets.delete("Years")

Raises:

ixmp4.data.run.exceptions.RunLockRequired – If no run lock is held.

get_by_name(name: str) → IndexSet

Retrieve an index set by name for this run.

run.optimization.indexsets.get_by_name("Years")
#> <IndexSet 1 name='Years'>

list(**kwargs: Unpack[IndexSetFilter]) → list[IndexSet]

List index sets for this run.

run.optimization.indexsets.list()
#> [<IndexSet 1 name='Years'>]

tabulate(**kwargs: Unpack[IndexSetFilter]) → DataFrame

Tabulate index sets for this run.

run.optimization.indexsets.tabulate()
#>    name    id
# 0  Years   1

class ixmp4.core.optimization.indexset.IndexSet(backend: Backend, dto: DtoT, run: ixmp4.core.run.Run)

Filter

alias of IndexSetFilter

NotUnique

alias of IndexSetNotUnique

NotFound

alias of IndexSetNotFound

DeletionPrevented

alias of IndexSetDeletionPrevented

DataInvalid

alias of IndexSetDataInvalid

docs: DocsDescriptor[IndexSetService, IndexSet]

Optimization IndexSet docs.

property id: int

Unique id.

property name: str

IndexSet name.

property run_id: int

Run id.

property data: list[float] | list[int] | list[str]

Data contained in the index set.

add_data(data: float | int | str | list[float] | list[int] | list[str]) → None

Adds data to the IndexSet.

Requires an active run lock — use with run.transact("message"): before calling this method.

Raises:

ixmp4.data.run.exceptions.RunLockRequired – If no run lock is held.

remove_data(data: float | int | str | list[float] | list[int] | list[str]) → None

Removes data from the IndexSet.

Requires an active run lock — use with run.transact("message"): before calling this method.

If data is None (the default), remove all data. Otherwise, data must specify all indexed columns. All other keys/columns are ignored.

Raises:

ixmp4.data.run.exceptions.RunLockRequired – If no run lock is held.

delete() → None

Delete this IndexSet.

Requires an active run lock — use with run.transact("message"): before calling this method.

Raises:

ixmp4.data.run.exceptions.RunLockRequired – If no run lock is held.

Optimization Scalars

class ixmp4.core.optimization.scalar.ScalarServiceFacade(backend: Backend, run: Run)

Used to manage scalars for a specific run.

create(name: str, value: float, unit: str | Unit | None = None) → Scalar

Create a scalar for the run.

Requires an active run lock — use with run.transact("message"): before calling this method.

run.optimization.scalars.create("discount", 0.05, unit="")
#> <Scalar 1 name='discount'>

Raises:

ixmp4.data.run.exceptions.RunLockRequired – If no run lock is held.

delete(x: Scalar | int | str) → None

Delete a scalar for the run.

Requires an active run lock — use with run.transact("message"): before calling this method.

run.optimization.scalars.delete("discount")

Raises:

ixmp4.data.run.exceptions.RunLockRequired – If no run lock is held.

get_by_name(name: str) → Scalar

Retrieve a scalar by name for this run.

run.optimization.scalars.get_by_name("discount")
#> <Scalar 1 name='discount'>

list(**kwargs: Unpack[ScalarFilter]) → list[Scalar]

List scalars for this run.

run.optimization.scalars.list()
#> [<Scalar 1 name='discount'>]

tabulate(**kwargs: Unpack[ScalarFilter]) → DataFrame

Tabulate scalars for this run.

run.optimization.scalars.tabulate()
#>    name    value  unit
# 0  discount 0.05   ""

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

Filter

alias of ScalarFilter

NotUnique

alias of ScalarNotUnique

NotFound

alias of ScalarNotFound

DeletionPrevented

alias of ScalarDeletionPrevented

docs: DocsDescriptor[ScalarService, Scalar]

Optimization Scalar docs.

property id: int

Unique id.

property name: str

Scalar name.

property run_id: int

Run id.

property value: float

Associated value.

property unit: Unit

Associated unit.

update(value: int | float | None = None, unit_name: str | None = None) → None

Updates data on the Scalar.

Requires an active run lock — use with run.transact("message"): before calling this method.

Raises:

ixmp4.data.run.exceptions.RunLockRequired – If no run lock is held.

delete() → None

Delete this Scalar.

Requires an active run lock — use with run.transact("message"): before calling this method.

Raises:

ixmp4.data.run.exceptions.RunLockRequired – If no run lock is held.

Optimization Equations

class ixmp4.core.optimization.equation.EquationServiceFacade(backend: Backend, run: ixmp4.core.run.Run)

Used to manage equations for a specific run.

create(name: str, constrained_to_indexsets: list[str] | None = None, column_names: list[str] | None = None) → Equation

Create a new equation for this run.

Requires an active run lock — use with run.transact("message"): before calling this method.

run.optimization.equations.create("Balance")
#> <Equation 1 name='Balance'>

Raises:

ixmp4.data.run.exceptions.RunLockRequired – If no run lock is held.

delete(x: Equation | int | str) → None

Delete an equation from the run.

Requires an active run lock — use with run.transact("message"): before calling this method.

run.optimization.equations.delete("Balance")

Raises:

ixmp4.data.run.exceptions.RunLockRequired – If no run lock is held.

get_by_name(name: str) → Equation

Retrieve an equation by name for this run.

run.optimization.equations.get_by_name("Balance")
#> <Equation 1 name='Balance'>

list(**kwargs: Unpack[EquationFilter]) → list[Equation]

List equations for this run.

run.optimization.equations.list()
#> [<Equation 1 name='Balance'>]

tabulate(**kwargs: Unpack[EquationFilter]) → DataFrame

Tabulate equations for this run.

run.optimization.equations.tabulate()
#>    name    id
# 0  Balance 1

class ixmp4.core.optimization.equation.Equation(backend: Backend, dto: DtoT, run: ixmp4.core.run.Run)

Filter

alias of EquationFilter

NotUnique

alias of EquationNotUnique

NotFound

alias of EquationNotFound

DeletionPrevented

alias of EquationDeletionPrevented

DataInvalid

alias of EquationDataInvalid

docs: DocsDescriptor[EquationService, Equation]

Optimization Equation docs.

property id: int

Unique id.

property name: str

Equation name.

property run_id: int

Run id.

property data: dict[str, list[float] | list[int] | list[str]]

Raw data dictionary for this equation.

property levels: list[float]

Level values associated with this equation.

property marginals: list[float]

Marginal values for this equation.

property indexset_names: list[str] | None

Names of index sets constraining this equation.

property column_names: list[str] | None

Names of columns for this equation.

add_data(data: dict[str, Any] | DataFrame) → None

Adds data to the Equation.

Requires an active run lock — use with run.transact("message"): before calling this method.

Raises:

ixmp4.data.run.exceptions.RunLockRequired – If no run lock is held.

remove_data(data: dict[str, Any] | DataFrame | None = None) → None

Removes data from the Equation.

Requires an active run lock — use with run.transact("message"): before calling this method.

If data is None (the default), remove all data. Otherwise, data must specify all indexed columns. All other keys/columns are ignored.

Raises:

ixmp4.data.run.exceptions.RunLockRequired – If no run lock is held.

delete() → None

Delete this Equation from the run.

Requires an active run lock — use with run.transact("message"): before calling this method.

Raises:

ixmp4.data.run.exceptions.RunLockRequired – If no run lock is held.

Optimization Parameters

class ixmp4.core.optimization.parameter.ParameterServiceFacade(backend: Backend, run: ixmp4.core.run.Run)

Used to manage parameters for a specific run.

create(name: str, constrained_to_indexsets: list[str], column_names: list[str] | None = None) → Parameter

Create a new parameter for the run.

Requires an active run lock — use with run.transact("message"): before calling this method.

run.optimization.parameters.create("Cost", ["Region", "Year"])
#> <Parameter 1 name='Cost'>

Raises:

ixmp4.data.run.exceptions.RunLockRequired – If no run lock is held.

delete(x: Parameter | int | str) → None

Delete a parameter from the run.

Requires an active run lock — use with run.transact("message"): before calling this method.

run.optimization.parameters.delete("Cost")

Raises:

ixmp4.data.run.exceptions.RunLockRequired – If no run lock is held.

get_by_name(name: str) → Parameter

Retrieve a parameter by name for this run.

run.optimization.parameters.get_by_name("Cost")
#> <Parameter 1 name='Cost'>

list(**kwargs: Unpack[ParameterFilter]) → list[Parameter]

List parameters for this run.

run.optimization.parameters.list()
#> [<Parameter 1 name='Cost'>]

tabulate(**kwargs: Unpack[ParameterFilter]) → DataFrame

Tabulate parameters for this run.

run.optimization.parameters.tabulate()
#>    name    id
# 0  Cost    1

class ixmp4.core.optimization.parameter.Parameter(backend: Backend, dto: DtoT, run: ixmp4.core.run.Run)

Filter

alias of ParameterFilter

NotUnique

alias of ParameterNotUnique

NotFound

alias of ParameterNotFound

DeletionPrevented

alias of ParameterDeletionPrevented

DataInvalid

alias of ParameterDataInvalid

docs: DocsDescriptor[ParameterService, Parameter]

Optimization Parameter docs.

property id: int

Unique id.

property name: str

Parameter name.

property run_id: int

Run id.

property data: dict[str, list[float] | list[int] | list[str]]

Raw data dictionary for this parameter.

property values: list[float]

List of numeric values for this parameter.

property units: list[str]

List of units associated with the parameter values.

property indexset_names: list[str]

Names of index sets constraining this parameter.

property column_names: list[str] | None

Names of columns for this parameter.

add_data(data: dict[str, Any] | DataFrame) → None

Adds data to the Parameter.

Requires an active run lock — use with run.transact("message"): before calling this method.

Raises:

ixmp4.data.run.exceptions.RunLockRequired – If no run lock is held.

remove_data(data: dict[str, Any] | DataFrame | None = None) → None

Removes data from the Parameter.

Requires an active run lock — use with run.transact("message"): before calling this method.

If data is None (the default), remove all data. Otherwise, data must specify all indexed columns. All other keys/columns are ignored.

Raises:

ixmp4.data.run.exceptions.RunLockRequired – If no run lock is held.

delete() → None

Delete this Parameter from the run.

Requires an active run lock — use with run.transact("message"): before calling this method.

Raises:

ixmp4.data.run.exceptions.RunLockRequired – If no run lock is held.

Optimization Tables

class ixmp4.core.optimization.table.TableServiceFacade(backend: Backend, run: ixmp4.core.run.Run)

Used to manage tables for a specific run.

create(name: str, constrained_to_indexsets: List[str], column_names: List[str] | None = None) → Table

Create a new table for this run.

Requires an active run lock — use with run.transact("message"): before calling this method.

run.optimization.tables.create("CostTable", ["region", "year"])
#> <Table 1 name='CostTable'>

Raises:

ixmp4.data.run.exceptions.RunLockRequired – If no run lock is held.

delete(x: Table | int | str) → None

Delete a table for the run.

Requires an active run lock — use with run.transact("message"): before calling this method.

run.optimization.tables.delete("CostTable")

Raises:

ixmp4.data.run.exceptions.RunLockRequired – If no run lock is held.

get_by_name(name: str) → Table

Retrieve a table by name for this run.

run.optimization.tables.get_by_name("CostTable")
#> <Table 1 name='CostTable'>

list(**kwargs: Unpack[TableFilter]) → list[Table]

List tables for this run.

run.optimization.tables.list()
#> [<Table 1 name='CostTable'>]

tabulate(**kwargs: Unpack[TableFilter]) → DataFrame

Tabulate tables for this run.

run.optimization.tables.tabulate()
#>    name    id
# 0  CostTable 1

class ixmp4.core.optimization.table.Table(backend: Backend, dto: DtoT, run: ixmp4.core.run.Run)

Filter

alias of TableFilter

NotUnique

alias of TableNotUnique

NotFound

alias of TableNotFound

DeletionPrevented

alias of TableDeletionPrevented

DataInvalid

alias of TableDataInvalid

docs: DocsDescriptor[TableService, Table]

Optimization Table docs.

property id: int

Unique id.

property name: str

Table name.

property run_id: int

Run id.

property data: dict[str, list[float] | list[int] | list[str]]

Raw data dictionary for this table.

property indexset_names: list[str]

Names of index sets constraining this table.

property column_names: list[str] | None

Names of columns for this table.

add_data(data: dict[str, Any] | DataFrame) → None

Adds data to the Table.

Requires an active run lock — use with run.transact("message"): before calling this method.

Raises:

ixmp4.data.run.exceptions.RunLockRequired – If no run lock is held.

remove_data(data: dict[str, Any] | DataFrame | None = None) → None

Removes data from the Table.

Requires an active run lock — use with run.transact("message"): before calling this method.

If data is None (the default), remove all data. Otherwise, data must specify all indexed columns. All other keys/columns are ignored.

Raises:

ixmp4.data.run.exceptions.RunLockRequired – If no run lock is held.

delete() → None

Delete this Table.

Requires an active run lock — use with run.transact("message"): before calling this method.

Raises:

ixmp4.data.run.exceptions.RunLockRequired – If no run lock is held.

Optimization Variables

class ixmp4.core.optimization.variable.VariableServiceFacade(backend: Backend, run: ixmp4.core.run.Run)

Used to manage optimization variables for a specific run.

create(name: str, constrained_to_indexsets: list[str] | None = None, column_names: list[str] | None = None) → Variable

Create a new optimization variable for the run.

Requires an active run lock — use with run.transact("message"): before calling this method.

run.optimization.variables.create("Production")
#> <Variable 1 name='Production'>

Raises:

ixmp4.data.run.exceptions.RunLockRequired – If no run lock is held.

delete(x: Variable | int | str) → None

Delete a variable from the run.

Requires an active run lock — use with run.transact("message"): before calling this method.

run.optimization.variables.delete("Production")

Raises:

ixmp4.data.run.exceptions.RunLockRequired – If no run lock is held.

get_by_name(name: str) → Variable

Get a variable by name for this run.

run.optimization.variables.get_by_name("Production")
#> <Variable 1 name='Production'>

list(**kwargs: Unpack[VariableFilter]) → list[Variable]

List variables defined for this run.

run.optimization.variables.list()
#> [<Variable 1 name='Production'>]

tabulate(**kwargs: Unpack[VariableFilter]) → DataFrame

Tabulate variables for this run.

run.optimization.variables.tabulate()
#>    name    id
# 0  Production 1

class ixmp4.core.optimization.variable.Variable(backend: Backend, dto: DtoT, run: ixmp4.core.run.Run)

Filter

alias of VariableFilter

NotUnique

alias of VariableNotUnique

NotFound

alias of VariableNotFound

DeletionPrevented

alias of VariableDeletionPrevented

DataInvalid

alias of VariableDataInvalid

docs: DocsDescriptor[VariableService, Variable]

Optimization Variable docs.

property id: int

Unique id.

property name: str

Variable name.

property run_id: int

Run id.

property data: dict[str, list[float] | list[int] | list[str]]

Raw data dictionary for this variable.

property levels: list[float]

Level values associated with this variable.

property marginals: list[float]

Marginal values for this variable.

property indexset_names: list[str] | None

Names of index sets constraining this variable.

property column_names: list[str] | None

Names of columns for this variable.

add_data(data: dict[str, Any] | DataFrame) → None

Adds data to the Variable.

Requires an active run lock — use with run.transact("message"): before calling this method.

Raises:

ixmp4.data.run.exceptions.RunLockRequired – If no run lock is held.

remove_data(data: dict[str, Any] | DataFrame | None = None) → None

Removes data from the Variable.

Requires an active run lock — use with run.transact("message"): before calling this method.

If data is None (the default), remove all data. Otherwise, data must specify all indexed columns. All other keys/columns are ignored.

Raises:

ixmp4.data.run.exceptions.RunLockRequired – If no run lock is held.

delete() → None

Delete this Variable from the run.

Requires an active run lock — use with run.transact("message"): before calling this method.

run.optimization.variables.delete("Production")

Raises:

ixmp4.data.run.exceptions.RunLockRequired – If no run lock is held.