结果与诊断¶
solve()、solve_heuristic() 和 solve_optx() 都返回 Solution。先检查是否有可行解，再读取变量和派生表达式的值。
安全读取结果¶
from optagent import OptModel
model = OptModel()
x = model.int(0, 10)
cost = 2 * x
model.constraint(x >= 3)
model.minimize(cost)
solution = model.solve(time_limit_s=1.0, log_level="off")
print(solution.status, solution.solver_name)
if solution.feasible:
print(solution.objectives)
print(x.value, cost.value)
else:
print(solution.diagnostics)
| 字段 | 如何使用 |
|---|---|
feasible |
是否取得可行赋值；不能用 False 单独判断无解 |
objectives |
按模型声明顺序排列的目标值元组 |
status |
本次求解状态；unknown、deadline 等停止状态不能单独证明模型无解 |
solver_name |
求解入口标识：混合求解为 hybrid，启发式求解为 heuristic，精确求解为 optx；精确后端记录在 diagnostics["backend"] 中 |
diagnostics |
路径相关的诊断字典；用 .get() 读取可选字段 |
best_bound |
精确后端报告的目标值界限；不可用时为 None，须结合下方的后端说明理解 |
gap |
当前由 HiGHS 提供的单目标相对间隙比值，0.001 表示 0.1%；不可用时为 None |
solve_time |
当前由 HiGHS 提供的后端搜索秒数，包含重试；不可用时为 None |
best_bound 对最小化目标是下界，对最大化目标是上界，描述后端所求解问题的界限，不能单独作为原模型的最优性证明。
HiGHS 的数值修正可能使最终 objectives 与后端候选目标不同；多目标的分阶段指标通过
diagnostics["backend_attempts"] 查询，此时便捷属性 best_bound 和 gap 为 None。
CP-SAT 也可提供 best_bound，取最近一次后端搜索的界限；多目标时仅对应当时处理的目标，不能视为整个多目标问题的界限。
CP-SAT 当前不填充 gap 和 solve_time。混合和启发式求解当前不填充这三个便捷属性。
solve_time 不含模型转换与结果校验，完整调用耗时可由业务端计时。
交互式 session.finish() 也返回 Solution，当前 solver_name 为 search；与上表三个一次性入口的标识分开处理。
OptX 的结论与后端信息¶
status、feasible 和 objectives 给出 OptAgent 本次求解的最终结论。
后端信息保留在 diagnostics 中，可按需查询，无需调用者另行选择验证层级：
print(solution.status, solution.feasible, solution.objectives)
print(solution.diagnostics.get("backend")) # highs 或 cp_sat
print(solution.diagnostics.get("backend_status"))
backend_status 是后端最后一次运行的原始状态。HiGHS 通过 backend_attempts 逐次记录目标、界限、间隙、耗时及有效数值参数；CP-SAT 的阶段统计位于 cp_sat。
原始状态用于排查问题；业务代码应依据公开的 status 与 feasible 处理最终结果。参数说明见求解与配置。
无值、超时与取消¶
未求解或模型变更后读取 .value 会抛出 RuntimeError。重新求解会清除旧值，因此应在变更或下一次求解前，将所需数值复制到业务数据结构。
混合和启发式求解可能在时间耗尽时返回 deadline，外部评价取消时返回 cancelled。精确求解在没有可交付的可行解时，可能返回 unknown 或 resource_limit。这些停止状态不能视为不可行证明；只有明确返回 infeasible 才表示已确认模型无解。
定位耗时阶段¶
| 路径 | 诊断字段 | 单位 / 含义 |
|---|---|---|
| 混合求解 | python_serialize_ns |
Python 序列化纳秒数 |
| 混合求解 | python_wire_bytes |
序列化载荷字节数 |
| 混合求解 | python_expression_count |
表达式数量 |
| 启发式及精确求解 | total_wall_time_s |
本次调用累计耗时，单位秒；早期停止时可能缺失 |
| HiGHS | backend_attempts |
各次后端运行记录，solve_time_s 以秒为单位 |
| CP-SAT | cp_sat |
编译、原生搜索和验证等统计；耗时字段以 _ns 结尾，单位纳秒 |
| 各入口 | termination_reason |
可选的具体停止原因 |
诊断字段取决于执行到达的阶段。业务控制流优先依赖 feasible 和公开结果字段，不要要求每次返回都带有相同的内部统计。
常见问题¶
模型可以创建，为什么求解器拒绝它？ 统一建模层比单个后端的表达能力更广。检查路径兼容性，尤其是非线性表达式、有限域边界和展开规模。
为什么增加一条表达式后旧值不可读？ 新表达式改变模型，旧解被失效。先完成全部建模，再求解和读值。
为什么设置一秒预算后调用稍晚才返回？ 预算采用协作式取消，正在执行的操作和结果清理会增加延迟。
提示求解组件不可用？ 检查安装所用解释器与运行解释器一致，并按安装说明安装匹配的 OptAgent wheel。HiGHS 和 CP-SAT 均已内置；源码开发环境需要重新构建对应内核。