diff --git a/.github/AGENTS.md b/.github/AGENTS.md new file mode 100644 index 000000000..3e5184a30 --- /dev/null +++ b/.github/AGENTS.md @@ -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 +``` + +### 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 +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 +``` + +### 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`** 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* diff --git a/.github/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md new file mode 100644 index 000000000..563581d27 --- /dev/null +++ b/.github/CODE_OF_CONDUCT.md @@ -0,0 +1 @@ +This project has adopted the [Contributor Covenant Code of Conduct](https://docs.rapids.ai/resources/conduct/). diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index 9e493f77b..452117b53 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -1,5 +1,5 @@ --- -name: Bug report +name: 🐛 Bug report about: Create a bug report to help us improve cuOpt title: "[BUG]" labels: "? - Needs Triage, bug" diff --git a/.github/ISSUE_TEMPLATE/documentation-request.md b/.github/ISSUE_TEMPLATE/documentation-request.md index 89a026f34..140bef44d 100644 --- a/.github/ISSUE_TEMPLATE/documentation-request.md +++ b/.github/ISSUE_TEMPLATE/documentation-request.md @@ -1,5 +1,5 @@ --- -name: Documentation request +name: 📚 Documentation request about: Report incorrect or needed documentation title: "[DOC]" labels: "? - Needs Triage, doc" diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md index 9bf7d8890..1a5d4e3f3 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -1,5 +1,5 @@ --- -name: Feature request +name: 🚀 Feature request about: Suggest an idea for cuOpt title: "[FEA]" labels: "? - Needs Triage, feature request" diff --git a/.github/ISSUE_TEMPLATE/submit-question.md b/.github/ISSUE_TEMPLATE/submit-question.md index 13271f601..973d9033d 100644 --- a/.github/ISSUE_TEMPLATE/submit-question.md +++ b/.github/ISSUE_TEMPLATE/submit-question.md @@ -1,5 +1,5 @@ --- -name: Submit question +name: ❓ Submit question about: Ask a general question about cuOpt title: "[QST]" labels: "? - Needs Triage, question" diff --git a/.github/SECURITY.md b/.github/SECURITY.md new file mode 100644 index 000000000..2e6ba9ff7 --- /dev/null +++ b/.github/SECURITY.md @@ -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: [psirt@nvidia.com](mailto:psirt@nvidia.com) +- 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 diff --git a/README.md b/README.md index 7924c7b82..b300e6604 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,15 @@ # cuOpt - GPU accelerated Optimization Engine [![Build Status](https://github.com/NVIDIA/cuopt/actions/workflows/build.yaml/badge.svg)](https://github.com/NVIDIA/cuopt/actions/workflows/build.yaml) +[![Version](https://img.shields.io/badge/version-26.02.00-blue)](https://github.com/NVIDIA/cuopt/releases) +[![Documentation](https://img.shields.io/badge/docs-latest-brightgreen)](https://docs.nvidia.com/cuopt/user-guide/latest/introduction.html) +[![Docker Hub](https://img.shields.io/badge/docker-nvidia%2Fcuopt-blue?logo=docker)](https://hub.docker.com/r/nvidia/cuopt) +[![Examples](https://img.shields.io/badge/examples-cuopt--examples-orange)](https://github.com/NVIDIA/cuopt-examples) +[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/NVIDIA/cuopt-examples/blob/cuopt_examples_launcher/cuopt_examples_launcher.ipynb) +[![NVIDIA Launchable](https://img.shields.io/badge/NVIDIA-Launchable-76b900?logo=nvidia)](https://brev.nvidia.com/launchable/deploy?launchableID=env-2qIG6yjGKDtdMSjXHcuZX12mDNJ) +[![Videos and Tutorials](https://img.shields.io/badge/Videos_and_Tutorials-red?logo=youtube)](https://docs.nvidia.com/cuopt/user-guide/latest/resources.html#cuopt-examples-and-tutorials-videos) + + NVIDIA® cuOpt™ is a GPU-accelerated optimization engine that excels in mixed integer linear programming (MILP), linear programming (LP), and vehicle routing problems (VRP). It enables near real-time solutions for large-scale challenges with millions of variables and constraints, offering easy integration into existing solvers and seamless deployment across hybrid and multi-cloud environments. @@ -146,13 +155,3 @@ For current release timelines and dates, refer to the [RAPIDS Maintainers Docs]( ## Contributing Guide Review the [CONTRIBUTING.md](CONTRIBUTING.md) file for information on how to contribute code and issues to the project. - -## Resources - -- [libcuopt (C) documentation](https://docs.nvidia.com/cuopt/user-guide/latest/cuopt-c/index.html) -- [cuopt (Python) documentation](https://docs.nvidia.com/cuopt/user-guide/latest/cuopt-python/index.html) -- [cuopt (Server) documentation](https://docs.nvidia.com/cuopt/user-guide/latest/cuopt-server/index.html) -- [Examples and Notebooks](https://github.com/NVIDIA/cuopt-examples) -- [Test cuopt with NVIDIA Launchable](https://brev.nvidia.com/launchable/deploy?launchableID=env-2qIG6yjGKDtdMSjXHcuZX12mDNJ): Examples notebooks are pulled and hosted on [NVIDIA Launchable](https://docs.nvidia.com/brev/latest/). -- [Test cuopt on Google Colab](https://colab.research.google.com/github/nvidia/cuopt-examples/): Examples notebooks can be opened in Google Colab. Please note that you need to choose a `Runtime` as `GPU` in order to run the notebooks. -- [cuOpt Examples and Tutorial Videos](https://docs.nvidia.com/cuopt/user-guide/latest/resources.html#cuopt-examples-and-tutorials-videos) diff --git a/ci/release/update-version.sh b/ci/release/update-version.sh index 24124ad56..eb85c4a12 100755 --- a/ci/release/update-version.sh +++ b/ci/release/update-version.sh @@ -131,6 +131,9 @@ done PROJECT_FILE="docs/cuopt/source/project.json" sed_runner 's/\("version": "\)[0-9][0-9]\.[0-9][0-9]\.[0-9][0-9]"/\1'${NEXT_FULL_TAG}'"/g' "${PROJECT_FILE}" +# Update README.md version badge +sed_runner 's/badge\/version-[0-9]\+\.[0-9]\+\.[0-9]\+-blue/badge\/version-'${NEXT_FULL_TAG}'-blue/g' README.md + # Update nightly sed_runner 's/'"cuopt_version: \"[0-9][0-9].[0-9][0-9]\""'/'"cuopt_version: \"${NEXT_SHORT_TAG}\""'/g' .github/workflows/nightly.yaml