# pyportfolio/pyportfolioopt architecture

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

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

## Overview

PyPortfolioOpt is a Python library for estimating portfolio inputs, optimizing continuous asset weights, and converting weights into purchasable share allocations. Its principal workflow, documented in the README, starts with price data, estimates expected returns and risk, optimizes weights, then optionally discretizes them using latest prices and a portfolio budget. The library also offers Black–Litterman, Critical Line Algorithm, hierarchical risk parity, and alternative risk objectives. Internal optimizer and objective-function modules support several optimization paths. Some subsystems are represented from the README and source index; unsampled implementation details and links are omitted where their runtime relationships are not shown.

Main entry points: [`pypfopt/efficient_frontier/efficient_frontier.py`](https://github.com/pyportfolio/pyportfolioopt/blob/main/pypfopt/efficient_frontier/efficient_frontier.py) (Mean-variance frontier), [`pypfopt/base/_base_optimizer.py`](https://github.com/pyportfolio/pyportfolioopt/blob/main/pypfopt/base/_base_optimizer.py) (Optimizer base), [`pypfopt/risk_models.py`](https://github.com/pyportfolio/pyportfolioopt/blob/main/pypfopt/risk_models.py) (Risk models), [`pypfopt/discrete_allocation.py`](https://github.com/pyportfolio/pyportfolioopt/blob/main/pypfopt/discrete_allocation.py) (Share allocation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Return And Risk Inputs"]
  node_expected["Expected returns"]
  node_risk["Risk models<br/>[risk_models.py]"]
end

subgraph group_optimization["Portfolio Optimization"]
  node_frontier["Mean-variance frontier"]
  node_cla["Critical Line Algorithm<br/>[cla.py]"]
  node_blacklitterman["Black-Litterman<br/>[black_litterman.py]"]
  node_hierarchical["Hierarchical Risk Parity"]
  node_semivariance["Semivariance frontier"]
  node_cvar["CVaR frontier<br/>[efficient_cvar.py]"]
  node_cdar["CDaR frontier<br/>[efficient_cdar.py]"]
end

subgraph group_allocation["Portfolio Construction"]
  node_discrete["Share allocation"]
  node_plotting["Portfolio plotting<br/>[plotting.py]"]
end

subgraph group_foundation["Optimizer Foundation"]
  node_objectives["Objective functions"]
  node_base["Optimizer base<br/>[_base_optimizer.py]"]
  node_exceptions["Optimization errors<br/>[exceptions.py]"]
end

node_investor(("Portfolio user"))
node_prices["Historical price data"]
node_continuous["Continuous portfolio weights"]
node_latest["Latest asset prices"]
node_purchased["Discrete holdings"]

node_investor -->|"supplies"| node_prices
node_prices -->|"estimates returns"| node_expected
node_prices -->|"estimates covariance"| node_risk
node_expected -->|"provides estimates"| node_frontier
node_risk -->|"provides covariance"| node_frontier
node_frontier -->|"optimizes weights"| node_continuous
node_continuous -->|"converts weights"| node_discrete
node_latest -->|"prices assets"| node_discrete
node_discrete -->|"returns holdings"| node_purchased
node_frontier -->|"inherits optimizer"| node_base
node_cla -->|"inherits optimizer"| node_base
node_blacklitterman -->|"inherits optimizer"| node_base
node_semivariance -->|"extends frontier"| node_frontier
node_cvar -->|"extends frontier"| node_frontier
node_cdar -->|"extends frontier"| node_frontier
node_hierarchical -.->|"uses risk models"| node_risk
node_frontier -.->|"uses objectives"| node_objectives
node_base -.->|"raises errors"| node_exceptions

click node_expected "https://github.com/pyportfolio/pyportfolioopt/blob/main/pypfopt/expected_returns.py"
click node_risk "https://github.com/pyportfolio/pyportfolioopt/blob/main/pypfopt/risk_models.py"
click node_frontier "https://github.com/pyportfolio/pyportfolioopt/blob/main/pypfopt/efficient_frontier/efficient_frontier.py"
click node_cla "https://github.com/pyportfolio/pyportfolioopt/blob/main/pypfopt/cla.py"
click node_blacklitterman "https://github.com/pyportfolio/pyportfolioopt/blob/main/pypfopt/black_litterman.py"
click node_hierarchical "https://github.com/pyportfolio/pyportfolioopt/blob/main/pypfopt/hierarchical_portfolio.py"
click node_semivariance "https://github.com/pyportfolio/pyportfolioopt/blob/main/pypfopt/efficient_frontier/efficient_semivariance.py"
click node_cvar "https://github.com/pyportfolio/pyportfolioopt/blob/main/pypfopt/efficient_frontier/efficient_cvar.py"
click node_cdar "https://github.com/pyportfolio/pyportfolioopt/blob/main/pypfopt/efficient_frontier/efficient_cdar.py"
click node_objectives "https://github.com/pyportfolio/pyportfolioopt/blob/main/pypfopt/objective_functions.py"
click node_base "https://github.com/pyportfolio/pyportfolioopt/blob/main/pypfopt/base/_base_optimizer.py"
click node_exceptions "https://github.com/pyportfolio/pyportfolioopt/blob/main/pypfopt/exceptions.py"
click node_discrete "https://github.com/pyportfolio/pyportfolioopt/blob/main/pypfopt/discrete_allocation.py"
click node_plotting "https://github.com/pyportfolio/pyportfolioopt/blob/main/pypfopt/plotting.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_expected,node_risk,node_investor toneBlue
class node_frontier,node_cla,node_blacklitterman,node_hierarchical,node_semivariance,node_cvar,node_cdar toneAmber
class node_discrete,node_plotting toneMint
class node_objectives,node_base,node_exceptions toneRose
class node_prices,node_continuous,node_latest,node_purchased toneIndigo
```

## Components

### Return And Risk Inputs

- [Expected returns](https://github.com/pyportfolio/pyportfolioopt/blob/main/pypfopt/expected_returns.py): `pypfopt/expected_returns.py`
- [Risk models](https://github.com/pyportfolio/pyportfolioopt/blob/main/pypfopt/risk_models.py): `pypfopt/risk_models.py`

### Portfolio Optimization

- [Mean-variance frontier](https://github.com/pyportfolio/pyportfolioopt/blob/main/pypfopt/efficient_frontier/efficient_frontier.py): `pypfopt/efficient_frontier/efficient_frontier.py`
- [Critical Line Algorithm](https://github.com/pyportfolio/pyportfolioopt/blob/main/pypfopt/cla.py): `pypfopt/cla.py`
- [Black-Litterman](https://github.com/pyportfolio/pyportfolioopt/blob/main/pypfopt/black_litterman.py): `pypfopt/black_litterman.py`
- [Hierarchical Risk Parity](https://github.com/pyportfolio/pyportfolioopt/blob/main/pypfopt/hierarchical_portfolio.py): `pypfopt/hierarchical_portfolio.py`
- [Semivariance frontier](https://github.com/pyportfolio/pyportfolioopt/blob/main/pypfopt/efficient_frontier/efficient_semivariance.py): `pypfopt/efficient_frontier/efficient_semivariance.py`
- [CVaR frontier](https://github.com/pyportfolio/pyportfolioopt/blob/main/pypfopt/efficient_frontier/efficient_cvar.py): `pypfopt/efficient_frontier/efficient_cvar.py`
- [CDaR frontier](https://github.com/pyportfolio/pyportfolioopt/blob/main/pypfopt/efficient_frontier/efficient_cdar.py): `pypfopt/efficient_frontier/efficient_cdar.py`

### Portfolio Construction

- [Share allocation](https://github.com/pyportfolio/pyportfolioopt/blob/main/pypfopt/discrete_allocation.py): `pypfopt/discrete_allocation.py`
- [Portfolio plotting](https://github.com/pyportfolio/pyportfolioopt/blob/main/pypfopt/plotting.py): `pypfopt/plotting.py`

### Optimizer Foundation

- [Objective functions](https://github.com/pyportfolio/pyportfolioopt/blob/main/pypfopt/objective_functions.py): `pypfopt/objective_functions.py`
- [Optimizer base](https://github.com/pyportfolio/pyportfolioopt/blob/main/pypfopt/base/_base_optimizer.py): `pypfopt/base/_base_optimizer.py`
- [Optimization errors](https://github.com/pyportfolio/pyportfolioopt/blob/main/pypfopt/exceptions.py): `pypfopt/exceptions.py`

### Other components

- **Portfolio user**
- **Historical price data**
- **Continuous portfolio weights**
- **Latest asset prices**
- **Discrete holdings**

## Connections

- Portfolio user → Historical price data: supplies (evidence: `README.md`)
- Historical price data → Expected returns: estimates returns (evidence: `README.md`)
- Historical price data → Risk models: estimates covariance (evidence: `README.md`)
- Expected returns → Mean-variance frontier: provides estimates (evidence: `README.md`)
- Risk models → Mean-variance frontier: provides covariance (evidence: `README.md`)
- Mean-variance frontier → Continuous portfolio weights: optimizes weights (evidence: `README.md`)
- Continuous portfolio weights → Share allocation: converts weights (evidence: `README.md`)
- Latest asset prices → Share allocation: prices assets (evidence: `README.md`)
- Share allocation → Discrete holdings: returns holdings (evidence: `README.md`)
- Mean-variance frontier → Optimizer base: inherits optimizer (evidence: `pypfopt/efficient_frontier/efficient_frontier.py`)
- Critical Line Algorithm → Optimizer base: inherits optimizer (evidence: `pypfopt/cla.py`)
- Black-Litterman → Optimizer base: inherits optimizer (evidence: `pypfopt/black_litterman.py`)
- Semivariance frontier → Mean-variance frontier: extends frontier (evidence: `pypfopt/efficient_frontier/efficient_semivariance.py`)
- CVaR frontier → Mean-variance frontier: extends frontier (evidence: `pypfopt/efficient_frontier/efficient_cvar.py`)
- CDaR frontier → Mean-variance frontier: extends frontier (evidence: `pypfopt/efficient_frontier/efficient_cdar.py`)
- Hierarchical Risk Parity → Risk models: uses risk models (evidence: `pypfopt/hierarchical_portfolio.py`)
- Mean-variance frontier → Objective functions: uses objectives (evidence: `pypfopt/efficient_frontier/efficient_frontier.py`)
- Optimizer base → Optimization errors: raises errors (evidence: `pypfopt/base/_base_optimizer.py`)
