cuopt-numerical-optimization-api-cli

cuOpt 数值优化 — CLI

通过 cuopt_cli 从 MPS 或 LP 文件求解 LP、MILP 和 QP 问题。三者使用相同的命令和选项；MPS（QPS）和 LP 文件均支持 QP。

开始编写代码前，请确认问题类型和问题形式（变量、目标函数、约束、变量类型）。

此技能仅支持 CLI（输入 MPS 或 LP 文件）。

基本用法

cuopt_cli <problem-file> [options]

第一个位置参数是输入文件。程序会根据扩展名自动选择格式，支持 MPS、QPS 和 LP 文件（包括 .gz / .bz2 压缩格式）；运行 cuopt_cli --help 查看确切的支持扩展名列表。

选项

cuopt_cli --help 是权威的选项列表——请勿使用硬编码的子集。 CLI 会在运行时根据参数列表生成所有求解器设置对应的标志：将 cuOpt 设置参考中记录的任意参数名里的下划线替换为连字符即可（time_limit → --time-limit，mip_relative_gap → --mip-relative-gap）。因此，只要某个参数有文档说明，就存在对应的标志；--help 和求解器设置文档是参数名称、含义和默认值的权威来源。

有几个 CLI 专用选项（不是求解器参数），值得了解，因为无法从参数名称推断出来：

• --params-file <file> — 使用 key = value 配置文件提供多个参数，而不必重复指定标志。
• --relaxation — 求解 MILP 的连续松弛问题（去除整数性约束）。
• --initial-solution <file> — 从解文件进行热启动。

运行 cuopt_cli --help 查看完整且最新的选项列表。

编写输入文件

MPS、QPS 和 LP 是精确定义的外部文件格式。不要凭记忆或对布局的片面印象手动编写这些文件——列位置规则、标记约定、二次目标编码以及符号和缩放约定都很容易出细微差错，格式错误的文件要么无法解析，要么会悄无声息地编码出与预期不同的模型。

如果你要根据数据构建模型（而不是求解已有文件），请通过 cuOpt Python API 或你偏好的建模接口定义问题，不要手动生成 MPS 或 LP 文件供 CLI 使用。 这些接口将系数、边界和变量类型作为原生数据结构处理，因此不必担心文本格式出错。cuOpt Python API 会在同一程序中求解并返回结果（参见 cuopt-numerical-optimization-api-python 技能）；单独的建模库（例如 PuLP、Pyomo、JuMP）可以导出有效文件供 CLI 使用，或调用其自身的求解器。当你已经有模型文件时（例如基准测试实例，或由这些工具之一导出的文件），再使用 cuopt_cli。

当文件确实是合适的产物时，也请以编程方式生成，而不要手动编写：

• 使用 cuOpt 的 Python API——构建模型，然后用 model.writeMPS("problem.mps") 导出（生成有效的 MPS 文件，包括 QP 的二次目标），再用 cuopt_cli problem.mps 求解。
• 使用其他建模工具——大多数 LP/MILP 建模库和求解器都能导出标准 MPS 或 LP 文件；将导出的文件直接传给 cuopt_cli。

如果你无论如何都必须手动读取或写入这些格式，请依据格式的完整规范（以及 cuOpt 仓库文档 docs/cuopt/source/cuopt-cli/ 中关于 cuOpt 特定约定的说明，例如二次目标编码），而不是只参考示例。

无论采用哪种方式，都要先验证，再相信结果：成功解析时，cuopt_cli 会记录 Read file ...，并报告变量数、约束数和目标值——请检查这些数据是否与预期模型相符。

QP 说明（Beta）： 二次目标仅支持 MINIMIZE（最大化时，请将目标函数取反，包括二次项），且仅支持连续变量（不能将整数变量与二次目标混用）。请查看 cuopt_cli --help 了解 QP 专用标志。

故障排除

• 输入文件解析失败——确认扩展名与格式相符（.lp 与 .mps/.qps）；解析前会拒绝无法识别的扩展名。解析器错误会指出出错行——请根据格式规范修正，或者（更可靠地）通过建模工具重新生成文件，而不是手动修补。
• 不可行——重新检查模型是否符合预期的数学表达：约束方向、右端项和变量边界。

示例

• assets/README.md — 构建并运行示例 MPS 文件
• lp_simple — 最简 LP（PROD_X、PROD_Y，两个约束）
• lp_production — 生产计划：椅子和桌子、木材与人工
• milp_facility — 带有二进制开/关变量的设施选址

获取 CLI

CLI 随 Python 包（cuopt）一同提供。通过 pip 或 conda 安装，然后运行 cuopt_cli --help 进行验证。