Merge pull request #15 from NVIDIA-AI-Blueprints/features/uv-lock_sequence_diagram

Migrate to uv package manager

Author: phuo-nv

.github/workflows/main.yml

@@ -50,22 +50,18 @@ jobs:
               python --version
               nvidia-smi
 
-              echo "===================== Create Virtual Environment ====================="
-              python -m venv .venv
-              source .venv/bin/activate
+              echo "===================== Install uv ====================="
+              curl -LsSf https://astral.sh/uv/install.sh | sh
+              export PATH="/root/.cargo/bin:$PATH"
 
-              echo "===================== Install Dependencies ====================="
-              python -m pip install --upgrade pip
-              pip install .
-
-              echo "===================== Install Development Tools ====================="
-              pip install ".[dev]"
+              echo "===================== Install Dependencies with uv ====================="
+              uv sync --extra dev
 
               echo "===================== Install Jupyter ====================="
-              pip install jupyter jupyterlab ipykernel papermill nbconvert
+              uv pip install jupyter jupyterlab ipykernel papermill nbconvert
 
               echo "===================== Create Jupyter Kernel ====================="
-              python -m ipykernel install --user --name=portfolio-opt --display-name "Portfolio Optimization"
+              uv run python -m ipykernel install --user --name=portfolio-opt --display-name "Portfolio Optimization"
 
               echo "===================== List Jupyter Kernel ====================="
               jupyter kernelspec list

.github/workflows/release-2512.yml

@@ -51,22 +51,18 @@ jobs:
               python --version
               nvidia-smi
 
-              echo "===================== Create Virtual Environment ====================="
-              python -m venv .venv
-              source .venv/bin/activate
+              echo "===================== Install uv ====================="
+              curl -LsSf https://astral.sh/uv/install.sh | sh
+              export PATH="/root/.cargo/bin:$PATH"
 
-              echo "===================== Install Dependencies ====================="
-              python -m pip install --upgrade pip
-              pip install .
-
-              echo "===================== Install Development Tools ====================="
-              pip install ".[dev]"
+              echo "===================== Install Dependencies with uv ====================="
+              uv sync --extra dev
 
               echo "===================== Install Jupyter ====================="
-              pip install jupyter jupyterlab ipykernel papermill nbconvert
+              uv pip install jupyter jupyterlab ipykernel papermill nbconvert
 
               echo "===================== Create Jupyter Kernel ====================="
-              python -m ipykernel install --user --name=portfolio-opt --display-name "Portfolio Optimization"
+              uv run python -m ipykernel install --user --name=portfolio-opt --display-name "Portfolio Optimization"
 
               echo "===================== List Jupyter Kernel ====================="
               jupyter kernelspec list

.gitignore

@@ -26,10 +26,14 @@ wheels/
 
 # Virtual environments
 venv/
+.venv/
 env/
 ENV/
 cufolio_venv/
 
+# uv cache
+.uv/
+
 # Jupyter Notebook
 .ipynb_checkpoints
 

CONTRIBUTING.md

@@ -44,25 +44,29 @@ There are many ways to contribute to Quantitative Portfolio Optimization develop
    cd cufolio
    ```
 
-2. **Create a Virtual Environment**
+2. **Install uv (if not already installed)**
 
    ```bash
-   python -m venv .venv
-   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+   curl -LsSf https://astral.sh/uv/install.sh | sh
+   ```
+
+   For Windows, use:
+   ```powershell
+   powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
    ```
 
 3. **Install Development Dependencies**
 
    ```bash
-   pip install -e ".[dev]"
+   uv sync --extra dev
    ```
 
-   This installs NVIDIA GPU-Accelerated Portfolio Optimization in editable mode along with development tools like `black`, `isort`, `flake8`, and `pre-commit`.
+   This automatically creates a virtual environment and installs the project in editable mode along with development tools like `black`, `isort`, `flake8`, and `pre-commit`.
 
 4. **Set Up Pre-commit Hooks**
 
    ```bash
-   pre-commit install
+   uv run pre-commit install
    ```
 
    This will automatically run code formatting and linting checks before each commit.
@@ -74,7 +78,8 @@ For a consistent development environment with all GPU dependencies:
 ```bash
 docker run --gpus all -it --rm -v $(pwd):/workspace nvcr.io/nvidia/pytorch:25.08-py3
 cd /workspace
-pip install -e ".[dev]"
+curl -LsSf https://astral.sh/uv/install.sh | sh
+uv sync --extra dev
 ```
 
 ## Coding Standards
@@ -97,8 +102,8 @@ All code must be formatted with:
 Run formatters before committing:
 
 ```bash
-black .
-isort .
+uv run black .
+uv run isort .
 ```
 
 Or let pre-commit hooks handle it automatically.
@@ -108,7 +113,7 @@ Or let pre-commit hooks handle it automatically.
 We use `flake8` for linting. Run it with:
 
 ```bash
-flake8 src/ 
+uv run flake8 src/ 
 ```
 
 ### Documentation
@@ -151,13 +156,13 @@ We encourage comprehensive testing of all new features and bug fixes.
 
 ```bash
 # Run all tests
-pytest
+uv run pytest
 
 # Run specific test file
-pytest tests/test_cvar_optimizer.py
+uv run pytest tests/test_cvar_optimizer.py
 
 # Run with coverage
-pytest --cov=src --cov-report=html
+uv run pytest --cov=src --cov-report=html
 ```
 
 ### Writing Tests
@@ -220,10 +225,10 @@ Explain what changes were made and why.
 2. **Run all checks** before submitting:
 
    ```bash
-   black .
-   isort .
-   flake8 src/
-   pytest
+   uv run black .
+   uv run isort .
+   uv run flake8 src/
+   uv run pytest
    ```
 
 3. **Create a Pull Request** with:

README.md

@@ -110,27 +110,26 @@ docker run --gpus all -it --rm nvcr.io/nvidia/pytorch:25.08-py3
 git clone https://github.com/NVIDIA-AI-Blueprints/quantitative-portfolio-optimization.git
 cd quantitative-portfolio-optimization
 
-# Create and activate virtual environment
-python -m venv .venv
-source .venv/bin/activate
+# Install uv (if not already installed)
+curl -LsSf https://astral.sh/uv/install.sh | sh
 
-# Install with all dependencies
-pip install .
+# Install with all dependencies using uv
+uv sync
 
 # Optional: Install development tools
-pip install ".[dev]"
+uv sync --extra dev
 
 # Install Jupyter and create kernel
-pip install jupyter jupyterlab ipykernel
+uv pip install jupyter jupyterlab ipykernel
 
 # Create a Jupyter kernel for this environment
-python -m ipykernel install --user --name=portfolio-opt --display-name "Portfolio Optimization"
+uv run python -m ipykernel install --user --name=portfolio-opt --display-name "Portfolio Optimization"
 
 # Launch Jupyter Lab
-jupyter lab
+uv run jupyter lab
 ```
 
-**Note:** The PyTorch container already includes CUDA and other GPU dependencies. This installation adds the optimization and ML libraries (cuOpt, cuML).
+**Note:** The PyTorch container already includes CUDA and other GPU dependencies. This installation adds the optimization and ML libraries (cuOpt, cuML). The `uv sync` command automatically creates a virtual environment and installs all dependencies from `uv.lock`.
 
 #### Using the Jupyter Kernel
 

pyproject.toml

@@ -41,6 +41,24 @@ cufolio = "src"
 [tool.setuptools.package-data]
 "*" = ["*.csv", "*.pkl", "*.parquet"]
 
+[tool.uv]
+managed = true
+index-url = "https://pypi.org/simple"
+
+[[tool.uv.index]]
+name = "nvidia"
+url = "https://pypi.nvidia.com/cuopt-cu13/"
+explicit = true
+
+[[tool.uv.index]]
+name = "nvidia-ml"
+url = "https://pypi.nvidia.com/cuml-cu13/"
+explicit = true
+
+[tool.uv.sources]
+cuopt-cu13 = { index = "nvidia" }
+cuml-cu13 = { index = "nvidia-ml" }
+
 [build-system]
 requires = ["setuptools>=64", "wheel"]
 build-backend = "setuptools.build_meta"