calibration-nn 0.2.0

Open-source Python calibration engine that uses neural networks as fast surrogates to calibrate stochastic volatility models (Heston, rough Heston, Bates, SABR, …) to implied volatility surfaces.

CaNN

CaNN is a Python calibration toolkit that uses neural networks as fast surrogates to calibrate stochastic volatility models (currently shipped with pretrained Heston and Rough Heston) to market surfaces.

Workflow (paper terminology)

CaNN’s workflow can be described in two phases:

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

   (model parameters, market inputs) → model output (typically implied volatility)

2. Backward pass (online calibration): solve the inverse problem using the trained surrogate

   calibrate model parameters to an observed market surface with a global optimizer (Differential Evolution).

For architecture details, see design.md.

Applied in practice (example use case)

The deep calibration technique used in CaNN (train a neural surrogate for fast forward pricing, then solve the inverse problem with a global optimizer) has been applied on real-market calibration problems beyond the toy/academic setting.

One concrete example is:

• Deep calibration of financial models: turning theory into practice (Springer). The authors use a CaNN-style workflow to calibrate the Trolle–Schwartz interest-rate model to swaption data (reported on Commerzbank market data, including stressed periods around COVID). Link (DOI): https://doi.org/10.1007/s11147-021-09183-7

This repository demonstrates the same technique (surrogate training + global optimization for calibration) for Heston and Rough Heston; the model family and market instruments can be swapped as long as you can generate (or obtain) training pairs of:

• parameters,
• market inputs (instrument + state features),
• observed target (e.g., price or implied volatility).

Features

• Model-agnostic configuration via YAML (ModelConfig) defining parameters, market inputs, and outputs.
• Surrogate training with a configurable MLP (PyTorch).
• Calibration via SciPy Differential Evolution with vectorized objective evaluation.
• Pretrained models loader for quick experimentation:
  • cann.pretrained.PretrainedHeston
  • cann.pretrained.PretrainedRoughHeston

Installation

Requirements

• Python >= 3.8
• PyTorch, NumPy, SciPy, Pandas, PyYAML

Install from PyPI

The published package name is calibration-nn (the import name remains cann).

pip install calibration-nn

Backward pass (online calibration): calibrate a market surface

Below is a minimal example using the pretrained Rough Heston surrogate.

import numpy as np

from cann.data.market_surface import MarketSurface
from cann.engine.calibration import calibrate_model
from cann.engine.calibration_config import CalibrationConfig
from cann.pretrained import PretrainedRoughHeston


trained_model = PretrainedRoughHeston()

# Example shapes:
#   market_inputs: (N, m) where columns match trained_model.model_config.market_inputs
#   observed:      (N,) or (N, 1)
market_inputs = np.array(
	[
		# [T, K/S, r]  (example layout used in scripts)
		[0.25, 1.00, 0.02],
		[0.50, 0.95, 0.02],
		[1.00, 1.05, 0.02],
	],
	dtype=float,
)

observed = np.array([0.20, 0.215, 0.23], dtype=float)

market_surface = MarketSurface(
	market_inputs=market_inputs,
	observed=observed,
	weights=None,
)

calib_cfg = trained_model.model_config.calibration_defaults or CalibrationConfig()

result = calibrate_model(
	trained_model=trained_model,
	market_surface=market_surface,
	calibration_config=calib_cfg,
)

print("converged:", result.converged)
print("final_loss:", result.final_loss)
print("optimal_parameters:", result.optimal_parameters)

Notes:

• Calibration uses GPU for surrogate inference if CUDA is available; otherwise it runs on CPU.
• The objective is evaluated in batches (CalibrationConfig.batch_size).

Forward pass (offline learning): train a surrogate (from your own dataset)

Training entrypoint:

• cann.engine.training.train_surrogate(model_config, parameters, market_inputs, observed, ...)

Minimal example (in-memory arrays):

import torch
import numpy as np

from cann.config.model_config import ModelConfig
from cann.engine.training import train_surrogate
from cann.engine.training_config import TrainingConfig


model_config = ModelConfig.from_yaml("cann/artifacts/heston_iv_v1/heston_iv.yaml")

# parameters:   (N, n)
# market_inputs:(N, m)
# observed:     (N,) or (N, 1)
parameters = np.random.randn(1000, model_config.num_parameters).astype(np.float32)
market_inputs = np.random.randn(1000, model_config.num_market_inputs).astype(np.float32)
observed = np.random.randn(1000).astype(np.float32)

training_cfg = model_config.train_defaults or TrainingConfig(epochs=100)

trained_model, test_dataset = train_surrogate(
	model_config=model_config,
	parameters=parameters,
	market_inputs=market_inputs,
	observed=observed,
	training_config=training_cfg,
	verbose=True,
)

# Save weights (pattern used by scripts)
torch.save(
	trained_model.surrogate.network.state_dict(),
	"model_state.pth",
)

Model configuration (YAML)

Model configuration is loaded via ModelConfig.from_yaml(path).

The YAML defines:

• parameters: ordered list of model parameters with bounds
• market_inputs: ordered list of market features
• outputs: ordered list of model outputs (network output dimension = len(outputs))
• optional defaults:
  • train_defaults (TrainingConfig)
  • calibration_defaults (CalibrationConfig)

In this repo, the shipped configs live next to artifacts. You can use them as examples and guides:

• cann/artifacts/heston_iv_v1/heston_iv.yaml

• cann/artifacts/rough_heston_v1/rough_heston.yaml

Pretrained artifacts

cann/pretrained.py loads pretrained checkpoints from cann/artifacts/*.

• It selects the newest model_state_*.pth checkpoint by modification time.
• It rebuilds the MLP architecture from train_defaults inside the YAML config.

Repository layout

High-level code structure:

• cann/config/: model schema (ModelConfig, ParameterSpec, ...)
• cann/data/: ParamSurfaceDataset, MarketSurface
• cann/surrogate/: MLP builder
• cann/engine/: training + calibration entrypoints
• cann/optim/: global optimizer wrapper (SciPy DE)
• cann/artifacts/: pretrained configs + checkpoints