{
  "markdown": "<!-- AI agents: Start by reading AGENTS.md -->\n# Portfolio Optimization Powered by NVIDIA cuOpt\n\n[![Build Status](https://github.com/NVIDIA-AI-Blueprints/portfolio-optimization/actions/workflows/main.yml/badge.svg)](https://github.com/NVIDIA-AI-Blueprints/portfolio-optimization/actions/workflows/main.yml)\n[![Checks](https://github.com/NVIDIA-AI-Blueprints/portfolio-optimization/actions/workflows/checks.yml/badge.svg)](https://github.com/NVIDIA-AI-Blueprints/portfolio-optimization/actions/workflows/checks.yml)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)\n[![Contributing](https://img.shields.io/badge/Contributing-Guide-green)](CONTRIBUTING.md)\n\n## Disclaimer\nThis project will download and install additional third-party open source software projects. Review the license terms of these open source projects before use.\n\n---\n\n## Overview\n\nThis portfolio optimization developer example addresses the financial industry's trade-off between **computational speed** and **model complexity**. By leveraging **NVIDIA accelerated computing** — **[NVIDIA cuOpt](https://github.com/NVIDIA/cuopt)** for GPU-accelerated portfolio solves, and **[RAPIDS cuML](https://github.com/rapidsai/cuml)** for GPU scenario generation — this solution transforms robust analysis (e.g., Mean-CVaR, large-scale simulations) from slow batch processing into a **fast, iterative workflow** for dynamic decision-making.\n\n### Accelerated Architecture\n\nThe end-to-end pipeline connects market data ingestion to optimal strategy backtesting using the NVIDIA CUDA ecosystem:\n\n#### 1. Data Science & Scenario Generation\n* **Technology:** **CUDA-X Data Science** — **[RAPIDS cuML](https://github.com/rapidsai/cuml)** for GPU KDE scenario generation\n* **Function:** Accelerates data preprocessing and the learning/sampling of return distributions.\n* **Performance:** Achieves speedups of up to **100x** when generating scenarios.\n\n#### 2. Mean-CVaR Optimization\n* **Technology:** **[NVIDIA cuOpt](https://github.com/NVIDIA/cuopt)** open-source solvers.\n* **Function:** Efficiently solves complex, scenario-based **Mean-CVaR portfolio optimization** problems.\n* **Performance:** Consistently outperforms state-of-the-art CPU-based solvers, with up to **160x speedups** in large-scale problems.\n\n#### 3. Strategy Backtesting & Refinement\n* **Technology:** **CUDA-X Data Science** and **HPC SDK**.\n* **Function:** Rigorously tests the **trading strategies** and provides insights into strategy fine-tuning.\n\n### Key Takeaways\n\n* **Speed-ups:** Up to **160x faster** optimization and **100x faster** scenario generation.\n* **Risk Modeling:** Enables the use of **Conditional Value-at-Risk (CVaR)** at production speed.\n* **Iterative Workflow:** Supports dynamic, fast, and data-driven optimization cycles.\n\n<p align=\"center\">\n    <img src=\"./docs/arch_diagram.png\" alt=\"architecture diagram for PO\" width=\"750\"/>\n</p>\n\n---\n## Get Started\n### System Requirements\n<details>\n<summary><b>Recommended Requirements for Best Performance</b></summary>\n\n- **System Architecture**:\n  - x86-64\n  - ARM64\n- **GPU**:\n  - NVIDIA H100 SXM (compute capability >= 9.0) and above\n- **CPU**:\n  - 32+ cores\n- **System Memory**:\n  - 64+ GB RAM\n- **NVMe SSD Storage**:\n  - 100+ GB free space\n- **CUDA**:\n  - 13.0\n- **NVIDIA Drivers**:\n  - Latest NVIDIA drivers (580.65.06+)\n- **OS**:\n  - Linux distributions with glibc>=2.28 (released in August 2018):\n    - Arch Linux (minimum version 2018-08-02)\n    - Debian (minimum version 10.0)\n    - Fedora (minimum version 29)\n    - Linux Mint (minimum version 20)\n    - Rocky Linux / Alma Linux / RHEL (minimum version 8)\n\nThe above configuration will provide optimal performance for large-scale optimization problems.\n\n</details>\n\n### Installation on PyTorch Container\n\nTo install dependencies on the NVIDIA PyTorch container:\n\n```bash\n# Start the container. Publish 8888 for Jupyter and 8501 for Streamlit.\ndocker run --gpus all -it --rm \\\n  -v ./:/workspace/host \\\n  --ipc=host \\\n  -p 8888:8888 \\\n  -p 8501:8501 \\\n  nvcr.io/nvidia/pytorch:25.10-py3\n\n# Clone the repository\ngit clone https://github.com/NVIDIA-AI-Blueprints/portfolio-optimization.git\ncd portfolio-optimization\n\n# Install uv (if not already installed)\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# To add $HOME/.local/bin to your PATH, either restart your shell or run:\nsource $HOME/.local/bin/env  # (sh, bash, zsh)\n# source $HOME/.local/bin/env.fish  # (fish)\n\n# Install with CUDA-specific dependencies, plus the Jupyter kernel tooling\nuv sync --extra cuda13 --group notebooks # full CUDA 13 stack currently tracks cuOpt/cuML 26.04\n# On CUDA 12 hosts, use the full cuOpt/cuML 26.06 stack:\n# uv sync --extra cuda12 --group notebooks\n# For direct SOCP testing on CUDA 13 with cuOpt 26.06:\n# uv sync --extra cuda13-socp --group notebooks\n\n# Optional: Install development tools (ruff, pytest, pre-commit)\nuv sync --extra cuda13 --group notebooks --group dev\n\n# Create a Jupyter kernel for this environment\nuv run python -m ipykernel install --user --name=portfolio-opt --display-name \"Portfolio Optimization\"\n\n# Launch Jupyter Lab\nuv run jupyter lab --no-browser --NotebookApp.token=''\n```\n\n**Note:** If you use a different container image than the suggested one above, during uv sync, use `--extra cuda12` for the full cuOpt/cuML 26.06 CUDA 12 stack or `--extra cuda13` for the current full CUDA 13 cuOpt/cuML stack. As of the cuOpt 26.06 release, `cuml-cu13` 26.06 is not published, so CUDA 13 SOCP testing with cuOpt 26.06 uses `--extra cuda13-socp`; that extra is cuOpt-only and is intended for direct SOCP preview/Mean-Variance variance-cap solves, not GPU KDE/CVaR rebalancing. The `uv sync` command automatically creates a virtual environment and installs all dependencies from `uv.lock`.\n\n**Tip:** To check your CUDA version, run `nvidia-smi` and look for \"CUDA Version\" in the output.\n\n**Important Notes:**\n- If you encounter \"No space left on device\" errors, set `UV_CACHE_DIR` to an alternate cache location: `export UV_CACHE_DIR=/path/to/cache/directory`\n- The `cuda12`, `cuda13`, and `cuda13-socp` extras are mutually exclusive - install only one based on your system's CUDA version and workflow\n- If you plan to run the Streamlit demo from this container, include `-p 8501:8501` when starting Docker. Docker port mappings cannot be added to an already-running container; restart the container with the port published if it was omitted.\n\n#### Using the Jupyter Kernel\n\nAfter launching Jupyter Lab:\n1. Navigate to the [`notebooks/`](notebooks/) directory\n2. Open any notebook (e.g., `cvar_basic.ipynb`)\n3. Select the \"Portfolio Optimization\" kernel from the kernel selector in the top-right corner\n4. If the kernel is not visible, refresh the page or restart Jupyter Lab\n\nTo list all available kernels:\n```bash\njupyter kernelspec list\n```\n\nTo remove the kernel later (if needed):\n```bash\njupyter kernelspec uninstall portfolio-opt\n```\n\n### Quick Start Locally\n\nExplore the example notebooks in the [`notebooks/`](notebooks/) directory:\n- **`cvar_basic.ipynb`**: Complete walkthrough of Mean-CVaR portfolio optimization with GPU acceleration\n- **`efficient_frontier.ipynb`**: A quick tutorial on how to generate efficient frontier.\n- **`rebalancing_strategies.ipynb`** Introduction to dynamic re-balancing and examples of testing strategies\n\n### Streamlit GTC Demo\n\nThe Streamlit demo from the GTC branch is available under [`demo/`](demo/) as a dynamic rebalancing app.\n\nIf you are using the PyTorch Docker container above, make sure it was started with `-p 8501:8501`. Streamlit must bind to `0.0.0.0` inside the container so the published Docker port can receive browser traffic.\n\n```bash\nuv pip install -r demo/requirements.txt\nuv run python -c \"from portfolio_optimization.utils import download_data; download_data('data/stock_data', datasets=['sp500'])\"\nuv run streamlit run demo/rebalancing_streamlit_app.py --server.address 0.0.0.0 --server.port 8501\n```\n\nFor a remote GPU host, also forward port `8501` from your laptop to the host running Docker:\n\n```bash\nssh -L 8501:localhost:8501 <user>@<remote-host>\n```\n\nSee [`demo/README_streamlit.md`](demo/README_streamlit.md) for focused deployment instructions.\n\n### Deploy on Brev\nDeploy using [Brev launchable](https://brev.nvidia.com/launchable/deploy?launchableID=env-360InRZzyHqDnJYQKIxaSggF8xI): start an instance on Brev.nvidia.com and follow the instructions in the notebooks.\n\n\n---\n## Contribution Guidelines\n\nWe welcome contributions to this project! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines on:\n- Code of conduct\n- How to submit issues and feature requests\n- Pull request process\n- Coding standards and best practices\n\n---\n## Community\n\nFor questions, discussions, and community support:\n- **Issues**: Report bugs and request features via [GitHub Issues](https://github.com/NVIDIA-AI-Blueprints/portfolio-optimization/issues)\n- **Discussions**: Join conversations in [GitHub Discussions](https://github.com/NVIDIA-AI-Blueprints/portfolio-optimization/discussions)\n\n---\n## References\n\n- [NVIDIA cuOpt](https://github.com/NVIDIA/cuopt) — source repository\n- [NVIDIA cuOpt Documentation](https://docs.nvidia.com/cuopt/)\n- [RAPIDS cuML](https://github.com/rapidsai/cuml) — source repository\n- [RAPIDS cuML Documentation](https://docs.rapids.ai/api/cuml/stable/)\n- Markowitz, H. (1952). \"Portfolio Selection\". *The Journal of Finance*, 7(1), 77-91.\n- Rockafellar, R. T., & Uryasev, S. (2000). \"Optimization of conditional value-at-risk\". *Journal of Risk*, 2, 21-42.\n\n---\n## License\n\nThis project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.\n",
  "bytes": 9675,
  "sha": "c9a7c7f14fbf8764cdf5619dcb14d57d823ea23824b6bb89d3e8bd98310c7c5a",
  "repo_slug": "nvidia-ai-blueprints/portfolio-optimization",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_nvidia_ai_blueprints_portfolio_optimizat_c907f0da/readme"
}