8.6.23. Model¶

class Model¶

代表一个数学优化模型。

方法

`__init__()`	构造一个Model
`addConstr()`	添加一个约束
`addConstrs()`	添加一组约束
`addGenConstrIndicator()`	向模型添加新的指示约束
`addLConstr()`	添加一个线性约束
`addMConstr()`	添加一组约束Ax <= b
`addMVar()`	添加一个MVar
`addPsdVar()`	添加一个半定变量
`addQConstr()`	添加一个线性约束
`addRange()`	添加一个范围约束
`addSOS()`	向模型添加新的SOS约束
`addVar()`	添加一个变量
`addVars()`	添加一组变量
`cbBranch()`	通过指定变量和该变量的下界和上界之间的拆分点来指定新分支策略
`cbCut()`	将新割平面添加到MIP模型
`cbGet()`	检索有关优化进度的其他数据
`cbGetNodeRel()`	检索当前松弛问题的解
`cbGetSolution()`	检索到目前为止最优解的值
`cbSetSolution()`	为MIP模型提供了一种新的可行解
`cbUseSolution()`	如果您已经通过 cbSetSolution 提供了解决方案，则可以选择调用该方法立即将解决方案提交给MIP求解器
`chgCoeff()`	修改约束矩阵中的一个系数值
`computeIIS()`	计算至少包含一个IIS（不可约不一致子系统）
`copy()`	返回一个Model的拷贝
`dispose()`	释放Model对应的资源
`getA()`	获取约束矩阵
`getAttr()`	获取一个attribute的值
`getCoeff()`	获取约束矩阵中的一个系数值
`getCol()`	获取一个变量对应的Column
`getConstrByName()`	通过约束的名称来获取约束对象
`getConstrs()`	获取Model中的所有约束列表
`getGenConstrIndicator()`	按其对象从模型中检索指示约束(Indicator constraint)
`getGenConstrs()`	检索该模型中的所有一般约束（General Constraint）
`getObjective()`	获取目标函数的表达式
`getParamInfo()`	获取parameter的相关信息
`getPsdConstrs()`	获取Model中的所有半定约束列表
`getPsdVars()`	获取Model中的所有半定变量列表
`getQCRow()`	获取二次约束对应的表达式
`getQConstrByName()`	通过二次约束的名称来获取二次约束对象
`getQConstrs()`	获取Model中的所有二次约束列表
`getRow()`	获取约束对应的表达式
`getSOS()`	检索有关SOS约束的信息
`getSOSs()`	检索模型中的所有SOS约束
`getVarByName()`	通过变量名称获取变量
`getVars()`	获取Model中的所有变量列表
`message()`	将字符串打印到日志
`optimize()`	开始模型优化
`read()`	从文件中读取数据，数据类型取决于文件名的后缀
`remove()`	从model中删除一些变量或约束
`reset()`	将模型置为未求解状态，清除所有和solution有关的数据
`resetParams()`	重设所有parameter成默认值
`setAttr()`	设置一个attribute值
`setObjective()`	设置目标函数
`setParam()`	设置一个参数的值
`terminate()`	在MIP回调函数中向求解器发送停止请求
`write()`	将模型数据写入一个文件

__init__(name='', env=None)¶

构造一个Model

Parameters

name='' – Model的名称
env=None – Model对应的Environment，为None时使用默认的Environment

example:

Model()
Model("DietProblem")
env = Env("env.log")
Model("", env)

addConstr(tmpConstr, name='')¶

添加一个约束。返回值可能为约束，二次约束，半定约束，约束矩阵，或二次约束矩阵，取决于TempConstr的值

Parameters

tmpConstr –
需要添加的TempConstr。TempConstr通常由以下类型通过比较运算符得到：
- Var
- MVar
- LinExpr
- MLinExpr
- QuadExpr
- MQuadExpr
- PsdExpr
name='' – 约束的名称。如果返回了一个MConstr或MQConstr，每个约束的名称会添加一个下标作为后缀。

example:

x = m.addVar()
mat = m.addMVar((2, 2))
m.addConstr(x + 1 <= 2, name="Constr")
m.addConstr(mat + 1 <= 2, name="MConstr")
coeff = numpy.random.random((2, 2))
px = m.addPsdVar(dim = 2)
m.addConstr(coeff * px == 2, name="PsdConstr")

addConstrs(generator, name='')¶

添加一组约束。返回一个tupledict，key为约束的下标，它由generator产生。value为约束

Parameters

generator – 约束的generator
name='' – 约束的名字。当name不为None和’’时，每个约束的名称会被添加一个下标作为后缀

example:

v = m.addMVar((2, 2))
c = m.addConstrs((v[i, j].item() <= 1 for i in range(2) for j in range(2)), name='c')

Note

当generator不产生下标时，将会抛出异常

addGenConstrIndicator(Var binvar, bool binval, lhs, str sense=None, float rhs=None, str name="")¶

向模型添加新的指示约束。

Parameters

binvar (Var) – 新Indicator约束的二进制变量。
binval (bool) – Indicator约束生效时的二进制值。
lhs – 可以是 float 、 Var 、 LinExpr 或 TempConstr 类型之一。它是新Indicator约束的左侧值。
sense=None (str) –
新约束的sense。可能的值有：
- MDO.LESS_EQUAL(‘<’)
- MDO.GREATER_EQUAL(‘>’)
- MDO.EQUAL(‘=’)
rhs=None (float) – 新约束的右侧值。
name="" (str) – 新约束的名称。

Note

如果 lhs 的类型为 TempConstr ，则参数 sense 和 rhs 应为None。

addLConstr(lhs, sense=None, rhs=None, name='')¶

添加一个线性约束

Parameters

lhs – 约束的左边部分。可以为TempConstr，这种情况下sense和rhs会被忽略。还可以为数字，变量或线性表达式。
sense=None –
约束的sense。可能的值有：
- MDO.LESS_EQUAL(‘<’)
- MDO.GREATER_EQUAL(‘>’)
- MDO.EQUAL(‘=’)
默认为MDO.LESS_EQUAL
rhs=None – 约束的右边部分。可以为数字，变量或线性表达式
name='' – 新约束的名称

example:

m.addLConstr(linExpr, '>', 0)

addMConstr(A, x, sense, b, name='')¶

添加一组约束Ax <= b。返回一个MConstr对象。

Parameters

A – 二维数组或numpy.ndarray。系数矩阵
x – 变量向量，可以为一维数组或numpy.ndarray。当为None时使用模型的所有变量。
sense –
可以为字符，一维数组或numpy.ndarray，表示约束中的比较符，可以为：
- MDO.LESS_EQUAL(‘<’)
- MDO.GREATER_EQUAL(‘>’)
- MDO.EQUAL(‘=’)
b – 约束右值。可以为一维数组或numpy.ndarray。
name='' – 约束的名称。当name不为None时，约束的名称将添加一个下标作为后缀。

addMVar(shape, lb=0.0, ub=float('inf'), obj=0.0, vtype='C', name='')¶

添加一个MVar

Parameters

shape – 指定要添加的MVar的shape
lb=0.0 – MVar中所有变量的lower bound，可以是单个数字，数组，或numpy.ndarray。当为numpy.ndarray时，需要有对应的shape
ub=float('inf') – MVar中所有变量的upper bound，可以是单个数字，数组，或numpy.ndarray。当为numpy.ndarray时，需要有对应的shape
obj=0.0 – MVar中所有变量在目标函数中的系数，可以是单个数字，数组，或numpy.ndarray。当为numpy.ndarray时，需要有对应的shape
vtype='C' –
MVar中所有变量的类型，可以是单个字符，数组，或numpy.ndarray。当为numpy.ndarray时，需要有对应的shape。变量的类型，分别为
- 连续型变量MDO.CONTINUOUS(‘C’)
- 二元变量MDO.BINARY(‘B’)
- 整数型变量MDO.INTEGER(‘I’)
- 半连续型变量MDO.SEMICONT(‘S’)
- 半整数型变量MDO.SEMIINT(‘N’)
name='' – MVar中所有变量的名称。当不为None时，变量的名称为name加上对应的下标

example:

m.addMVar((2, 2))
m.addMVar((2, 2), lb = 0)
m.addMVar((2, 2), lb = [1, 2, 3, 4])

addPsdVar(dim=0, obj=None, name='')¶

添加一个半定变量

Parameters

dim=0 – 半定变量的矩阵维度
obj=None – 半定变量的目标函数系数，是一个对称方阵。
name='' – 半定变量的名称。

example:

m.addPsdVar(dim = 2, name = "X0")
m.addPsdVar(obj = mat)

Note

参数dim和obj，必须只提供一个。

addQConstr(lhs, sense=None, rhs=None, name='')¶

添加一个线性约束

Parameters

lhs – 约束的左边部分。可以为TempConstr，这种情况下sense和rhs会被忽略。还可以为数字，变量或线性或二次表达式。
sense=None –
约束的sense。可能的值有：
- MDO.LESS_EQUAL(‘<’)
- MDO.GREATER_EQUAL(‘>’)
- MDO.EQUAL(‘=’)
默认为MDO.LESS_EQUAL
rhs=None – 约束的右边部分。可以为数字，变量或线性或二次表达式。
name='' – 新约束的名称

Note

如果这些表达式里没有二次项，方法会报错。

addRange(expr, lower, upper, name='')¶

添加一个范围约束

Parameters

expr – 约束中的表达式。可以为变量或线性表达式，或是Psd表达式
lower – 约束对应表达式的下界。只能为数字或None，None表示负infinity
upper – 约束对应表达式的上界，只能为数字或None，None表示正infinity
name='' – 约束的名称

example:

m.addRange(x * 2 + y * 3, 1, 10)
m.addRange(mat1 * px1, 0, 1)

addSOS(type, vars, wts=None)¶

向模型添加新的SOS约束。

Parameters

type –
新SOS约束的类型。有效类型包括:
- MDO.SOS_TYPE1
- MDO.SOS_TYPE2
vars – 与新SOS约束关联的变量列表。
wts=None – 每个参与变量的权重列表。默认值: [1，2，…]

example:

m = Model()
x = m.addVars(3)
m.addSOS(MDO.SOS_TYPE1, list(x.values()))

addVar(lb=0, ub=float('inf'), obj=0, vtype='C', name='', column=None)¶

添加一个变量

Parameters

lb=0 – 变量的lower bound
ub=float('inf') – 变量的upper bound
obj=0 – 变量在目标函数中的系数
vtype='C' –
变量的类型，分别为
- 连续型变量MDO.CONTINUOUS(‘C’)
- 二元变量MDO.BINARY(‘B’)
- 整数型变量MDO.INTEGER(‘I’)
- 半连续型变量MDO.SEMICONT(‘S’)
- 半整数型变量MDO.SEMIINT(‘N’)
name='' – 变量的名称。
column=None – 设置变量在已有约束中的系数

example:

m.addVar()
m.addVar(vtype=MDO.INTEGER)
m.addVar(name='x')

addVars(*indices, lb=0.0, ub=float('inf'), obj=0.0, vtype='C', name='')¶

添加一组变量。返回一个tupledict，key为索引，value为变量

Parameters

*indices –
变量的索引
lb=0.0 – 变量组中所有变量的lower bound，可以是单个数字，数组，或numpy.ndarray。当为numpy.ndarray时，它的shape必须等于indices
ub=float('inf') – 变量组中所有变量的upper bound，可以是单个数字，数组，或numpy.ndarray。当为numpy.ndarray时，它的shape必须等于indices
obj=0.0 – 变量组中所有变量在目标函数中的系数，可以是单个数字，数组，或numpy.ndarray。当为numpy.ndarray时，它的shape必须等于indices
vtype='C' –
变量组中所有变量的类型，可以是单个字符，数组，或numpy.ndarray。当为numpy.ndarray时，它的shape必须等于indices 变量的类型，分别为
- 连续型变量MDO.CONTINUOUS(‘C’)
- 二元变量MDO.BINARY(‘B’)
- 整数型变量MDO.INTEGER(‘I’)
- 半连续型变量MDO.SEMICONT(‘S’)
- 半整数型变量MDO.SEMIINT(‘N’)
name='' – 变量组中所有变量的名称。当不为None和’’时，变量的名称为name加上对应的下标

example:

m.addVars(2, 2)
m.addVars(2, 2, lb=0)
m.addVars(2, 2, lb=[1, 2, 3, 4])
m.addVars(2, 2, lb=numpy.array([1, 2, 3, 4]).reshape(2,2))
td = m.addVars(2, 2)
linExpr = td.sum()

cbBranch(var, value, way)¶

通过指定变量和该变量的下界和上界之间的拆分点来指定新分支策略。返回：

0: 提交成功

1: 提交是合法的，但值不正确（如不可行）

2: 提交是正确的，但没有被接受

Parameters

var – 产生分支的变量。
value – 分割点。它应该在变量的下界和上界之间。
way –
首先要考虑的分支。有效选项包括:
- <0: 首先考虑下行分支。
- >0: 首先考虑向上分支。

Note

方法只能在回调函数中调用。

cbCut(lhs, sense, rhs)¶

将新割平面添加到MIP模型。返回:

0: 提交成功

1: 提交是合法的，但值不正确（如不可行）

2: 提交是正确的，但没有被接受

Parameters

lhs – 新割平面的左侧值。可以是 Var 或 LinExpr
sense – 新割平面的比较符。
rhs – 新割平面的右侧值。可以是 Var 或 LinExpr

Note

方法只能在回调函数中调用。

cbGet(what)¶

检索有关优化进度的其他数据。

Parameters: what – 用户回调请求的数据ID。

Note

方法只能在回调函数中调用。

cbGetNodeRel(vars)¶

检索当前松弛问题的解。

Parameters: vars – Var对象或Var对象列表，以指定要检索解值的变量。

Note

方法只能在回调函数中调用。

cbGetSolution(vars)¶

检索到目前为止最优解的值。

Parameters: vars – Var对象或Var对象列表，以指定要检索解的变量。

Note

方法只能在回调函数中调用。

cbSetSolution(vars, sol)¶

为MIP模型提供了一种新的可行解。如果方案可行，将返回对应的目标值。

Parameters

vars – 变量或变量的列表，指定需要设置解的变量。
sol – double或double值的列表，用于指定要提供的新的可行解。

Note

方法只能在回调函数中调用。

cbUseSolution()¶

如果您已经通过 cbSetSolution 提供了解决方案，则可以选择调用该方法立即将解决方案提交给MIP求解器。方法返回一个包含2个元素的元组: status和目标值。 status可以是:

0: 提交成功

1: 提交有效但不正确 (不可行等)

2: 提交是正确的，但未被接受。

Note

方法只能在回调函数中调用。

chgCoeff(constr, var, newvalue)¶

修改约束矩阵中的一个系数值

Parameters

constr – 对应的约束
var – 对应的变量
newvalue – 新的系数值

example:

coeff = m.getCoeff(constr, var)
m.chgCoeff(constr, var, coeff + 1)

computeIIS(callback=None)¶

计算至少包含一个IIS（不可约不一致子系统）。 IIS是变量边界和约束边界的子集，该子集满足:

子集对应的子问题仍然不可行

删除该子集中的任何边界后，子问题变得可行。

有关更多详细信息，请检查IIS相关属性的变量和约束。

Parameters: callback=None – 设置用户定义的回调函数。

Note

子系统的基数应该很小。请注意，这个问题应该是不可解的。

copy()¶

返回一个Model的拷贝

example:

another = model.copy()

Note

对Model的拷贝将会消耗更多内存资源

dispose()¶

释放Model对应的资源。

example:

model.dispose()

getA()¶

获取约束矩阵。将返回一个scipy.sparse包中的稀疏矩阵。

example:

m.getA()

getAttr(attrname, objs=None)¶

获取一个attribute的值

Parameters

attrname – attribute的名称
objs=None – 变量或约束的列表，表示获取对应的变量或约束的attribute。为None时表示获取模型级别的attribute。

example:

v = m.addMVar((3,))
print(m.getAttr("ModelName"))
print(m.modelname)
print(m.getAttr("VarName", v.tolist()))
print(v.varname)

Note

Attribute的读写也可以直接通过对象属性读写完，这种情况下，属性名称大小写不敏感

getCoeff(constr, var)¶

获取约束矩阵中的一个系数值

Parameters

constr – 对应的约束
var – 对应的变量

example:

coeff = m.getCoeff(constr, var)
m.chgCoeff(constr, var, coeff + 1)

getCol(var)¶

获取一个变量对应的Column

Parameters: var – 对应的变量

example:

column = m.getCol(x)

getConstrByName(name)¶

通过约束的名称来获取约束对象

Parameters: name – 约束的名称

example:

c.constrname = 'myconstr'
print(c.sameAs(m.getConstrByName('myconstr')))

getConstrs()¶

获取Model中的所有约束列表

example:

m.getConstrs()

getGenConstrIndicator(GenConstr genconstr)¶

按其对象从模型中检索指示约束(Indicator constraint)。将返回包含5个元素的元组:

该Indicator约束的二进制变量。

Indicator约束生效时的二进制值。

该Indicator约束的线性表达式。

该Indicator约束的约束比较符。

该Indicator约束的右侧值。

Parameters: genconstr (GenConstr) – Indicator约束对象。

getGenConstrs()¶: 检索该模型中的所有一般约束（General Constraint）

getObjective()¶

获取目标函数的表达式

example:

expr = m.getObjective()

getParamInfo(paramname)¶

获取parameter的相关信息。返回一个包含6个元素的tuple，其分别为：

parameter的名称

parameter的类型

parameter的当前值

parameter允许的最小值，当parameter为字符串类型时，该字段为’’

parameter允许的最大值，当parameter为字符串类型时，该字段为’’

parameter的默认值

Parameters: paramname – parameter的名称

example:

pname, ptype, pval, pmin, pmax, pdef = m.getParamInfo('MaxTime')

Note

参数名称可以包含’*’和’?’通配符，当匹配到不止一个参数名称时，打印所有匹配的参数

getPsdConstrs()¶

获取Model中的所有半定约束列表

example:

m.getPsdConstrs()

getPsdVars()¶

获取Model中的所有半定变量列表

example:

m.getPsdVars()

getQCRow(qconstr)¶

获取二次约束对应的表达式

Parameters: qconstr – 对应的二次约束

getQConstrByName(name)¶

通过二次约束的名称来获取二次约束对象

Parameters: name – 二次约束的名称

getQConstrs()¶: 获取Model中的所有二次约束列表。

getRow(constr)¶

获取约束对应的表达式

Parameters: constr – 对应的约束

example:

m.getRow(c)

getSOS(sos)¶

检索有关SOS约束的信息。该方法返回一个三元组:

指示sos类型的整数。

参与变量列表。

每个参与变量的权重列表。

Parameters: sos – 要检索有关信息的SOS约束。

example:

m = Model()
m.addVars(3)
sos = m.addSOS(MDO.SOS_TYPE1, m.getVars())
type, vars, wts = m.getSOS(sos)

getSOSs()¶

检索模型中的所有SOS约束。

example:

m = Model()
x = m.addVars()
m.addSOS(MDO.SOS_TYPE1, list(x.values()))
print(m.getSOSs())

getVarByName(name)¶

通过变量名称获取变量

Parameters: name – 变量的名称

example:

v.varname = 'myvar'
print(v.sameAs(m.getVarByName('myvar')))

getVars()¶

获取Model中的所有变量列表

example:

m.getVars()

message(message)¶

将字符串打印到日志

Parameters: message – 要打印的字符串

example:

m.message("Start to optimize")
m.optimize()
m.message("Ok")

optimize(callback=None)¶

开始模型优化。这可能需要一些时间，取决于问题的复杂性。

Parameters

callback=None –

设置用户定义的回调函数。用户定义的函数有两个参数 model 和 where ，其中 model 可用于上下文传递:

def callback(model, where):
    model._calls += 1

model = read("prob.mps")
model._calls = 0
model.optimize(callback)
print(model._calls)

注意只有名称前缀为 “_” 的成员变量才能添加到 model 以进行上下文传递。

example:

m.optimize()

read(filename)¶

从文件中读取数据，数据类型取决于文件名的后缀。

Parameters: filename – 文件的名称。后缀会隐含数据类型，如”.prm”表示加载一个parameter setting，”.mst”表示加载MIP的初始解.

example:

m.read("trial1.prm")

remove(item)¶

从model中删除一些变量或约束

Parameters

item –

要删除的对象，可以为

Var，要删除的变量
PsdVar，要删除的PSD变量
MVar，要删除的变量矩阵，矩阵中的所有变量将从Model中删除
Constr，要删除的约束
QConstr，要删除的二次约束
PsdConstr，要删除的PSD约束
SOS，要删除的SOS约束
GenConstr，要删除的一般约束
MConstr，要删除的约束矩阵，矩阵中的所有约束将从model中删除
MQConstr，要删除的二次约束矩阵，矩阵中所有的二次约束将从model中删除
list或tuple，集合中所有上述的对象将从Model中删除
dict，所有value包含的上述对象将从Model中删除，key则忽略

example:

m.remove(x)
m.remove(c)
m.remove([x0, x1, x2])
m.remove({'x0': x0, 'x1': x1})

reset(clearall=0)¶

将模型置为未求解状态，清除所有和solution有关的数据

Parameters: clearall=0 – 为0时只清理solution，为1时清理所有求解相关数据

example:

m.optimize()
m.reset(1)
m.optimize()

resetParams()¶

重设所有parameter成默认值

example:

m.resetParams()

setAttr(attrname, objs, newvalues=None)¶

设置一个attribute值

Parameters

attrname – attribute的名称
objs – 可以为变量或约束列表，表示设置变量和约束的对应attribute 当newvalues为None时，则objs将被作为一个attribute的新值
newvalues=None – 一个包含attribute新值的数组，数组的长度和objs的长度应相同

example:

m.modelname = "DietProblem"
m.setAttr("ModelName", "DietProblem")
vars = m.addMVar((3,))
vars.varname = ["x0", "x1", "x2"]
name_list = ["x3", "x1", "x2"]
var_list = vars.tolist()
for i in range(len(var_list)):
    var_list[i].setAttr("VarName", name_list[i])

Note

Attribute的读写也可以直接通过对象属性读写完，这种情况下，属性名称大小写不敏感

setObjective(expr, sense=0)¶

设置目标函数

Parameters

expr – 目标函数的表达式
sense=0 –
目标函数的优化方向，包括：
- MDO.MINIMIZE(1)
- MDO.MAXIMIZE(-1)
其他不合法值，将使用现有的优化方向默认优化方向为MDO_MINIMIZE

example:

m.setObjective(x + 2 * y, MDO.MINIMIZE)

setParam(paramname, paramvalue)¶

设置一个参数的值

Parameters

paramname – 需要设置的参数名称
paramvalue – 需要设置的参数值

example:

m.setParam("MaxTime", 10)
m.setParam("MaxTi*", 10)
m.setParam("MaxTi*", "default")

Note

参数名称可以包含’*’和’?’通配符，当匹配到不止一个参数名称时，不修改参数值。
参数值为’default’时，可以将参数重设为默认值。

terminate()¶: 在MIP回调函数中向求解器发送停止请求。求解器终止后，将从 model.optimize 返回错误代码 ABORT_CTRL_C 。

Note

方法只能在回调函数中调用。

write(filename)¶

将模型数据写入一个文件。数据类型取决于文件名的后缀。

Parameters

filename –

要写入的文件名。合法后缀包括：

’.lp’

’.mps’

’.qps’

这些会将模型本身写入文件，另外

’.sol’

’.bas’

’.prm’

’.mst’

指定这些后缀的文件名，会将solution，basis，parameter setting或MIP starts写入文件。另外，在合法的文件名称后，还可以再次添加’.gz’或’.bz2’后缀来指定压缩格式。

example:

m.write("prob.mps")
m.write("settings.prm.gz")