Adding best practices and details #692
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||||
|---|---|---|---|---|---|---|---|---|
| @@ -0,0 +1,312 @@ | ||||||||
| # AGENTS.md - AI Coding Agent Guidelines for cuOpt | ||||||||
|
|
||||||||
| > This file provides essential context for AI coding assistants (Codex, Cursor, GitHub Copilot, etc.) working with the NVIDIA cuOpt codebase. | ||||||||
| --- | ||||||||
|
|
||||||||
| ## Project Overview | ||||||||
|
|
||||||||
| **cuOpt** is NVIDIA's GPU-accelerated optimization engine for: | ||||||||
| - **Mixed Integer Linear Programming (MILP)** | ||||||||
| - **Linear Programming (LP)** | ||||||||
| - **Quadratic Programming (QP)** | ||||||||
| - **Vehicle Routing Problems (VRP)** including TSP and PDP | ||||||||
|
|
||||||||
| ### Architecture | ||||||||
|
|
||||||||
| ``` | ||||||||
| cuopt/ | ||||||||
| ├── cpp/ # Core C++ engine (libcuopt, libmps_parser) | ||||||||
| │ ├── include/cuopt/ # Public C/C++ headers | ||||||||
| │ ├── src/ # Implementation (CUDA kernels, algorithms) | ||||||||
| │ └── tests/ # C++ unit tests (gtest) | ||||||||
| ├── python/ | ||||||||
| │ ├── cuopt/ # Python bindings and routing API | ||||||||
| │ ├── cuopt_server/ # REST API server | ||||||||
| │ ├── cuopt_self_hosted/ # Self-hosted deployment utilities | ||||||||
| │ └── libcuopt/ # Python wrapper for C library | ||||||||
| ├── ci/ # CI/CD scripts and Docker configurations | ||||||||
| ├── conda/ # Conda recipes and environment files | ||||||||
| ├── docs/ # Documentation source | ||||||||
| ├── datasets/ # Test datasets for LP, MIP, routing | ||||||||
| └── notebooks/ # Example Jupyter notebooks | ||||||||
| ``` | ||||||||
|
|
||||||||
| ### Supported APIs | ||||||||
|
|
||||||||
| | API Type | LP | MILP | QP | Routing | | ||||||||
| |----------|:--:|:----:|:--:|:-------:| | ||||||||
| | C API | ✓ | ✓ | ✓ | ✗ | | ||||||||
| | C++ API | ✓ | ✓ | ✓ | ✓ | | ||||||||
| | Python | ✓ | ✓ | ✓ | ✓ | | ||||||||
| | Server | ✓ | ✓ | ✓ | ✓ | | ||||||||
|
|
||||||||
| --- | ||||||||
|
|
||||||||
| ## Setup and Installation | ||||||||
|
|
||||||||
| ### System Requirements | ||||||||
|
|
||||||||
| - **CUDA**: 12.5+ or 13.0+ | ||||||||
| - **GPU**: Volta architecture or better (Compute Capability ≥7.0) | ||||||||
| - **Driver**: ≥525.60.13 (Linux), ≥527.41 (Windows) | ||||||||
| - **Python**: 3.10 - 3.13 | ||||||||
| - **OS**: Linux (x86_64, aarch64), Windows via WSL2 | ||||||||
|
|
||||||||
| ### Development Environment Setup | ||||||||
|
|
||||||||
| ```bash | ||||||||
| # Clone repository | ||||||||
| CUOPT_HOME=$(pwd)/cuopt | ||||||||
| git clone https://github.com/NVIDIA/cuopt.git $CUOPT_HOME | ||||||||
| cd $CUOPT_HOME | ||||||||
|
|
||||||||
| # Create conda environment (recommended) | ||||||||
| conda env create --name cuopt_dev --file conda/environments/all_cuda-130_arch-$(uname -m).yaml | ||||||||
| conda activate cuopt_dev | ||||||||
|
|
||||||||
| # Build all components | ||||||||
| ./build.sh | ||||||||
|
|
||||||||
| # Build specific components | ||||||||
| ./build.sh libmps_parser libcuopt # C++ libraries only | ||||||||
| ./build.sh libcuopt -g # Debug build | ||||||||
| ``` | ||||||||
|
Comment on lines
+64
to
+74
There was a problem hiding this comment. 🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -euo pipefail
# AGENTS.md referenced files (existence check)
ls -la conda/environments 2>/dev/null || echo "conda/environments not found"
ls -la datasets 2>/dev/null || echo "datasets directory not found"
# Find likely matching conda env files
fd -a 'all_cuda-130_arch-.*\.ya?ml' conda/environments 2>/dev/null || echo "No matching conda env files"
# Check referenced dataset scripts
fd -a 'get_test_data\.sh' 2>/dev/null || echo "get_test_data.sh not found"
fd -a 'download_.*_test_dataset\.sh' 2>/dev/null || echo "No matching download scripts"
# Check pytest path exists
ls -la python/cuopt/cuopt/tests 2>/dev/null || echo "Tests directory not found"Repository: NVIDIA/cuopt Length of output: 1609 🏁 Script executed: # Read the full AGENTS.md file to see lines 64-74 and 94-106
cat -n .github/AGENTS.md | sed -n '60,110p'Repository: NVIDIA/cuopt Length of output: 1615 🏁 Script executed: # Check for download scripts in datasets subdirectories
find datasets -name "download_*.sh" -type f 2>/dev/null | sortRepository: NVIDIA/cuopt Length of output: 158 All referenced paths and commands are correct, but fix the shell command structure on line 98. Lines 64-74: The conda environment file ( Lines 94-106: The test data scripts ( However, line 98 is missing the 🤖 Prompt for AI Agents |
||||||||
|
|
||||||||
| ### Quick Install (Users) | ||||||||
|
|
||||||||
| ```bash | ||||||||
| # Pip (CUDA 12.x) | ||||||||
| pip install --extra-index-url=https://pypi.nvidia.com \ | ||||||||
| cuopt-server-cu12==25.12.* cuopt-sh-client==25.12.* | ||||||||
|
|
||||||||
| # Conda | ||||||||
| conda install -c rapidsai -c conda-forge -c nvidia \ | ||||||||
| cuopt-server=25.12.* cuopt-sh-client=25.12.* | ||||||||
| ``` | ||||||||
|
|
||||||||
| --- | ||||||||
|
|
||||||||
| ## Testing Workflows | ||||||||
|
|
||||||||
| ### Running Tests | ||||||||
|
|
||||||||
| ```bash | ||||||||
| # Download test datasets first | ||||||||
| cd $CUOPT_HOME/datasets && ./get_test_data.sh | ||||||||
| cd $CUOPT_HOME && datasets/linear_programming/download_pdlp_test_dataset.sh | ||||||||
| datasets/mip/download_miplib_test_dataset.sh | ||||||||
| export RAPIDS_DATASET_ROOT_DIR=$CUOPT_HOME/datasets/ | ||||||||
|
|
||||||||
| # C++ tests (gtest) | ||||||||
| ctest --test-dir ${CUOPT_HOME}/cpp/build | ||||||||
|
|
||||||||
| # Python tests (pytest) | ||||||||
| pytest -v ${CUOPT_HOME}/python/cuopt/cuopt/tests | ||||||||
| ``` | ||||||||
|
|
||||||||
| ### CI Scripts | ||||||||
|
|
||||||||
| Located in `ci/` directory: | ||||||||
| - `build_cpp.sh` - Build C++ components | ||||||||
| - `build_python.sh` - Build Python packages | ||||||||
| - `test_cpp.sh` - Run C++ tests | ||||||||
| - `test_python.sh` - Run Python tests | ||||||||
| - `check_style.sh` - Code style verification | ||||||||
|
|
||||||||
| --- | ||||||||
|
|
||||||||
| ## Coding Style and Conventions | ||||||||
|
|
||||||||
| ### C++ Style | ||||||||
|
|
||||||||
| - **Naming**: `snake_case` for all names (except test cases which use PascalCase) | ||||||||
| - **Prefixes**: | ||||||||
| - `d_` for device data variables | ||||||||
| - `h_` for host data variables | ||||||||
| - `_t` suffix for template type parameters | ||||||||
| - `_` suffix for private member variables | ||||||||
| - **Formatting**: Enforced by `clang-format` (config: `cpp/.clang-format`) | ||||||||
| - **Include order**: Local → RAPIDS → Related libs → Dependencies → STL | ||||||||
|
|
||||||||
| ```cpp | ||||||||
| // Example naming conventions | ||||||||
| template <typename i_t> | ||||||||
| class locations_t { | ||||||||
| private: | ||||||||
| i_t n_locations_{}; | ||||||||
| i_t* d_locations_{}; // device pointer | ||||||||
| }; | ||||||||
| ``` | ||||||||
| ### File Extensions | ||||||||
| | Extension | Usage | | ||||||||
| |-----------|-------| | ||||||||
| | `.hpp` | C++ headers | | ||||||||
| | `.cpp` | C++ source | | ||||||||
| | `.cu` | CUDA C++ source (nvcc required) | | ||||||||
| | `.cuh` | CUDA headers with device code | | ||||||||
| ### Python Style | ||||||||
| - Follow PEP 8 guidelines | ||||||||
| - Use type hints where applicable | ||||||||
| - Tests use `pytest` framework | ||||||||
| ### Pre-commit Hooks | ||||||||
| ```bash | ||||||||
| # Install pre-commit | ||||||||
| pip install pre-commit | ||||||||
| # Run all checks | ||||||||
| pre-commit run --all-files --show-diff-on-failure | ||||||||
| # Auto-run on commits | ||||||||
| pre-commit install | ||||||||
| ``` | ||||||||
|
|
||||||||
| --- | ||||||||
|
|
||||||||
| ## Pull Request Guidelines | ||||||||
|
|
||||||||
| ### Workflow | ||||||||
|
|
||||||||
| 1. Fork the repository and create a descriptive branch (`fix-documentation`, `add-feature-x`) | ||||||||
| 2. Implement changes with appropriate unit tests | ||||||||
| 3. Run pre-commit hooks: `pre-commit run --all-files` | ||||||||
| 4. Sign off commits: `git commit -s -m "Your message"` | ||||||||
| 5. Open PR (draft for CI testing without review) | ||||||||
| 6. Ensure all CI checks pass | ||||||||
| 7. Address reviewer feedback | ||||||||
|
|
||||||||
| ### Commit Signing (Required) | ||||||||
|
|
||||||||
| All commits must be signed off to certify origin: | ||||||||
|
|
||||||||
| ```bash | ||||||||
| git commit -s -m "Add cool feature" | ||||||||
| # Results in: Signed-off-by: Your Name <[email protected]> | ||||||||
| ``` | ||||||||
|
|
||||||||
| ### Code Review Focus Areas | ||||||||
|
|
||||||||
| - Correctness and performance | ||||||||
| - Memory management (use RMM, avoid raw pointers) | ||||||||
| - CUDA error handling (`RAFT_CUDA_TRY` macro) | ||||||||
| - Test coverage for new functionality | ||||||||
| - Documentation for public APIs | ||||||||
|
|
||||||||
| --- | ||||||||
|
|
||||||||
| ## Common Pitfalls and Troubleshooting | ||||||||
|
|
||||||||
| ### Build Issues | ||||||||
|
|
||||||||
| | Problem | Solution | | ||||||||
| |---------|----------| | ||||||||
| | Cython changes not reflected | Rerun Python build: `./build.sh cuopt` | | ||||||||
| | Missing `nvcc` | Ensure CUDA toolkit in PATH or set `$CUDACXX` | | ||||||||
| | Conda environment issues | Update env: `conda env update --file conda/environments/...` | | ||||||||
|
|
||||||||
| ### Runtime Issues | ||||||||
|
|
||||||||
| | Problem | Solution | | ||||||||
| |---------|----------| | ||||||||
| | CUDA out of memory | Reduce problem size or use streaming | | ||||||||
| | Slow library loading (debug) | Device debug symbols cause delay; use selectively | | ||||||||
| | Import errors | Verify `$CONDA_PREFIX` matches install location | | ||||||||
|
|
||||||||
| ### Debugging | ||||||||
|
|
||||||||
| ```bash | ||||||||
| # Debug build | ||||||||
| ./build.sh libcuopt -g | ||||||||
|
|
||||||||
| # CUDA debugging | ||||||||
| cuda-gdb -ex r --args python script.py | ||||||||
|
|
||||||||
| # Memory checking | ||||||||
| compute-sanitizer --tool memcheck python script.py | ||||||||
| ``` | ||||||||
|
|
||||||||
| ### Adding Device Debug Symbols (Selectively) | ||||||||
|
|
||||||||
| ```cmake | ||||||||
| # In cpp/CMakeLists.txt - only for specific files | ||||||||
| set_source_files_properties(src/routing/data_model_view.cu | ||||||||
| PROPERTIES COMPILE_OPTIONS "-G") | ||||||||
| ``` | ||||||||
|
|
||||||||
| --- | ||||||||
|
|
||||||||
| ## Key Files Reference | ||||||||
|
|
||||||||
| | Purpose | Location | | ||||||||
| |---------|----------| | ||||||||
| | Main build script | `build.sh` | | ||||||||
| | Dependencies | `dependencies.yaml` | | ||||||||
| | C++ formatting | `cpp/.clang-format` | | ||||||||
| | Conda environments | `conda/environments/` | | ||||||||
| | Test data download | `datasets/get_test_data.sh` | | ||||||||
| | CI configuration | `ci/` | | ||||||||
| | Version info | `VERSION` | | ||||||||
|
|
||||||||
| --- | ||||||||
|
|
||||||||
| ## Error Handling Patterns | ||||||||
|
|
||||||||
| ### Runtime Assertions | ||||||||
|
|
||||||||
| ```cpp | ||||||||
| // Use CUOPT_EXPECTS for runtime checks | ||||||||
| CUOPT_EXPECTS(lhs.type() == rhs.type(), "Column type mismatch"); | ||||||||
|
|
||||||||
| // Use CUOPT_FAIL for unreachable code paths | ||||||||
| CUOPT_FAIL("This code path should not be reached."); | ||||||||
| ``` | ||||||||
| ### CUDA Error Checking | ||||||||
| ```cpp | ||||||||
| // Always wrap CUDA calls | ||||||||
| RAFT_CUDA_TRY(cudaMemcpy(&dst, &src, num_bytes)); | ||||||||
| ``` | ||||||||
|
|
||||||||
| --- | ||||||||
|
|
||||||||
| ## Memory Management Guidelines | ||||||||
|
|
||||||||
| - **Never use raw `new`/`delete`** - Use RMM allocators | ||||||||
| - **Prefer `rmm::device_uvector<T>`** for device memory | ||||||||
| - **All operations should be stream-ordered** - Accept `cuda_stream_view` | ||||||||
| - **Views (`*_view` suffix) are non-owning** - Don't manage their lifetime | ||||||||
|
|
||||||||
| --- | ||||||||
|
|
||||||||
| ## Quick Command Reference | ||||||||
|
|
||||||||
| ```bash | ||||||||
| # Build everything | ||||||||
| ./build.sh | ||||||||
|
|
||||||||
| # Build help | ||||||||
| ./build.sh --help | ||||||||
|
|
||||||||
| # Run style checks | ||||||||
| pre-commit run --all-files | ||||||||
|
|
||||||||
| # Run C++ tests | ||||||||
| ctest --test-dir cpp/build | ||||||||
|
|
||||||||
| # Run Python tests | ||||||||
| pytest -v python/cuopt/cuopt/tests | ||||||||
|
|
||||||||
| # Debug build | ||||||||
| ./build.sh libcuopt -g | ||||||||
| ``` | ||||||||
|
|
||||||||
| --- | ||||||||
|
|
||||||||
| *Last updated: December 2024 | cuOpt v25.12* | ||||||||
|
There was a problem hiding this comment. Avoid “emphasis as heading” + update stale metadata (“Last updated: December 2024”) given this PR is Dec 2025. -*Last updated: December 2024 | cuOpt v25.12*
+## Metadata
+Last updated: December 2025 | cuOpt v25.12📝 Committable suggestion
Suggested change
🧰 Tools🪛 markdownlint-cli2 (0.18.1)312-312: Emphasis used instead of a heading (MD036, no-emphasis-as-heading) 🤖 Prompt for AI Agents |
||||||||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| This project has adopted the [Contributor Covenant Code of Conduct](https://docs.rapids.ai/resources/conduct/). |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| @@ -0,0 +1,15 @@ | ||||||||||
| Security | ||||||||||
| --------- | ||||||||||
| NVIDIA is dedicated to the security and trust of our software products and services, including all source code repositories managed through our organization. | ||||||||||
|
|
||||||||||
| If you need to report a security issue, please use the appropriate contact points outlined below. Please do not report security vulnerabilities through GitHub/GitLab. | ||||||||||
|
|
||||||||||
| Reporting Potential Security Vulnerability in NVIDIA cuOpt | ||||||||||
| ---------------------------------------------------------- | ||||||||||
| To report a potential security vulnerability in NVIDIA cuOpt: | ||||||||||
|
|
||||||||||
| - Web: [Security Vulnerability Submission Form](https://www.nvidia.com/object/submit-security-vulnerability.html) | ||||||||||
| - E-Mail: [[email protected]](mailto:[email protected]) | ||||||||||
| - We encourage you to use the following PGP key for secure email communication: [NVIDIA public PGP Key for communication](https://www.nvidia.com/en-us/security/pgp-key) | ||||||||||
| - Please include the following information: | ||||||||||
| - Product/Driver name and version/branch that contains the vulnerability | ||||||||||
|
Comment on lines
+14
to
+15
There was a problem hiding this comment. Fix nested list indentation (markdownlint MD007) to avoid inconsistent rendering. -- Please include the following information:
- - Product/Driver name and version/branch that contains the vulnerability
+- Please include the following information:
+ - Product/Driver name and version/branch that contains the vulnerability📝 Committable suggestion
Suggested change
🧰 Tools🪛 markdownlint-cli2 (0.18.1)15-15: Unordered list indentation (MD007, ul-indent) 🤖 Prompt for AI Agents |
||||||||||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Add a language to the fenced code block (markdownlint MD040).
.github/AGENTS.md around lines 17 to 33: the fenced code block doesn't specify a
language, triggering markdownlint MD040; update the opening fence to include a
language (e.g., use
text orbash) so the block is explicitly annotated andlinting passes, then save the file.