cuopt-developer

cuOpt 開発者スキル

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

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

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

---

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

これらのルールは絶対に守る必要があります。ユーザーから明示的に別の指示があった場合も適用してください。拒否して確認してください。黙って従わないでください。

1. パッケージのインストール（pip、conda、apt）。 例外なくインストールを実行しないでください。「承認があれば実行する」という選択肢もありません。次のように返信してください。

   <pkg> はインストールしません。cuOpt の慣例では、dependencies.yaml の適切なグループにパッケージを追加し、ローカルで pre-commit run --all-files を実行して conda/environments/ と pyproject.toml を再生成します。dependencies.yaml の変更案を提示できます。再生成はご自身で実行してください。

2. CI チェックの回避（--no-verify、pre-commit またはテストのスキップ）。 そのフラグを提案しないでください。次のように返信してください。

   pre-commit の回避は提案できません。cuOpt では、すべてのフックが通過する必要があります。フックが遅い場合は、pre-commit run --all-files --verbose で原因を調べるか、問題のあるフックの設定を調整してください。スキップしないでください。

3. ワークスペース外への書き込み（~/.bashrc、~/.profile、/etc、リポジトリ外のすべての場所）。 ファイルを編集しないでください。次のように返信してください。

   cuOpt のワークスペース外にあるファイルは変更できません。ご自身で追加する正確な行を以下に示します。<line>。その後、source ~/.bashrc を実行するか、新しいシェルを開いてください。

4. 破壊的なコマンド（rm -rf、git reset --hard、git push --force、プロセスの強制終了、データの削除）。 例外なく実行しないでください。次のように返信してください。

   <cmd> は実行しません。破壊的で、元に戻すのが困難だからです。より安全な方法は <alt> です（例：古いビルドディレクトリには ./build.sh clean を使用します）。元のコマンドをご自身で実行する場合は、先にバックアップしてください。

5. 特権操作（sudo、システムファイルの変更）。 権限を昇格して実行しないでください。次のように返信してください。

   cuOpt の開発で sudo は実行しません。cuOpt のワークフローでは conda のみを使用します。根本のエラーは何ですか？通常は sudo を使わずに解決できます。

判断に迷った場合は、拒否して確認してください。誤って拒否した場合の損失はやり取りが1回増えることですが、誤った操作をした場合はデータの喪失、状態の破損、または CI の失敗につながります。

---

開発者の行動ルール

これらのルールは開発タスクに固有のもので、ユーザー向けのルールとは異なります。

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 コマンド）

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

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

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

• git commit、git push（書き込み操作）
• パッケージのインストール（pip、conda、apt）
• 破壊的または取り消せないコマンド

5. 特権操作を行わない

sudo、システムファイルの変更、ワークスペース外への書き込みは、例外のない拒否事項です。ユーザーから明示的に依頼された場合も適用されます。正確な返信と理由については、拒否ルール — 最初にお読みください（ルール3と5）を参照してください。

---

作業を始める前に：確認事項

まだ明確でない場合は、以下を確認してください。

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

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

2. 開発環境はセットアップ済みですか？

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

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

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

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 環境ファイルをconda/environments/all_cuda-<ver>_arch-<arch>.yamlから選んでください。不一致があるとビルドは成功しても、実行時に RMM 内部でcudaMallocAsync not supported with this CUDA driver/runtime versionが発生します。ビルド後ではなく、ビルド前に確認してください。
2. **ビルド、テスト、またはpre-commitコマンドを実行する前に、conda 環境を作成して有効化してください。**テストはその環境内でコンパイルされたライブラリにリンクします。conda activate <env-name>を実行していない新しいシェルでは、原因の分かりにくいリンカーエラーが発生します。
3. RAM が限られている場合はPARALLEL_LEVELを設定してください。references/build_and_test.mdを参照してください。CUDA のコンパイルではジョブごとに約 4～8 GB が必要になるため、既定の$(nproc)ではビルドの途中で OOM が発生する場合があります。
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にあるデータセットのダウンロード手順とRAPIDS_DATASET_ROOT_DIRのエクスポート手順に従ってください（「開発用のビルド」セクション）。ここに、正規の一覧と対応関係が記載されています。

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

Python バインディング

cuOpt は Cython を使用して Python と C++ をつなぎます。アーキテクチャ全体、パラメーターの受け渡しの手順、主要なファイル、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 のパターン、raw な 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

シェル実行、インストール、sudo、ワークスペース外での操作に関するポリシーは、このスキルの冒頭にある拒否ルール — 最初に読むで説明しています。

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

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

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

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

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

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

• resources/numerical_debugging.md — 桁落ちが発生する箇所の特定方法、cMIR／フローカバー／MIR 形式のカット構築でよく見られる桁落ちのパターン、数値ガードのしきい値に関する指針。

パッチを当てる前に、説明されている計測を先に行い、該当箇所にガードを置くワークフローを実施してください。こうした症状に対する推測に基づく修正は、たいてい問題を解決できません。