# oskarimikkila/empirical-deep-hedging architecture

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

- Interactive diagram: https://gitdiagram.com/oskarimikkila/empirical-deep-hedging
- Repository: https://github.com/oskarimikkila/empirical-deep-hedging

## Overview

##### Project type and purpose
- This is a Python-based research codebase for “Empirical Deep Hedging” (Mikkilä & Kanniainen, 2021). It implements a deep reinforcement-learning (actor-critic) approach to hedging under various volatility models (GBM, Heston, empirical).
- Key use cases:
- Train a hedging agent (`main.py`)
- Validate and select the best model (`testing.py --validate`)
- Evaluate a trained model on test scenarios (`testing.py --test`)

##### File structure
- Top-level:
- `main.py`, `testing.py` – entry points for training and evaluation
- `requirements.txt`, `settings.json` – global config and dependencies
- `data/` – historical time series and param CSVs
- `settings/` – preconfigured JSONs for different model/risk-factor setups
- `include/` modules:
- `env.py`, `option_functions.py` – simulation environment & option payoffs
- `data_keeper.py` – episode buffer and batch preparation
- `actor_critic.py`, `network.py` – RL agent and neural-network architectures
- `simulation.py` – orchestrates scenario generation loops
- `settings.py` – parses JSON settings into usable parameters
- `utility.py` – logging, metrics, helper routines

##### Key insights from README
- Supports three volatility frameworks (GBM, Heston, Empirical) × three risk factors
- Default settings read from `settings.json` unless overridden by `--settings`
- Targets Python 3.8, tested on Windows; dependencies in `requirements.txt`

##### Main components
a. Data Layer
- Historical time series (`data/1yr_treasury.csv`)
- Model parameters (`data/heston_params.csv`)
- Settings JSONs (`settings/*.json`)
b. Simulation Layer
- `env.py`: market environment stepping
- `option_functions.py`: payoff calculations
- `simulation.py`: runs Monte Carlo scenarios using settings
c. Data Keeper Layer
- `data_keeper.py`: collects transitions, prepares training batches
d. Model Layer
- `network.py`: defines neural-network modules
- `actor_critic.py`: builds the actor and critic, loss functions
e. Orchestration/Control
- `main.py`:
– Load settings + data
– Initialize environment, data keeper, actor-critic agent
– Loop: simulate → collect → train → save checkpoints
- `testing.py`:
– Load saved model
– Re-simulate or replay validation/test episodes
– Compute metrics, pick best checkpoint
f. External Dependencies & Outputs
- PyTorch/TensorFlow (per `requirements.txt`)
- Checkpoint files, logs, result CSVs or figures

##### Relationships and interactions
- Settings JSON → parsed by `settings.py` → passed to `env.py`, `simulation.py`, `network.py`
- Raw data CSVs → loaded by `simulation.py` for scenario generation
- `simulation.py` + `option_functions.py` produce state, reward trajectories → `data_keeper.py`
- `data_keeper.py` yields batches → fed into `actor_critic.py` → updates via `network.py`
- `main.py` orchestrates the train loop; `testing.py` re-uses `env.py` + `network.py` for evaluation

##### Architectural patterns and principles
- Modular separation: data, simulation, model, orchestration
- Configuration-driven via JSON for reproducibility
- Clear pipeline: Input → Simulate → Buffer → Learn → Evaluate
- Single-process batch training (no microservices), but easily parallelizable at the simulation stage

##### Detail level
- Every module in `include/` as its own component
- Data folder and settings folder as sources for the simulation engine
- Model checkpoint files as the output of the training pipeline

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Layer
    subgraph "Data Layer"
        DT1["Historical Time Series<br/>1yr_treasury.csv"]:::data
        DT2["Model Parameters<br/>heston_params.csv"]:::data
        CF["Global Settings<br/>settings.json"]:::data
        CF2["Experiment Settings<br/>settings/*.json"]:::data
    end

    %% Configuration Parser
    subgraph "Configuration Parser"
        SP["JSON Settings Loader<br/>settings.py"]:::data
    end

    %% Simulation Layer
    subgraph "Simulation Layer"
        ENV["Market Environment<br/>include/env.py"]:::sim
        OPT["Option Payoff Functions<br/>include/option_functions.py"]:::sim
        SIM["Scenario Generation Orchestrator<br/>include/simulation.py"]:::sim
    end

    %% Data Keeper Layer
    subgraph "Data Keeper Layer"
        DK["Episode Buffer & Batch Prep<br/>include/data_keeper.py"]:::keeper
    end

    %% Model Layer
    subgraph "Model Layer"
        NN["Neural Network Definitions<br/>include/network.py"]:::model
        AC["Actor-Critic Agent & Loss<br/>include/actor_critic.py"]:::model
    end

    %% Utility & Helpers
    subgraph "Utility & Helpers"
        UH["Logging, Metrics, I/O<br/>include/utility.py"]:::util
    end

    %% Orchestration/Control
    subgraph "Orchestration/Control"
        MAIN(["Training Entry Point<br/>main.py"]):::orch
        TEST(["Validation & Testing<br/>testing.py"]):::orch
    end

    %% External Dependencies & Docs
    subgraph "External & Documentation"
        REQ["Python Packages List<br/>requirements.txt"]:::deps
        RD["Project Overview & Instructions<br/>README.md"]:::docs
    end

    %% Data & Config Flows
    DT1 -->|loads| SIM
    DT2 -->|loads| SIM
    CF -->|parsed by| SP
    CF2 -->|parsed by| SP
    SP -->|settings| ENV
    SP -->|settings| SIM
    SP -->|settings| NN

    %% Simulation to Data Keeper
    SIM -->|trajectories| DK
    OPT -->|payoffs| SIM

    %% Data Keeper to Model
    DK -->|batches| AC
    AC -->|uses| NN

    %% Utility & Helpers connections
    UH -->|logging| MAIN
    UH -->|metrics| TEST
    UH -->|helpers| AC

    %% Orchestration flows
    MAIN -->|init env| ENV
    MAIN -->|train loop| SIM
    MAIN -->|calls| DK
    MAIN -->|updates| AC
    AC -->|checkpoints| MAIN
    MAIN -->|outputs| REQ

    TEST -->|loads model| AC
    TEST -->|replay| ENV
    TEST -->|reports| RD

    %% Dependencies & Docs
    REQ -->|used by| MAIN
    RD -->|guides| MAIN

    %% Click Events
    click DT1 "https://github.com/oskarimikkila/empirical-deep-hedging/blob/master/data/1yr_treasury.csv"
    click DT2 "https://github.com/oskarimikkila/empirical-deep-hedging/blob/master/data/heston_params.csv"
    click CF "https://github.com/oskarimikkila/empirical-deep-hedging/blob/master/settings.json"
    click CF2 "https://github.com/oskarimikkila/empirical-deep-hedging/tree/master/settings"
    click SP "https://github.com/oskarimikkila/empirical-deep-hedging/blob/master/include/settings.py"
    click ENV "https://github.com/oskarimikkila/empirical-deep-hedging/blob/master/include/env.py"
    click OPT "https://github.com/oskarimikkila/empirical-deep-hedging/blob/master/include/option_functions.py"
    click SIM "https://github.com/oskarimikkila/empirical-deep-hedging/blob/master/include/simulation.py"
    click DK "https://github.com/oskarimikkila/empirical-deep-hedging/blob/master/include/data_keeper.py"
    click NN "https://github.com/oskarimikkila/empirical-deep-hedging/blob/master/include/network.py"
    click AC "https://github.com/oskarimikkila/empirical-deep-hedging/blob/master/include/actor_critic.py"
    click UH "https://github.com/oskarimikkila/empirical-deep-hedging/blob/master/include/utility.py"
    click MAIN "https://github.com/oskarimikkila/empirical-deep-hedging/blob/master/main.py"
    click TEST "https://github.com/oskarimikkila/empirical-deep-hedging/blob/master/testing.py"
    click REQ "https://github.com/oskarimikkila/empirical-deep-hedging/blob/master/requirements.txt"
    click RD "https://github.com/oskarimikkila/empirical-deep-hedging/blob/master/README.md"

    %% Styles
    classDef data fill:#cce5ff,stroke:#004085,color:#004085
    classDef sim fill:#d4edda,stroke:#155724,color:#155724
    classDef keeper fill:#fff3cd,stroke:#856404,color:#856404
    classDef model fill:#f8d7da,stroke:#721c24,color:#721c24
    classDef util fill:#e2e3e5,stroke:#383d41,color:#383d41
    classDef orch fill:#e2d4f0,stroke:#4b0082,color:#4b0082
    classDef deps fill:#ffe5b4,stroke:#b35900,color:#b35900
    classDef docs fill:#f0f0f0,stroke:#6c757d,color:#6c757d
```
