Getting started
===============

Installation
------------

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

.. code-block:: bash

   pip install calibration-nn

Backward pass (online calibration): calibrate a market surface
--------------------------------------------------------------

This demonstrates the **backward pass (online calibration)** using a bundled pretrained surrogate
(trained during the **forward pass (offline learning)**).

.. code-block:: python

   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()

   # Columns of market_inputs must match trained_model.model_config.market_inputs
   # (in this repo's scripts: [T, K/S, r]).
   market_inputs = np.array(
       [
           [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)