导出 MD

OptModel 方法详情¶

方法索引¶

变量与常量

constant · bool · int · float · set · list · interval · optional_interval

约束与目标

add_constraint · minimize · maximize

算术与聚合

sum · prod · min · max · sub · abs · dist · div · mod · pow

比较与逻辑

eq · neq · geq · leq · gt · lt · not_ · and_ · or_ · xor · iif

集合关系

partition · disjoint · cover · union · intersection

数组与索引

array · at · range · count · contains · index · distinct · sort · find · step_array

数学函数

sqrt · sin · cos · round · ceil · floor · log · exp

区间属性

start · end · length · presence · hull

Lambda 与外部函数

lambda_function · call · piecewise · create_int_external_function · create_double_external_function · create_int_array_external_function · create_double_array_external_function

求解

solve · solve_optx · solve_cpsat · solve_mathopt

模型文件

save · read_model

constraint() 是 add_constraint() 的别名。

方法详情¶

以下示例沿用 model = OptModel()。除求解接口外，示例只构建表达式，注释中的结果表示求值结果。

将优化模型构建为不可变表达式图，并对其求解。

变量和表达式属于各自的模型，不能跨模型组合。

示例

from optagent import OptModel

model = OptModel()

PB 文件加载的模型持有不可变快照，首次修改才恢复完整 Python 表达式图。声明容器拥有插入的可变数据并跟踪嵌套修改；编辑时应从模型取得声明。容器支持序列和映射操作，但不保证内置列表或字典的具体类型。浅拷贝共享嵌套视图；深拷贝分离容器数据，表达式句柄仍属于原模型。

求解及交互式会话期间模型冻结；新增表达式、修改声明或通过旧引用进行嵌套写入会抛出 RuntimeError，求解或会话结束后恢复建模。

参数：

名称	类型	描述	默认
`model_id`	`str`	可选模型标识，通常省略，不是结果查询键。	`''`

属性：

名称	类型	描述
`model_id`		可选模型标识。
`decisions`		按创建顺序保存的决策变量声明。
`constraints`		按创建顺序保存的约束声明。
`objectives`		按创建顺序保存、以字典序确定优先级的目标声明。
`external_functions`		按名称索引的已注册外部函数。

constant() ¶

创建常量表达式；省略类型时根据值推断。

示例

value = model.constant(7)  # 固定值 7

参数：

名称	类型	描述	默认
`value`	`Any`	固定的布尔值、数值、整数集合或嵌套数组。	必需
`type_`	`OptType \| ArrayType \| None`	可选的建模类型；省略或传 `None` 时根据 `value` 推断。	`None`

返回：

类型	描述
`Expression`	常量表达式。

异常：

类型	描述
`TypeError`	值无法用指定类型表示。
`ValueError`	数值非有限，或超出支持范围。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：CPSAT 要求数值可按整数表示；MATHOPT、OPTX 可展开受支持的复合常量，并保留无效值语义。

bool() ¶

声明布尔决策变量。

示例

enabled = model.bool()  # 决定是否启用

参数：

名称	类型	描述	默认
`default`	`bool \| object`	可选布尔初值；省略时由求解器构造，不会固定最终值。	`未指定`
`name`	`str`	可选名称，默认为空字符串，不影响求解语义。	`''`

返回：

类型	描述
`Expression`	布尔决策表达式。

异常：

类型	描述
`TypeError`	`default` 不是布尔值。

求解器支持：

SEARCH：支持
CPSAT：支持
MATHOPT：支持
OPTX：支持
说明：布尔变量可用于四条求解路径；完整模型仍须满足各路径的表达式限制。

int() ¶

声明整数决策变量。

示例

quantity = model.int(lb=0, ub=10)  # 0 到 10 之间的整数

参数：

名称	类型	描述	默认
`lb`	`int \| None`	整数下界，包含端点；`None` 表示不声明下界。	`None`
`ub`	`int \| None`	整数上界，包含端点；`None` 表示不声明上界。	`None`
`default`	`int \| object`	可选整数初值，须在上下界内；省略时由求解器构造，不会固定最终值。	`未指定`
`name`	`str`	可选名称，默认为空字符串，不影响求解语义。	`''`

返回：

类型	描述
`Expression`	整数决策表达式。

异常：

类型	描述
`TypeError`	边界或初值不是整数。
`ValueError`	边界无效，或初值超出边界。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：CPSAT、MATHOPT 与 OPTX 的有限展开要求整数有限界及安全数值范围；OPTX 保留普通仿射模型的无界整数支持，不会为展开静默收紧变量域。

float() ¶

声明浮点决策变量。

示例

amount = model.float(lb=0.0, ub=10.0)  # 0 到 10 之间的连续值

参数：

名称	类型	描述	默认
`lb`	`float \| None`	有限数值下界，包含端点；`None` 表示不声明下界。	`None`
`ub`	`float \| None`	有限数值上界，包含端点；`None` 表示不声明上界。	`None`
`default`	`float \| object`	可选有限数值初值，须在上下界内；省略时由求解器构造，不会固定最终值。	`未指定`
`name`	`str`	可选名称，默认为空字符串，不影响求解语义。	`''`

返回：

类型	描述
`Expression`	浮点决策表达式。

异常：

类型	描述
`TypeError`	边界或初值不是数值。
`ValueError`	数值非有限、边界无效，或初值超出边界。

求解器支持：

SEARCH：支持
CPSAT：不支持
MATHOPT：支持
OPTX：支持
说明：CPSAT 不支持浮点决策变量。MATHOPT 与 OPTX 可接受连续变量，表达式仍须满足对应后端限制。

set() ¶

声明从有限整数全集中选择成员的无序集合决策变量。

成员来自 0 到 universe_size - 1，无序且不重复。可为空集；数量由约束决定。

示例

selected = model.set(3)  # 可选编号为 0、1、2
model.add_constraint(model.count(selected) == 2)  # 恰好选 2 个

参数：

名称	类型	描述	默认
`universe_size`	`int`	非负整数 `n`，可选编号为 `0` 到 `n - 1`，不是选中数量；`n=0` 时只能为空集。	必需
`default`	`Iterable[int] \| object`	可选初始成员，如 `[0, 2]`；须为范围内且不重复的整数。省略时由求解器构造，不固定最终成员。	`未指定`
`name`	`str`	可选名称，默认为空字符串，不影响求解语义。	`''`

返回：

类型	描述
`Expression`	集合决策表达式，可用于计数、成员判断、集合运算及集合关系。

异常：

类型	描述
`TypeError`	全集大小或成员不是整数（布尔值不接受），或 `default` 不可迭代。
`ValueError`	全集大小为负、整数超出 64 位有符号范围，或初始成员越界、重复。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：CPSAT、MATHOPT、OPTX 将有限集合、序列和整数区间展开为辅助变量与约束，受有限域及展开规模限制；返回时重建原始复合值。

list() ¶

声明从有限整数全集中选择成员并决定顺序的序列决策变量。

成员来自 0 到 universe_size - 1，有序且不重复。长度可变；完整排列需约束长度等于 universe_size。

示例

route = model.list(3)  # 选择编号 0、1、2，并决定顺序
model.add_constraint(model.count(route) == 3)  # 完整排列，如 [2, 0, 1]

参数：

名称	类型	描述	默认
`universe_size`	`int`	非负整数 `n`，可选编号为 `0` 到 `n - 1`，不是固定长度；`n=0` 时只能为空序列。	必需
`default`	`Iterable[int] \| object`	可选初始序列，如 `[2, 0]`；须为范围内且不重复的整数，保留输入顺序。省略时由求解器构造，不固定最终值。	`未指定`
`name`	`str`	可选名称，默认为空字符串，不影响求解语义。	`''`

返回：

类型	描述
`Expression`	有序且成员不重复的序列决策表达式，可继续索引、计数或参与集合关系。

异常：

类型	描述
`TypeError`	全集大小或成员不是整数（布尔值不接受），或 `default` 不可迭代。
`ValueError`	全集大小为负、整数超出 64 位有符号范围，或初始成员越界、重复。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：CPSAT、MATHOPT、OPTX 将有限集合、序列和整数区间展开为辅助变量与约束，受有限域及展开规模限制；返回时重建原始复合值。

interval() ¶

在给定时间边界内声明必选区间决策变量，边界包含端点。

时间窗口不固定持续时间；需要时用 length 另加约束。

示例

task = model.interval(0, 10)  # 起止时间位于 0 到 10 内
model.add_constraint(task.length == 3)  # 持续 3 个时间单位

参数：

名称	类型	描述	默认
`min_start`	`int`	最早允许开始的整数时间，默认 0。	`0`
`max_end`	`int`	最晚允许结束的整数时间，默认 0，不能小于 `min_start`。	`0`
`default`	`dict[str, Any] \| None \| object`	可选初值映射，如 `{"start": 1, "end": 4}`；须位于时间窗口内。初值不固定最终起止时间，任务始终存在。	`未指定`
`name`	`str`	可选名称，默认为空字符串，不影响求解语义。	`''`

返回：

类型	描述
`Expression`	必选区间表达式。

异常：

类型	描述
`TypeError`	边界或初值字段的类型无效。
`ValueError`	边界或初始区间相互矛盾。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：CPSAT、MATHOPT、OPTX 将有限集合、序列和整数区间展开为辅助变量与约束，受有限域及展开规模限制；返回时重建原始复合值。

optional_interval() ¶

声明可在解中缺席的区间决策变量。

用 presence 判断是否存在；缺席时不要直接使用起止时间。

示例

task = model.optional_interval(0, 10)
model.add_constraint(model.presence(task))  # 本例要求任务存在

参数：

名称	类型	描述	默认
`min_start`	`int`	最早允许开始的整数时间，默认 0。	`0`
`max_end`	`int`	最晚允许结束的整数时间，默认 0，不能小于 `min_start`。	`0`
`default`	`dict[str, Any] \| None \| object`	可选初值映射，使用 `start`、`end`、`present` 字段；`present=False` 表示初始缺席，不固定最终状态。	`未指定`
`name`	`str`	可选名称，默认为空字符串，不影响求解语义。	`''`

返回：

类型	描述
`Expression`	可选区间表达式。

异常：

类型	描述
`TypeError`	边界或初值字段的类型无效。
`ValueError`	边界或初始区间相互矛盾。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：CPSAT、MATHOPT、OPTX 将有限集合、序列和整数区间展开为辅助变量与约束，受有限域及展开规模限制；返回时重建原始复合值。

add_constraint() ¶

将布尔表达式添加为模型约束。

constraint() 是其别名。只创建布尔表达式不会自动添加约束。

示例

x = model.int(0, 10)
model.add_constraint(x >= 4)  # 可行解必须满足 x >= 4

参数：

名称	类型	描述	默认
`expression`	`Expression`	可行解必须满足的布尔表达式。	必需
`name`	`str`	可选名称，默认为空字符串，不影响求解语义。	`''`

异常：

类型	描述
`TypeError`	`expression` 不是布尔表达式。
`ValueError`	`expression` 属于另一个模型。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：支持取决于所有根表达式。OPTX 支持可精确展开的 MILP，另支持显式标量连续凸二次最小化或凹二次最大化目标及线性约束；QP 不允许未固定的整数变量，且只能位于最后目标优先级。

minimize() ¶

追加一个数值最小化目标。

多个目标按添加顺序进行字典序比较。

示例

x = model.int(0, 10)
model.minimize(x)  # 寻找尽可能小的 x

参数：

名称	类型	描述	默认
`expression`	`Expression`	要最小化的数值表达式。	必需
`name`	`str`	可选名称，默认为空字符串，不影响求解语义。	`''`

异常：

类型	描述
`TypeError`	`expression` 不是数值表达式。
`ValueError`	`expression` 属于另一个模型。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：支持取决于所有根表达式。OPTX 支持可精确展开的 MILP，另支持显式标量连续凸二次最小化或凹二次最大化目标及线性约束；QP 不允许未固定的整数变量，且只能位于最后目标优先级。

maximize() ¶

追加一个数值最大化目标。

多个目标按添加顺序进行字典序比较。

示例

x = model.int(0, 10)
model.maximize(x)  # 寻找尽可能大的 x

参数：

名称	类型	描述	默认
`expression`	`Expression`	要最大化的数值表达式。	必需
`name`	`str`	可选名称，默认为空字符串，不影响求解语义。	`''`

异常：

类型	描述
`TypeError`	`expression` 不是数值表达式。
`ValueError`	`expression` 属于另一个模型。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：支持取决于所有根表达式。OPTX 支持可精确展开的 MILP，另支持显式标量连续凸二次最小化或凹二次最大化目标及线性约束；QP 不允许未固定的整数变量，且只能位于最后目标优先级。

iif() ¶

创建条件表达式：arg1 为真时取 arg2，否则取 arg3。

用于模型条件选择，不能用 Python 的 if 替代。

示例

enabled = model.bool()
cost = model.iif(enabled, 10, 0)  # 启用时为 10，否则为 0

参数：

名称	类型	描述	默认
`arg1`	`IntExpressionLike`	决定分支的布尔表达式或布尔值。	必需
`arg2`	`ExpressionLike`	条件为真时的值或表达式，须与 `arg3` 类型兼容。	必需
`arg3`	`ExpressionLike`	条件为假时的值或表达式，须与 `arg2` 类型兼容。	必需

返回：

类型	描述
`Expression`	条件表达式。

异常：

类型	描述
`TypeError`	条件不是布尔类型，或分支类型不兼容。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：Exact 路径转换布尔逻辑、条件分支及有效性；子表达式必须可转换。OPTX 条件行须可推得有限 Big-M，无法证明界时明确拒绝，不人为指定大数。

min() ¶

创建数值操作数或映射结果的最小值表达式。

示例

result = model.min([8, 3, 5])  # 3

参数：

名称	类型	描述	默认
`*args`	`VariadicExpressionLike`	多个数值操作数、单个可迭代对象，或数据源与映射 Lambda。	`()`

返回：

类型	描述
`Expression`	最小值表达式。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：CPSAT、MATHOPT 通过辅助变量与约束转换；CPSAT 还要求整数值。OPTX 在可证明有限界时用分支选择保持完整等式语义，不依赖目标优化方向。

max() ¶

创建数值操作数或映射结果的最大值表达式。

示例

result = model.max(8, 3, 5)  # 8

参数：

名称	类型	描述	默认
`*args`	`VariadicExpressionLike`	多个数值操作数、单个可迭代对象，或数据源与映射 Lambda。	`()`

返回：

类型	描述
`Expression`	最大值表达式。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：CPSAT、MATHOPT 通过辅助变量与约束转换；CPSAT 还要求整数值。OPTX 在可证明有限界时用分支选择保持完整等式语义，不依赖目标优化方向。

prod() ¶

创建数值操作数或映射结果的乘积表达式。

示例

result = model.prod(2, 3, 4)  # 24

参数：

名称	类型	描述	默认
`*args`	`VariadicExpressionLike`	多个数值操作数、单个可迭代对象，或数据源与映射 Lambda。	`()`

返回：

类型	描述
`Expression`	乘积表达式。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：CPSAT 支持有界整数乘积；MATHOPT 的一般变量乘积需要 GSCIP 或 GUROBI。OPTX 支持常数倍、Bool 或有界 Int 乘有界数值及有限 prod；连续乘积仅在可识别的连续凸 QP 目标中支持，一般双线性约束不支持。

sum() ¶

创建数值操作数或映射结果的求和表达式。

示例

result = model.sum([2, 3, 4])  # 9

参数：

名称	类型	描述	默认
`*args`	`VariadicExpressionLike`	多个数值操作数、单个可迭代对象，或数据源与映射 Lambda。	`()`

返回：

类型	描述
`Expression`	求和表达式。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：CPSAT 要求整数值与整数系数。MATHOPT、OPTX 支持有限集合与符号 Lambda 聚合，受展开限制；OPTX 条件连续贡献须能证明有限界。加减及负号遵循相同限制。

sub() ¶

创建数值差表达式 arg1 - arg2。

示例

x = model.int(0, 10)
result = model.sub(x, 3)  # x - 3

参数：

名称	类型	描述	默认
`arg1`	`ExpressionLike`	被减数表达式或数值。	必需
`arg2`	`ExpressionLike`	减数表达式或数值。	必需

返回：

类型	描述
`Expression`	差值表达式。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：CPSAT 要求整数值与整数系数。MATHOPT、OPTX 支持有限集合与符号 Lambda 聚合，受展开限制；OPTX 条件连续贡献须能证明有限界。加减及负号遵循相同限制。

eq() ¶

创建判断两个兼容表达式是否相等的布尔表达式。

示例

x = model.int(0, 10)
model.add_constraint(model.eq(x, 3))  # x == 3

参数：

名称	类型	描述	默认
`arg1`	`ExpressionLike`	左操作数。	必需
`arg2`	`ExpressionLike`	右操作数。	必需

返回：

类型	描述
`Expression`	判断相等的布尔表达式。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：CPSAT、MATHOPT、OPTX 支持可转换的整数及复合值比较，受有限展开限制。OPTX 保留顶层连续仿射 ==、>=、<=；一般嵌套连续比较仍不支持。

neq() ¶

创建判断两个兼容表达式是否不等的布尔表达式。

示例

x = model.int(0, 10)
model.add_constraint(model.neq(x, 3))  # x != 3

参数：

名称	类型	描述	默认
`arg1`	`ExpressionLike`	左操作数。	必需
`arg2`	`ExpressionLike`	右操作数。	必需

返回：

类型	描述
`Expression`	判断不等的布尔表达式。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：CPSAT、MATHOPT、OPTX 可转换有界整数及受支持复合类型的不等比较；一般连续变量的不等关系不支持。

geq() ¶

创建判断 arg1 是否大于等于 arg2 的布尔表达式。

示例

x = model.int(0, 10)
model.add_constraint(model.geq(x, 3))  # x >= 3

参数：

名称	类型	描述	默认
`arg1`	`ExpressionLike`	左侧数值或布尔操作数；布尔值按 0/1 解释。	必需
`arg2`	`ExpressionLike`	右侧数值或布尔操作数；布尔值按 0/1 解释。	必需

返回：

类型	描述
`Expression`	布尔比较表达式。

异常：

类型	描述
`TypeError`	操作数不支持所请求的大小比较。
`ValueError`	操作数不是有限数值，或表达式属于另一模型。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：CPSAT、MATHOPT、OPTX 支持可转换的整数及复合值比较，受有限展开限制。OPTX 保留顶层连续仿射 ==、>=、<=；一般嵌套连续比较仍不支持。

leq() ¶

创建判断 arg1 是否小于等于 arg2 的布尔表达式。

示例

x = model.int(0, 10)
model.add_constraint(model.leq(x, 3))  # x <= 3

参数：

名称	类型	描述	默认
`arg1`	`ExpressionLike`	左侧数值或布尔操作数；布尔值按 0/1 解释。	必需
`arg2`	`ExpressionLike`	右侧数值或布尔操作数；布尔值按 0/1 解释。	必需

返回：

类型	描述
`Expression`	布尔比较表达式。

异常：

类型	描述
`TypeError`	操作数不支持所请求的大小比较。
`ValueError`	操作数不是有限数值，或表达式属于另一模型。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：CPSAT、MATHOPT、OPTX 支持可转换的整数及复合值比较，受有限展开限制。OPTX 保留顶层连续仿射 ==、>=、<=；一般嵌套连续比较仍不支持。

gt() ¶

创建判断 arg1 是否大于 arg2 的布尔表达式。

示例

x = model.int(0, 10)
model.add_constraint(model.gt(x, 3))  # x > 3

参数：

名称	类型	描述	默认
`arg1`	`ExpressionLike`	左侧数值、布尔或区间操作数；布尔值按 0/1 解释。	必需
`arg2`	`ExpressionLike`	右侧数值、布尔或区间操作数；布尔值按 0/1 解释。	必需

返回：

类型	描述
`Expression`	布尔比较表达式。

异常：

类型	描述
`TypeError`	操作数不支持所请求的大小比较。
`ValueError`	操作数不是有限数值，或表达式属于另一模型。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：Exact 路径的严格比较要求可转换的整数语义，不支持一般连续变量的严格不等式。OPTX 同时支持有限整数比较的布尔化与组合。

lt() ¶

创建判断 arg1 是否小于 arg2 的布尔表达式。

示例

x = model.int(0, 10)
model.add_constraint(model.lt(x, 3))  # x < 3

参数：

名称	类型	描述	默认
`arg1`	`ExpressionLike`	左侧数值、布尔或区间操作数；布尔值按 0/1 解释。	必需
`arg2`	`ExpressionLike`	右侧数值、布尔或区间操作数；布尔值按 0/1 解释。	必需

返回：

类型	描述
`Expression`	布尔比较表达式。

异常：

类型	描述
`TypeError`	操作数不支持所请求的大小比较。
`ValueError`	操作数不是有限数值，或表达式属于另一模型。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：Exact 路径的严格比较要求可转换的整数语义，不支持一般连续变量的严格不等式。OPTX 同时支持有限整数比较的布尔化与组合。

abs() ¶

创建数值表达式的绝对值表达式。

示例

result = model.abs(-3)  # 3

参数：

名称	类型	描述	默认
`arg1`	`ExpressionLike`	数值表达式或数值。	必需

返回：

类型	描述
`Expression`	绝对值表达式。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：CPSAT、MATHOPT 通过辅助变量与约束转换；CPSAT 还要求整数值。OPTX 在可证明有限界时用分支选择保持完整等式语义，不依赖目标优化方向。

dist() ¶

创建两个数值表达式之差的绝对值表达式。

示例

result = model.dist(2, 5)  # |2 - 5| = 3

参数：

名称	类型	描述	默认
`arg1`	`ExpressionLike`	第一个数值表达式或数值。	必需
`arg2`	`ExpressionLike`	第二个数值表达式或数值。	必需

返回：

类型	描述
`Expression`	绝对距离表达式。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：CPSAT、MATHOPT 通过辅助变量与约束转换；CPSAT 还要求整数值。OPTX 在可证明有限界时用分支选择保持完整等式语义，不依赖目标优化方向。

div() ¶

创建两个数值表达式的浮点除法表达式。

求值时除数不能为零；整数输入也可得到小数。

示例

result = model.div(9, 4)  # 2.25

参数：

名称	类型	描述	默认
`arg1`	`ExpressionLike`	被除数表达式或数值。	必需
`arg2`	`ExpressionLike`	除数表达式或数值。	必需

返回：

类型	描述
`Expression`	除法表达式。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：CPSAT 不支持变量除数，常量除数也须满足整数要求。MATHOPT 的变量除数域不能包含零且需要 GSCIP 或 GUROBI。OPTX 支持非零常数及域不含零的有限整数除数，后者要求商有可靠有限界；一般连续变量除数不支持。

mod() ¶

创建 arg1 除以 arg2 的整数余数表达式。

除数不能为零；负数余数采用 C++ 符号规则，可能与 Python 的 % 不同。

示例

result = model.mod(9, 4)  # 1

参数：

名称	类型	描述	默认
`arg1`	`IntExpressionLike`	被除数表达式或数值。	必需
`arg2`	`IntExpressionLike`	除数表达式或数值。	必需

返回：

类型	描述
`Expression`	余数表达式。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：Exact 路径要求可转换的有界整数运算。MATHOPT、OPTX 用小有限域表支持变量整除和取模，零除保留无效性；整除向下取整，余数沿用 C++ 符号规则，不等同 Python 的负数 %。

not_() ¶

创建布尔表达式的逻辑非表达式。

示例

enabled = model.bool()
model.add_constraint(model.not_(enabled))  # 要求 enabled 为 False

参数：

名称	类型	描述	默认
`arg1`	`IntExpressionLike`	布尔表达式或布尔值。	必需

返回：

类型	描述
`Expression`	逻辑非表达式。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：Exact 路径转换布尔逻辑、条件分支及有效性；子表达式必须可转换。OPTX 条件行须可推得有限 Big-M，无法证明界时明确拒绝，不人为指定大数。

and_() ¶

创建布尔操作数或映射结果的逻辑与表达式。

示例

x = model.int(0, 10)
model.add_constraint(model.and_(x >= 2, x <= 5))  # 两个条件都要满足

参数：

名称	类型	描述	默认
`*args`	`VariadicExpressionLike`	多个布尔操作数、单个可迭代对象，或数据源与映射 Lambda。	`()`

返回：

类型	描述
`Expression`	逻辑与表达式。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：Exact 路径转换布尔逻辑、条件分支及有效性；子表达式必须可转换。OPTX 条件行须可推得有限 Big-M，无法证明界时明确拒绝，不人为指定大数。

or_() ¶

创建布尔操作数或映射结果的逻辑或表达式。

示例

x = model.int(0, 10)
model.add_constraint(model.or_(x == 2, x == 5))  # 至少满足一个条件

参数：

名称	类型	描述	默认
`*args`	`VariadicExpressionLike`	多个布尔操作数、单个可迭代对象，或数据源与映射 Lambda。	`()`

返回：

类型	描述
`Expression`	逻辑或表达式。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：Exact 路径转换布尔逻辑、条件分支及有效性；子表达式必须可转换。OPTX 条件行须可推得有限 Big-M，无法证明界时明确拒绝，不人为指定大数。

xor() ¶

创建异或表达式：为真的操作数个数为奇数时结果为真。

两个输入时表示恰好一个为真；多个输入时表示真值数量为奇数。

示例

a, b = model.bool(), model.bool()
model.add_constraint(model.xor(a, b))  # 恰好一个为 True

参数：

名称	类型	描述	默认
`*args`	`VariadicExpressionLike`	多个布尔操作数，或单个操作数可迭代对象。	`()`

返回：

类型	描述
`Expression`	异或表达式。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：Exact 路径转换布尔逻辑、条件分支及有效性；子表达式必须可转换。OPTX 条件行须可推得有限 Big-M，无法证明界时明确拒绝，不人为指定大数。

count() ¶

创建集合、序列、区间或数组的元素数量表达式。

示例

values = model.array([8, 3, 5])
size = model.count(values)  # 3

参数：

名称	类型	描述	默认
`arg1`	`Expression`	集合、序列、数组或区间表达式；lambda 参数在绑定实参后核验容器类型。返回成员数、数组元素数或区间中的整数时间点数。	必需

返回：

类型	描述
`Expression`	整数类型的数量表达式。

异常：

类型	描述
`TypeError`	`arg1` 不是受支持的集合表达式。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：CPSAT、MATHOPT、OPTX 支持有限数组、序列及动态索引，范围与长度须可有界展开；元素及索引表达式也须受支持，保留活动槽与索引有效性。

contains() ¶

创建判断集合或区间是否包含指定元素的布尔表达式。

示例

selected = model.set(3)
model.add_constraint(model.contains(selected, 1))  # 必须选中编号 1

参数：

名称	类型	描述	默认
`arg1`	`Expression`	要检索的集合、序列、区间或数组表达式。	必需
`arg2`	`IntExpressionLike`	要查找的元素或区间。	必需

返回：

类型	描述
`Expression`	判断包含关系的布尔表达式。

异常：

类型	描述
`TypeError`	数据源或元素类型不受支持，或两者不兼容。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：CPSAT、MATHOPT、OPTX 支持有限数组、序列及动态索引，范围与长度须可有界展开；元素及索引表达式也须受支持，保留活动槽与索引有效性。

at() ¶

使用一个或多个整数索引访问序列或数组。

索引应在有效范围内。需要越界默认值时，使用 expression.at(index, default=...)。

示例

values = model.array([8, 3, 5])
result = model.at(values, 1)  # 3，下标从 0 开始

参数：

名称	类型	描述	默认
`arg1`	`Expression`	待访问的序列或数组表达式；lambda 参数在绑定实参后核验类型和维度。	必需
`*args`	`IntExpressionLike`	从 0 开始的整数索引，可以是表达式；多维数组按维度顺序传入。	`()`

返回：

类型	描述
`Expression`	索引对应的元素或子数组表达式。

异常：

类型	描述
`TypeError`	数据源不支持索引，或索引不是整数。
`ValueError`	索引数量与数据源维度不匹配。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：CPSAT、MATHOPT、OPTX 支持有限数组、序列及动态索引，范围与长度须可有界展开；元素及索引表达式也须受支持，保留活动槽与索引有效性。

array() ¶

从值创建数组表达式，或通过 Lambda 映射数据源生成数组。

数组可包含重复元素，不会自动创建决策变量。

示例

values = model.array([8, 3, 8])  # 固定数组，允许重复元素

参数：

名称	类型	描述	默认
`*args`	`ArrayVariadicExpressionLike`	多个位置参数值、单个嵌套可迭代对象，或数据源、映射 Lambda 与可选默认值。	`()`

返回：

类型	描述
`Expression`	由常量、表达式元素或 Lambda 生成的数组表达式。

异常：

类型	描述
`TypeError`	成员类型不兼容，或值不受支持。
`ValueError`	数组为空，或维度不兼容。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：CPSAT、MATHOPT、OPTX 支持有限数组、序列及动态索引，范围与长度须可有界展开；元素及索引表达式也须受支持，保留活动槽与索引有效性。

range() ¶

创建左闭右开的整数范围表达式。

示例

values = model.range(2, 5)  # [2, 3, 4]，不包含终点 5

参数：

名称	类型	描述	默认
`arg1`	`IntExpressionLike`	省略 `arg2` 时表示不包含的终点；否则表示包含的起点。	必需
`arg2`	`typing.Optional[IntExpressionLike]`	可选终点，不包含该值。	`None`

返回：

类型	描述
`Expression`	序列类型的范围表达式。

异常：

类型	描述
`TypeError`	任一边界不是整数表达式。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：CPSAT、MATHOPT、OPTX 支持有限数组、序列及动态索引，范围与长度须可有界展开；元素及索引表达式也须受支持，保留活动槽与索引有效性。

index() ¶

创建查找整数在序列表达式中位置的表达式。

下标从 0 开始；未找到时返回 -1。

示例

route = model.list(3)
model.add_constraint(model.index(route, 2) == 0)  # 编号 2 排在首位

参数：

名称	类型	描述	默认
`arg1`	`Expression`	要查找的序列表达式；lambda 参数在绑定实参后核验序列类型。	必需
`arg2`	`IntExpressionLike`	要定位的整数编号或整数表达式。	必需

返回：

类型	描述
`Expression`	整数位置表达式。

异常：

类型	描述
`TypeError`	数据源不是序列，或元素不是整数。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：CPSAT、MATHOPT、OPTX 支持有限数组、序列及动态索引，范围与长度须可有界展开；元素及索引表达式也须受支持，保留活动槽与索引有效性。

union() ¶

创建包含任一输入中所有成员的并集表达式，重复成员只保留一次。

返回无序集合，不自动添加约束；无输入时返回空集。

示例

a = model.constant({0, 1})
b = model.constant({1, 2})
result = model.union(a, b)  # {0, 1, 2}

参数：

名称	类型	描述	默认
`*args`	`VariadicExpression`	同一模型的集合、序列或整数数组表达式，可混用。传 `a, b` 或 `[a, b]` 均可；原始集合须先用 `constant` 转换。	`()`

返回：

类型	描述
`Expression`	集合类型的并集表达式；求解得到可行解后 `.value` 为 Python 集合。

异常：

类型	描述
`TypeError`	操作数不是支持的表达式类型，例如传入整数或区间。
`ValueError`	操作数属于其他模型。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：CPSAT、MATHOPT、OPTX 支持有限域中的关系与集合展开，受辅助变量和展开规模限制；区间交集需要可转换的整数边界。

intersection() ¶

创建所有输入共有成员的交集表达式；全部输入为区间时，创建交叠区间表达式。

无公共成员时返回空集；无输入时报错。全部输入为区间时返回交叠区间。

示例

a = model.constant({0, 1})
b = model.constant({1, 2})
result = model.intersection(a, b)  # {1}

参数：

名称	类型	描述	默认
`*args`	`VariadicExpression`	至少一个同一模型的集合、序列或整数数组表达式，可混用；也可全部为区间。支持 `a, b` 或 `[a, b]`，区间不可与集合混用。	`()`

返回：

类型	描述
`Expression`	集合输入返回集合类型的表达式；全部为区间输入时返回区间类型的表达式。

异常：

类型	描述
`TypeError`	操作数类型不受支持，或把区间与集合类表达式混合输入。
`ValueError`	未提供任何输入，或操作数属于其他模型。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：CPSAT、MATHOPT、OPTX 支持有限域中的关系与集合展开，受辅助变量和展开规模限制；区间交集需要可转换的整数边界。

distinct() ¶

创建包含数据源中不同整数值的集合表达式；也可先用 Lambda 生成去重键。

返回去重后的集合，不是判断是否重复的布尔值。

示例

values = model.array([2, 1, 2])
result = model.distinct(values)  # 集合 {1, 2}

参数：

名称	类型	描述	默认
`arg1`	`Expression`	整数数组表达式；带 Lambda 时也接受集合、序列或区间数据源。	必需
`arg2`	`typing.Optional[Expression]`	可选的模型 Lambda，用于生成去重键。	`None`

返回：

类型	描述
`Expression`	去重后的集合表达式，而不是布尔表达式。

异常：

类型	描述
`TypeError`	数据源不可迭代，或 `arg2` 不是有效的 Lambda。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：CPSAT、MATHOPT、OPTX 支持有限数组、序列及动态索引，范围与长度须可有界展开；元素及索引表达式也须受支持，保留活动槽与索引有效性。

sort() ¶

创建按值或 Lambda 排序键排序后的数组表达式。

升序排列，保留重复成员，不改变原数据。

示例

values = model.array([3, 1, 3])
result = model.sort(values)  # [1, 3, 3]

参数：

名称	类型	描述	默认
`array`	`Expression`	要排序的数组表达式。	必需
`func`	`typing.Optional[Expression]`	可选 Lambda，用于生成排序键。	`None`

返回：

类型	描述
`Expression`	排序后的数组表达式。

异常：

类型	描述
`TypeError`	数据源不是数组，或 `func` 不是有效的 Lambda。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：CPSAT、MATHOPT、OPTX 支持有限数组、序列及动态索引，范围与长度须可有界展开；元素及索引表达式也须受支持，保留活动槽与索引有效性。

find() ¶

创建查找成员首次归属哪个子集合的索引表达式。

返回第一个包含该成员的子集合下标，从 0 开始；未找到时返回 -1。

示例

groups = model.array([model.constant({0}), model.constant({1, 2})])
result = model.find(groups, 2)  # 1：编号 2 位于第二个集合

参数：

名称	类型	描述	默认
`arg1`	`Expression`	由集合或序列表达式组成的模型数组，如 `model.array([a, b])`。	必需
`arg2`	`IntExpressionLike`	要查找的整数编号或整数表达式。	必需

返回：

类型	描述
`Expression`	包含该成员的第一个子集合的零基下标表达式；未找到时为 -1。

异常：

类型	描述
`TypeError`	数据源不受支持，或元素不是整数。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：CPSAT、MATHOPT、OPTX 支持有限数组、序列及动态索引，范围与长度须可有界展开；元素及索引表达式也须受支持，保留活动槽与索引有效性。

partition() ¶

判断共同全集中的每个成员是否恰好出现在一个分组中。

例如全集 {0, 1, 2} 可划分为 {0} 和 {1, 2}；不能遗漏或跨组重复。返回布尔表达式，需传给 add_constraint 才生效。

示例

a, b = model.set(3), model.set(3)
model.add_constraint(model.partition(a, b))  # 0、1、2 各分配一次

参数：

名称	类型	描述	默认
`*args`	`VariadicExpression`	至少一个同一模型的决策变量，须全部为 `set` 或全部为 `list`，且 `universe_size` 相同、变量不重复。支持 `a, b`、`[a, b]` 或直接构造的 `model.array([a, b])`；不接受常量或派生集合。	`()`

返回：

类型	描述
`Expression`	布尔表达式，表示每个可选成员恰好归属一组；不会自动加入模型约束。

异常：

类型	描述
`TypeError`	成员不是集合或序列决策变量，或混用了集合和序列。
`ValueError`	未提供变量、重复传入同一变量、全集大小不同，或变量属于其他模型。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：CPSAT、MATHOPT、OPTX 支持有限域中的关系与集合展开，受辅助变量和展开规模限制；区间交集需要可转换的整数边界。

disjoint() ¶

判断共同全集中的每个成员是否最多出现在一个分组中，允许成员不被选择。

允许遗漏成员，例如 {0} 和 {2}；不能跨组重复。返回布尔表达式，需传给 add_constraint 才生效。

示例

a, b = model.set(3), model.set(3)
model.add_constraint(model.disjoint(a, b))  # 每个编号最多分配一次

参数：

名称	类型	描述	默认
`*args`	`VariadicExpression`	至少一个同一模型的决策变量，须全部为 `set` 或全部为 `list`，且 `universe_size` 相同、变量不重复。支持 `a, b`、`[a, b]` 或直接构造的 `model.array([a, b])`；不接受常量或派生集合。	`()`

返回：

类型	描述
`Expression`	布尔表达式，表示每个可选成员最多归属一组；不会自动加入模型约束。

异常：

类型	描述
`TypeError`	成员不是集合或序列决策变量，或混用了集合和序列。
`ValueError`	未提供变量、重复传入同一变量、全集大小不同，或变量属于其他模型。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：CPSAT、MATHOPT、OPTX 支持有限域中的关系与集合展开，受辅助变量和展开规模限制；区间交集需要可转换的整数边界。

cover() ¶

判断共同全集中的每个成员是否至少出现在一个分组中，允许跨组重复。

允许跨组重复，例如 {0, 1} 和 {1, 2} 覆盖全集 {0, 1, 2}。返回布尔表达式，需传给 add_constraint 才生效。

示例

a, b = model.set(3), model.set(3)
model.add_constraint(model.cover(a, b))  # 每个编号至少分配一次

参数：

名称	类型	描述	默认
`*args`	`VariadicExpression`	至少一个同一模型的决策变量，须全部为 `set` 或全部为 `list`，且 `universe_size` 相同、变量不重复。支持 `a, b`、`[a, b]` 或直接构造的 `model.array([a, b])`；不接受常量或派生集合。	`()`

返回：

类型	描述
`Expression`	布尔表达式，表示每个可选成员至少归属一组；不会自动加入模型约束。

异常：

类型	描述
`TypeError`	成员不是集合或序列决策变量，或混用了集合和序列。
`ValueError`	未提供变量、重复传入同一变量、全集大小不同，或变量属于其他模型。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：CPSAT、MATHOPT、OPTX 支持有限域中的关系与集合展开，受辅助变量和展开规模限制；区间交集需要可转换的整数边界。

hull() ¶

创建包含所有给定区间的最小区间表达式。

区间之间的空隙也包含在结果中；缺席区间不扩大结果范围。

示例

a, b = model.interval(0, 10), model.interval(0, 10)
span = model.hull(a, b)  # 同时包含 a、b 的最小区间

参数：

名称	类型	描述	默认
`*args`	`VariadicExpression`	多个区间表达式，或单个区间可迭代对象。	`()`

返回：

类型	描述
`Expression`	包围所有输入区间的区间表达式。

异常：

类型	描述
`TypeError`	某个操作数不是区间表达式。
`ValueError`	未提供任何区间。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：CPSAT、MATHOPT、OPTX 支持可有界展开的整数区间及其存在性语义，子表达式也须可转换；缺席区间的属性有效性按源模型保留。

step_array() ¶

将断点数组与取值数组展开为分段常量数组。

各断点为对应段的独占终点，末断点决定输出数组长度。

示例

ends = model.array([2, 5])
values = model.array([10, 20])
result = model.step_array(ends, values)  # [10, 10, 20, 20, 20]

参数：

名称	类型	描述	默认
`array1`	`Expression`	由严格递增的正断点组成的常量数组。	必需
`array2`	`Expression`	常量数组，每个断点对应一个取值。	必需

返回：

类型	描述
`Expression`	已展开的分段常量数组表达式。

异常：

类型	描述
`TypeError`	操作数不是相互兼容的一维常量数组。
`ValueError`	数组为空、长度不同、断点无效，或结果超过展开规模上限。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：Exact 路径要求断点为常量，输出与查询表达式可转换，且受有限展开规模限制。CPSAT 还要求整数值；OPTX 条件行须有可靠有限界。

sqrt() ¶

创建数值表达式的平方根表达式。

示例

result = model.sqrt(9)  # 3.0

参数：

名称	类型	描述	默认
`arg1`	`ExpressionLike`	数值或数值表达式，求值时必须非负。	必需

返回：

类型	描述
`Expression`	浮点平方根表达式。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：CPSAT 仅可处理固定值或小有限整数域，结果须可按整数表示。MATHOPT 可通过 GSCIP 或 GUROBI 二次约束转换非负输入。OPTX 支持常量及小有限整数输入表，允许浮点输出；一般连续 sqrt 不支持。

sin() ¶

创建正弦表达式，输入以弧度为单位。

示例

result = model.sin(0.0)  # 0.0

参数：

名称	类型	描述	默认
`arg1`	`ExpressionLike`	以弧度为单位的数值表达式或数值。	必需

返回：

类型	描述
`Expression`	浮点正弦表达式。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：CPSAT、MATHOPT、OPTX 仅处理固定值或小有限整数输入域，不支持一般连续输入。OPTX 允许表输出为浮点数，但须满足系数安全范围；CPSAT 还要求结果可按整数表示。

cos() ¶

创建余弦表达式，输入以弧度为单位。

示例

result = model.cos(0.0)  # 1.0

参数：

名称	类型	描述	默认
`arg1`	`ExpressionLike`	以弧度为单位的数值表达式或数值。	必需

返回：

类型	描述
`Expression`	浮点余弦表达式。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：CPSAT、MATHOPT、OPTX 仅处理固定值或小有限整数输入域，不支持一般连续输入。OPTX 允许表输出为浮点数，但须满足系数安全范围；CPSAT 还要求结果可按整数表示。

round() ¶

创建将数值舍入为整数的表达式。

中点向远离零的方向舍入，与 Python 的 round 不同。

示例

result = model.round(2.5)  # 3

参数：

名称	类型	描述	默认
`arg1`	`ExpressionLike`	数值表达式或数值。	必需

返回：

类型	描述
`Expression`	舍入后的整数表达式。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：Exact 路径支持整数输入的恒等转换及固定输入；不支持一般连续变量输入的取整。CPSAT 仍要求编译中间值为整数。

ceil() ¶

创建向上取整表达式，即大于等于输入的最小整数。

示例

result = model.ceil(2.1)  # 3

参数：

名称	类型	描述	默认
`arg1`	`ExpressionLike`	数值表达式或数值。	必需

返回：

类型	描述
`Expression`	向上取整后的整数表达式。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：Exact 路径支持整数输入的恒等转换及固定输入；不支持一般连续变量输入的取整。CPSAT 仍要求编译中间值为整数。

floor() ¶

创建向下取整表达式，即小于等于输入的最大整数。

示例

result = model.floor(-2.1)  # -3

参数：

名称	类型	描述	默认
`arg1`	`ExpressionLike`	数值表达式或数值。	必需

返回：

类型	描述
`Expression`	向下取整后的整数表达式。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：Exact 路径支持整数输入的恒等转换及固定输入；不支持一般连续变量输入的取整。CPSAT 仍要求编译中间值为整数。

log() ¶

创建数值表达式的自然对数表达式。

示例

result = model.log(1.0)  # 0.0

参数：

名称	类型	描述	默认
`arg1`	`ExpressionLike`	数值或数值表达式，求值时必须大于零。	必需

返回：

类型	描述
`Expression`	浮点对数表达式。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：CPSAT、MATHOPT、OPTX 仅处理固定值或小有限整数输入域，不支持一般连续输入。OPTX 允许表输出为浮点数，但须满足系数安全范围；CPSAT 还要求结果可按整数表示。

exp() ¶

创建以自然常数 e 为底的指数表达式。

示例

result = model.exp(0.0)  # 1.0

参数：

名称	类型	描述	默认
`arg1`	`ExpressionLike`	数值指数表达式或数值。	必需

返回：

类型	描述
`Expression`	浮点指数表达式。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：CPSAT、MATHOPT、OPTX 仅处理固定值或小有限整数输入域，不支持一般连续输入。OPTX 允许表输出为浮点数，但须满足系数安全范围；CPSAT 还要求结果可按整数表示。

pow() ¶

创建幂表达式，结果类型为浮点数。

示例

result = model.pow(2, 3)  # 8.0

参数：

名称	类型	描述	默认
`arg1`	`ExpressionLike`	数值底数表达式或数值。	必需
`arg2`	`ExpressionLike`	数值指数表达式或数值。	必需

返回：

类型	描述
`Expression`	浮点幂表达式。

异常：

类型	描述
`TypeError`	任一操作数不是数值类型。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：Exact 路径要求固定指数。OPTX 支持常量、0/1 次幂及受限有限整数域幂，连续平方可进入显式连续凸 QP 目标；一般连续高次幂关系不支持。CPSAT 还要求整数值，MATHOPT 的非线性乘积需要 GSCIP 或 GUROBI。

start() ¶

获取区间起点表达式。

等价于 task.start；可选任务缺席时没有可用的起点值。

示例

task = model.interval(0, 10)
model.add_constraint(model.start(task) >= 2)  # 不早于时间 2 开始

参数：

名称	类型	描述	默认
`interval`	`Expression`	要读取属性的区间表达式。	必需

返回：

类型	描述
`Expression`	整数起点表达式。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：CPSAT、MATHOPT、OPTX 支持可有界展开的整数区间及其存在性语义，子表达式也须可转换；缺席区间的属性有效性按源模型保留。

end() ¶

获取区间终点表达式。

等价于 task.end；终点不包含在区间内，可选任务缺席时没有可用的终点值。

示例

task = model.interval(0, 10)
model.add_constraint(model.end(task) <= 8)  # 不晚于时间 8 完成

参数：

名称	类型	描述	默认
`interval`	`Expression`	要读取属性的区间表达式。	必需

返回：

类型	描述
`Expression`	整数终点表达式。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：CPSAT、MATHOPT、OPTX 支持可有界展开的整数区间及其存在性语义，子表达式也须可转换；缺席区间的属性有效性按源模型保留。

length() ¶

获取区间长度表达式。

区间存在时等于 end - start，也可使用 task.length。

示例

task = model.interval(0, 10)
model.add_constraint(model.length(task) == 3)  # 持续时间为 3

参数：

名称	类型	描述	默认
`interval`	`Expression`	要读取属性的区间表达式。	必需

返回：

类型	描述
`Expression`	整数长度表达式。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：CPSAT、MATHOPT、OPTX 支持可有界展开的整数区间及其存在性语义，子表达式也须可转换；缺席区间的属性有效性按源模型保留。

presence() ¶

创建判断可选区间是否存在的布尔表达式。

必选区间始终存在；可选区间可能缺席。

示例

task = model.optional_interval(0, 10)
exists = model.presence(task)  # 存在时为 True，缺席时为 False

参数：

名称	类型	描述	默认
`interval`	`Expression`	要读取属性的区间表达式。	必需

返回：

类型	描述
`Expression`	表示区间是否存在的布尔表达式。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：CPSAT、MATHOPT、OPTX 支持可有界展开的整数区间及其存在性语义，子表达式也须可转换；缺席区间的属性有效性按源模型保留。

create_int_external_function() ¶

注册返回单个整数的外部回调函数。

注册后调用返回的函数生成表达式；Python 回调在求解评价时执行。

示例

square = model.create_int_external_function(lambda args: args[0] ** 2)
result = square(3)  # 9

参数：

名称	类型	描述	默认
`func`	`typing.Callable[..., IntLike]`	接收单个只读外部参数容器的回调函数。	必需

返回：

类型	描述
`ExternalFunction`	已注册的整数外部函数。

异常：

类型	描述
`TypeError`	`func` 不是可检查签名的单参数可调用对象。

求解器支持：

SEARCH：支持
CPSAT：不支持
MATHOPT：不支持
OPTX：不支持
说明：外部回调可由 SEARCH 求值。CPSAT、MATHOPT、OPTX 无法把任意回调转换成约束；仅注册但未调用回调，不代表该后端支持回调。

create_double_external_function() ¶

注册返回单个浮点数的外部回调函数。

注册后调用返回的函数生成表达式；Python 回调在求解评价时执行。

示例

half = model.create_double_external_function(lambda args: args[0] / 2.0)
result = half(3)  # 1.5

参数：

名称	类型	描述	默认
`func`	`typing.Callable[..., NumberLike]`	接收单个只读外部参数容器的回调函数。	必需
`grad`	`typing.Optional[typing.Callable[..., typing.Iterable[NumberLike]]]`	可选梯度回调，为每个参数返回一个梯度分量。保留兼容，当前搜索算法不使用它。	`None`

返回：

类型	描述
`ExternalFunction`	已注册的浮点外部函数。

异常：

类型	描述
`TypeError`	任一回调不是可检查签名的单参数可调用对象。

求解器支持：

SEARCH：支持
CPSAT：不支持
MATHOPT：不支持
OPTX：不支持
说明：外部回调可由 SEARCH 求值。CPSAT、MATHOPT、OPTX 无法把任意回调转换成约束；仅注册但未调用回调，不代表该后端支持回调。

create_int_array_external_function() ¶

注册返回整数可迭代对象的外部回调函数。

注册后调用返回的函数生成表达式；Python 回调在求解评价时执行。

示例

pair = model.create_int_array_external_function(lambda args: [args[0], args[0] + 1])
result = pair(3)  # [3, 4]

参数：

名称	类型	描述	默认
`func`	`typing.Callable[..., typing.Iterable[IntLike]]`	接收单个只读外部参数容器的回调函数。	必需

返回：

类型	描述
`ExternalFunction`	已注册的整数数组外部函数。

异常：

类型	描述
`TypeError`	`func` 不是可检查签名的单参数可调用对象。

求解器支持：

SEARCH：支持
CPSAT：不支持
MATHOPT：不支持
OPTX：不支持
说明：外部回调可由 SEARCH 求值。CPSAT、MATHOPT、OPTX 无法把任意回调转换成约束；仅注册但未调用回调，不代表该后端支持回调。

create_double_array_external_function() ¶

注册返回数值可迭代对象的外部回调函数。

注册后调用返回的函数生成表达式；Python 回调在求解评价时执行。

示例

pair = model.create_double_array_external_function(lambda args: [args[0] / 2.0, args[0] / 4.0])
result = pair(4)  # [2.0, 1.0]

参数：

名称	类型	描述	默认
`func`	`typing.Callable[..., typing.Iterable[NumberLike]]`	接收单个只读外部参数容器的回调函数。	必需

返回：

类型	描述
`ExternalFunction`	已注册的浮点数组外部函数。

异常：

类型	描述
`TypeError`	`func` 不是可检查签名的单参数可调用对象。

求解器支持：

SEARCH：支持
CPSAT：不支持
MATHOPT：不支持
OPTX：不支持
说明：外部回调可由 SEARCH 求值。CPSAT、MATHOPT、OPTX 无法把任意回调转换成约束；仅注册但未调用回调，不代表该后端支持回调。

call() ¶

调用模型 Lambda 或已注册的外部函数。

第一个参数为模型 Lambda 或已注册外部函数，后续参数是其调用实参。

示例

square = model.lambda_function(lambda x: x * x)
result = model.call(square, 3)  # 9

参数：

名称	类型	描述	默认
`*args`	`ExpressionLike`	第一个参数为函数，后接多个操作数或单个操作数可迭代对象。	`()`

返回：

类型	描述
`Expression`	Lambda 或外部函数的调用表达式。

异常：

类型	描述
`TypeError`	第一个参数不是可调用的模型对象。
`ValueError`	缺少参数，或参数属于另一个模型。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：CPSAT、MATHOPT、OPTX 可展开符号 Lambda，其函数体、参数及展开规模必须满足转换限制；call 调用外部回调不支持。OPTX 原生 QP 目标暂要求显式标量展开。

piecewise() ¶

创建分段线性函数在 arg3 处的取值表达式。

示例

points = model.array([0, 10])
values = model.array([0, 100])
result = model.piecewise(points, values, 5)  # 线性插值得到 50.0

参数：

名称	类型	描述	默认
`arg1`	`Expression`	至少两个非递减横坐标断点组成的常量数组。	必需
`arg2`	`Expression`	对应的函数值常量数组，长度须与 `arg1` 相同。	必需
`arg3`	`ExpressionLike`	查询位置的数值或表达式；建议位于断点范围内。	必需

返回：

类型	描述
`Expression`	浮点插值结果表达式。

异常：

类型	描述
`TypeError`	数组或查询值的类型不受支持。
`ValueError`	数组长度无效，或断点顺序不正确。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：Exact 路径仅支持可转换的分段表达式；连续插值要求常量且严格递增的断点，并覆盖整个查询域。CPSAT 还要求整数值与系数；OPTX 用有限分支线性等式编码，须通过数值与展开预算检查。

lambda_function() ¶

通过 Python 可调用对象构建可复用的模型 Lambda。

建模时用符号参数执行 Python 函数，保存其表达式；不是求值时运行的 Python 回调。

示例

square = model.lambda_function(lambda x: x * x)
result = model.call(square, 3)  # 9

参数：

名称	类型	描述	默认
`func`	`typing.Callable[..., Expression]`	立即使用符号参数调用的 Python 可调用对象，用于构建 Lambda 函数体。	必需

返回：

类型	描述
`Expression`	可复用的 Lambda 表达式。

异常：

类型	描述
`TypeError`	回调不受支持，或构建函数体时失败。
`ValueError`	函数体捕获了未声明的 Lambda 参数。

求解器支持：

SEARCH：支持
CPSAT：条件支持
MATHOPT：条件支持
OPTX：条件支持
说明：CPSAT、MATHOPT、OPTX 可展开符号 Lambda，其函数体、参数及展开规模必须满足转换限制；call 调用外部回调不支持。OPTX 原生 QP 目标暂要求显式标量展开。

save() ¶

保存模型为 protobuf 文件，可选择 gzip 压缩。

保留表达式图、变量域、名称、目标顺序和声明初值，不保存求解结果或 Python 代码。保存不会使当前解值失效；用 read_model(path) 读取后可继续编辑和求解。 .pb.gz 使用 gzip 级别 6，.pb 保存未压缩内容。写入成功后才替换已有文件。

参数：

名称	类型	描述	默认
`path`	`str \| os.PathLike[str]`	目标文件的字符串或路径对象，后缀为 .pb 或 .pb.gz，不区分大小写，父目录必须存在。	必需

异常：

类型	描述
`TypeError`	路径或模型数据类型错误。
`ValueError`	后缀或模型数据无效，或模型含有无法恢复的外部 Python 回调。
`OSError`	目标无法写入或替换。

示例：

>>> model.save("model.pb.gz")

solve() ¶

使用本地搜索求解器求解模型。

选项按名称传入；先检查 solution.feasible，再读取 .value。修改模型后旧值失效。

示例

x = model.int(0, 10)
model.minimize(x)
solution = model.solve(time_limit_s=1.0)
if solution.feasible:
    print(x.value)

参数：

名称	类型	描述	默认
`time_limit_s`	`float`	正的有限实际时间上限，单位为秒。	`30.0`
`objective_threshold`	`Mapping[int, int \| float] \| None`	可选的目标索引到阈值的映射。	`None`
`log_level`	`str`	求解日志模式：`"off"`、`"on"` 或 `"debug"`。	`'on'`
`external_evaluation_limit`	`int \| None`	可选的外部回调实际启动次数上限，必须为正整数；失败计入，已知结果和复用不额外计费。	`None`
`memory_limit_bytes`	`int \| None`	可选的管理内存字节上限，必须为正整数且不超过 `sys.maxsize`。默认 `None` 根据系统和容器余量自动管理；覆盖搜索工作区、候选和算法存储。这是协作式目标，不是进程总内存上限；系统压力可能降低实际生效目标。	`None`
`deterministic`	`bool`	默认 `True` 使用有序并行搜索；`False` 切回吞吐模式。相同输入、种子、算法配置、运行版本和评价预算在正常完成时复现相同结果。时间、取消或资源压力导致提前结束时不保证相同终态。暂不支持外部回调及依赖时间预算的 HiGHS 搜索路径。	`True`
`evaluation_limit`	`int \| None`	可选的正整数搜索评价上限，包含内部试算，不包含初始化。	`None`
`random_seed`	`int`	随机种子，整数，范围为 `0` 到 `2**64 - 1`。	`1`
`worker_threads`	`int \| None`	可选的正整数物理线程数，最大为 `1024`；默认采用机器报告的硬件并发数。	`None`

返回：

类型	描述
`'Solution'`	搜索结束时的求解结果。

异常：

类型	描述
`TypeError`	选项类型无效。
`ValueError`	选项值超出允许范围，或已知评价点的结果冲突。
`RuntimeError`	本地搜索内核不可用。
`LicenseError`	内核拒绝当前许可证。

求解器支持：

SEARCH：求解入口
说明：此方法选择 SEARCH 求解路径；模型中各接口的支持条件仍适用。

solve_optx() ¶

通过 OptX / HiGHS 路径求解模型。

不支持的模型会报错，不自动退回本地搜索；读取 .value 前检查 solution.feasible。

对于以整数变量为主的大型 MIP 模型，可设置 parallel="on" 尝试缩短求解时间，效果取决于模型和机器。不指定 threads 时由 HiGHS 自动选择线程数，并可能复用已有线程池。其他选项沿用默认值，包括 30 秒时间限制。并行 MIP 搜索需要后端实际可用线程数大于 1。

示例

x = model.int(0, 10)
model.minimize(x)
solution = model.solve_optx()

按需启用并行 MIP 搜索：

from optagent import OptxConfig

solution = model.solve_optx(config=OptxConfig(parallel="on"))

参数：

名称	类型	描述	默认
`config`	`Any \| None`	可选的 OptX 求解配置。	`None`
`objective_threshold`	`Mapping[int, int \| float] \| None`	可选的目标索引到阈值的映射。	`None`

返回：

类型	描述
`'Solution'`	HiGHS 结束时的求解结果。

异常：

类型	描述
`TypeError`	配置或阈值选项类型无效。
`OptxUnsupportedError`	模型包含不受支持的表达式。
`ValueError`	配置或阈值无效。
`RuntimeError`	本地 OptX 桥接不可用，或候选未通过原模型验证；验证失败详情见异常的 `diagnostics`。
`LicenseError`	内核拒绝当前许可证。

求解器支持：

OPTX：求解入口
说明：此方法选择 OPTX 求解路径；模型中各接口的支持条件仍适用。

solve_cpsat() ¶

通过 OR-Tools CP-SAT 路径求解模型。

需安装 OR-Tools。选项按名称传入；读取 .value 前检查 solution.feasible。

示例

x = model.int(0, 10)
model.minimize(x)
solution = model.solve_cpsat(time_limit_s=10.0)

参数：

名称	类型	描述	默认
`**kwargs`	`Any`	按名称传入：`config` 为可选 `CpSatConfig`；`time_limit_s` 为正数秒数，覆盖配置中的时间限制，均未指定时默认 30 秒。不接受 `objective_threshold`。	`{}`

返回：

类型	描述
`'Solution'`	CP-SAT 结束时的求解结果。

求解器支持：

CPSAT：求解入口
说明：此方法选择 CPSAT 求解路径；模型中各接口的支持条件仍适用。

solve_mathopt() ¶

通过 OR-Tools MathOpt 路径求解模型。

需安装 OR-Tools，且所选后端可用。选项按名称传入；读取 .value 前检查 solution.feasible。

示例

x = model.int(0, 10)
model.minimize(x)
solution = model.solve_mathopt(time_limit_s=10.0)

参数：

名称	类型	描述	默认
`**kwargs`	`Any`	按名称传入：`config` 为可选 `MathOptConfig`（默认后端 GSCIP）；`time_limit_s` 为正数秒数，覆盖配置中的时间限制，均未指定时默认 30 秒。不接受 `objective_threshold`。	`{}`

返回：

类型	描述
`'Solution'`	MathOpt 结束时的求解结果。

求解器支持：

MATHOPT：求解入口
说明：此方法选择 MATHOPT 求解路径；模型中各接口的支持条件仍适用。

跨接口的求解路径选择与限制对照见求解器支持矩阵。