Public API

Pretrained models

cann.pretrained.PretrainedHeston(artifact_dir=None)

Load the bundled pretrained Heston implied-volatility surrogate.

Parameters:

artifact_dir (str | None) – Optional path to an artifact directory. If not provided, uses the package-bundled cann/artifacts/heston_iv_v1.

Returns:

Loaded trained model wrapper.

Return type:

TrainedModel

Raises:

• FileNotFoundError – If the artifact directory/config/state dict cannot be found.

• ValueError – If the model config does not include train_defaults.

cann.pretrained.PretrainedRoughHeston(artifact_dir=None)

Load the bundled pretrained Rough Heston surrogate.

Parameters:

artifact_dir (str | None) – Optional path to an artifact directory. If not provided, uses the package-bundled cann/artifacts/rough_heston_v1.

Returns:

Loaded trained model wrapper.

Return type:

TrainedModel

Raises:

• FileNotFoundError – If the artifact directory/config/state dict cannot be found.

• ValueError – If the model config does not include train_defaults.

Calibration

cann.engine.calibration.calibrate_model(trained_model, market_surface, calibration_config)

Calibrate model parameters to a market surface using a trained surrogate.

The columns of market_surface.market_inputs must match the feature ordering specified by trained_model.model_config.market_inputs.

This constructs a loss function J(θ) and passes it to the optimizer.

Parameters:

• trained_model (TrainedModel) – The trained surrogate model to be calibrated.

• market_surface (MarketSurface) – The market surface data for calibration.

• calibration_config (CalibrationConfig) – Configuration settings for the calibration process.

Returns:

The result of the calibration optimization.

Return type:

CalibrationResult

Notes

The optimization is performed with a global optimizer (Differential Evolution). Surrogate inference is batched and will use CUDA if available, otherwise CPU.

class cann.engine.calibration_config.CalibrationConfig(optimizer='de', strategy='best1bin', max_iter=2000, pop_size=10, tol=0.01, mutation=(0.5, 1.0), recombination=0.7, init='latinhypercube', polish=True, batch_size=32768, weight_atm=1.0, seed=42)

Bases: object

Settings for the calibration optimization process.

Key fields include max_iter, pop_size, strategy, and inference batch_size.

batch_size = 32768

classmethod from_dict(cfg)

Create a CalibrationConfig instance from a dictionary.

Parameters:

cfg (dict) – Dictionary containing configuration parameters.

Returns:

Parsed calibration configuration.

Return type:

CalibrationConfig

Notes

If mutation is provided as a string (e.g. from YAML), it is parsed via ast.literal_eval() when possible.

init = 'latinhypercube'

max_iter = 2000

mutation = (0.5, 1.0)

optimizer = 'de'

polish = True

pop_size = 10

recombination = 0.7

seed = 42

strategy = 'best1bin'

tol = 0.01

weight_atm = 1.0

class cann.engine.calibration_config.CalibrationResult(optimal_parameters, final_loss, num_iterations, num_function_evals, runtime_seconds, converged, diagnostics)

Bases: object

Result of the calibration optimization process after optimization.

Fields include optimal_parameters, final_loss, convergence diagnostics, and optional optimizer diagnostics.

converged

diagnostics

final_loss

num_function_evals

num_iterations

optimal_parameters

runtime_seconds

Market data

class cann.data.market_surface.MarketSurface(market_inputs, observed, weights=None, metadata=None)

Bases: object

Container for market surface data used in model calibration.

Fields:

market_inputs (shape (N, m)), observed (shape (N,) or (N, 1)), optional weights (shape (N,)), and optional metadata.

market_inputs

metadata = None

observed

weights = None