# pfnet-research/pfhedge architecture

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

- Interactive diagram: https://gitdiagram.com/pfnet-research/pfhedge
- Repository: https://github.com/pfnet-research/pfhedge

## Overview

#### Purpose and Public Surface
PFHedge is a PyTorch library for Monte Carlo deep hedging of financial derivatives under market frictions. Users compose instruments, a hedging model, input features, and a risk criterion; then train and price through `Hedger`. Package exports are rooted at `pfhedge/__init__.py`, with main public domains in `pfhedge/instruments/__init__.py` and `pfhedge/nn/__init__.py`. Runnable usage entry points are the scripts/notebook in `examples/`, especially `examples/example_readme.py`.

#### Instrument Domain Model
The instrument layer separates tradable simulated underliers (“primary” instruments) from contingent claims (“derivatives”). Shared abstractions establish the contract and likely device/dtype/state behavior at `pfhedge/instruments/base.py`, `pfhedge/instruments/primary/base.py`, and `pfhedge/instruments/derivative/base.py`. Derivative implementations bind one or more underliers and define payoff/contract-specific attributes, e.g. `pfhedge/instruments/derivative/european.py`, `pfhedge/instruments/derivative/lookback.py`, and `pfhedge/instruments/derivative/variance_swap.py`.

#### Market Simulation Pipeline
Primary instruments model paths and market costs; concrete models include geometric Brownian, stochastic-volatility, rates, and jump processes in `pfhedge/instruments/primary/brownian.py`, `pfhedge/instruments/primary/heston.py`, and `pfhedge/instruments/primary/rough_bergomi.py`. The underlying stochastic-process implementations are factored into `pfhedge/stochastic/engine.py`, `pfhedge/stochastic/brownian.py`, and `pfhedge/stochastic/heston.py`. This boundary lets instruments expose finance-facing objects while stochastic modules generate tensor-valued paths.

#### Feature Assembly
Feature objects turn derivative state, underlier paths, and prior hedge decisions into model inputs. The extensible feature contract and lookup mechanism live in `pfhedge/features/_base.py` and `pfhedge/features/_getter.py`; composition/container handling is in `pfhedge/features/container.py`. Features are central to the recurrent control loop because `prev_hedge` makes each time-step decision depend on the prior position.

#### Hedging and Optimization Orchestration
`pfhedge/nn/modules/hedger.py` is the main application controller and PyTorch `Module`: it simulates/evaluates a derivative, constructs sequential feature tensors, invokes the strategy, derives portfolio P&L including transaction costs, applies a risk criterion, and supports fitting/pricing. Strategy networks and controls include `pfhedge/nn/modules/mlp.py`, `pfhedge/nn/modules/clamp.py`, and `pfhedge/nn/modules/naked.py`. Training delegates parameter updates to standard PyTorch optimizers; GPU and dtype movement follow PyTorch module/tensor semantics.

#### Models, Baselines, and Risk Objectives
Risk measures used as training objectives reside in `pfhedge/nn/modules/loss.py`, including entropic risk and expected shortfall. Analytic/model-based benchmark strategies are organized under `pfhedge/nn/modules/bs/`, with generic Black-Scholes machinery in `pfhedge/nn/modules/bs/_base.py` and derivative-specific formulas such as `pfhedge/nn/modules/bs/european.py`. Transaction-cost-aware Whalley–Wilmott logic is in `pfhedge/nn/modules/ww.py`; SVI-related modeling is in `pfhedge/nn/modules/svi.py`.

#### Differentiation, Runtime, and Delivery
`pfhedge/autogreek.py` differentiates user pricing functions through PyTorch autograd to calculate Greeks, crossing the pricing/autodiff boundary without separate finite-difference infrastructure. The material runtime dependency is PyTorch; no server, database, or external market-data service is represented. Packaging is defined by `pyproject.toml`; GitHub Actions provides CI, docs, examples, release, and version-bump workflows under `.github/workflows/`. Documentation is built from `docs/source/`.

Main entry points: [`pfhedge/nn/modules/hedger.py`](https://github.com/pfnet-research/pfhedge/blob/main/pfhedge/nn/modules/hedger.py) (Hedger), [`pfhedge/__init__.py`](https://github.com/pfnet-research/pfhedge/blob/main/pfhedge/__init__.py) (PFHedge exports), [`pfhedge/instruments/derivative/base.py`](https://github.com/pfnet-research/pfhedge/blob/main/pfhedge/instruments/derivative/base.py) (Derivative contracts), [`pfhedge/instruments/base.py`](https://github.com/pfnet-research/pfhedge/blob/main/pfhedge/instruments/base.py) (Instrument contracts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public["Public Surface"]
  node_example["Runnable examples<br/>usage entry point<br/>[example_readme.py]"]
  node_package["PFHedge exports<br/>package API<br/>[__init__.py]"]
  node_instrument_api["Instrument exports<br/>domain API<br/>[__init__.py]"]
  node_nn_api["Neural API<br/>domain API<br/>[__init__.py]"]
end

subgraph group_market["Instruments &amp; Simulation"]
  node_instrument_base["Instrument contracts<br/>abstract domain model<br/>[base.py]"]
  node_primary["Primary instruments<br/>tradable simulators<br/>[base.py]"]
  node_derivative["Derivative contracts<br/>contingent claims<br/>[base.py]"]
  node_derivative_impl["Derivative implementations<br/>claim models<br/>[european.py]"]
  node_primary_models["Market model instruments<br/>primary models<br/>[brownian.py]"]
  node_stochastic["Stochastic processes<br/>path generators<br/>[engine.py]"]
end

subgraph group_hedging["Hedging Runtime"]
  node_features["Feature system<br/>feature contract<br/>[_base.py]"]
  node_feature_container["Feature composition<br/>feature assembly<br/>[container.py]"]
  node_hedger["Hedger<br/>PyTorch controller<br/>[hedger.py]"]
  node_strategy["Strategy networks<br/>hedge controls<br/>[mlp.py]"]
  node_risk["Risk objectives<br/>loss criteria<br/>[loss.py]"]
  node_benchmarks["Analytic benchmarks<br/>model strategies<br/>[_base.py]"]
  node_autogreek["AutoGreek<br/>autodiff utility<br/>[autogreek.py]"]
end

subgraph group_delivery["Delivery"]
  node_packaging["Package build<br/>packaging<br/>[pyproject.toml]"]
  node_ci["GitHub Actions<br/>automation"]
  node_docs["Documentation source"]
end

node_example -->|"uses"| node_package
node_package -->|"exports"| node_instrument_api
node_package -->|"exports"| node_nn_api
node_instrument_api -->|"exposes"| node_instrument_base
node_instrument_base -->|"base for"| node_primary
node_instrument_base -->|"base for"| node_derivative
node_derivative -->|"implemented by"| node_derivative_impl
node_derivative -->|"binds underliers"| node_primary
node_primary -->|"implemented by"| node_primary_models
node_primary_models -->|"uses paths from"| node_stochastic
node_hedger -->|"simulates and values"| node_derivative
node_hedger -->|"assembles inputs"| node_feature_container
node_feature_container -->|"composes"| node_features
node_features -->|"reads state"| node_derivative
node_hedger -->|"invokes sequentially"| node_strategy
node_strategy -->|"consumes feature tensors"| node_features
node_hedger -->|"optimizes"| node_risk
node_benchmarks -.->|"provides baseline strategies"| node_strategy
node_autogreek -.->|"differentiates pricing functions"| node_hedger
node_packaging -->|"builds"| node_package
node_ci -->|"validates and releases"| node_packaging
node_docs -.->|"documents"| node_package

click node_example "https://github.com/pfnet-research/pfhedge/blob/main/examples/example_readme.py"
click node_package "https://github.com/pfnet-research/pfhedge/blob/main/pfhedge/__init__.py"
click node_instrument_api "https://github.com/pfnet-research/pfhedge/blob/main/pfhedge/instruments/__init__.py"
click node_nn_api "https://github.com/pfnet-research/pfhedge/blob/main/pfhedge/nn/__init__.py"
click node_instrument_base "https://github.com/pfnet-research/pfhedge/blob/main/pfhedge/instruments/base.py"
click node_primary "https://github.com/pfnet-research/pfhedge/blob/main/pfhedge/instruments/primary/base.py"
click node_derivative "https://github.com/pfnet-research/pfhedge/blob/main/pfhedge/instruments/derivative/base.py"
click node_derivative_impl "https://github.com/pfnet-research/pfhedge/blob/main/pfhedge/instruments/derivative/european.py"
click node_primary_models "https://github.com/pfnet-research/pfhedge/blob/main/pfhedge/instruments/primary/brownian.py"
click node_stochastic "https://github.com/pfnet-research/pfhedge/blob/main/pfhedge/stochastic/engine.py"
click node_features "https://github.com/pfnet-research/pfhedge/blob/main/pfhedge/features/_base.py"
click node_feature_container "https://github.com/pfnet-research/pfhedge/blob/main/pfhedge/features/container.py"
click node_hedger "https://github.com/pfnet-research/pfhedge/blob/main/pfhedge/nn/modules/hedger.py"
click node_strategy "https://github.com/pfnet-research/pfhedge/blob/main/pfhedge/nn/modules/mlp.py"
click node_risk "https://github.com/pfnet-research/pfhedge/blob/main/pfhedge/nn/modules/loss.py"
click node_benchmarks "https://github.com/pfnet-research/pfhedge/blob/main/pfhedge/nn/modules/bs/_base.py"
click node_autogreek "https://github.com/pfnet-research/pfhedge/blob/main/pfhedge/autogreek.py"
click node_packaging "https://github.com/pfnet-research/pfhedge/blob/main/pyproject.toml"

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_example,node_package,node_instrument_api,node_nn_api toneBlue
class node_instrument_base,node_primary,node_derivative,node_derivative_impl,node_primary_models,node_stochastic toneAmber
class node_features,node_feature_container,node_hedger,node_strategy,node_risk,node_benchmarks,node_autogreek toneMint
class node_packaging,node_ci,node_docs toneRose
```

## Components

### Public Surface

- [Runnable examples](https://github.com/pfnet-research/pfhedge/blob/main/examples/example_readme.py): usage entry point · Demonstrates instrument-to-training workflows. · `examples/example_readme.py`
- [PFHedge exports](https://github.com/pfnet-research/pfhedge/blob/main/pfhedge/__init__.py): package API · `pfhedge/__init__.py`
- [Instrument exports](https://github.com/pfnet-research/pfhedge/blob/main/pfhedge/instruments/__init__.py): domain API · `pfhedge/instruments/__init__.py`
- [Neural API](https://github.com/pfnet-research/pfhedge/blob/main/pfhedge/nn/__init__.py): domain API · `pfhedge/nn/__init__.py`

### Instruments & Simulation

- [Instrument contracts](https://github.com/pfnet-research/pfhedge/blob/main/pfhedge/instruments/base.py): abstract domain model · Defines shared instrument state, device, and dtype behavior. · `pfhedge/instruments/base.py`
- [Primary instruments](https://github.com/pfnet-research/pfhedge/blob/main/pfhedge/instruments/primary/base.py): tradable simulators · Finance-facing underliers with paths and market costs. · `pfhedge/instruments/primary/base.py`
- [Derivative contracts](https://github.com/pfnet-research/pfhedge/blob/main/pfhedge/instruments/derivative/base.py): contingent claims · Bind underliers and define payoffs. · `pfhedge/instruments/derivative/base.py`
- [Derivative implementations](https://github.com/pfnet-research/pfhedge/blob/main/pfhedge/instruments/derivative/european.py): claim models · European, lookback, and variance-swap contracts. · `pfhedge/instruments/derivative/european.py`
- [Market model instruments](https://github.com/pfnet-research/pfhedge/blob/main/pfhedge/instruments/primary/brownian.py): primary models · Brownian, Heston, and rough Bergomi underliers. · `pfhedge/instruments/primary/brownian.py`
- [Stochastic processes](https://github.com/pfnet-research/pfhedge/blob/main/pfhedge/stochastic/engine.py): path generators · Generates tensor-valued market paths for instruments. · `pfhedge/stochastic/engine.py`

### Hedging Runtime

- [Feature system](https://github.com/pfnet-research/pfhedge/blob/main/pfhedge/features/_base.py): feature contract · Resolves derivative state, paths, and prior hedge inputs. · `pfhedge/features/_base.py`
- [Feature composition](https://github.com/pfnet-research/pfhedge/blob/main/pfhedge/features/container.py): feature assembly · `pfhedge/features/container.py`
- [Hedger](https://github.com/pfnet-research/pfhedge/blob/main/pfhedge/nn/modules/hedger.py): PyTorch controller · Runs sequential hedging, P&L, fitting, and pricing. · `pfhedge/nn/modules/hedger.py`
- [Strategy networks](https://github.com/pfnet-research/pfhedge/blob/main/pfhedge/nn/modules/mlp.py): hedge controls · MLP strategies and position constraints. · `pfhedge/nn/modules/mlp.py`
- [Risk objectives](https://github.com/pfnet-research/pfhedge/blob/main/pfhedge/nn/modules/loss.py): loss criteria · Entropic risk and expected shortfall objectives. · `pfhedge/nn/modules/loss.py`
- [Analytic benchmarks](https://github.com/pfnet-research/pfhedge/blob/main/pfhedge/nn/modules/bs/_base.py): model strategies · Black-Scholes and transaction-cost-aware baselines. · `pfhedge/nn/modules/bs/_base.py`
- [AutoGreek](https://github.com/pfnet-research/pfhedge/blob/main/pfhedge/autogreek.py): autodiff utility · Computes Greeks through PyTorch autograd. · `pfhedge/autogreek.py`

### Delivery

- [Package build](https://github.com/pfnet-research/pfhedge/blob/main/pyproject.toml): packaging · `pyproject.toml`
- **GitHub Actions**: automation · Runs CI, docs, examples, releases, and version bumps.
- **Documentation source**: documentation

## Connections

- Runnable examples → PFHedge exports: uses
- PFHedge exports → Instrument exports: exports
- PFHedge exports → Neural API: exports
- Instrument exports → Instrument contracts: exposes
- Instrument contracts → Primary instruments: base for
- Instrument contracts → Derivative contracts: base for
- Derivative contracts → Derivative implementations: implemented by
- Derivative contracts → Primary instruments: binds underliers
- Primary instruments → Market model instruments: implemented by
- Market model instruments → Stochastic processes: uses paths from
- Hedger → Derivative contracts: simulates and values
- Hedger → Feature composition: assembles inputs
- Feature composition → Feature system: composes
- Feature system → Derivative contracts: reads state
- Hedger → Strategy networks: invokes sequentially
- Strategy networks → Feature system: consumes feature tensors
- Hedger → Risk objectives: optimizes
- Analytic benchmarks → Strategy networks: provides baseline strategies
- AutoGreek → Hedger: differentiates pricing functions
- Package build → PFHedge exports: builds
- GitHub Actions → Package build: validates and releases
- Documentation source → PFHedge exports: documents