Portfolio Risk Simulation

High-performance Monte Carlo simulation for portfolio risk analysis with GPU acceleration and vectorized operations.

Features

• High Performance: GPU acceleration (CuPy) and optimized NumPy vectorization.
• Interactive Visualizations: Beautiful, interactive charts with Plotly for comprehensive analysis.
• Risk Metrics: VaR, CVaR, percentiles, and probability distributions.
• Flexible Configuration: Easy portfolio setup and customizable parameters.
• Professional Output: Detailed reporting with comprehensive metrics.
• Modern Python: Type hints, dataclasses, and clean architecture.

Quick Start

Automated Installation (Recommended)

cd monte-carlo
./scripts/setup.sh
# Choose: 1) Basic 2) Performance 3) GPU 4) Development 5) Full

Using Makefile (Alternative)

make setup-env      # Create virtual environment
make install-dev    # Install development dependencies
make dev-setup      # Complete development setup

Manual Installation

python -m venv .venv
source .venv/bin/activate
pip install -r requirements/core.txt

Docker Installation

# Development environment
docker-compose --profile dev up monte-carlo-dev

# Production environment
docker-compose --profile prod up monte-carlo-prod

# GPU-accelerated environment (requires NVIDIA Docker)
docker-compose --profile gpu up monte-carlo-gpu

Usage

Basic Simulation

python -m portfolio_risk.simulation                    # Run simulation
N_PATHS=5000000 python -m portfolio_risk.simulation    # Custom parameters
monte-carlo-sim                                         # Using installed script

With Interactive Visualizations

VISUALIZE=true python -m portfolio_risk.simulation           # Show interactive charts
SAVE_CHARTS=true python -m portfolio_risk.simulation         # Save charts to files
VISUALIZE=true SAVE_CHARTS=true python -m portfolio_risk.simulation  # Both

Makefile Commands

Environment Setup

make setup-env      # Create virtual environment
make install        # Install core dependencies
make install-dev    # Install development dependencies
make install-gpu    # Install GPU dependencies
make dev-setup      # Complete development setup

Development

make format         # Format code with black and isort
make lint           # Run linting with flake8
make type-check     # Run type checking with mypy
make quality-check  # Run all code quality checks

Testing

make test           # Run tests
make test-coverage  # Run tests with coverage report
make benchmark      # Run performance benchmarks

Execution

make run            # Run simulation
make run-small      # Run with 100K paths
make run-medium     # Run with 1M paths
make run-large      # Run with 10M paths
make run-xlarge     # Run with 50M paths

Docker

make docker-build   # Build Docker images
make docker-dev     # Run development container
make docker-prod    # Run production container
make docker-gpu     # Run GPU container
make docker-test    # Run tests in container

Configuration

Environment Variables

N_PATHS=10000000          # Number of simulation paths
HORIZON_YEARS=1.0         # Time horizon in years
INITIAL_VALUE=100000.0    # Initial portfolio value
RANDOM_SEED=42            # Random seed for reproducibility
LOG_LEVEL=INFO            # Logging level (DEBUG, INFO, WARNING, ERROR)
VISUALIZE=false           # Show interactive visualizations (true/false)
SAVE_CHARTS=false         # Save charts to files (true/false)

Portfolio Setup

Modify parameters in the create_default_portfolio_config() function.

Performance Optimizations

Strategy	Speedup	Description
GPU Acceleration	10-100x	CUDA with CuPy for massive parallelism.
Vectorized Operations	10-50x	NumPy vectorization and SIMD.
Memory Optimization	2-5x	Efficient float32 arrays and caching.
JIT Compilation	5-20x	Optional Numba for critical paths.

Example Output

Console Output

======================================================================
    MONTE CARLO PORTFOLIO RISK ANALYSIS RESULTS
======================================================================

[SIMULATION CONFIGURATION]
   Device:                    CPU (NumPy)
   Simulation Paths:          10,000,000
   Time Horizon:              1.0 years
   Initial Portfolio Value:   $100,000.00
   Computation Time:          0.20 seconds

[PORTFOLIO PARAMETERS]
   Expected Annual Return:    0.0725 (7.25%)
   Annual Volatility:         0.1249 (12.49%)

[RISK METRICS]
   Mean Terminal Value:       $107,518.44
   Standard Deviation:        $13,478.73
   10th Percentile:           $90,904.80
   Median (50th Percentile):  $106,684.56
   90th Percentile:           $125,203.61
   Value at Risk (95%):       $13,122.99
   Conditional VaR (95%):     $17,452.44
   Probability of Loss:       30.23%
======================================================================

Interactive Visualizations

When enabled with VISUALIZE=true, the simulation generates:

• Distribution Histogram: Terminal portfolio values distribution
• Risk Metrics Chart: Key percentiles visualization
• VaR/CVaR Analysis: Value at Risk and Conditional VaR
• Cumulative Distribution: CDF with probability analysis
• Simulation Paths Over Time: Visualization of individual paths showing portfolio evolution
• Comprehensive Dashboard: All charts in a single interactive view with 5 subplots

Charts can be saved as HTML (interactive) and PNG (static) with SAVE_CHARTS=true.

Development

Code Quality

make quality-check                    # Run all quality checks
make format                          # Format code
make lint                            # Run linting
make type-check                      # Type checking

Testing

make test                            # Run tests
make test-coverage                   # Run tests with coverage
pytest tests/ -v --cov=portfolio_risk  # Manual testing

Performance Analysis

make profile                         # Profile performance

Docker Development

make docker-dev                      # Development container
make docker-test                     # Test in container
docker-compose --profile dev up      # Full development environment

CI/CD

The project includes GitHub Actions workflows for:

• Continuous Integration: Tests across multiple Python versions and OS
• Code Quality: Linting, type checking, and security scans
• Performance: Automated benchmarking
• Security: Bandit security analysis and dependency scanning
• Publishing: Automated PyPI publishing on releases

Project Structure

monte-carlo/
├── .github/workflows/     # GitHub Actions CI/CD
├── config/               # Configuration files
├── portfolio_risk/       # Portfolio risk analysis package
├── requirements/         # Dependency specifications
├── scripts/             # Setup and utility scripts
├── tests/               # Test suite
├── docker-compose.yml   # Docker orchestration
├── Dockerfile          # Multi-stage Docker build
├── Makefile           # Development commands
└── pyproject.toml     # Modern Python packaging

Dependencies

Category	Package	Purpose
Core	numpy, scipy	Numerical computing and statistics.
Visualization	plotly, kaleido	Interactive charts and static exports.
Performance	numba, psutil	Optional JIT compilation and monitoring.
GPU	cupy-cuda11x/12x	Optional CUDA acceleration.
Development	pytest, pytest-cov	Testing and coverage.
Quality	black, flake8, mypy, isort	Code formatting, linting, type checking.
Container	docker, docker-compose	Containerization and orchestration.

Troubleshooting

Issue	Solution
CUDA not found	Install CUDA toolkit or use CPU-only mode (automatic fallback).
Memory errors	Reduce N_PATHS parameter (e.g., from 10M to 1M paths).
Import errors	Activate virtual environment: source .venv/bin/activate
Slow performance	If you have NVIDIA GPU + CUDA: make install-gpu. Otherwise, reduce N_PATHS or use smaller simulations.

License

MIT License.