cuopt-numerical-optimization-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

cuOpt Numerical Optimization API

cuOpt数值优化API

Model and solve LP, MILP, and QP problems using NVIDIA cuOpt's GPU-accelerated solver.

使用NVIDIA cuOpt的GPU加速求解器建模并求解LP、MILP和QP问题。

Interface Selection

接口选择

Choose the reference for the user's interface:

Interface	When to use	Reference
Python	User is writing Python code	references/python_api.md
C / C++	User is embedding in a C/C++ application	references/c_api.md
CLI	User is solving from MPS files on the command line	references/cli_api.md

If the interface is not yet clear, ask before writing any code.

Already using a modeling language? cuOpt also works as a solver backend for third-party modeling tools — AMPL, GAMS / GAMSPy, PuLP, JuMP, Pyomo, and CVXPY — with near-zero code changes (point the model's solver at cuOpt). CVXPY additionally covers convex QP and, in beta, QCQP / SOCP. Prefer this when the user already has a model in one of these tools rather than porting it to the cuOpt API. See Third-Party Modeling Languages.

根据用户使用的接口选择对应的参考文档：

接口	使用场景	参考文档
Python	用户编写Python代码时	references/python_api.md
C / C++	用户将其嵌入C/C++应用程序时	references/c_api.md
CLI	用户通过命令行从MPS文件求解问题时	references/cli_api.md

如果尚未明确接口类型，请在编写代码前询问用户。

已在使用建模语言？ cuOpt还可作为第三方建模工具的求解器后端——包括AMPL、GAMS / GAMSPy、PuLP、JuMP、Pyomo和CVXPY——几乎无需修改代码（只需将模型的求解器指向cuOpt即可）。CVXPY额外支持凸QP，且在测试版中支持QCQP / SOCP。如果用户已使用上述工具构建模型，建议优先采用这种方式，而非将模型移植到cuOpt API。详情请参阅第三方建模语言。

Choosing LP vs MILP vs QP

选择LP、MILP还是QP

Decide from the objective and variables:

If the objective is...	And variables are...	Use
Linear (sum of `c_i * x_i` )	All continuous	LP
Linear	Some integer or binary	MILP
Has squared ( `xx` ) or cross ( `xy` ) terms	Continuous (integer QP not supported)	QP (beta)

Prefer LP when the problem allows it. LP solves faster and has stronger optimality guarantees. Use MILP only when the problem logically requires whole numbers or yes/no decisions. Use QP only when the objective is genuinely quadratic (variance, squared error, kinetic energy).

Use LP when every quantity can meaningfully be fractional: flows, proportions, rates, dollars, hours, tonnes of material, etc.
Use MILP when the problem mentions counts of discrete entities, yes/no choices, or either/or decisions (e.g. open a facility or not, assign a person to a shift, number of trucks).
Use QP when the objective minimizes variance, squared error, or any expression with
```
x*x
```
or
```
x*y
```
terms (portfolio optimization, least squares, regularized regression).

根据目标函数和变量类型决定：

若目标函数为...	且变量为...	使用
线性（ `c_i * x_i` 的和）	全部为连续型	LP
线性	部分为整数型或二进制型	MILP
包含平方项（ `xx` ）或交叉项（ `xy` ）	连续型（不支持整数QP）	QP（测试版）

在问题允许的情况下优先选择LP。LP求解速度更快，且具有更强的最优性保证。仅当问题逻辑上需要整数或是非决策时才使用MILP。仅当目标函数确实为二次型（如方差、平方误差、动能）时才使用QP。

使用LP：当所有量都可以合理取分数值时，例如流量、比例、速率、金额、时长、物料吨数等。
使用MILP：当问题涉及离散实体的数量、是非选择或二选一决策时（例如是否开设某个设施、是否为员工分配班次、卡车数量等）。
使用QP：当目标函数是最小化方差、平方误差或任何包含
```
x*x
```
或
```
x*y
```
项的表达式时（例如投资组合优化、最小二乘法、正则化回归）。

Integer vs Continuous from Wording

从表述判断整数型与连续型变量

Problem wording / concept	Variable type	Examples
Discrete entities (counts)	INTEGER	Workers, cars, trucks, machines, pilots, facilities, units to manufacture
Yes/no or on/off	INTEGER (binary, lb=0 ub=1)	Open a facility, run a machine, assign a person to a shift
Amounts that can be fractional	CONTINUOUS	Tonnes, litres, dollars, hours, kWh, proportion of capacity
Rates or fractions	CONTINUOUS	Utilization, percentage, share of budget

Rule of thumb: "How many things" → INTEGER. "How much" → CONTINUOUS.

问题表述/概念	变量类型	示例
离散实体（数量）	整数型	工人、汽车、卡车、机器、飞行员、设施、生产单位数量
是非或开关状态	整数型（二进制，下限=0，上限=1）	是否开设设施、是否运行机器、是否为员工分配班次
可取值为分数的数量	连续型	吨数、升数、金额、时长、千瓦时、产能比例
速率或比例	连续型	利用率、百分比、预算份额

经验法则： “有多少个物品” → 整数型。“有多少量” → 连续型。

QP Rules (all interfaces)

QP规则（所有接口通用）

MINIMIZE only — the solver rejects MAXIMIZE for quadratic objectives. To maximize
```
f(x)
```
, minimize
```
-f(x)
```
and negate the reported objective value.
Continuous variables only — integer QP is not supported.
Q should be positive semi-definite for a convex, well-posed problem.
Beta — API may evolve; treat as production-capable for typical convex QP.

仅支持最小化——求解器会拒绝最大化二次目标函数的请求。若要最大化
```
f(x)
```
，可改为最小化
```
-f(x)
```
，然后将得到的目标值取反。
仅支持连续型变量——不支持整数QP。
Q矩阵应为半正定矩阵，以保证问题是凸的、适定的。
测试版——API可能会演进；对于典型的凸QP问题，可视为具备生产可用性。

Dual Values

对偶值

Duals and reduced costs are available for LP and QP only:

MILP — no duals (integer optima are not continuous).
Quadratic constraints — duals unavailable even for LP/QP; all values return
```
NaN
```
.
PDLP warmstart — LP only; MILP solves do not accept a PDLP warmstart.

对偶值和缩减成本仅适用于LP和QP：

MILP——无对偶值（整数最优解不是连续的）。
二次约束——即使对于LP/QP，对偶值也不可用；所有值均返回
```
NaN
```
。
PDLP热启动——仅适用于LP；MILP求解不接受PDLP热启动。

Common Issues (all interfaces)

常见问题（所有接口通用）

Problem	Likely cause	Fix
Infeasible	Conflicting constraints	Check constraint logic and bounds
Unbounded	Missing bounds	Add variable bounds
Slow solve	Large problem	Set time limit; increase gap tolerance
QP rejected with MAXIMIZE	QP only supports MINIMIZE	Negate the objective; negate the result
QP returns non-optimal	Q not PSD or badly scaled	Check Q is PSD; rescale variables

问题	可能原因	解决方法
不可行	约束条件冲突	检查约束逻辑和边界
无界	缺少变量边界	添加变量边界
求解缓慢	问题规模较大	设置时间限制；增大间隙容差
QP因最大化请求被拒绝	QP仅支持最小化	对目标函数取反；对结果取反
QP返回非最优解	Q矩阵非半正定或缩放不佳	检查Q矩阵是否为半正定；重新缩放变量

Solver Settings (concepts)

求解器设置（概念）

Setting	Purpose
`time_limit`	Stop after N seconds
`mip_relative_gap`	Stop MILP when within X% of optimal
`mip_absolute_tolerance`	Absolute MIP gap stop
`log_to_console`	Enable solver logging

Syntax varies by interface — see the interface reference file.

设置项	用途
`time_limit`	N秒后停止求解
`mip_relative_gap`	当MILP解与最优解的相对间隙在X%以内时停止求解
`mip_absolute_tolerance`	达到绝对MIP间隙时停止求解
`log_to_console`	启用求解器日志

语法因接口而异——请参阅对应接口的参考文档。