Design

This page is a Sphinx-rendered version of the project design notes in docs/design.md.

Problem Statement

CaNN calibrates option pricing models (e.g. Rough Heston, Bates) to market data.

To match the naming used in the paper, the workflow can be described in two phases:

1. Forward pass (offline learning): learn a surrogate mapping from

model parameters + market conditions → implied volatility

2. Backward pass (online calibration): invert that mapping with a global optimizer to fit model parameters to an observed market surface.

Mathematical Overview

For detailed math and notation, see the repository document docs/math-overview.md and the included HTML export docs/math.html.

High-Level Architecture

Model Configuration

A structural description of:

• parameter vector $theta in mathbb{R}^n$ (names, bounds, metadata)

• market condition vector $x in mathbb{R}^m$ (feature names, metadata)

• outputs (typically implied volatility)

Data

Two primary containers:

• cann.data.datasets.ParamSurfaceDataset for synthetic training tuples

• cann.data.market_surface.MarketSurface for a single observed market snapshot

Surrogate Network

A model-agnostic MLP built from configuration:

• input dimension n + m

• output dimension len(outputs)

Training Engine

Trains the surrogate and returns a cann.engine.training.TrainedModel. The public entrypoint is cann.engine.training.train_surrogate().

Calibration Engine

Defines a weighted MSE loss over market points and minimizes it with a global optimizer. The public entrypoint is cann.engine.calibration.calibrate_model().

Optimization

Provides global optimization routines (currently Differential Evolution).

Public API Entry Points

• Training: cann.engine.training.train_surrogate()

• Calibration: cann.engine.calibration.calibrate_model()

• Pretrained artifacts: cann.pretrained.PretrainedHeston() and cann.pretrained.PretrainedRoughHeston()