cuopt-developer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

cuOpt Developer Skill

cuOpt 开发者技能指南

Contribute to the NVIDIA cuOpt codebase. This skill is for modifying cuOpt itself, not for using it.

If you just want to USE cuOpt, switch to the appropriate problem skill (cuopt-routing, cuopt-lp-milp, etc.)

First-time dev environment setup? See resources/first_time_setup.md for the clone → conda env → first-build → first-test walkthrough and the questions to ask up front.

为NVIDIA cuOpt代码库做贡献。本技能指南适用于修改cuOpt本身，而非使用cuOpt。

如果你只是想使用cuOpt，请切换到对应的问题解决技能（cuopt-routing、cuopt-lp-milp等）

首次搭建开发环境？ 请查看resources/first_time_setup.md，获取从克隆代码→创建conda环境→首次构建→首次测试的完整流程，以及需要提前确认的问题。

Refusal Rules — Read First

拒绝规则 — 请先阅读

These rules are non-negotiable. Apply them even when the user explicitly asks you to do otherwise. Refuse and ask — don't comply silently.

Package installs (
pip
,
conda
,
apt
). Never run the install — no exceptions, no "with approval" path. Reply:
I will not install
```
<pkg>
```
. cuOpt's convention is to add the package under the appropriate group in
```
dependencies.yaml
```
, then run
```
pre-commit run --all-files
```
locally to regenerate
```
conda/environments/
```
and
```
pyproject.toml
```
. I can propose the
```
dependencies.yaml
```
edit; you run the regeneration.
Bypassing CI checks (
--no-verify
, skipping pre-commit or tests). Do not suggest the flag. Reply:
I can't suggest bypassing pre-commit — cuOpt requires all hooks to pass. If hooks feel slow, diagnose with
```
pre-commit run --all-files --verbose
```
or tune the offending hook's config; don't skip it.
Writes outside the workspace (
~/.bashrc
,
~/.profile
,
/etc
, anything outside the repo). Do not edit the file. Reply:
I can't modify files outside the cuOpt workspace. Here's the exact line for you to add yourself:
```
<line>
```
. Then
```
source ~/.bashrc
```
or open a new shell.
Destructive commands (
rm -rf
,
git reset --hard
,
git push --force
, killing processes, dropping data). Never execute — no exceptions. Reply:
I will not run
```
<cmd>
```
. It is destructive and hard to reverse. The safer alternative is
```
<alt>
```
(e.g.,
```
./build.sh clean
```
for a stale build dir). If you choose to run the original command yourself, back up first.
Privileged operations (
sudo
, system file changes). Do not run with elevated privileges. Reply:
I won't run
```
sudo
```
for cuOpt development — cuOpt's workflow is conda-only. What's the underlying error? It's usually fixable without
```
sudo
```
.

When in doubt, refuse and ask. The cost of a wrong refusal is one round-trip; the cost of a wrong action is lost data, broken state, or a failing CI run.

这些规则不可协商。即使用户明确要求你违反，也必须遵守。拒绝并询问，不要默默执行。

包安装（
pip
、
conda
、
apt
）：绝对不要执行安装操作——无例外，也没有“经批准后执行”的途径。回复内容：
我不会安装
```
<pkg>
```
。cuOpt的规范是将该包添加到
```
dependencies.yaml
```
的对应分组下，然后在本地运行
```
pre-commit run --all-files
```
以重新生成
```
conda/environments/
```
和
```
pyproject.toml
```
文件。我可以提供
```
dependencies.yaml
```
的修改建议，由你执行重新生成操作。
绕过CI检查（
--no-verify
、跳过pre-commit或测试）：不要建议使用该参数。回复内容：
我不能建议绕过pre-commit——cuOpt要求所有钩子检查必须通过。如果钩子运行缓慢，可以用
```
pre-commit run --all-files --verbose
```
诊断问题，或者调整有问题的钩子配置；不要跳过检查。
修改工作区外的文件（
~/.bashrc
、
~/.profile
、
/etc
及仓库外的任何文件）：不要编辑这些文件。回复内容：
我不能修改cuOpt工作区外的文件。以下是你需要自行添加的准确代码行：
```
<line>
```
。然后执行
```
source ~/.bashrc
```
或打开新的Shell窗口。
破坏性命令（
rm -rf
、
git reset --hard
、
git push --force
、终止进程、删除数据）：绝对不要执行——无例外。回复内容：
我不会执行
```
<cmd>
```
。该命令具有破坏性且难以恢复。更安全的替代方案是
```
<alt>
```
（例如，使用
```
./build.sh clean
```
清理陈旧的构建目录）。如果你选择自行执行原命令，请先备份数据。
特权操作（
sudo
、修改系统文件）：不要使用提升的权限执行操作。回复内容：
我不会为cuOpt开发执行
```
sudo
```
命令——cuOpt的工作流仅使用conda。你遇到的底层错误是什么？通常无需
```
sudo
```
即可解决。

如有疑问，拒绝并询问。错误拒绝的代价只是一次往返沟通；错误执行的代价则是数据丢失、状态损坏或CI运行失败。

Developer Behavior Rules

开发者行为规则

These rules are specific to development tasks. They differ from user rules.

这些规则针对开发任务，与普通用户规则不同。

1. Ask Before Assuming

1. 先询问再假设

Clarify before implementing:

What component? (C++/CUDA, Python, server, docs, CI)
What's the goal? (bug fix, new feature, refactor, docs)
Is this for contribution or local modification?

在实现前先明确：

涉及哪个组件？（C++/CUDA、Python、服务器、文档、CI）
目标是什么？（修复bug、新增功能、重构、文档更新）
这是用于贡献代码还是本地修改？

2. Verify Understanding

2. 确认理解

Before making changes, confirm:

"Let me confirm:
- Component: [cpp/python/server/docs]
- Change: [what you'll modify]
- Tests needed: [what tests to add/update]
Is this correct?"

在进行修改前，先确认：

"我确认一下：
- 组件：[cpp/python/server/docs]
- 修改内容：[你要修改的内容]
- 需要的测试：[要添加/更新的测试]
是否正确？"

3. Follow Codebase Patterns

3. 遵循代码库模式

Read existing code in the area you're modifying
Match naming conventions, style, and patterns
Don't invent new patterns without discussion

阅读你要修改区域的现有代码
匹配命名规范、风格和模式
未经讨论不要创建新的模式

4. Ask Before Running — Modified for Dev

4. 执行前询问 — 针对开发场景调整

OK to run without asking (expected for dev work):

```
./build.sh
```
and build commands
```
pytest
```
,
```
ctest
```
(running tests)
```
pre-commit run
```
,
```
./ci/check_style.sh
```
(formatting)
```
git status
```
,
```
git diff
```
,
```
git log
```
(read-only git)

Set up pre-commit hooks (once per clone):

```
pre-commit install
```
— hooks then run automatically on every
```
git commit
```
. If a hook fails, the commit is blocked until you fix the issue.

Still ask before:

```
git commit
```
,
```
git push
```
(write operations)
Package installs (
```
pip
```
,
```
conda
```
,
```
apt
```
)
Any destructive or irreversible commands

无需询问即可执行（开发工作中的常规操作）：

```
./build.sh
```
及其他构建命令
```
pytest
```
、
```
ctest
```
（运行测试）
```
pre-commit run
```
、
```
./ci/check_style.sh
```
（代码格式化）
```
git status
```
、
```
git diff
```
、
```
git log
```
（只读Git操作）

设置pre-commit钩子（每个代码克隆仅需执行一次）：

```
pre-commit install
```
— 钩子会在每次
```
git commit
```
时自动运行。如果钩子检查失败，提交会被阻止，直到你修复问题。

仍需先询问再执行：

```
git commit
```
、
```
git push
```
（写入操作）
包安装（
```
pip
```
、
```
conda
```
、
```
apt
```
）
任何破坏性或不可逆的命令

5. No Privileged Operations

5. 禁止特权操作

sudo

, system file changes, and writes outside the workspace are non-negotiable refusals — they apply even when the user explicitly asks. See Refusal Rules — Read First (rules 3 and 5) for the exact replies and rationale.

sudo

、修改系统文件及修改工作区外文件属于不可协商的拒绝项——即使用户明确要求也必须遵守。请查看拒绝规则 — 请先阅读中的规则3和规则5，获取准确回复及理由。

Before You Start: Required Questions

开始前：必问问题

Ask these if not already clear:

What are you trying to change?
- Solver algorithm/performance?
- Python API?
- Server endpoints?
- Documentation?
- CI/build system?
Do you have the development environment set up?
- Built the project successfully?
- Ran tests?
Is this for contribution or local modification?
- If contributing: will need to follow DCO signoff
Which branch should this target?
- During development phase:
```
main
```
- During burn down:
```
release/YY.MM
```
  (e.g.,
```
release/26.06
```
  ) for the current release,
```
main
```
  for the next
- Check if a release branch exists:
```
git branch -r | grep release
```
- For current timelines, see the RAPIDS Maintainers Docs

如果以下信息不明确，请询问：

你想要修改什么？
- 求解器算法/性能？
- Python API？
- 服务器端点？
- 文档？
- CI/构建系统？
你是否已搭建好开发环境？
- 是否成功构建了项目？
- 是否运行过测试？
这是用于贡献代码还是本地修改？
- 如果是贡献代码：需要遵循DCO签署流程
目标分支是哪个？
- 开发阶段：
```
main
```
- 版本收尾阶段：当前版本对应
```
release/YY.MM
```
  （例如
```
release/26.06
```
  ），下一版本对应
```
main
```
- 检查是否存在发布分支：
```
git branch -r | grep release
```
- 查看当前时间线，请参考RAPIDS Maintainers Docs

Project Architecture

项目架构

cuopt/
├── cpp/                    # Core C++ engine
│   ├── include/cuopt/      # Public C/C++ headers
│   ├── src/                # Implementation (CUDA kernels)
│   └── tests/              # C++ unit tests (gtest)
├── python/
│   ├── cuopt/              # Python bindings and routing API
│   ├── cuopt_server/       # REST API server
│   ├── cuopt_self_hosted/  # Self-hosted deployment
│   └── libcuopt/           # Python wrapper for C library
├── ci/                     # CI/CD scripts
├── docs/                   # Documentation source
└── datasets/               # Test datasets

cuopt/
├── cpp/                    # 核心C++引擎
│   ├── include/cuopt/      # 公开C/C++头文件
│   ├── src/                # 实现代码（CUDA内核）
│   └── tests/              # C++单元测试（gtest）
├── python/
│   ├── cuopt/              # Python绑定及路由API
│   ├── cuopt_server/       # REST API服务器
│   ├── cuopt_self_hosted/  # 自托管部署
│   └── libcuopt/           # C库的Python封装
├── ci/                     # CI/CD脚本
├── docs/                   # 文档源文件
└── datasets/               # 测试数据集

Supported APIs

支持的API

API Type	LP	MILP	QP	Routing
C API	✓	✓	✓	✗
C++ API	(internal)	(internal)	(internal)	(internal)
Python	✓	✓	✓	✓
Server	✓	✓	✗	✓

API类型	LP	MILP	QP	路由
C API	✓	✓	✓	✗
C++ API	（内部使用）	（内部使用）	（内部使用）	（内部使用）
Python	✓	✓	✓	✓
Server	✓	✓	✗	✓

Safety Rules (Non-Negotiable)

安全规则（不可协商）

Minimal Diffs

最小化代码变更

Change only what's necessary
Avoid drive-by refactors
No mass reformatting of unrelated code

只修改必要的内容
避免顺带重构无关代码
不要对无关代码进行大规模格式化

No API Invention

禁止自行创建API

Don't invent new APIs without discussion
Align with existing patterns in
```
docs/cuopt/source/
```
Server schemas must match OpenAPI spec

未经讨论不要创建新的API
与
```
docs/cuopt/source/
```
中的现有模式保持一致
服务器架构必须符合OpenAPI规范

Don't Bypass CI

不要绕过CI

Never suggest
```
--no-verify
```
or skipping checks
All PRs must pass CI

永远不要建议使用
```
--no-verify
```
或跳过检查
所有PR必须通过CI检查

CUDA/GPU Hygiene

CUDA/GPU规范

Keep operations stream-ordered
Follow existing RAFT/RMM patterns
No raw
```
new
```
/
```
delete
```
- use RMM allocators

保持操作的流顺序
遵循现有的RAFT/RMM模式
不要使用原生
```
new
```
/
```
delete
```
— 使用RMM分配器

Build & Test

构建与测试

Pre-flight Checks (Required Before First Build or Test)

预检查（首次构建或测试前必须执行）

Skipping any of these surfaces as confusing runtime errors later. Run them in order:

Check CUDA driver compatibility. Run
```
nvidia-smi
```
and read the CUDA Version in the top-right corner — that's the maximum CUDA your driver supports. Pick a conda env file from
```
conda/environments/all_cuda-<ver>_arch-<arch>.yaml
```
whose CUDA major version is ≤ that. A mismatch builds successfully but fails at runtime inside RMM with
```
cudaMallocAsync not supported with this CUDA driver/runtime version
```
— verify this before the build, not after.
Create and activate the conda env before any build, test, or
```
pre-commit
```
command. Tests link against libraries compiled inside that env; a fresh shell without
```
conda activate <env-name>
```
hits cryptic linker errors.
Set
PARALLEL_LEVEL
if RAM is constrained — see resources/build_and_test.md. The default
```
$(nproc)
```
can OOM mid-build because CUDA compilation needs ~4–8 GB per job.
For tests, fetch datasets first. cuOpt tests need MPS files not in the repo — follow the dataset download steps in CONTRIBUTING.md ("Building for development" section) and export
```
RAPIDS_DATASET_ROOT_DIR
```
.

跳过任何一项都会导致后续出现难以理解的运行时错误。请按顺序执行：

检查CUDA驱动兼容性。运行
```
nvidia-smi
```
，查看右上角的CUDA Version——这是你的驱动支持的最高CUDA版本。从
```
conda/environments/all_cuda-<ver>_arch-<arch>.yaml
```
中选择一个CUDA主版本**≤该版本的conda环境文件。版本不匹配会导致构建成功但运行时在RMM中失败，报错
cudaMallocAsync not supported with this CUDA driver/runtime version
——请在构建前**验证，不要等到构建后。
创建并激活conda环境，然后再执行任何构建、测试或
```
pre-commit
```
命令。测试会链接到该环境中编译的库；如果新Shell未执行
```
conda activate <env-name>
```
，会出现难以理解的链接错误。
设置
PARALLEL_LEVEL
（如果内存受限）——请查看resources/build_and_test.md。默认值
```
$(nproc)
```
可能会导致构建过程中内存不足，因为CUDA编译每个任务需要约4–8 GB内存。
运行测试前先获取数据集。cuOpt测试需要不在仓库中的MPS文件——请遵循CONTRIBUTING.md中“Building for development”部分的数据集下载步骤，并导出
```
RAPIDS_DATASET_ROOT_DIR
```
。

Quick Reference

快速参考

bash

./build.sh             # Build everything
./build.sh --help      # List components: libcuopt, cuopt, cuopt_server, docs
ctest --test-dir cpp/build              # C++ tests
pytest -v python/cuopt/cuopt/tests      # Python tests
pytest -v python/cuopt_server/tests     # Server tests

For component-specific build commands, run-test detail, and

PARALLEL_LEVEL

configuration, see resources/build_and_test.md.

bash

./build.sh             # 构建所有内容
./build.sh --help      # 列出可构建组件：libcuopt、cuopt、cuopt_server、docs
ctest --test-dir cpp/build              # 运行C++测试
pytest -v python/cuopt/cuopt/tests      # 运行Python测试
pytest -v python/cuopt_server/tests     # 运行服务器测试

如需组件特定的构建命令、详细测试步骤及

PARALLEL_LEVEL

配置，请查看resources/build_and_test.md。

Download test datasets before running tests

运行测试前下载测试数据集

cuOpt tests depend on MPS/data files that are not checked into the repo. A missing dataset surfaces as a

MPS_PARSER_ERROR ... Error opening MPS file

test failure at 0ms — it is not a build or logic failure.

Before running any C++ or Python tests, follow the dataset download and

RAPIDS_DATASET_ROOT_DIR

export steps in the repo's

CONTRIBUTING.md

("Building for development" section) — that is the canonical list and mapping.

If a test fails with a missing-file error, run the matching download step from

CONTRIBUTING.md

and re-run the test. Do not report missing-dataset failures back to the user as the task outcome.

cuOpt测试依赖未纳入仓库的MPS/数据文件。缺失数据集会导致测试失败，报错

MPS_PARSER_ERROR ... Error opening MPS file

，且耗时为0ms——这不是构建或逻辑错误。

在运行任何C++或Python测试前，请遵循仓库

CONTRIBUTING.md

中“Building for development”部分的数据集下载及

RAPIDS_DATASET_ROOT_DIR

导出步骤——这是官方的步骤及映射说明。

如果测试因文件缺失失败，请执行

CONTRIBUTING.md

中对应的下载步骤，然后重新运行测试。不要将缺失数据集导致的失败作为任务结果反馈给用户。

Python Bindings

Python绑定

cuOpt uses Cython to bridge Python and C++. See resources/python_bindings.md for the full architecture, parameter flow walkthrough, key files, and Cython patterns.

cuOpt使用Cython实现Python与C++的桥接。如需了解完整架构、参数流转流程、关键文件及Cython模式，请查看resources/python_bindings.md。

Contributing — Commits, PRs, Common Tasks

贡献指南 — 提交、PR、常见任务

For pre-commit setup, DCO sign-off (

git commit -s

), the fork-based PR workflow, the draft-PR rule for agents, PR-description rules (keep it short — no "how it works" walkthroughs or file tables), script and CI/workflow authoring principles (extend existing files before adding new ones; no speculative flags, restated defaults, or silent fallbacks), and step-by-step common-task recipes (adding a solver parameter, dependency, server endpoint, or CUDA kernel), see resources/contributing.md.

如需pre-commit设置、DCO签署（

git commit -s

）、基于fork的PR工作流、代理的草稿PR规则、PR描述规则（保持简洁——无需“工作原理”说明或文件列表）、脚本及CI/工作流编写原则（优先扩展现有文件，再添加新文件；不要添加推测性参数、重复默认值或静默回退），以及常见任务的分步指南（添加求解器参数、依赖、服务器端点或CUDA内核），请查看resources/contributing.md。

Coding Conventions

编码规范

For C++ naming (

snake_case

d_

h_

prefixes,

_t

suffix), file extensions (

.hpp

.cpp

.cu

.cuh

and which compiler each uses), include order, Python style, error handling (

CUOPT_EXPECTS

RAFT_CUDA_TRY

), memory management (RMM patterns, no raw

new

delete

), and test-impact rules, see resources/conventions.md.

如需C++命名规范（

snake_case

、

d_

h_

前缀、

_t

后缀）、文件扩展名（

.hpp

.cpp

.cu

.cuh

及对应的编译器）、头文件包含顺序、Python风格、错误处理（

CUOPT_EXPECTS

、

RAFT_CUDA_TRY

）、内存管理（RMM模式、禁止原生

new

delete

）及测试影响规则，请查看resources/conventions.md。

Troubleshooting & CI

故障排查与CI

For build/test pitfalls (Cython rebuild, OOM, CUDA driver mismatch, missing

nvcc

) and CI failure diagnostics (style checks, DCO failures, dependency drift), see resources/troubleshooting.md.

如需构建/测试常见问题（Cython重建、内存不足、CUDA驱动版本不匹配、缺失

nvcc

）及CI失败诊断（风格检查、DCO失败、依赖漂移），请查看resources/troubleshooting.md。

Key Files Reference

关键文件参考

Purpose	Location
Main build script	`build.sh`
Dependencies	`dependencies.yaml`
C++ formatting	`.clang-format`
Conda environments	`conda/environments/`
Test data	`datasets/`
CI scripts	`ci/`

用途	位置
主构建脚本	`build.sh`
依赖配置	`dependencies.yaml`
C++格式化规则	`.clang-format`
Conda环境配置	`conda/environments/`
测试数据	`datasets/`
CI脚本	`ci/`

Canonical Documentation

权威文档

Contributing/build/test: CONTRIBUTING.md
CI scripts: ci/README.md
Release scripts: ci/release/README.md
Docs build: docs/cuopt/README.md
Python binding architecture: resources/python_bindings.md

Shell-execution, install, sudo, and outside-workspace policies are covered by Refusal Rules — Read First at the top of this skill.

贡献/构建/测试：CONTRIBUTING.md
CI脚本：ci/README.md
发布脚本：ci/release/README.md
文档构建：docs/cuopt/README.md
Python绑定架构：resources/python_bindings.md

Shell执行、安装、sudo及工作区外操作的规则，请参考顶部的拒绝规则 — 请先阅读。