Models¶

Short-rate and volatility models.

models ¶

Runtime source shim for the native itofin.models submodule.

The real itofin.models is a compiled submodule registered into sys.modules by the extension (see crates/itofin-py/src/lib.rs); it wins at import time, so nothing here runs. This file exists only so static type checkers resolve from itofin.models import ... from models.pyi without a reportMissingModuleSource warning.

Auto-generated by scripts/gen_submodule_shims.py from models.pyi; do not edit or delete by hand.

HestonModel ¶

HestonModel(process: HestonProcess)

The five-parameter calibrated Heston model.

The parameters are seeded from the process it is built on and overwritten in place by a calibration, so the getters read the fitted values afterwards.

Seed the model from a process.

Parameters:

Name	Type	Description	Default
`process`	`HestonProcess`	The process whose five parameters seed the model.	required

Raises:

Type	Description
`ItofinError`	If a seeded parameter violates its constraint: theta, kappa, sigma and v0 must be strictly positive and rho must lie in [-1, 1].

theta ¶

theta() -> float

Return the long-run variance.

Returns:

Name	Type	Description
`float`	`float`	The current value of theta.

kappa ¶

kappa() -> float

Return the mean-reversion speed.

Returns:

Name	Type	Description
`float`	`float`	The current value of kappa.

sigma ¶

sigma() -> float

Return the volatility of variance.

Returns:

Name	Type	Description
`float`	`float`	The current value of sigma.

rho ¶

rho() -> float

Return the spot/variance correlation.

Returns:

Name	Type	Description
`float`	`float`	The current value of rho.

v0 ¶

v0() -> float

Return the initial variance.

Returns:

Name	Type	Description
`float`	`float`	The current value of v0.

calibrate ¶

calibrate(helpers: list[HestonModelHelper], method: LevenbergMarquardt, end_criteria: EndCriteria, integration_order: int) -> None

Fit the five parameters to the helpers and write them back.

One analytic Heston engine of the given integration order is built on this model and installed on every helper, so all helpers price through the same engine the optimizer drives. The fitted parameters are readable through the getters afterwards.

Parameters:

Name	Type	Description	Default
`helpers`	`list[HestonModelHelper]`	The calibration instruments to fit; must not be empty.	required
`method`	`LevenbergMarquardt`	The optimizer driving the fit.	required
`end_criteria`	`EndCriteria`	The stopping rule handed to the optimizer.	required
`integration_order`	`int`	The order of the Gauss-Laguerre integration the engine uses; at most 192.	required

Raises:

Type	Description
`ItofinError`	If integration_order exceeds 192, if helpers is empty, or if the optimization itself fails.

HullWhite ¶

HullWhite(curve: YieldTermStructure, a: float, sigma: float)

The one-factor Hull-White short-rate model.

Fitted to the term structure it is built on; a calibration overwrites a and sigma in place, so the getters read the fitted values afterwards.

Fit the model to a term structure.

Parameters:

Name	Type	Description	Default
`curve`	`YieldTermStructure`	The term structure the model fits; its forward rate at 0 is read at construction.	required
`a`	`float`	The mean-reversion speed, under the Vasicek positivity constraint.	required
`sigma`	`float`	The short-rate volatility, under the same constraint.	required

Raises:

Type	Description
`ItofinError`	If the curve is empty or a parameter violates its constraint.

a ¶

a() -> float

Return the mean-reversion speed.

Returns:

Name	Type	Description
`float`	`float`	The current value of a, read as the first calibrated-model
	`float`	parameter.

sigma ¶

sigma() -> float

Return the short-rate volatility.

Returns:

Name	Type	Description
`float`	`float`	The current value of sigma, read as the second calibrated-model
	`float`	parameter.

r0 ¶

r0() -> float

Return the fitted initial short rate.

Returns:

Name	Type	Description
`float`	`float`	The short rate r0 implied by the fitted term structure.

discount_bond_option ¶

discount_bond_option(option_type: OptionType, strike: float, maturity: float, bond_maturity: float) -> float

Price a European option on a zero-coupon bond.

Parameters:

Name	Type	Description	Default
`option_type`	`OptionType`	Call or put.	required
`strike`	`float`	The option strike, as a bond price.	required
`maturity`	`float`	The option expiry, as a time in years.	required
`bond_maturity`	`float`	The maturity of the underlying zero-coupon bond, as a time in years.	required

Returns:

Name	Type	Description
`float`	`float`	The option price.

Raises:

Type	Description
`ItofinError`	If the fitted curve is not linked or the arguments are rejected by the underlying Black formula.

calibrate ¶

calibrate(helpers: list[SwaptionHelper], method: LevenbergMarquardt, end_criteria: EndCriteria, fix_reversion: bool) -> None

Fit a and sigma to the helpers and write them back.

One Jamshidian swaption engine is built on this model and installed on every helper, so all swaptions price through the same analytic engine the optimizer drives.

Parameters:

Name	Type	Description	Default
`helpers`	`list[SwaptionHelper]`	The calibration instruments to fit; must not be empty.	required
`method`	`LevenbergMarquardt`	The optimizer driving the fit.	required
`end_criteria`	`EndCriteria`	The stopping rule handed to the optimizer.	required
`fix_reversion`	`bool`	Pin the mean reversion a and free only sigma; when False both parameters are free.	required

Raises:

Type	Description
`ItofinError`	If helpers is empty or the optimization itself fails.

HestonModelHelper ¶

HestonModelHelper(maturity: Period, calendar: Calendar, s0: float, strike: float, volatility: float, risk_free_rate: float, dividend_yield: float, error_type: CalibrationErrorType, reference_date: Date, day_counter: DayCounter, settings: Settings)

A Black-vol calibration helper over a flat-vol surface.

Assembles its own volatility quote and two flat curves from the scalar market inputs, so no handle crosses the binding boundary.

Build the helper from scalar market inputs.

Parameters:

Name	Type	Description	Default
`maturity`	`Period`	The option tenor.	required
`calendar`	`Calendar`	The calendar the maturity rolls on.	required
`s0`	`float`	The spot level.	required
`strike`	`float`	The option strike.	required
`volatility`	`float`	The market Black volatility, held as a quote.	required
`risk_free_rate`	`float`	The flat risk-free rate, made into a curve compounded continuously on an annual frequency.	required
`dividend_yield`	`float`	The flat dividend yield, made into a curve on the same convention as the risk-free rate.	required
`error_type`	`CalibrationErrorType`	How the market and model prices are compared.	required
`reference_date`	`Date`	The date the two flat curves are anchored on; it is used only to assemble them, not forwarded to the core.	required
`day_counter`	`DayCounter`	The day count the curves accrue on, used the same way.	required
`settings`	`Settings`	The evaluation-date store the helper reads.	required

calibration_error ¶

calibration_error() -> float

Return the error between the market and model values.

Meaningful once a calibration has installed a pricing engine on the helper; the comparison follows the helper's error type.

Returns:

Name	Type	Description
`float`	`float`	The calibration error under the configured error type.

Raises:

Type	Description
`ItofinError`	If the market or model valuation fails, or the implied volatility solve does.

SwaptionHelper ¶

SwaptionHelper(maturity: Period, length: Period, volatility: float, index: IborIndex, fixed_leg_tenor: Period, fixed_leg_day_counter: DayCounter, floating_leg_day_counter: DayCounter, curve: YieldTermStructure, error_type: CalibrationErrorType, nominal: float)

A co-terminal swaption calibration instrument.

Builds its own European swaption from the maturity, length and index, so no swap or swaption object is needed. The swaption is struck at the forward on shifted-lognormal volatility with zero shift, takes the index's own settlement days, and compounds its averaging.

Build the helper and the swaption underlying it.

Parameters:

Name	Type	Description	Default
`maturity`	`Period`	The option tenor, the time to the swaption expiry.	required
`length`	`Period`	The tenor of the underlying swap.	required
`volatility`	`float`	The market volatility, held as a quote.	required
`index`	`IborIndex`	The index the floating leg fixes on.	required
`fixed_leg_tenor`	`Period`	The payment tenor of the fixed leg.	required
`fixed_leg_day_counter`	`DayCounter`	The day count the fixed leg accrues on.	required
`floating_leg_day_counter`	`DayCounter`	The day count the floating leg accrues on.	required
`curve`	`YieldTermStructure`	The discount curve.	required
`error_type`	`CalibrationErrorType`	How the market and model prices are compared.	required
`nominal`	`float`	The notional of the underlying swap.	required

calibration_error ¶

calibration_error() -> float

Return the error between the market and model values.

Meaningful once a calibration has installed a pricing engine on the helper; the comparison follows the helper's error type.

Returns:

Name	Type	Description
`float`	`float`	The calibration error under the configured error type.

Raises:

Type	Description
`ItofinError`	If the market or model valuation fails, or the implied volatility solve does.

CalibrationErrorType ¶

How market and model prices are compared during calibration.

RelativePriceError is |market - model| / market, PriceError is market - model, and ImpliedVolError compares the two implied volatilities.