Cuopt Developer

3. Follow Codebase Patterns

• 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

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

5. No Privileged Operations

Same as user rules — never without explicit request:

• No sudo
• No system file changes
• No writes outside workspace

Before You Start: Required Questions

Ask these if not already clear:

1. What are you trying to change?

   • Solver algorithm/performance?
   • Python API?
   • Server endpoints?
   • Documentation?
   • CI/build system?

2. Do you have the development environment set up?

   • Built the project successfully?
   • Ran tests?

3. Is this for contribution or local modification?

   • If contributing: will need to follow DCO signoff

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

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

Supported APIs

Safety Rules (Non-Negotiable)

Minimal Diffs

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

No API Invention

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

Don't Bypass CI

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

CUDA/GPU Hygiene

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

Build & Test

PARALLEL_LEVEL

PARALLEL_LEVEL controls the number of parallel compile jobs. It defaults to $(nproc) (all cores), which can cause OOM on machines with limited RAM — CUDA compilation is memory-intensive. Set it based on your system's available RAM (roughly 4-8 GB per job):

export PARALLEL_LEVEL=8   # adjust based on available RAM

Build Everything

./build.sh

Build Specific Components

./build.sh libcuopt    # C++ library
./build.sh cuopt       # Python package
./build.sh cuopt_server # Server
./build.sh docs        # Documentation

Run Tests

# C++ tests
ctest --test-dir cpp/build

# Python tests
pytest -v python/cuopt/cuopt/tests

# Server tests
pytest -v python/cuopt_server/tests

Python Bindings

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.

Before You Commit

1. Install Pre-commit Hooks

Run once per clone to have style checks run automatically on every git commit:

pre-commit install

If a hook fails, the commit is blocked — fix the issues and commit again. To check all files manually (e.g., before pushing), run pre-commit run --all-files --show-diff-on-failure.

2. Make Meaningful Commits

Group related changes into logical commits rather than committing all files at once. Each commit should represent one coherent change (e.g., separate the C++ change from the Python binding update from the test addition). This makes git log and git bisect useful for debugging later.

3. Sign Your Commits (DCO Required)

git commit -s -m "Your message"

4. Use Forks for Pull Requests

Never push branches directly to the main cuOpt repository. Use the fork workflow:

# 1. Clone the main repo
git clone [email protected]:NVIDIA/cuopt.git
cd cuopt

# 2. Add your fork as a remote
git remote add fork [email protected]:<your-username>/cuopt.git

# 3. Create a branch from the appropriate base (see branching strategy below)
git checkout -b my-feature-branch

# 4. Make changes, commit, then push to your fork
git push fork my-feature-branch

# 5. Create PR from your fork → upstream base branch

This applies to both human contributors and AI agents. Agents must never push to the upstream repo directly — provide the push command for the user to review and execute from their fork.

Pull Requests Created by Agents

When an AI agent creates a pull request, it must be a draft PR (gh pr create --draft). This gives the developer time to review and iterate on the changes before any reviewers get pinged. The developer will mark it as ready for review when satisfied.

PR Descriptions

Keep PR summaries short and informative. State what changed and why in a few bullet points. Avoid verbose explanations, full file listings, or restating the diff. Reviewers read the code — the summary should give them context, not a transcript.

Coding Conventions

C++ Naming

File Extensions

Include Order

1. Local headers
2. RAPIDS headers
3. Related libraries
4. Dependencies
5. STL

Python Style

• Follow PEP 8
• Use type hints
• Tests use pytest

Error Handling

Runtime Assertions

CUOPT_EXPECTS(condition, "Error message");
CUOPT_FAIL("Unreachable code reached");

CUDA Error Checking

RAFT_CUDA_TRY(cudaMemcpy(...));

Memory Management

// ❌ WRONG
int* data = new int[100];

// ✅ CORRECT - use RMM