5.11. Model¶

class Model¶

The optimization model.

Properties

`DualGap`	The gap for dual problem.
`DualObjVal`	The objective value for dual problem.
`MinSense`	Check if this model is to be minimized.
`ModelSense`	Model sense (minimization(1) or maximization(-1)).
`Name`	The name of this model.
`NumConstrs`	The number of constraints this model has.
`NumIters`	The number of optimization iterations.
`ObjVal`	The objective value for primal problem.
`PrimalGap`	The gap for primal problem.
`PrimalObjVal`	The objective value for primal problem.
`SolverTime`	The optimization time.
`Status`	The optimization status.
`StatusString`	The optimization status string message.

Methods

`__init__()`	Construct a model.
`addConstr()`	Add a new constraint to this model.
`getConstr()`	Get constraint object by its index.
`removeConstr()`	Remove constraint(s) from model.
`getObjective()`	Get the objective function as an expression.
`setObjective()`	Set objective function for this model.
`getOption()`	Get value for an option.
`getOptionInfo()`	Get the metadata for an option.
`setOption()`	Set a new value for an option.
`getParam()`	Retrieve the parameter in this model.
`getVar()`	Get variable object by its index.
`getVarByName()`	Get variable by its name.
`optimize()`	Optimize this model.
`write()`	Write this model to a file.
`dispose()`	Instantly free memory for model object, or model may be freed automatically by garbage collector.

property DualGap: float¶: The gap for dual problem.

property DualObjVal: float¶: The objective value for dual problem.

property MinSense: bool¶: Check if this model is to be minimized.

property ModelSense: int¶: Model sense (minimization(1) or maximization(-1)).

property Name: str¶: The name of this model.

property NumConstrs: int¶: The number of constraints this model has.

property NumIters: int¶: The number of optimization iterations.

property ObjVal: float¶: The objective value for primal problem.

property PrimalGap: float¶: The gap for primal problem.

property PrimalObjVal: float¶: The objective value for primal problem.

property SolverTime: float¶: The optimization time.

property Status: int¶

The optimization status.

SOLVE_UNKNOWN = 0

SOLVE_OPT_SUCCESS = 1

SOLVE_INFEASIBLE = 2

SOLVE_UNBOUNDED = 3

SOLVE_OVER_MAX_ITER = 4

SOLVE_OVER_MAX_TIME = 5

SOLVE_NAN_FOUND = 6

SOLVE_PRE_FAILURE = 7

SOLVE_EXCEPT_ERROR = 8

SOLVE_GET_SOL_FAILURE = 9

SOLVE_ERROR = 10

property StatusString: str¶: The optimization status string message.

__init__(obj: Model | None = None, file: str | None = None, logfile: str | None = None)¶

Construct a model.

param obj:

Type: Optional[Model] = None

The model to copy. When both obj and file have assigned values, obj is used and file is ignored.

param file:

Type: Optional[str] = None

The file to read model from. The compression type is encoded in the file name as a suffix (.gz, .bz2), for instance “model.input.gz” implies a gzip compression type.

param logfile:

Type: Optional[str] = None

The file to write log to.

Add a new constraint to this model.

param lexpr:

Type: Union[TensorLike, ArrayLike, Constr]

The left-side-hand value for new constraint. If it is a Constr, the rest arguments will be ignored.

param sense:

Type: Optional[str] = None

The comparator for new constraint.

It is:

‘<’ for less than or equal to.

‘>’ for greater than or equal to.

‘=’ for equal to.

‘N’ for NSD.

‘P’ for PSD

param rexpr:

Type: Union[TensorLike, ArrayLike, Constr] = None

The right-side-hand value for new constraint.

return:

Type: Constr

The newly added constraint.

getConstr(index: int)¶

Get constraint object by its index.

param index:

Type: int

Constraint index.

return:

Type: Constr

The indexed constraint.

removeConstr(constrs: Constr | Iterable[Constr])¶

Remove constraint(s) from model.

param constrs:

Type: Union[Constr, Iterable[Constr]]

The constraints to be removed.

getObjective()¶

Get the objective function as an expression.

return:

Type: Expr

The objective function.

Note

If model has no objective function, this method raise an error.

setObjective(expr: TensorLike | ArrayLike, modelsense: int = 0)¶

Set objective function for this model.

Note that only scalar or expression with 1 element can be set as objective function.

param expr:

Type: Union[TensorLike, ArrayLike]

The objective function. Pass a None to clear objective function.

param modelsense:

Type: int = 0

Optimization sense, MINIMIZE(1) or MAXIMIZE(-1). Default 0 means keep the current sense (minimize if not previously set).

getOption(name: str)¶

Get value for an option.

param name:

Type: str

The option name.

return:

Type: Union[int, float]

The current option value.

Note

User may use Options.XXX to specify option name.

getOptionInfo(name: str)¶

Get the metadata for an option.

param name:

Type: str

The option name.

return:

Type: Tuple[str, Union[int, float], Union[int, float], Union[int, float]]

A tuple with 4 elements will be returned: the canonical option name, the minimal value allowed (inclusive), the maximal value allowed(inclusive), and the default value

Note

User may use Options.XXX to specify option name.

setOption(name: str, value: int | float)¶

Set a new value for an option.

param name:

Type: str

The option name.

param value:

Type: Union[int, float]

The new option value.

Note

User may use Options.XXX to specify option name.

getParam(name: str)¶

Retrieve the parameter in this model.

param name:

Type: str

The parameter name.

return:

Type: Param

The parameter to be retrieved.

getVar(index: int)¶

Get variable object by its index.

param index:

Type: int

Variable index.

return:

Type: Var

The indexed variable.

getVarByName(name: str)¶

Get variable by its name.

param name:

Type: str

Variable name.

return:

Type: Var

The variable, or None if no such variable exist.

optimize(paramdict: Dict[str, ArrayLike] | None = {}, tuner: Callable[[TuningContext], None] | None = None)¶

Optimize this model.

def hptune(ctx: TuningContext):
    print(ctx)

p = Param("param1", 2, 2)
x = Var(2, 2)

model.setObjective(sum(p @ x))
model.optimize({"param1": [[1, 2], [3, 4]]}, hptune)

param paramdict:

Type: Optional[Dict[str, ArrayLike]] = {}

The constant value to be bounded to parameter.

param tuner:

Type: Optional[Callable[[TuningContext], None]] = None

The customized hyper parameter tuning function.

write(fname: str)¶

Write this model to a file.

param fname:

Type: str

The output file name. The compression type is encoded in the file name as a suffix (.gz, .bz2), for instance “model.output.gz” implies a gzip compression type.

Note

A model with user defined function (aka. UDF) can not be serialized to file.

dispose()¶: Instantly free memory for model object, or model may be freed automatically by garbage collector.