# robertmartin8/pyportfolioopt architecture

> Architecture diagram of the GitHub repository robertmartin8/pyportfolioopt, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/robertmartin8/pyportfolioopt
- Repository: https://github.com/robertmartin8/pyportfolioopt

## Overview

##### Project type and purpose
- This is an open-source, full-featured Python library (PyPortfolioOpt) for quantitative portfolio optimization.
- It provides modules to compute expected returns, estimate risk (covariance), define objective functions, solve optimization problems (mean-variance, Black-Litterman, CVaR, HRP, etc.), and convert continuous weights to discrete allocations.

##### File structure
- Top-level directories:
- pypfopt/            ← core Python package
- tests/              ← pytest test suite + test resources
- docs/               ← Sphinx documentation source
- cookbook/           ← Jupyter notebooks & sample data
- example/            ← standalone example scripts
- docker/             ← Dockerfile for containerized usage
- Root config files: setup.py, pyproject.toml, requirements.txt, .github workflows (CI), readthedocs.yml
- CI/CD: GitHub Actions (.github/workflows), codecov integration
- Packaging: supports pip, poetry, Docker, editable installs

##### README for additional insights
- Key external dependencies: pandas, numpy, cvxpy, scikit-learn (for covariance shrinkage), matplotlib (via plotting module)
- Architectural principles: modularity (swap in custom components), layered design, extensive testing (pytest), inline & external docs (Sphinx)

##### Main components and their interactions
a. User Interface Layer
- Python API (import pypfopt)
- Example scripts & Jupyter notebooks (cookbook/, example/)
- CLI via Docker container or interactive IPython/Jupyter
b. Data Ingestion Layer
- pandas DataFrames loaded from CSVs or external price APIs
- test fixtures under tests/resources
c. Core Library Layer (pypfopt package)
- expected_returns.py
- risk_models.py
- objective_functions.py
- base_optimizer.py (abstract interface)
- black_litterman.py
- discrete_allocation.py
- cla.py (Critical Line Algorithm)
- hierarchical_portfolio.py
- plotting.py
- exceptions.py
d. Solver Layer
- cvxpy (quadratic programming)
- scikit-learn covariance estimators (Ledoit-Wolf, OAS, etc.)
e. Persistence & I/O
- save_weights_to_file (CSV)
- get_latest_prices (web API)
f. Testing & Quality
- pytest tests that exercise every module
- CI pipelines: linting (.flake8), coverage, GitHub Actions
g. Documentation
- Sphinx source in docs/, ReadTheDocs integration
- Media assets for conceptual flowcharts & plots
h. Deployment / Packaging
- setup.py / pyproject.toml for PyPI distribution
- Dockerfile for containerized dev & execution

##### Relationships & Data Flow
- User code loads price data → pandas DataFrame → feed into expected_returns & risk_models → yield μ (vector) & Σ (matrix) → instantiate Optimizer (EfficientFrontier, CVaR, HRP, CLA, etc.) → call objective (max_sharpe, min_volatility, efficient_return, etc.) → cvxpy solver → raw_weights → cleaned_weights → optional discrete_allocation → output (weights.csv or Python dict).

##### Architectural patterns & design principles
- Layered architecture: clear separation between data input, computation, optimization, I/O.
- Modular plugin pattern: users can add custom objectives via ef.add_objective.
- Dependency inversion: core optimizers depend on abstract base_optimizer and interface, not concrete solvers.
- Extensive testing enforces correctness and facilitates refactoring.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface Layer"
        direction TB
        UI_API["Python API (import pypfopt)"]:::ui
        ExampleScripts["Example Scripts"]:::ui
        Notebooks["Jupyter Notebooks & Sample Data"]:::ui
    end

    %% Data Ingestion Layer
    subgraph "Data Ingestion Layer"
        direction TB
        DataCSV{{"CSV Files"}}:::data
        ExternalAPI["External Price APIs"]:::external
        TestResources{{"Test Resources"}}:::data
    end

    %% Core Library Layer
    subgraph "Core Library Layer"
        direction TB
        Init["pypfopt/__init__.py"]:::core
        ExpectedReturns["pypfopt/expected_returns.py"]:::core
        RiskModels["pypfopt/risk_models.py"]:::core
        ObjectiveFunctions["pypfopt/objective_functions.py"]:::core
        BaseOptimizer["pypfopt/base_optimizer.py"]:::core
        BlackLitterman["pypfopt/black_litterman.py"]:::core
        DiscreteAllocation["pypfopt/discrete_allocation.py"]:::core
        CLA["pypfopt/cla.py"]:::core
        HRP["pypfopt/hierarchical_portfolio.py"]:::core
        Plotting["pypfopt/plotting.py"]:::core
        Exceptions["pypfopt/exceptions.py"]:::core
        subgraph "Efficient Frontier Modules"
            direction TB
            EF_MV["efficient_frontier/efficient_frontier.py"]:::core
            EF_CVaR["efficient_frontier/efficient_cvar.py"]:::core
            EF_CDaR["efficient_frontier/efficient_cdar.py"]:::core
            EF_Semi["efficient_frontier/efficient_semivariance.py"]:::core
        end
    end

    %% Solver Layer
    subgraph "Solver Layer"
        direction TB
        CVXPy["cvxpy"]:::external
        Sklearn["scikit-learn"]:::external
    end

    %% Persistence & I/O
    subgraph "Persistence & I/O"
        direction TB
        SaveWeights{{"save_weights_to_file (CSV)"}}:::data
        GetPrices["get_latest_prices()"]:::external
    end

    %% Testing & Quality
    subgraph "Testing & Quality"
        direction TB
        Tests["pytest Test Suite"]:::ci
        Lint["flake8 Linting"]:::ci
        Coverage["Codecov"]:::ci
        GitHubActions["GitHub Actions CI"]:::ci
    end

    %% Documentation
    subgraph "Documentation"
        direction TB
        SphinxDocs["Sphinx Source (docs/)"]:::doc
        MediaAssets["Media Assets"]:::doc
    end

    %% Deployment / Packaging
    subgraph "Deployment / Packaging"
        direction TB
        Setup["setup.py & pyproject.toml"]:::ci
        Dockerfile["docker/Dockerfile"]:::ci
    end

    %% Relationships
    UI_API -->|loads data| DataCSV
    UI_API -->|calls API| ExternalAPI
    ExampleScripts --> DataCSV
    Notebooks --> DataCSV
    DataCSV --> ExpectedReturns
    ExternalAPI --> GetPrices
    GetPrices --> ExpectedReturns
    ExpectedReturns --> RiskModels
    RiskModels --> ObjectiveFunctions
    ObjectiveFunctions --> BaseOptimizer
    BaseOptimizer -->|instantiates| EF_MV
    BaseOptimizer -->|instantiates| EF_CVaR
    BaseOptimizer -->|instantiates| EF_CDaR
    BaseOptimizer -->|instantiates| EF_Semi
    BaseOptimizer --> BlackLitterman
    BaseOptimizer --> CLA
    BaseOptimizer --> HRP
    EF_MV --> CVXPy
    EF_CVaR --> CVXPy
    EF_CDaR --> CVXPy
    EF_Semi --> CVXPy
    CVXPy -->|"solves optimization"| BaseOptimizer
    Sklearn --> RiskModels
    BaseOptimizer --> DiscreteAllocation
    DiscreteAllocation --> SaveWeights
    SaveWeights -->|"output CSV"| UI_API

    Tests --> ExpectedReturns
    Tests --> RiskModels
    Tests --> ObjectiveFunctions
    Tests --> BaseOptimizer
    Tests --> BlackLitterman
    Tests --> DiscreteAllocation
    Tests --> CLA
    Tests --> HRP
    Tests --> Plotting
    Tests --> EF_MV
    GitHubActions --> Tests
    GitHubActions --> Lint
    GitHubActions --> Coverage

    ExampleScripts --> SphinxDocs
    Notebooks --> SphinxDocs
    SphinxDocs --> MediaAssets

    Setup -->|package for PyPI| UI_API
    Dockerfile -->|container for UI| UI_API

    %% Click Events
    click ExpectedReturns "https://github.com/robertmartin8/pyportfolioopt/blob/master/pypfopt/expected_returns.py"
    click RiskModels "https://github.com/robertmartin8/pyportfolioopt/blob/master/pypfopt/risk_models.py"
    click ObjectiveFunctions "https://github.com/robertmartin8/pyportfolioopt/blob/master/pypfopt/objective_functions.py"
    click BaseOptimizer "https://github.com/robertmartin8/pyportfolioopt/blob/master/pypfopt/base_optimizer.py"
    click BlackLitterman "https://github.com/robertmartin8/pyportfolioopt/blob/master/pypfopt/black_litterman.py"
    click DiscreteAllocation "https://github.com/robertmartin8/pyportfolioopt/blob/master/pypfopt/discrete_allocation.py"
    click CLA "https://github.com/robertmartin8/pyportfolioopt/blob/master/pypfopt/cla.py"
    click HRP "https://github.com/robertmartin8/pyportfolioopt/blob/master/pypfopt/hierarchical_portfolio.py"
    click Plotting "https://github.com/robertmartin8/pyportfolioopt/blob/master/pypfopt/plotting.py"
    click Exceptions "https://github.com/robertmartin8/pyportfolioopt/blob/master/pypfopt/exceptions.py"
    click EF_MV "https://github.com/robertmartin8/pyportfolioopt/blob/master/pypfopt/efficient_frontier/efficient_frontier.py"
    click EF_CVaR "https://github.com/robertmartin8/pyportfolioopt/blob/master/pypfopt/efficient_frontier/efficient_cvar.py"
    click EF_CDaR "https://github.com/robertmartin8/pyportfolioopt/blob/master/pypfopt/efficient_frontier/efficient_cdar.py"
    click EF_Semi "https://github.com/robertmartin8/pyportfolioopt/blob/master/pypfopt/efficient_frontier/efficient_semivariance.py"
    click Init "https://github.com/robertmartin8/pyportfolioopt/blob/master/pypfopt/__init__.py"
    click ExampleScripts "https://github.com/robertmartin8/pyportfolioopt/blob/master/example/examples.py"
    click Notebooks "https://github.com/robertmartin8/pyportfolioopt/tree/master/cookbook/"
    click SphinxDocs "https://github.com/robertmartin8/pyportfolioopt/tree/master/docs/"
    click Dockerfile "https://github.com/robertmartin8/pyportfolioopt/tree/master/docker/Dockerfile"
    click Setup "https://github.com/robertmartin8/pyportfolioopt/blob/master/setup.py"
    click GitHubActions "https://github.com/robertmartin8/pyportfolioopt/blob/master/.github/workflows/main.yml"
    click Coverage "https://github.com/robertmartin8/pyportfolioopt/blob/master/.github/workflows/codecov.yml"
    click Tests "https://github.com/robertmartin8/pyportfolioopt/tree/master/tests/"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#1E90FF,color:#000;
    classDef external fill:#90EE90,stroke:#228B22,color:#000;
    classDef ui fill:#D3D3D3,stroke:#696969,color:#000;
    classDef data fill:#FFE4B5,stroke:#FF8C00,color:#000;
    classDef ci fill:#FFA07A,stroke:#FF4500,color:#000;
    classDef doc fill:#DDA0DD,stroke:#800080,color:#000;
```
