# aditya6969/4fpdv-calibration architecture

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

- Interactive diagram: https://gitdiagram.com/aditya6969/4fpdv-calibration
- Repository: https://github.com/aditya6969/4fpdv-calibration

## Overview

This repository implements a 4-factor path-dependent volatility model calibration pipeline for SPX/VIX options, VIX futures, and historical market series. The principal workflow loads and filters market data, optimizes parameters against a selected calibration objective, then reprices and saves diagnostics; a historical harness repeats that workflow by date. Separate objectives support time-series, likelihood, mixed, and futures fits, while pricing can use Monte Carlo or a VIX neural network. Edges reflect README statements and excerpted/indexed references; unsampled implementation details are not assumed.

Main entry points: [`calibrate.py`](https://github.com/aditya6969/4fpdv-calibration/blob/main/calibrate.py) (Single-date engine), [`pricing_vix_neural_bnp.py`](https://github.com/aditya6969/4fpdv-calibration/blob/main/pricing_vix_neural_bnp.py) (VIX pricing), [`sampler_PDV_bnp.py`](https://github.com/aditya6969/4fpdv-calibration/blob/main/sampler_PDV_bnp.py) (Path simulator), [`mixed_loss.py`](https://github.com/aditya6969/4fpdv-calibration/blob/main/mixed_loss.py) (Mixed objective)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Calibration runs"]
  node_engine["Single-date engine<br/>[calibrate.py]"]
  node_backtest["Historical backtest"]
end

subgraph group_objectives["Calibration objectives"]
  node_spxobjectives["Smile objectives<br/>[calibrate.py]"]
  node_vixobjective["VIX time-series fit<br/>[vix_ts_loss.py]"]
  node_mleobjective["Historical likelihood<br/>[mle_loss.py]"]
  node_mixedobjective["Mixed objective<br/>[mixed_loss.py]"]
  node_futuresobjective["Futures objectives"]
  node_expiry["Expiry extraction"]
end

subgraph group_pricing["Simulation and pricing"]
  node_simulator["Path simulator<br/>[sampler_PDV_bnp.py]"]
  node_vixpricing["VIX pricing"]
end

subgraph group_training["Neural model"]
  node_nnassets["Neural model assets"]
  node_nnscaling["Scaling parameters"]
  node_nngeneration["Training data generation<br/>[train_vix_nn.py]"]
end

node_marketdata[("Market data")]
node_user(("Operator"))
node_results["Calibration results"]

node_user -->|"runs"| node_engine
node_user -->|"starts backtest"| node_backtest
node_backtest -->|"runs per date"| node_engine
node_marketdata -->|"supplies inputs"| node_engine
node_engine -->|"optimizes against"| node_spxobjectives
node_engine -->|"selects objective"| node_vixobjective
node_engine -->|"selects objective"| node_mleobjective
node_engine -->|"selects objective"| node_mixedobjective
node_engine -->|"selects objective"| node_futuresobjective
node_engine -->|"uses expiries"| node_expiry
node_engine -->|"simulates paths"| node_simulator
node_mixedobjective -->|"evaluates likelihood"| node_mleobjective
node_mixedobjective -->|"adds time-series loss"| node_vixobjective
node_mixedobjective -->|"simulates paths"| node_simulator
node_mixedobjective -->|"prices VIX"| node_vixpricing
node_vixobjective -->|"computes VIX"| node_simulator
node_vixobjective -->|"prices VIX"| node_vixpricing
node_futuresobjective -->|"uses time-series loss"| node_vixobjective
node_futuresobjective -->|"simulates paths"| node_simulator
node_futuresobjective -->|"prices VIX"| node_vixpricing
node_vixpricing -->|"uses simulated factors"| node_simulator
node_engine -->|"saves diagnostics"| node_results
node_backtest -->|"reads history"| node_marketdata
node_nngeneration -->|"uses simulator"| node_simulator
node_nngeneration -.->|"generates training data"| node_nnassets
node_vixpricing -.->|"loads model"| node_nnassets
node_vixpricing -.->|"uses scaling"| node_nnscaling

click node_engine "https://github.com/aditya6969/4fpdv-calibration/blob/main/calibrate.py"
click node_backtest "https://github.com/aditya6969/4fpdv-calibration/blob/main/calibrate_historical.py"
click node_marketdata "https://github.com/aditya6969/4fpdv-calibration/tree/main/data"
click node_spxobjectives "https://github.com/aditya6969/4fpdv-calibration/blob/main/calibrate.py"
click node_vixobjective "https://github.com/aditya6969/4fpdv-calibration/blob/main/vix_ts_loss.py"
click node_mleobjective "https://github.com/aditya6969/4fpdv-calibration/blob/main/mle_loss.py"
click node_mixedobjective "https://github.com/aditya6969/4fpdv-calibration/blob/main/mixed_loss.py"
click node_futuresobjective "https://github.com/aditya6969/4fpdv-calibration/blob/main/vix_fut_ts_mle_loss.py"
click node_expiry "https://github.com/aditya6969/4fpdv-calibration/blob/main/times_to_maturity.py"
click node_simulator "https://github.com/aditya6969/4fpdv-calibration/blob/main/sampler_PDV_bnp.py"
click node_vixpricing "https://github.com/aditya6969/4fpdv-calibration/blob/main/pricing_vix_neural_bnp.py"
click node_nnassets "https://github.com/aditya6969/4fpdv-calibration/tree/main/neural_network/model_NN_batch64-7Bayesian"
click node_nnscaling "https://github.com/aditya6969/4fpdv-calibration/tree/main/neural_network/model_NN_batch64-7Bayesian_scaling"
click node_nngeneration "https://github.com/aditya6969/4fpdv-calibration/blob/main/train_vix_nn.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_engine,node_backtest toneBlue
class node_spxobjectives,node_vixobjective,node_mleobjective,node_mixedobjective,node_futuresobjective,node_expiry,node_marketdata toneAmber
class node_simulator,node_vixpricing toneMint
class node_nnassets,node_nnscaling,node_nngeneration toneRose
class node_user,node_results toneIndigo
```

## Components

### Calibration runs

- [Single-date engine](https://github.com/aditya6969/4fpdv-calibration/blob/main/calibrate.py): `calibrate.py`
- [Historical backtest](https://github.com/aditya6969/4fpdv-calibration/blob/main/calibrate_historical.py): `calibrate_historical.py`

### Calibration objectives

- [Smile objectives](https://github.com/aditya6969/4fpdv-calibration/blob/main/calibrate.py): `calibrate.py`
- [VIX time-series fit](https://github.com/aditya6969/4fpdv-calibration/blob/main/vix_ts_loss.py): `vix_ts_loss.py`
- [Historical likelihood](https://github.com/aditya6969/4fpdv-calibration/blob/main/mle_loss.py): `mle_loss.py`
- [Mixed objective](https://github.com/aditya6969/4fpdv-calibration/blob/main/mixed_loss.py): `mixed_loss.py`
- [Futures objectives](https://github.com/aditya6969/4fpdv-calibration/blob/main/vix_fut_ts_mle_loss.py): `vix_fut_ts_mle_loss.py`
- [Expiry extraction](https://github.com/aditya6969/4fpdv-calibration/blob/main/times_to_maturity.py): `times_to_maturity.py`

### Simulation and pricing

- [Path simulator](https://github.com/aditya6969/4fpdv-calibration/blob/main/sampler_PDV_bnp.py): `sampler_PDV_bnp.py`
- [VIX pricing](https://github.com/aditya6969/4fpdv-calibration/blob/main/pricing_vix_neural_bnp.py): `pricing_vix_neural_bnp.py`

### Neural model

- [Neural model assets](https://github.com/aditya6969/4fpdv-calibration/tree/main/neural_network/model_NN_batch64-7Bayesian): `neural_network/model_NN_batch64-7Bayesian`
- [Scaling parameters](https://github.com/aditya6969/4fpdv-calibration/tree/main/neural_network/model_NN_batch64-7Bayesian_scaling): `neural_network/model_NN_batch64-7Bayesian_scaling`
- [Training data generation](https://github.com/aditya6969/4fpdv-calibration/blob/main/train_vix_nn.py): `train_vix_nn.py`

### Other components

- [Market data](https://github.com/aditya6969/4fpdv-calibration/tree/main/data): `data`
- **Operator**
- **Calibration results**

## Connections

- Operator → Single-date engine: runs (evidence: `README.md`)
- Operator → Historical backtest: starts backtest (evidence: `README.md`)
- Historical backtest → Single-date engine: runs per date (evidence: `calibrate_historical.py`)
- Market data → Single-date engine: supplies inputs (evidence: `README.md`)
- Single-date engine → Smile objectives: optimizes against (evidence: `README.md`)
- Single-date engine → VIX time-series fit: selects objective (evidence: `calibrate.py`)
- Single-date engine → Historical likelihood: selects objective (evidence: `calibrate.py`)
- Single-date engine → Mixed objective: selects objective (evidence: `calibrate.py`)
- Single-date engine → Futures objectives: selects objective (evidence: `calibrate.py`)
- Single-date engine → Expiry extraction: uses expiries (evidence: `calibrate.py`)
- Single-date engine → Path simulator: simulates paths (evidence: `calibrate.py`)
- Mixed objective → Historical likelihood: evaluates likelihood (evidence: `mixed_loss.py`)
- Mixed objective → VIX time-series fit: adds time-series loss (evidence: `mixed_loss.py`)
- Mixed objective → Path simulator: simulates paths (evidence: `mixed_loss.py`)
- Mixed objective → VIX pricing: prices VIX (evidence: `mixed_loss.py`)
- VIX time-series fit → Path simulator: computes VIX (evidence: `vix_ts_loss.py`)
- VIX time-series fit → VIX pricing: prices VIX (evidence: `vix_ts_loss.py`)
- Futures objectives → VIX time-series fit: uses time-series loss (evidence: `vix_fut_ts_mle_loss.py`)
- Futures objectives → Path simulator: simulates paths (evidence: `vix_fut_ts_mle_loss.py`)
- Futures objectives → VIX pricing: prices VIX (evidence: `vix_fut_ts_mle_loss.py`)
- VIX pricing → Path simulator: uses simulated factors (evidence: `pricing_vix_neural_bnp.py`)
- Single-date engine → Calibration results: saves diagnostics (evidence: `README.md`)
- Historical backtest → Market data: reads history (evidence: `README.md`)
- Training data generation → Path simulator: uses simulator (evidence: `train_vix_nn.py`)
- Training data generation → Neural model assets: generates training data
- VIX pricing → Neural model assets: loads model
- VIX pricing → Scaling parameters: uses scaling
