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; it wins at import time, so nothing here runs. This file exists only so static type checkers resolve from itofin.models import ... from models/__init__.pyi without a reportMissingModuleSource warning.

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

BatesModel ¶

BatesModel(process: BatesProcess)

Eight-parameter Bates model retaining the original observable market.

Seed the calibrated model from its process.

v0 ¶

v0() -> float

Return the fitted initial variance.

kappa ¶

kappa() -> float

Return the fitted variance mean-reversion speed.

theta ¶

theta() -> float

Return the fitted long-run variance.

sigma ¶

sigma() -> float

Return the fitted volatility of variance.

rho ¶

rho() -> float

Return the fitted spot/variance correlation.

lambda_ ¶

lambda_() -> float

Return the fitted Poisson jump intensity.

nu ¶

nu() -> float

Return the fitted logarithmic jump mean.

delta ¶

delta() -> float

Return the fitted logarithmic jump standard deviation.

params ¶

params() -> list[float]

Return theta, kappa, sigma, rho, v0, nu, delta, lambda_ in that order.

set_params ¶

set_params(params: Sequence[float]) -> None

Atomically replace eight validated parameters and invalidate engines.

calibrate ¶

calibrate(helpers: Sequence[HestonModelHelper], method: LevenbergMarquardt | Simplex | ConjugateGradient | SteepestDescent | DifferentialEvolution | ParticleSwarm | HybridSimulatedAnnealing | Firefly, end_criteria: EndCriteria, integration_order: int = 144, *, constraint: NoConstraint | PositiveConstraint | BoundaryConstraint | CompositeConstraint | None = None, weights: Optional[Sequence[float]] = None, fix_parameters: Optional[Sequence[bool]] = None) -> None

Fit existing Heston helpers with a retained Bates engine.

Optional weights correspond to helpers. The eight-element fixed mask is ordered theta, kappa, sigma, rho, v0, nu, delta, lambda_.

GJRGARCHModel ¶

GJRGARCHModel(process: GJRGARCHProcess)

Six-parameter GJR-GARCH model retaining live spot and yield curves.

Parameters and fixed masks are ordered omega, alpha, beta, gamma, lambda_, daily_variance. Variance and omega use daily units, not annual units.

Seed the model from a retained process with FullTruncation discretization.

daily_variance ¶

daily_variance() -> float

Return the fitted initial daily variance.

omega ¶

omega() -> float

Return the fitted daily variance intercept.

alpha ¶

alpha() -> float

Return the fitted squared innovation coefficient.

beta ¶

beta() -> float

Return the fitted lagged variance coefficient.

gamma ¶

gamma() -> float

Return the fitted asymmetric innovation coefficient.

lambda_ ¶

lambda_() -> float

Return the fitted innovation risk premium.

params ¶

params() -> list[float]

Return omega, alpha, beta, gamma, lambda_, daily_variance in that order.

set_params ¶

set_params(params: Sequence[float]) -> None

Atomically replace six validated parameters and invalidate pricing engines.

process ¶

process() -> GJRGARCHProcess

Return the current process snapshot, retaining live market inputs.

Replacing model parameters creates a new FullTruncation process; an earlier returned process keeps its own parameter snapshot.

calibrate ¶

calibrate(helpers: Sequence[HestonModelHelper], method: LevenbergMarquardt | Simplex | ConjugateGradient | SteepestDescent | DifferentialEvolution | ParticleSwarm | HybridSimulatedAnnealing | Firefly, end_criteria: EndCriteria, *, constraint: NoConstraint | PositiveConstraint | BoundaryConstraint | CompositeConstraint | None = None, weights: Optional[Sequence[float]] = None, fix_parameters: Optional[Sequence[bool]] = None) -> None

Fit Heston Black-volatility helpers with the analytic GJR approximation.

Weights correspond to helpers. The six-element fixed mask uses the same order as params(). Failed calibration restores the model parameters.

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: Sequence[HestonModelHelper], method: LevenbergMarquardt | Simplex | ConjugateGradient | SteepestDescent | DifferentialEvolution | ParticleSwarm | HybridSimulatedAnnealing | Firefly, end_criteria: EndCriteria, integration_order: int, *, constraint: NoConstraint | PositiveConstraint | BoundaryConstraint | CompositeConstraint | None = None, weights: Optional[Sequence[float]] = None, fix_parameters: Optional[Sequence[bool]] = None) -> 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 \| Simplex \| ConjugateGradient \| SteepestDescent`	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
`constraint`	`Constraint \| None`	Additional reusable parameter constraint.	`None`
`weights`	`list[float] \| None`	One weight per calibration helper.	`None`
`fix_parameters`	`list[bool] \| None`	Fixed mask in theta, kappa, sigma, rho, v0 order.	`None`

Raises:

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

calibrate_cos ¶

calibrate_cos(helpers: Sequence[HestonModelHelper], method: LevenbergMarquardt | Simplex | ConjugateGradient | SteepestDescent | DifferentialEvolution | ParticleSwarm | HybridSimulatedAnnealing | Firefly, end_criteria: EndCriteria, l: float = 16.0, n: int = 200, *, constraint: NoConstraint | PositiveConstraint | BoundaryConstraint | CompositeConstraint | None = None, weights: Optional[Sequence[float]] = None, fix_parameters: Optional[Sequence[bool]] = None) -> None

Fit with a COS engine, retaining existing analytic calibration defaults.

calibrate_exponential_fitting ¶

calibrate_exponential_fitting(helpers: Sequence[HestonModelHelper], method: LevenbergMarquardt | Simplex | ConjugateGradient | SteepestDescent | DifferentialEvolution | ParticleSwarm | HybridSimulatedAnnealing | Firefly, end_criteria: EndCriteria, control_variate: ExponentialFittingControlVariate = Optimal, scaling: Optional[float] = None, alpha: float = -0.5, *, constraint: NoConstraint | PositiveConstraint | BoundaryConstraint | CompositeConstraint | None = None, weights: Optional[Sequence[float]] = None, fix_parameters: Optional[Sequence[bool]] = None) -> None

Fit with exponentially fitted quadrature and the selected control variate.

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.

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: Sequence[SwaptionHelper], method: LevenbergMarquardt | Simplex | ConjugateGradient | SteepestDescent | DifferentialEvolution | ParticleSwarm | HybridSimulatedAnnealing | Firefly, end_criteria: EndCriteria, fix_reversion: bool, *, constraint: NoConstraint | PositiveConstraint | BoundaryConstraint | CompositeConstraint | None = None, weights: Optional[Sequence[float]] = None, fix_parameters: Optional[Sequence[bool]] = None) -> 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 \| Simplex \| ConjugateGradient \| SteepestDescent`	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
`constraint`	`Constraint \| None`	Additional reusable parameter constraint.	`None`
`weights`	`list[float] \| None`	One weight per calibration helper.	`None`
`fix_parameters`	`list[bool] \| None`	Fixed mask in a, sigma order; cannot be combined with fix_reversion=True.	`None`

Raises:

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

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.