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:

  - :class:`cann.data.datasets.ParamSurfaceDataset` for synthetic training tuples
  - :class:`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 :class:`cann.engine.training.TrainedModel`.
  The public entrypoint is :func:`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 :func:`cann.engine.calibration.calibrate_model`.

Optimization
  Provides global optimization routines (currently Differential Evolution).


Public API Entry Points
-----------------------

- Training: :func:`cann.engine.training.train_surrogate`
- Calibration: :func:`cann.engine.calibration.calibrate_model`
- Pretrained artifacts: :func:`cann.pretrained.PretrainedHeston` and
  :func:`cann.pretrained.PretrainedRoughHeston`