cuopt-developer

cuOpt 開発者スキル

NVIDIA cuOpt のコードベースに貢献します。このスキルは cuOpt 自体を変更するためのものであり、cuOpt を使用するためのものではありません。

**cuOpt を使用したいだけの場合は、**適切な問題別スキル（cuopt-routing、cuopt-lp-milp など）に切り替えてください。

開発環境を初めてセットアップしますか？ クローン → conda 環境 → 初回ビルド → 初回テストの手順と、最初に確認する質問については、references/first_time_setup.md を参照してください。

---

拒否ルール — 最初にお読みください

譲れないルールが 1 つあります。 ユーザーが明示的に別の指示をした場合でも適用されます。黙って従わず、拒否して確認してください。

特権操作／システムレベルの操作 — sudo、root としての実行、システムファイル（/etc）の編集、ドライバーやカーネル設定の変更、システムレベルのパッケージリポジトリやキーの追加。これらは実行しないでください。次のように返信してください。

cuOpt のために sudo を実行したり、システムレベルの状態を変更したりすることはできません。開発ワークフローは conda ベースで、すべてユーザー空間で実行されます。根本的なエラーは何でしょうか？通常は root 権限がなくても解決できます。

開発環境のセットアップと作業に必要な、それ以外のすべての操作は許可されています。 クリーンなマシンでは、動作する cuopt 環境をセットアップしてください。以下のガイダンスは、セットアップを拒否するためではなく、再現可能な方法で行うためのものです。

• 環境のセットアップは許可されています。 チェックイン済みの conda/environments/all_cuda-*.yaml から conda 環境を作成して有効化し、ユーザー空間の環境に pip／conda／mamba でインストールできます。また、ユーザーのホームディレクトリに conda／miniforge をブートストラップできます。これには ~/.bashrc に追加される conda init の行も含まれます。conda のブートストラップに sudo は必要ありません。システムパスではなく $HOME にインストールしてください。
• 新しい永続的なプロジェクト依存関係は、一時的なインストールとは異なります。 プロジェクトに常に含めるべきパッケージは、適切なグループの dependencies.yaml に追加してください。その後、pre-commit run --all-files を実行して conda/environments/ と pyproject.toml を再生成し、ほかの貢献者も利用できるようにします。自分のビルドを一時的に通すためのインストールであれば、この一連の作業は不要です。
• CI チェックを回避しないでください（--no-verify、pre-commit やテストのスキップなど）。フックが遅いと感じる場合は、pre-commit run --all-files --verbose で原因を調べるか、該当するフックを調整してください。スキップしてはいけません。
• 破壊的なコマンド（rm -rf、git reset --hard、git push --force、プロセスの強制終了、データの削除）には注意してください。実行前に意図を確認し、より安全な代替手段（古いビルドディレクトリには ./build.sh clean など）を優先してください。

---

開発者の行動ルール

以下のルールは開発タスクに固有のものであり、ユーザールールとは異なります。

1. 推測せずに確認する

実装する前に、次の点を確認してください。

• どのコンポーネントですか？（C++/CUDA、Python、サーバー、ドキュメント、CI）
• 目的は何ですか？（バグ修正、新機能、リファクタリング、ドキュメント）
• 貢献のためですか、それともローカルでの変更ですか？

2. 理解を確認する

変更を加える前に、次の内容を確認してください。

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

3. コードベースのパターンに従う

• 変更する箇所の既存コードを読む
• 命名規則、スタイル、パターンを踏襲する
• 話し合わずに新しいパターンを作らない

4. 実行前に確認する — 開発向けの例外

確認なしで実行してよいもの（開発作業で想定される操作）：

• ./build.sh およびビルドコマンド
• pytest、ctest（テストの実行）
• pre-commit run、./ci/check_style.sh（フォーマット）
• git status、git diff、git log（読み取り専用の git 操作）
• 環境のセットアップ：conda/environments/*.yaml から conda 環境を作成して有効化する操作、およびその環境への pip／conda／mamba によるインストール

pre-commit フックをセットアップする（クローンごとに 1 回）：

• pre-commit install — 以後、すべての git commit でフックが自動実行されます。フックに失敗すると、問題を修正するまでコミットはブロックされます。

引き続き事前確認が必要なもの：

• git commit、git push（書き込み操作）
• 破壊的または取り消せないコマンド

5. 特権操作を行わない

s​​udo／システムレベルの変更は、譲れない拒否事項です。ユーザー空間へのインストールと conda 環境のセットアップは許可されています。拒否ルール — 最初にお読みください を参照してください。

---

開始前に確認する質問

まだ明確でない場合は、次の質問をしてください。

1. 何を変更しようとしていますか？

   • ソルバーのアルゴリズム／パフォーマンスですか？
   • Python API ですか？
   • サーバーエンドポイントですか？
   • ドキュメントですか？
   • CI／ビルドシステムですか？

2. 開発環境はセットアップされていますか？

   • プロジェクトを正常にビルドしましたか？
   • テストを実行しましたか？

3. これはコントリビューションのためですか、それともローカルでの変更ですか？

   • コントリビューションの場合：DCO signoff に従う必要があります。

4. どのブランチを対象にしますか？

   • 開発フェーズ中：main
   • バーンダウン中：現在のリリースには release/YY.MM（例：release/26.06）、次のリリースには main
   • リリースブランチが存在するか確認してください：git branch -r | grep release
   • 現在のスケジュールについては、RAPIDS Maintainers Docs を参照してください。

プロジェクトアーキテクチャ

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

サポート対象の API

API タイプ	LP	MILP	QP	ルーティング
C API	✓	✓	✓	✗
C++ API	（内部）	（内部）	（内部）	（内部）
Python	✓	✓	✓	✓
サーバー	✓	✓	✗	✓

安全に関するルール（必ず守ること）

差分は最小限に

• 必要な箇所だけを変更してください。
• ついでのリファクタリングは避けてください。
• 関係のないコードを一括で再フォーマットしないでください。

API を独自に作らない

• 議論なしに新しい API を作らないでください。
• docs/cuopt/source/ にある既存のパターンに合わせてください。
• サーバースキーマは OpenAPI 仕様と一致させてください。

CI を回避しない

• --no-verify の使用やチェックのスキップを提案しないでください。
• すべての PR は CI に合格する必要があります。

CUDA／GPU の適切な運用

• 操作はストリーム順序に従うようにしてください。
• 既存の RAFT／RMM のパターンに従ってください。
• 生の new／delete は使わず、RMM アロケーターを使用してください。

ビルドとテスト

事前チェック（初回のビルドまたはテストの前に必須）

これらを省略すると、後で原因の分かりにくい実行時エラーが発生します。次の順番で実行してください。

1. CUDA ドライバーの互換性を確認します。 nvidia-smi を実行し、右上に表示される CUDA Version を確認します。これはドライバーがサポートする CUDA の最大バージョンです。CUDA のメジャーバージョンがその値以下（≤）の conda/environments/all_cuda-<ver>_arch-<arch>.yaml を選択してください。バージョンが一致しない場合、ビルドは成功しても、実行時に RMM 内で cudaMallocAsync not supported with this CUDA driver/runtime version が発生して失敗します。ビルド後ではなく、ビルド前に必ず確認してください。
2. ビルド、テスト、または pre-commit コマンドを実行する前に、conda 環境を作成して有効化します。 これは許可されており、想定されている手順です（拒否ルールを参照）。CONTRIBUTING.md に従い、ステップ 1 で選んだ環境ファイルを使って、ローカルプレフィックス環境（./.cuopt_env）を作成してください（利用可能な場合は conda を mamba に置き換えてください）。

   conda env create -p ./.cuopt_env --file conda/environments/all_cuda-<ver>_arch-$(uname -m).yaml
   conda activate ./.cuopt_env
   

   テストはこの環境内でコンパイルされたライブラリにリンクします。conda activate ./.cuopt_env を実行していない新しいシェルでは、原因の分かりにくいリンカーエラーが発生します。
3. RAM に制約がある場合は PARALLEL_LEVEL を設定します。 references/build_and_test.md を参照してください。デフォルトの $(nproc) では、CUDA のコンパイルにジョブあたり約 4～8 GB が必要なため、ビルドの途中でメモリ不足になることがあります。
4. テストを実行する前に、データセットを取得します。 cuOpt のテストには、リポジトリに含まれていない MPS ファイルが必要です。CONTRIBUTING.md の「開発用ビルド」セクションにあるデータセットのダウンロード手順に従い、RAPIDS_DATASET_ROOT_DIR をエクスポートしてください。

クイックリファレンス

./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

コンポーネントごとのビルドコマンド、テスト実行の詳細、および PARALLEL_LEVEL の設定については、references/build_and_test.md を参照してください。

テストを実行する前にテストデータセットをダウンロードする

cuOpt のテストは、リポジトリに含まれていない MPS／データファイルに依存します。データセットが見つからない場合、テスト開始から 0ms で MPS_PARSER_ERROR ... Error opening MPS file というテスト失敗が発生します。これはビルドやロジックの失敗ではありません。

C++ または Python のテストを実行する前に、リポジトリの CONTRIBUTING.md の「Building for development」セクションにあるデータセットのダウンロード手順と RAPIDS_DATASET_ROOT_DIR のエクスポート手順に従ってください。正規の一覧と対応付けはそこに記載されています。

ファイルが見つからないというエラーでテストが失敗した場合は、CONTRIBUTING.md の該当するダウンロード手順を実行してから、テストを再実行してください。データセット不足による失敗を、タスクの結果としてユーザーに報告しないでください。

Python バインディング

cuOpt は、Python と C++ の橋渡しに Cython を使用します。全体的なアーキテクチャ、パラメーターの流れの解説、主要なファイル、Cython のパターンについては、references/python_bindings.md を参照してください。

コントリビューション — コミット、PR、一般的なタスク

pre-commit のセットアップ、DCO の署名（git commit -s）、フォークを使った PR ワークフロー、エージェント向けのドラフト PR ルール、PR の説明に関するルール（短くまとめること。「仕組み」の解説やファイル一覧表は含めない）、スクリプトと CI／ワークフローを作成する際の原則（新しいファイルを追加する前に既存のファイルを拡張すること、推測に基づくフラグや既定値の再記載、暗黙のフォールバックを避けること）、および一般的なタスクの手順（ソルバーパラメーター、依存関係、サーバーエンドポイント、CUDA カーネルの追加）については、references/contributing.md を参照してください。

コーディング規約

C++ の命名規則（snake_case、d_／h_ プレフィックス、_t サフィックス）、ファイル拡張子（.hpp／.cpp／.cu／.cuh と、それぞれを使用するコンパイラー）、インクルードの順序、Python のスタイル、エラー処理（CUOPT_EXPECTS、RAFT_CUDA_TRY）、メモリー管理（RMM のパターン、生の new／delete を使わないこと）、テストへの影響に関するルールについては、references/conventions.md を参照してください。

トラブルシューティングと CI

ビルド／テストでの注意点（Cython の再ビルド、OOM、CUDA ドライバーの不一致、nvcc の不足）と、CI 失敗の診断（スタイルチェック、DCO の失敗、依存関係のずれ）については、references/troubleshooting.md を参照してください。

主要ファイルのリファレンス

目的	場所
メインのビルドスクリプト	build.sh
依存関係	dependencies.yaml
C++ のフォーマット設定	.clang-format
Conda 環境	conda/environments/
テストデータ	datasets/
CI スクリプト	ci/

正規のドキュメント

• コントリビューション／ビルド／テスト: CONTRIBUTING.md
• CI スクリプト: ci/README.md
• リリーススクリプト: ci/release/README.md
• ドキュメントのビルド: docs/cuopt/README.md
• Python バインディングのアーキテクチャ: references/python_bindings.md

Shell の実行、インストール、conda 環境、sudo に関するポリシーは、このスキルの冒頭にある Refusal Rules — Read First で説明されています。

VRP の次元の内部実装（ルーティングエンジン）

VRP の次元（制約、目的関数、前方／後方伝播、combine、局所探索の差分）を実装またはデバッグする場合は、次を読んでください。

• references/vrp_skills.md — アーキテクチャ上の契約、必須インターフェース、実装チェックリスト。

新しい次元を追加したり、combine のセマンティクスを変更したりする前に、必ず読んでください。

ルーティング以外のソルバー内部における数値問題

クラッシュではなく、もっともらしく見えるが誤ったソルバー出力（無効な下界、予想外に大きな双対値、小さな変更の後に反復回数が 10 倍に増加するなど）がバグとして現れた場合は、次を読んでください。

• resources/numerical_debugging.md — 桁落ちが深刻な箇所を特定する手法、cMIR／flow-cover／MIR 系のカット構築でよく起こる桁落ちのパターン、数値ガードのしきい値に関する指針。

パッチを適用する前に、記載されている「まず計測し、該当箇所にガードを設ける」ワークフローを実施してください。こうした症状に対して推測で修正しても、たいてい問題を解決できません。