Instruments

Options, swaps and other tradable instruments.

instruments

Runtime source shim for the native itofin.instruments submodule.

The real itofin.instruments 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.instruments import ... from instruments.pyi without a reportMissingModuleSource warning.

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

OptionType

The call/put flag.

A fieldless enum mirroring the core option type; the signed discriminant convention behind the two variants stays in the core.

VanillaOption

VanillaOption(option_type: OptionType, strike: float, expiry: Date, settings: Settings)

A single-asset vanilla option: European by construction, American through american().

Valuation is lazy: an accessor reprices only once an observed input - the attached engine, or the evaluation date on the Settings the option registered with - has notified it.

Build the European-exercise option, exercisable only at expiry.

Parameters:

Name	Type	Description	Default
option_type	OptionType	Whether the payoff is a call or a put.	required
strike	float	The strike of the plain vanilla payoff.	required
expiry	Date	The single date the option may be exercised on.	required
settings	Settings	The explicit settings supplying the evaluation date the option prices against.	required

american classmethod

american(option_type: OptionType, strike: float, earliest: Date, latest: Date, settings: Settings) -> VanillaOption

Build the option exercisable at any time over [earliest, latest].

The option pays on exercise rather than at expiry. This is the exercise the Monte Carlo American engine requires; the analytic European engine rejects it.

Parameters:

Name	Type	Description	Default
option_type	OptionType	Whether the payoff is a call or a put.	required
strike	float	The strike of the plain vanilla payoff.	required
earliest	Date	The first date the option may be exercised on.	required
latest	Date	The last date the option may be exercised on.	required
settings	Settings	The explicit settings supplying the evaluation date the option prices against.	required

Returns:

Name	Type	Description
VanillaOption	VanillaOption	The American-exercise option.

Raises:

Type	Description
ItofinError	If earliest is after latest.

set_engine

set_engine(process: BlackScholesProcess) -> None

Attach an analytic European engine built on process.

Parameters:

Name	Type	Description	Default
process	BlackScholesProcess	The process the engine prices on; the exact object this Python instance holds is threaded in.	required

set_heston_engine

set_heston_engine(model: HestonModel, integration_order: int) -> None

Attach an analytic Heston engine built on model.

The analytic Heston engine fills only the value, so npv() works but the greeks raise on this path.

Parameters:

Name	Type	Description	Default
model	HestonModel	The calibrated Heston model to price under.	required
integration_order	int	The order of the Gauss-Laguerre integration.	required

Raises:

Type	Description
ItofinError	If integration_order exceeds 192.

set_mc_engine

set_mc_engine(engine: MCEuropeanEngine) -> None

Attach the Monte Carlo European engine.

Parameters:

Name	Type	Description	Default
engine	MCEuropeanEngine	The engine, which already holds the process it prices on.	required

set_mc_heston_engine

set_mc_heston_engine(engine: MCEuropeanHestonEngine) -> None

Attach the Monte Carlo Heston engine.

Parameters:

Name	Type	Description	Default
engine	MCEuropeanHestonEngine	The engine, which already holds the Heston process it prices on.	required

set_mc_american_engine

set_mc_american_engine(engine: MCAmericanEngine) -> None

Attach the Monte Carlo American engine.

The option must have been built through american(): a European-exercise option raises ItofinError ("wrong exercise given") from npv().

Parameters:

Name	Type	Description	Default
engine	MCAmericanEngine	The engine, which already holds the process it prices on.	required

calculate

calculate() -> None

Force the valuation, so a later accessor reads a warm cache.

Idempotent: the core short-circuits on a valid cache, and the option reprices only once an observed input notified it.

Raises:

Type	Description
ItofinError	If no engine is attached, no evaluation date is set, or the attached engine refuses the option.

is_calculated

is_calculated() -> bool

Return whether the cached results are currently valid.

Returns:

Name	Type	Description
bool	bool	True when the next accessor reads the cache rather than repricing.

price

price(process: BlackScholesProcess) -> float

Attach an analytic European engine on process and return the NPV.

The one-shot form of set_engine followed by npv. The other engines have their own one-shots: price_heston, price_mc, price_mc_heston and price_mc_american.

Parameters:

Name	Type	Description	Default
process	BlackScholesProcess	The process the engine prices on.	required

Returns:

Name	Type	Description
float	float	The present value under the analytic European engine.

Raises:

Type	Description
ItofinError	If no evaluation date is set or the engine refuses the option.

price_heston

price_heston(model: HestonModel, integration_order: int) -> float

Attach an analytic Heston engine on model and return the NPV.

The one-shot form of set_heston_engine followed by npv. The greeks stay unavailable on this path.

Parameters:

Name	Type	Description	Default
model	HestonModel	The calibrated Heston model to price under.	required
integration_order	int	The order of the Gauss-Laguerre integration.	required

Returns:

Name	Type	Description
float	float	The present value under the analytic Heston engine.

Raises:

Type	Description
ItofinError	If integration_order exceeds 192, no evaluation date is set, or the engine refuses the option.

price_mc

price_mc(engine: MCEuropeanEngine) -> float

Attach the Monte Carlo European engine and return the NPV.

The one-shot form of set_mc_engine followed by npv.

Parameters:

Name	Type	Description	Default
engine	MCEuropeanEngine	The engine, which already holds the process it prices on.	required

Returns:

Name	Type	Description
float	float	The present value under the Monte Carlo European engine.

Raises:

Type	Description
ItofinError	If no evaluation date is set or the engine refuses the option.

price_mc_heston

price_mc_heston(engine: MCEuropeanHestonEngine) -> float

Attach the Monte Carlo Heston engine and return the NPV.

The one-shot form of set_mc_heston_engine followed by npv.

Parameters:

Name	Type	Description	Default
engine	MCEuropeanHestonEngine	The engine, which already holds the Heston process it prices on.	required

Returns:

Name	Type	Description
float	float	The present value under the Monte Carlo Heston engine.

Raises:

Type	Description
ItofinError	If no evaluation date is set or the engine refuses the option.

price_mc_american

price_mc_american(engine: MCAmericanEngine) -> float

Attach the Monte Carlo American engine and return the NPV.

The one-shot form of set_mc_american_engine followed by npv. The option must have been built through american(): a European-exercise option raises ItofinError ("wrong exercise given").

Parameters:

Name	Type	Description	Default
engine	MCAmericanEngine	The engine, which already holds the process it prices on.	required

Returns:

Name	Type	Description
float	float	The present value under the Monte Carlo American engine.

Raises:

Type	Description
ItofinError	If the option is not American-exercise, no evaluation date is set, or the engine refuses the option.

results

results() -> Results

Return a frozen snapshot of the valuation, calculating first.

The snapshot does not track the option: once taken, an evaluation-date or engine change reprices the live accessors and leaves it alone.

Returns:

Name	Type	Description
Results	Results	A copy of the valuation results.

Raises:

Type	Description
ItofinError	On anything that makes the valuation fail.

npv

npv() -> float

Return the present value.

Returns:

Name	Type	Description
float	float	The option value under the attached engine.

Raises:

Type	Description
ItofinError	If no evaluation date or no engine is set.

delta

delta() -> float

Return the option delta.

Returns:

Name	Type	Description
float	float	The sensitivity to the underlying spot.

Raises:

Type	Description
ItofinError	If the attached engine does not provide it, which the analytic Heston engine does not.

gamma

gamma() -> float

Return the option gamma.

Returns:

Name	Type	Description
float	float	The second-order sensitivity to the underlying spot.

Raises:

Type	Description
ItofinError	If the attached engine does not provide it.

theta

theta() -> float

Return the option theta.

Returns:

Name	Type	Description
float	float	The sensitivity to the passage of time.

Raises:

Type	Description
ItofinError	If the attached engine does not provide it.

vega

vega() -> float

Return the option vega.

Returns:

Name	Type	Description
float	float	The sensitivity to the volatility.

Raises:

Type	Description
ItofinError	If the attached engine does not provide it.

rho

rho() -> float

Return the option rho.

Returns:

Name	Type	Description
float	float	The sensitivity to the risk-free rate.

Raises:

Type	Description
ItofinError	If the attached engine does not provide it.

dividend_rho

dividend_rho() -> float

Return the option dividend rho.

Returns:

Name	Type	Description
float	float	The sensitivity to the dividend yield.

Raises:

Type	Description
ItofinError	If the attached engine does not provide it.

error_estimate

error_estimate() -> float

Return the standard error on the present value.

Returns:

Name	Type	Description
float	float	The Monte Carlo standard error.

Raises:

Type	Description
ItofinError	On the engines that do not produce one, which is every analytic engine here.

exercise_probability

exercise_probability() -> float

Return the fraction of simulated paths exercised before expiry.

Returns:

Name	Type	Description
float	float	The exercise probability reported by the engine.

Raises:

Type	Description
ItofinError	On every engine that does not report it - only MCAmericanEngine does.

SwapType

Which side of the named leg the swap is seen from.

A fieldless enum; the signed leg multiplier the two variants stand for stays in the core.

VanillaSwap

VanillaSwap(swap_type: SwapType, nominal: float, fixed_schedule: Schedule, fixed_rate: float, fixed_day_count: DayCounter, float_schedule: Schedule, ibor_index: IborIndex, spread: float, floating_day_count: DayCounter, settings: Settings)

A fixed-vs-Ibor interest-rate swap.

Pricing needs an engine: call set_engine before fair_rate or npv.

Build the swap from both schedules spelled out.

Parameters:

Name	Type	Description	Default
swap_type	SwapType	Whether the fixed leg is paid or received.	required
nominal	float	The notional both legs accrue on.	required
fixed_schedule	Schedule	The fixed leg's payment schedule.	required
fixed_rate	float	The rate the fixed leg accrues at.	required
fixed_day_count	DayCounter	The day count of the fixed leg.	required
float_schedule	Schedule	The floating leg's payment schedule.	required
ibor_index	IborIndex	The index the floating leg fixes off.	required
spread	float	The spread added to every floating fixing.	required
floating_day_count	DayCounter	The day count of the floating leg.	required
settings	Settings	The explicit settings supplying the evaluation date and the stored fixings.	required

Raises:

Type	Description
ItofinError	If the floating leg cannot be built, a degenerate leg being the usual cause.

set_engine

set_engine(curve: YieldTermStructure, settings: Settings) -> None

Attach a discounting engine over curve so the swap prices.

The engine is built with the settings-driven flow defaults, leaving the settlement date, the NPV date and the settlement-date-flows flag unset.

Parameters:

Name	Type	Description	Default
curve	YieldTermStructure	The curve the flows discount on.	required
settings	Settings	The settings the engine resolves its dates against.	required

calculate

calculate() -> None

Force the valuation. Idempotent.

Raises:

Type	Description
ItofinError	If no engine is attached, no evaluation date is set, or the attached engine refuses the swap.

is_calculated

is_calculated() -> bool

Return whether the cached results are currently valid.

Returns:

Name	Type	Description
bool	bool	True when the next accessor reads the cache.

price

price(curve: YieldTermStructure, settings: Settings) -> float

Attach a discounting engine over curve and return the NPV.

set_engine followed by npv, in one call, and it takes the same two arguments for the same reason.

Parameters:

Name	Type	Description	Default
curve	YieldTermStructure	The curve the flows discount on.	required
settings	Settings	The settings the engine resolves its dates against.	required

Returns:

Name	Type	Description
float	float	The swap value under the freshly built engine.

Raises:

Type	Description
ItofinError	On anything that makes the valuation fail.

results

results() -> Results

Return a frozen snapshot of the valuation, calculating first.

Returns:

Name	Type	Description
Results	Results	A copy of the valuation results.

Raises:

Type	Description
ItofinError	On anything that makes the valuation fail.

fair_rate

fair_rate() -> float

Return the fixed rate that zeroes the swap NPV.

Returns:

Name	Type	Description
float	float	The fair fixed rate.

Raises:

Type	Description
ItofinError	If no engine is attached or the swap has expired.

npv

npv() -> float

Return the swap NPV under the attached engine.

Returns:

Name	Type	Description
float	float	The present value.

Raises:

Type	Description
ItofinError	If no engine is attached.

nominal

nominal() -> float

Return the notional both legs accrue on.

Returns:

Name	Type	Description
float	float	The single nominal.

Raises:

Type	Description
ItofinError	If the legs carry per-coupon nominals, which leaves no single one to report.

fixed_rate

fixed_rate() -> float

Return the fixed-leg rate.

Returns:

Name	Type	Description
float	float	The rate the fixed leg accrues at.

MakeVanillaSwap

MakeVanillaSwap(swap_tenor: Period, ibor_index: IborIndex, settings: Settings, fixed_rate: float | None = None, forward_start: Period | None = None, effective_date: Date | None = None, nominal: float | None = None, fixed_leg_tenor: Period | None = None, fixed_leg_day_count: DayCounter | None = None)

Market-convention builder for a VanillaSwap.

Derives the start and end dates, both schedules, the fixed-leg tenor and day count and the discounting engine from a swap tenor and an Ibor index, so the caller states conventions instead of hand-building two schedules. fixed_rate=None builds a par swap: the fair rate is computed and written into the fixed leg, so the result prices to a zero NPV.

The core builder is a consumed-self fluent chain, which does not cross the FFI boundary; this facade takes the overrides as constructor keywords and assembles the chain inside build(). Only four overrides are exposed; every other core one keeps its default, so the discounting curve is always the index's forwarding curve. The built swap already carries its DiscountingSwapEngine.

Store the configuration the chain is assembled from in build().

Parameters:

Name	Type	Description	Default
swap_tenor	Period	The length of the swap.	required
ibor_index	IborIndex	The index the floating leg fixes off, and whose forwarding curve discounts.	required
settings	Settings	The explicit settings supplying the evaluation date and the stored fixings.	required
fixed_rate	float | None	The rate of the fixed leg; None builds a par swap.	None
forward_start	Period | None	The delay before the swap starts; None starts it spot, at a zero-day period.	None
effective_date	Date | None	The start date; None derives it from the evaluation date.	None
nominal	float | None	The notional; None keeps the core default.	None
fixed_leg_tenor	Period | None	The fixed-leg payment tenor; None takes the currency's market convention.	None
fixed_leg_day_count	DayCounter | None	The fixed-leg day count; None takes the currency's market convention.	None

build

build() -> VanillaSwap

Build the priced swap.

Returns:

Name	Type	Description
VanillaSwap	VanillaSwap	The swap, already carrying its discounting engine.

Raises:

Type	Description
ItofinError	If effective_date is unset and no evaluation date is set to derive the start from; if the index is neither EUR nor USD, the two the fixed-leg defaults are known for; or if the par-rate fill fails to price.

Position

The side taken in a contract.

A fieldless enum; Long is an FRA purchase (a future long loan, short deposit), Short an FRA sale. The signed settlement multiplier the two variants stand for stays in the core.

ForwardRateAgreement

ForwardRateAgreement(index: IborIndex, value_date: Date, fra_type: Position, strike_forward_rate: float, notional_amount: float, discount_curve: YieldTermStructure | None)

A forward rate agreement over an Ibor index.

The FRA prices without an engine, so the valuation accessors work as soon as it is built. It settles and expires on its value date - the day the underlying loan begins - not on the later maturity date.

Build the indexed-coupon FRA.

The maturity is the index's own maturity of the value date and the forward rate is the index fixing.

Parameters:

Name	Type	Description	Default
index	IborIndex	The index the forward rate is forecast by.	required
value_date	Date	The day the underlying loan begins.	required
fra_type	Position	The side taken, Long or Short.	required
strike_forward_rate	float	The simple rate agreed on.	required
notional_amount	float	The notional the settlement accrues on.	required
discount_curve	YieldTermStructure | None	The curve the settlement discounts on; None discounts on the index's forwarding curve instead.	required

Raises:

Type	Description
ItofinError	If the notional is not positive or the maturity cannot be derived from the value date.

with_maturity staticmethod

with_maturity(index: IborIndex, value_date: Date, maturity_date: Date, fra_type: Position, strike_forward_rate: float, notional_amount: float, discount_curve: YieldTermStructure | None) -> ForwardRateAgreement

Build the FRA over an explicit [value_date, maturity_date] window.

The forward rate is the par approximation off the index's forwarding curve; the maturity is adjusted on the index's fixing calendar under the index's convention.

Parameters:

Name	Type	Description	Default
index	IborIndex	The index supplying the forwarding curve and the conventions.	required
value_date	Date	The day the underlying loan begins.	required
maturity_date	Date	The day the underlying loan ends, before adjustment.	required
fra_type	Position	The side taken, Long or Short.	required
strike_forward_rate	float	The simple rate agreed on.	required
notional_amount	float	The notional the settlement accrues on.	required
discount_curve	YieldTermStructure | None	The curve the settlement discounts on; None discounts on the index's forwarding curve instead.	required

Returns:

Name	Type	Description
ForwardRateAgreement	ForwardRateAgreement	The explicit-window FRA.

Raises:

Type	Description
ItofinError	If the notional is not positive or the value date is not earlier than the adjusted maturity date.

forward_rate

forward_rate() -> float

Return the forward rate associated with the FRA term.

Returns:

Name	Type	Description
float	float	The simple forward rate over the FRA window.

Raises:

Type	Description
ItofinError	If the index has no forwarding curve or fixing covering the term.

amount

amount() -> float

Return the payoff on the value date.

Returns:

Name	Type	Description
float	float	The settlement amount, signed by the position.

Raises:

Type	Description
ItofinError	On an expired FRA, which has no settlement amount.

npv

npv() -> float

Return the settlement amount discounted to the value date.

Discounts on the discount curve, or on the index's forwarding curve when none was given.

Returns:

Name	Type	Description
float	float	The present value.

Raises:

Type	Description
ItofinError	If no evaluation date is set or the curves cannot cover the term.

value_date

value_date() -> Date

Return the day the underlying loan begins.

The FRA settles and expires on this date.

Returns:

Name	Type	Description
Date	Date	The value date.

maturity_date

maturity_date() -> Date

Return the day the underlying loan ends.

Adjusted on the index's fixing calendar under the index's convention.

Returns:

Name	Type	Description
Date	Date	The adjusted maturity date.

OvernightIndexedSwap

A fixed leg versus a compounded overnight leg.

Only MakeOis builds one, so it always arrives priced; there is no set_engine and no raw constructor (both deferred with the two-schedule master ctor).

fair_rate

fair_rate() -> float

Return the fixed rate that zeroes the swap NPV.

Returns:

Name	Type	Description
float	float	The fair fixed rate, read through the swap's base.

Raises:

Type	Description
ItofinError	If the swap has expired or its engine fails to price.

calculate

calculate() -> None

Force the valuation. Idempotent.

Raises:

Type	Description
ItofinError	If no evaluation date is set or the engine refuses the swap.

is_calculated

is_calculated() -> bool

Return whether the cached results are currently valid.

Returns:

Name	Type	Description
bool	bool	True when the next accessor reads the cache.

price

price() -> float

Price the swap and return the NPV.

The only no-argument price(): MakeOis already attached the discounting engine, so none is left to install.

Returns:

Name	Type	Description
float	float	The present value.

Raises:

Type	Description
ItofinError	On anything that makes the valuation fail, including the "null pricing engine" a swap that somehow arrived without one reports.

results

results() -> Results

Return a frozen snapshot of the valuation, calculating first.

Returns:

Name	Type	Description
Results	Results	A copy of the valuation results.

Raises:

Type	Description
ItofinError	On anything that makes the valuation fail.

npv

npv() -> float

Return the swap NPV under the engine the builder attached.

Returns:

Name	Type	Description
float	float	The present value.

Raises:

Type	Description
ItofinError	On anything that makes the valuation fail.

nominal

nominal() -> float

Return the notional both legs accrue on.

Returns:

Name	Type	Description
float	float	The single nominal, read through the swap's base.

Raises:

Type	Description
ItofinError	If the legs carry per-coupon nominals, which leaves no single one to report.

fixed_rate

fixed_rate() -> float

Return the fixed-leg rate.

Returns:

Name	Type	Description
float	float	The rate given to the builder, or the fair rate it filled in for a par swap.

MakeOis

MakeOis(swap_tenor: Period, overnight_index: OvernightIndex, settings: Settings, fixed_rate: float | None = None, forward_start: Period | None = None, effective_date: Date | None = None, nominal: float | None = None, payment_lag: int | None = None, discounting_term_structure: YieldTermStructure | None = None, averaging_method: RateAveraging | None = None)

Market-convention builder for an OvernightIndexedSwap.

Derives the start and end dates, both schedules and the discounting engine from a swap tenor and an overnight index, so the caller states conventions instead of hand-building two schedules. fixed_rate=None builds a par swap: the fair rate is computed off a temporary swap and written into the fixed leg, so the result prices to a zero NPV.

The core builder is a consumed-self fluent chain, which does not cross the FFI boundary; this facade takes the overrides as constructor keywords and assembles the chain inside build(). Only five overrides are exposed; every other core one keeps its default, and the four the core rejects outright (telescopic value dates, lookback, lockout and observation shift) are unreachable from here by construction. The built swap already carries its DiscountingSwapEngine.

Store the configuration the chain is assembled from in build().

Parameters:

Name	Type	Description	Default
swap_tenor	Period	The length of the swap.	required
overnight_index	OvernightIndex	The index the overnight leg compounds.	required
settings	Settings	The explicit settings supplying the evaluation date and the stored fixings.	required
fixed_rate	float | None	The rate of the fixed leg; None builds a par swap.	None
forward_start	Period | None	The delay before the swap starts; None starts it spot, at a zero-day period.	None
effective_date	Date | None	The start date; None derives it from the evaluation date.	None
nominal	float | None	The notional; None keeps the core default.	None
payment_lag	int | None	The days between accrual end and payment; None keeps the core default.	None
discounting_term_structure	YieldTermStructure | None	The curve the flows discount on; None keeps the core default.	None
averaging_method	RateAveraging | None	Whether the overnight fixings compound or are averaged; None keeps the core default.	None

build

build() -> OvernightIndexedSwap

Build the priced swap.

Returns:

Name	Type	Description
OvernightIndexedSwap	OvernightIndexedSwap	The swap, already carrying its discounting engine.

Raises:

Type	Description
ItofinError	If effective_date is unset and no evaluation date is set to derive the start from; if the schedule or the overnight leg is degenerate; or if the par-rate fill fails to price.

EuropeanExercise

EuropeanExercise(date: Date)

A single-date exercise schedule.

Held as the exercise trait object the swaption constructor takes, so the same value reaches the instrument.

Build the exercise schedule.

Parameters:

Name	Type	Description	Default
date	Date	The single date the option may be exercised on.	required

SettlementType

How a swaption settles on exercise.

SettlementMethod

The settlement mechanics under a settlement type.

Physical pairs with PhysicalOTC or PhysicalCleared, cash with CollateralizedCashPrice or ParYieldCurve. The consistency check runs at pricing time, not construction, so a mismatched pair only surfaces from npv().

Swaption

Swaption(swap: VanillaSwap, exercise: EuropeanExercise, settlement_type: SettlementType, settlement_method: SettlementMethod, settings: Settings)

A European option to enter a vanilla swap.

The swaption registers with the underlying swap and with the evaluation date on the Settings it was built with (D5). Pricing needs an engine: call one of the three setters before npv.

Build the swaption over swap.

Parameters:

Name	Type	Description	Default
swap	VanillaSwap	The swap the option enters; it needs no discounting engine of its own, the swaption engine reading its arguments instead.	required
exercise	EuropeanExercise	The single exercise date.	required
settlement_type	SettlementType	Whether exercise settles physically or in cash.	required
settlement_method	SettlementMethod	The mechanics under that type; an inconsistent pair surfaces from npv(), not here.	required
settings	Settings	The explicit settings supplying the evaluation date the swaption prices against.	required

set_jamshidian_engine

set_jamshidian_engine(model: HullWhite) -> None

Attach a Jamshidian engine so the swaption prices off Hull-White.

The engine is European-only: a non-European exercise errors at pricing time.

Parameters:

Name	Type	Description	Default
model	HullWhite	The short-rate model supplying the dynamics.	required

set_black_engine

set_black_engine(engine: BlackSwaptionEngine) -> None

Attach a Black engine, pricing off a swaption volatility surface.

The engine is built separately, so the same one can be shared across swaptions. It must carry the same Settings object as this swaption: two different settings would price the swap and the option on different dates with no error raised.

Parameters:

Name	Type	Description	Default
engine	BlackSwaptionEngine	The engine and its volatility surface.	required

set_bachelier_engine

set_bachelier_engine(engine: BachelierSwaptionEngine) -> None

Attach a Bachelier engine, pricing off a normal-volatility surface.

The same-Settings requirement as set_black_engine applies.

Parameters:

Name	Type	Description	Default
engine	BachelierSwaptionEngine	The engine and its normal-volatility surface.	required

calculate

calculate() -> None

Force the valuation. Idempotent.

Raises:

Type	Description
ItofinError	If no engine is attached, no evaluation date is set, or the (settlement type, method) pair is inconsistent, which the core checks here rather than at construction.

is_calculated

is_calculated() -> bool

Return whether the cached results are currently valid.

Returns:

Name	Type	Description
bool	bool	True when the next accessor reads the cache.

price

price(engine: BlackSwaptionEngine) -> float

Attach the Black engine and return the NPV.

set_black_engine followed by npv, in one call. Black is the primary because it is the standard swaption engine; the Jamshidian and Bachelier engines keep their own setters.

Parameters:

Name	Type	Description	Default
engine	BlackSwaptionEngine	The engine to install and price on.	required

Returns:

Name	Type	Description
float	float	The swaption value.

Raises:

Type	Description
ItofinError	On anything that makes the valuation fail.

results

results() -> Results

Return a frozen snapshot of the valuation, calculating first.

Returns:

Name	Type	Description
Results	Results	A copy of the valuation results.

Raises:

Type	Description
ItofinError	On anything that makes the valuation fail.

npv

npv() -> float

Return the swaption NPV under the attached engine.

Returns:

Name	Type	Description
float	float	The present value.

Raises:

Type	Description
ItofinError	If no engine is attached or the (settlement type, method) pair is inconsistent.

CapFloorType

Whether the instrument caps, floors or collars its floating leg.

Collar reaches an instrument only through a raw coupon-vector constructor: CapFloor.collar here, or the YoYInflationCapFloor ones on the inflation side. MakeCapFloor refuses it, so CapFloor(...) does not accept it.

CapFloor

CapFloor(cap_floor_type: CapFloorType, tenor: Period, ibor_index: IborIndex, strike: float, forward_start: Period, settings: Settings)

A cap, floor or collar over a floating (ibor) leg.

The constructor runs the standard market builder MakeCapFloor: its leg carries a unit nominal and one strike, and a zero forward_start excludes the spot caplet, so the leg is one coupon shorter than the schedule - that is what lets the cap price without a historical index fixing at the evaluation date.

The cap/floor/collar staticmethods take an IborLeg the caller laid out instead and cap exactly it, spot caplet and all. They are the only route to a collar on this side, and the route a hand-built leg's own notional, day counter and fixing days reach the coupons by. Either way the core pads a short strike list across every coupon by repeating its last entry.

Build a standard market cap or floor through MakeCapFloor.

Parameters:

Name	Type	Description	Default
cap_floor_type	CapFloorType	Cap or Floor; the builder refuses Collar.	required
tenor	Period	The length of the capped leg.	required
ibor_index	IborIndex	The index the floating leg fixes off.	required
strike	float	The single strike, padded across every coupon.	required
forward_start	Period	The delay before the leg starts; a zero period excludes the spot caplet.	required
settings	Settings	The explicit settings supplying the evaluation date and the stored fixings.	required

Raises:

Type	Description
ItofinError	If cap_floor_type is Collar, if the derived schedule is degenerate, or if the start has to be derived and no evaluation date is set.

cap staticmethod

cap(leg: IborLeg, cap_rates: list[float], settings: Settings) -> CapFloor

Build a cap over the coupons leg builds, struck at cap_rates.

Unlike the constructor this keeps whatever leg it is given: the spot caplet stays, and the leg's own notional, day counter and fixing days reach the coupons.

Parameters:

Name	Type	Description	Default
leg	IborLeg	The leg whose coupons are capped.	required
cap_rates	list[float]	The cap strikes, padded to the leg length by repeating the last entry.	required
settings	Settings	The explicit settings the instrument resolves its dates against.	required

Returns:

Name	Type	Description
CapFloor	CapFloor	The cap over that leg.

Raises:

Type	Description
ItofinError	On an empty cap_rates list, or on whatever building the leg's coupons reports, a missing notional above all.

floor staticmethod

floor(leg: IborLeg, floor_rates: list[float], settings: Settings) -> CapFloor

Build a floor over the coupons leg builds, struck at floor_rates.

Parameters:

Name	Type	Description	Default
leg	IborLeg	The leg whose coupons are floored.	required
floor_rates	list[float]	The floor strikes, padded as cap() pads.	required
settings	Settings	The explicit settings the instrument resolves its dates against.	required

Returns:

Name	Type	Description
CapFloor	CapFloor	The floor over that leg.

Raises:

Type	Description
ItofinError	Fallible as cap(), on an empty list or a leg whose coupons cannot be built.

collar staticmethod

collar(leg: IborLeg, cap_rates: list[float], floor_rates: list[float], settings: Settings) -> CapFloor

Build a collar: long the cap at cap_rates, short the floor at floor_rates.

The collar is worth the one less the other, and this is the only route to one over a floating leg.

Parameters:

Name	Type	Description	Default
leg	IborLeg	The leg whose coupons are collared.	required
cap_rates	list[float]	The cap strikes, padded as cap() pads.	required
floor_rates	list[float]	The floor strikes, padded the same way.	required
settings	Settings	The explicit settings the instrument resolves its dates against.	required

Returns:

Name	Type	Description
CapFloor	CapFloor	The collar over that leg.

Raises:

Type	Description
ItofinError	On either list being empty, both being required, or on a leg whose coupons cannot be built.

cap_rates

cap_rates() -> list[float]

Return the cap strikes, one per coupon.

Returns:

Type	Description
list[float]	list[float]: The cap strikes; empty for a floor.

floor_rates

floor_rates() -> list[float]

Return the floor strikes, one per coupon.

Returns:

Type	Description
list[float]	list[float]: The floor strikes; empty for a cap.

coupon_count

coupon_count() -> int

Return the number of optionlets.

Returns:

Name	Type	Description
int	int	One per floating coupon on the leg.

set_black_engine

set_black_engine(engine: BlackCapFloorEngine) -> None

Attach a Black engine, pricing each optionlet off a volatility surface.

The engine is built separately, so the same one can be shared across instruments. It must resolve its dates against the same Settings object as this cap/floor: two different settings would price the leg and the optionlets on different dates with no error raised.

Parameters:

Name	Type	Description	Default
engine	BlackCapFloorEngine	The engine and its optionlet volatility surface.	required

calculate

calculate() -> None

Force the valuation. Idempotent.

Raises:

Type	Description
ItofinError	If no engine is attached, no evaluation date is set, or the engine refuses the instrument.

is_calculated

is_calculated() -> bool

Return whether the cached results are currently valid.

The Black engine observes its volatility handle, so moving a quote the engine was built over reaches the cap and flips this back to False.

Returns:

Name	Type	Description
bool	bool	True when the next accessor reads the cache.

price

price(engine: BlackCapFloorEngine) -> float

Attach engine and return the NPV.

Parameters:

Name	Type	Description	Default
engine	BlackCapFloorEngine	The engine to install and price on.	required

Returns:

Name	Type	Description
float	float	The cap/floor value.

Raises:

Type	Description
ItofinError	On anything that makes the valuation fail.

results

results() -> Results

Return a frozen snapshot of the valuation, calculating first.

Returns:

Name	Type	Description
Results	Results	A copy of the valuation results.

Raises:

Type	Description
ItofinError	On anything that makes the valuation fail.

npv

npv() -> float

Return the cap/floor NPV under the attached engine.

Returns:

Name	Type	Description
float	float	The present value.

Raises:

Type	Description
ItofinError	If no engine is attached, which the core reports as "null pricing engine".

ProtectionSide

Which leg of a default-protection contract a party holds: the buyer pays the premium leg and receives the default payment, the seller the reverse.

PricingModel

The model a quoted contract is inverted under by CreditDefaultSwap.implied_hazard_rate: Midpoint is not ISDA conform, Isda carries the three fidelity flags the core fixes at that call site.

CreditDefaultSwap

CreditDefaultSwap(side: ProtectionSide, notional: float, spread: float, schedule: Schedule, payment_convention: BusinessDayConvention, day_counter: DayCounter, settles_accrual: bool, pays_at_default_time: bool, settings: Settings)

A credit-default swap quoted as a running spread.

init takes the C++ default terms with settles_accrual and pays_at_default_time quoted; with_terms additionally exposes protection_start and rebates_accrual.

These direct constructors keep the remaining CdsTerms fields at their core defaults: claim (a face-value claim, which needs a claim facade that does not exist yet), last_period_day_counter, upfront_date and cash_settlement_days. trade_date and an upfront are not set here but are reachable through MakeCreditDefaultSwap (with_trade_date and the upfront_rate constructor argument).

Build a contract on the C++ default terms.

Parameters:

Name	Type	Description	Default
side	ProtectionSide	Whether protection is bought or sold.	required
notional	float	The notional the premium and protection are quoted on.	required
spread	float	The running spread the premium leg pays.	required
schedule	Schedule	The premium leg's payment schedule.	required
payment_convention	BusinessDayConvention	The roll applied to the premium payment dates.	required
day_counter	DayCounter	The day count the premium accrues on.	required
settles_accrual	bool	Whether the accrued coupon settles on default.	required
pays_at_default_time	bool	Whether the protection pays at default rather than at maturity.	required
settings	Settings	The explicit settings supplying the evaluation date the contract prices against.	required

Raises:

Type	Description
ItofinError	If the schedule is empty, if the protection start follows the first accrual date under a pre-Big-Bang date-generation rule, or if the premium leg cannot be built.

with_terms staticmethod

with_terms(side: ProtectionSide, notional: float, spread: float, schedule: Schedule, payment_convention: BusinessDayConvention, day_counter: DayCounter, settings: Settings, protection_start: Date | None = None, settles_accrual: bool = True, pays_at_default_time: bool = True, rebates_accrual: bool = True) -> CreditDefaultSwap

Build a contract quoting the terms init defaults.

The three flags carry the core defaults verbatim, so calling this with only the positional arguments builds exactly what init builds.

Parameters:

Name	Type	Description	Default
side	ProtectionSide	Whether protection is bought or sold.	required
notional	float	The notional the premium and protection are quoted on.	required
spread	float	The running spread the premium leg pays.	required
schedule	Schedule	The premium leg's payment schedule.	required
payment_convention	BusinessDayConvention	The roll applied to the premium payment dates.	required
day_counter	DayCounter	The day count the premium accrues on.	required
settings	Settings	The explicit settings; it precedes the defaulted terms because a Python signature cannot put a required argument after an optional one.	required
protection_start	Date | None	The first date a default triggers the contract; None takes the schedule's first date, which is what init does.	None
settles_accrual	bool	Whether the accrued coupon settles on default.	True
pays_at_default_time	bool	Whether the protection pays at default rather than at maturity.	True
rebates_accrual	bool	Whether the protection seller rebates the accrued current coupon.	True

Returns:

Name	Type	Description
CreditDefaultSwap	CreditDefaultSwap	The contract on those terms.

Raises:

Type	Description
ItofinError	On the same conditions init reports.

set_engine

set_engine(engine: MidPointCdsEngine) -> None

Attach a mid-point engine so the contract prices.

The engine is built separately, so one engine can be shared across contracts. It must resolve its dates against the same Settings object as this contract.

Parameters:

Name	Type	Description	Default
engine	MidPointCdsEngine	The engine and its default-probability and discount curves.	required

set_isda_engine

set_isda_engine(engine: IsdaCdsEngine) -> None

Attach an ISDA engine so the contract prices under the standard model.

A separate setter rather than a widened set_engine: the two engine facades are unrelated classes, so one argument cannot name both. The same sharing and same-Settings rules apply, and the ISDA engine additionally refuses curves outside its specification when the contract prices.

Parameters:

Name	Type	Description	Default
engine	IsdaCdsEngine	The ISDA engine and its curves.	required

calculate

calculate() -> None

Force the valuation. Idempotent.

Raises:

Type	Description
ItofinError	If no engine is attached, no evaluation date is set, or the engine refuses the contract.

is_calculated

is_calculated() -> bool

Return whether the cached results are currently valid.

Returns:

Name	Type	Description
bool	bool	True when the next accessor reads the cache.

price

price(engine: MidPointCdsEngine) -> float

Attach the mid-point engine and return the NPV.

set_engine followed by npv, in one call. The mid-point engine is the primary because it is the core's own default CDS engine; set_isda_engine stays a separate setter.

Parameters:

Name	Type	Description	Default
engine	MidPointCdsEngine	The engine to install and price on.	required

Returns:

Name	Type	Description
float	float	The contract value.

Raises:

Type	Description
ItofinError	On anything that makes the valuation fail.

results

results() -> Results

Return a frozen snapshot of the valuation, calculating first.

Returns:

Name	Type	Description
Results	Results	A copy of the valuation results.

Raises:

Type	Description
ItofinError	On anything that makes the valuation fail.

npv

npv() -> float

Return the contract NPV under the attached engine.

Returns:

Name	Type	Description
float	float	The present value.

Raises:

Type	Description
ItofinError	If no engine is attached, which the core reports as "null pricing engine".

fair_spread

fair_spread() -> float

Return the running spread that prices the contract at zero.

Returns:

Name	Type	Description
float	float	The fair running spread.

Raises:

Type	Description
ItofinError	If no engine is attached, and when the engine priced a worthless premium leg and so provided no fair spread.

fair_upfront

fair_upfront() -> float

Return the upfront that prices the contract at zero.

Returns:

Name	Type	Description
float	float	The fair upfront, as a fraction of the notional.

Raises:

Type	Description
ItofinError	On the same conditions fair_spread reports.

notional

notional() -> float

Return the notional the premium and the protection are quoted on.

Returns:

Name	Type	Description
float	float	The contract notional.

accrual_rebate_amount

accrual_rebate_amount() -> float | None

Return the accrued coupon the protection seller rebates.

A contract traded in the past still carries the flow: the core builds it whenever the flag is set, regardless of the trade date, so None here means the flag was off, never a stale trade. Such a flow carries a real accrued amount but settled on a past date, so it no longer reaches the value. The amount is returned bare rather than behind a cash-flow facade, there being none.

Returns:

Type	Description
float | None	float | None: The rebated amount, or None when the contract does not rebate accrual at all.

accrual_rebate_date

accrual_rebate_date() -> Date | None

Return the date the accrual rebate settles on.

Returns:

Type	Description
Date | None	Date | None: The cash-settlement date the upfront also pays on, or None on the same terms as accrual_rebate_amount.

coupon_leg_npv

coupon_leg_npv() -> float

Return the premium leg's NPV.

Returns:

Name	Type	Description
float	float	The present value of the premium leg.

Raises:

Type	Description
ItofinError	On the same conditions fair_spread reports.

default_leg_npv

default_leg_npv() -> float

Return the protection leg's NPV.

Returns:

Name	Type	Description
float	float	The present value of the protection leg.

Raises:

Type	Description
ItofinError	On the same conditions fair_spread reports.

implied_hazard_rate

implied_hazard_rate(target_npv: float, discount: YieldTermStructure, day_counter: DayCounter, recovery_rate: float, accuracy: float, model: PricingModel) -> float

Return the flat hazard rate at which this contract is worth target_npv.

The solve stands on its own engine rather than on whichever one set_engine attached: it builds a flat, quote-backed probability curve and prices on model against discount. There is therefore no probability-curve argument - the curve being solved for is the one the core builds.

Parameters:

Name	Type	Description	Default
target_npv	float	The value the contract is solved to.	required
discount	YieldTermStructure	The curve the flows discount on.	required
day_counter	DayCounter	The day count of the internal flat curve, not of the contract. Under PricingModel.Isda both it and discount must count Act/365 (Fixed), which is what the ISDA engine requires of its curves.	required
recovery_rate	float	The recovery assumed on default.	required
accuracy	float	The tolerance the solve stops at, on the rate.	required
model	PricingModel	The model the contract is inverted under.	required

Returns:

Name	Type	Description
float	float	The flat hazard rate.

Raises:

Type	Description
ItofinError	On a malformed contract, and when the solve does not converge, which includes a pricing failure at some hazard rate.

MakeCreditDefaultSwap

MakeCreditDefaultSwap(term_date: Date, running_spread: float, settings: Settings, nominal: float | None = None, upfront_rate: float | None = None, side: ProtectionSide | None = None, trade_date: Date | None = None)

Market-convention builder for a CreditDefaultSwap: derives the premium schedule from a maturity and the post-Big-Bang CDS conventions, and takes the trade date from the evaluation date settings carries.

An unset optional keeps the core default: a Buyer side, a nominal of 1, no upfront, a 3M coupon tenor, the pre-CDS2015 DateGeneration.CDS rule, a Following roll, an Act/360 day counter and three cash-settlement days. Only the term-date quotation is exposed; the tenor and explicit-schedule ones and the accrual-rebate flag are not, the latter being reachable through CreditDefaultSwap.with_terms.

Store the configuration the chain is assembled from in build().

Each build() runs a fresh chain, so one builder object cannot carry a setting into a later contract.

Parameters:

Name	Type	Description	Default
term_date	Date	The maturity the premium schedule is derived from.	required
running_spread	float	The running spread the premium leg pays.	required
settings	Settings	The explicit settings supplying the evaluation date the trade is dated off.	required
nominal	float | None	The notional; None keeps the core default of 1.	None
upfront_rate	float | None	The upfront as a fraction of the notional; None keeps the core default of none.	None
side	ProtectionSide | None	Which side the contract holds; None keeps the core default of Buyer.	None
trade_date	Date | None	Overrides the evaluation date the trade is otherwise dated off, which is how a contract traded in the past is built.	None

build

build() -> CreditDefaultSwap

Build the contract, which carries no engine.

Attach one with set_engine or set_isda_engine before pricing.

Returns:

Name	Type	Description
CreditDefaultSwap	CreditDefaultSwap	The contract on the market conventions.

Raises:

Type	Description
ItofinError	If no evaluation date is set, the trade date being derived from it, and on whatever the contract construction rejects.

ZeroCouponInflationSwap

ZeroCouponInflationSwap(swap_type: SwapType, nominal: float, start_date: Date, maturity: Date, fixed_calendar: Calendar, fixed_convention: BusinessDayConvention, day_counter: DayCounter, fixed_rate: float, inflation_index: ZeroInflationIndex, observation_lag: Period, observation_interpolation: CpiInterpolationType, inflation_calendar: Calendar | None, inflation_convention: BusinessDayConvention | None, settings: Settings)

One fixed flow against one inflation-indexed flow, both exchanged at maturity.

fixed_rate is the K that at inception matches the inflation growth. SwapType names the inflation leg, so a Payer pays inflation and receives fixed.

maturity is pre-adjustment: each leg's payment date is it rolled on that leg's calendar and convention, while the year fraction behind the fixed amount stays on the raw date. inflation_calendar and inflation_convention fall back to the fixed-leg ones when None.

The core omits adjust_inf_obs_dates from its own signature, so there is nothing to expose here; the leg and cash-flow accessors are not surfaced either, there being no cash-flow facade.

Build the swap from its two exchanged flows.

Parameters:

Name	Type	Description	Default
swap_type	SwapType	Which side the inflation leg is seen from; a Payer pays inflation and receives fixed.	required
nominal	float	The notional both flows are quoted on.	required
start_date	Date	The inception the index ratio is measured from.	required
maturity	Date	The raw, pre-adjustment maturity.	required
fixed_calendar	Calendar	The calendar the fixed payment rolls on.	required
fixed_convention	BusinessDayConvention	The roll applied to the fixed payment date.	required
day_counter	DayCounter	The day count behind the fixed amount, which stays on the raw maturity.	required
fixed_rate	float	The K that at inception matches the inflation growth.	required
inflation_index	ZeroInflationIndex	The index the indexed flow observes.	required
observation_lag	Period	How far back the maturity fixing is observed.	required
observation_interpolation	CpiInterpolationType	How the observed fixing is interpolated.	required
inflation_calendar	Calendar | None	The calendar the inflation payment rolls on; None falls back to fixed_calendar.	required
inflation_convention	BusinessDayConvention | None	The roll applied to the inflation payment date; None falls back to fixed_convention.	required
settings	Settings	The explicit settings supplying the evaluation date and the stored fixings.	required

Raises:

Type	Description
ItofinError	If the observation lag is too short for the index to observe fixings that exist, which under Linear interpolation costs a further publication period.

set_engine

set_engine(engine: DiscountingSwapEngine) -> None

Attach a discounting engine so the swap prices.

Parameters:

Name	Type	Description	Default
engine	DiscountingSwapEngine	The engine, which must resolve its dates against the same Settings object as this swap.	required

calculate

calculate() -> None

Force the valuation. Idempotent.

Raises:

Type	Description
ItofinError	If no engine is attached, no evaluation date is set, or the engine refuses the swap.

is_calculated

is_calculated() -> bool

Return whether the cached results are currently valid.

Returns:

Name	Type	Description
bool	bool	True when the next accessor reads the cache.

price

price(engine: DiscountingSwapEngine) -> float

Attach engine and return the NPV.

Parameters:

Name	Type	Description	Default
engine	DiscountingSwapEngine	The engine to install and price on.	required

Returns:

Name	Type	Description
float	float	The swap value.

Raises:

Type	Description
ItofinError	On anything that makes the valuation fail.

results

results() -> Results

Return a frozen snapshot of the valuation, calculating first.

Returns:

Name	Type	Description
Results	Results	A copy of the valuation results.

Raises:

Type	Description
ItofinError	On anything that makes the valuation fail.

npv

npv() -> float

Return the swap NPV under the attached engine.

Returns:

Name	Type	Description
float	float	The present value.

Raises:

Type	Description
ItofinError	If no engine is attached, and if no curve is linked into the index, which leaves the indexed flow unforecastable.

fair_rate

fair_rate() -> float

Return the index ratio de-compounded over the swap's own year fraction.

Needs no engine - it reads the indexed flow rather than any priced result.

Returns:

Name	Type	Description
float	float	The rate that would price the swap at zero.

Raises:

Type	Description
ItofinError	If no curve is linked into the index, the flow's amount being a forecast off the inflation curve.

fixed_leg_npv

fixed_leg_npv() -> float

Return the fixed leg's NPV, priced on demand.

Returns:

Name	Type	Description
float	float	The present value of the fixed flow.

Raises:

Type	Description
ItofinError	On the same conditions npv reports.

inflation_leg_npv

inflation_leg_npv() -> float

Return the inflation leg's NPV, priced on demand.

Returns:

Name	Type	Description
float	float	The present value of the indexed flow.

Raises:

Type	Description
ItofinError	On the same conditions npv reports.

fixed_leg_bps

fixed_leg_bps() -> float

Return the fixed leg's sensitivity to a basis point on the quoted rate.

Computed in closed form rather than read off the engine, whose own leg BPS is zero for a non-coupon flow.

Returns:

Name	Type	Description
float	float	The basis-point value of the fixed flow.

Raises:

Type	Description
ItofinError	On the same conditions npv reports, the calculation needing the engine's discount factor at the fixed leg's end date.

maturity_date

maturity_date() -> Date

Return the contract maturity, raw and pre-adjustment.

Returns:

Name	Type	Description
Date	Date	The maturity, which is not either leg's payment date.

obs_date

obs_date() -> Date

Return the date the maturity fixing is observed at.

Returns:

Name	Type	Description
Date	Date	The maturity less the observation lag, unsnapped.

inflation_fixing_date

inflation_fixing_date() -> Date

Return the observation date, read off the indexed flow.

Both names are kept because both exist in the core, and the oracle asserts they coincide.

Returns:

Name	Type	Description
Date	Date	The same date as obs_date.

YearOnYearInflationSwap

YearOnYearInflationSwap(swap_type: SwapType, nominal: float, fixed_schedule: Schedule, fixed_rate: float, fixed_day_count: DayCounter, yoy_schedule: Schedule, yoy_index: YoYInflationIndex, observation_lag: Period, interpolation: CpiInterpolationType, spread: float, yoy_day_count: DayCounter, payment_calendar: Calendar, payment_convention: BusinessDayConvention, settings: Settings)

A fixed leg against a leg of year-on-year inflation coupons, both paid over a schedule.

SwapType names the fixed leg, so a Payer pays fixed and receives inflation - the opposite reading from ZeroCouponInflationSwap, where it names the inflation leg.

The two schedules are independent inputs. The fixed leg takes its payment calendar from its own schedule while the year-on-year leg pays on payment_calendar; both adjust with payment_convention. spread is added to every forecast rate on the year-on-year leg.

Pricing needs an engine: call set_engine first. Every priced accessor drives the calculation, so all of them mutate.

Build the swap from its two schedules.

Parameters:

Name	Type	Description	Default
swap_type	SwapType	Which side the fixed leg is seen from; a Payer pays fixed and receives inflation.	required
nominal	float	The notional both legs accrue on.	required
fixed_schedule	Schedule	The fixed leg's payment schedule, which also supplies its payment calendar.	required
fixed_rate	float	The rate the fixed leg accrues at.	required
fixed_day_count	DayCounter	The day count of the fixed leg.	required
yoy_schedule	Schedule	The year-on-year leg's schedule.	required
yoy_index	YoYInflationIndex	The index the coupons fix off.	required
observation_lag	Period	How far back each coupon's fixings are observed.	required
interpolation	CpiInterpolationType	How the observed fixings are interpolated.	required
spread	float	Added to every forecast rate on the year-on-year leg.	required
yoy_day_count	DayCounter	The day count of the year-on-year leg.	required
payment_calendar	Calendar	The calendar the year-on-year leg pays on.	required
payment_convention	BusinessDayConvention	The roll both legs adjust their payment dates with.	required
settings	Settings	The explicit settings supplying the evaluation date and the stored fixings.	required

Raises:

Type	Description
ItofinError	If either leg cannot be built, notably from an observation lag that leaves a coupon unbuildable.

set_engine

set_engine(engine: DiscountingSwapEngine) -> None

Attach a discounting engine so the swap prices.

Parameters:

Name	Type	Description	Default
engine	DiscountingSwapEngine	The engine, which must resolve its dates against the same Settings object this swap was built with.	required

calculate

calculate() -> None

Force the valuation. Idempotent.

Raises:

Type	Description
ItofinError	If no engine is attached, no evaluation date is set, or the engine refuses the swap.

is_calculated

is_calculated() -> bool

Return whether the cached results are currently valid.

Returns:

Name	Type	Description
bool	bool	True when the next accessor reads the cache.

price

price(engine: DiscountingSwapEngine) -> float

Attach engine and return the NPV.

Parameters:

Name	Type	Description	Default
engine	DiscountingSwapEngine	The engine to install and price on.	required

Returns:

Name	Type	Description
float	float	The swap value.

Raises:

Type	Description
ItofinError	On anything that makes the valuation fail.

results

results() -> Results

Return a frozen snapshot of the valuation, calculating first.

Returns:

Name	Type	Description
Results	Results	A copy of the valuation results.

Raises:

Type	Description
ItofinError	On anything that makes the valuation fail.

npv

npv() -> float

Return the swap NPV under the attached engine.

Returns:

Name	Type	Description
float	float	The present value.

Raises:

Type	Description
ItofinError	If no engine is attached, and if no curve is linked into the index, which leaves the coupons unforecastable.

fair_rate

fair_rate() -> float

Return the fixed rate that would price the swap at zero.

Recovered from the NPV and the fixed leg's BPS, so it prices on demand and needs an engine.

Returns:

Name	Type	Description
float	float	The fair fixed rate.

Raises:

Type	Description
ItofinError	On the same conditions npv reports.

fair_spread

fair_spread() -> float

Return the spread over the index that would price the swap at zero.

Recovered off the year-on-year leg.

Returns:

Name	Type	Description
float	float	The fair spread.

Raises:

Type	Description
ItofinError	On the same conditions fair_rate reports.

fixed_leg_npv

fixed_leg_npv() -> float

Return the fixed leg's NPV, priced on demand.

Returns:

Name	Type	Description
float	float	The present value of the fixed leg.

Raises:

Type	Description
ItofinError	On the same conditions npv reports.

yoy_leg_npv

yoy_leg_npv() -> float

Return the year-on-year leg's NPV, priced on demand.

Returns:

Name	Type	Description
float	float	The present value of the inflation leg.

Raises:

Type	Description
ItofinError	On the same conditions npv reports.

fixed_rate

fixed_rate() -> float

Return the quoted fixed rate the swap was struck at.

Returns:

Name	Type	Description
float	float	The fixed-leg rate.

spread

spread() -> float

Return the spread the year-on-year coupons carry over the index.

Returns:

Name	Type	Description
float	float	The quoted spread.

MakeYoYInflationCapFloor

MakeYoYInflationCapFloor(cap_floor_type: CapFloorType, index: YoYInflationIndex, length: int, calendar: Calendar, observation_lag: Period, interpolation: CpiInterpolationType, settings: Settings, nominal: float | None = None, effective_date: Date | None = None, payment_day_counter: DayCounter | None = None, payment_adjustment: BusinessDayConvention | None = None, fixing_days: int | None = None, engine: YoYInflationCapFloorEngine | None = None, as_optionlet: bool = False, forward_start: Period | None = None, first_caplet_excluded: bool = False, strike: float | None = None, atm_strike: YieldTermStructure | None = None)

The standard market builder for a year-on-year inflation cap or floor.

It derives an annual year-on-year leg from a length in years, trims that leg to the optionlets asked for, and strikes it either at an explicit strike or at the money off atm_strike. Exactly one of the two is required: the core refuses both together and neither at all, at build time rather than at the setters, so both surface from build().

The core builder is a consumed-self fluent chain, which does not cross the FFI boundary; this facade takes the whole configuration up front and assembles the chain inside build(), as MakeVanillaSwap does. An unset optional leaves the core default in place: a 1,000,000 nominal, a ModifiedFollowing payment roll, a 30/360 bond-basis day counter, no fixing days, every optionlet kept and no forward start.

Trimming happens before the at-the-money fill, so as_optionlet and first_caplet_excluded change what an unset strike resolves to: the rate that reprices whatever survives, not the whole leg's.

CapFloorType.Collar has no path here - the builder carries a single strike, and a collar needs two strike vectors - so a collar is built through YoYInflationCapFloor.collar over a leg of its own instead.

Store the configuration the chain is assembled from in build().

Parameters:

Name	Type	Description	Default
cap_floor_type	CapFloorType	Cap or Floor; Collar has no path here.	required
index	YoYInflationIndex	The index the optionlets fix off.	required
length	int	The length of the derived annual leg, in years.	required
calendar	Calendar	The calendar the payments roll on.	required
observation_lag	Period	How far back each coupon's fixings are observed.	required
interpolation	CpiInterpolationType	How the observed fixings are interpolated.	required
settings	Settings	The explicit settings supplying the evaluation date and the stored fixings.	required
nominal	float | None	The notional; None keeps the core default of 1,000,000.	None
effective_date	Date | None	The start date; None derives it from the evaluation date.	None
payment_day_counter	DayCounter | None	The day count; None keeps the core default of 30/360 bond basis.	None
payment_adjustment	BusinessDayConvention | None	The payment roll; None keeps the core default of ModifiedFollowing.	None
fixing_days	int | None	The fixing days of the coupons; None keeps the core default of none.	None
engine	YoYInflationCapFloorEngine | None	An engine installed on the built instrument; None leaves it unpriced.	None
as_optionlet	bool	Whether to keep only the last optionlet.	False
forward_start	Period | None	The delay before the leg starts; None keeps the core default of no forward start.	None
first_caplet_excluded	bool	Whether to drop the front optionlet.	False
strike	float | None	The explicit strike; exactly one of this and atm_strike is required.	None
atm_strike	YieldTermStructure | None	The curve the at-the-money strike is filled off; exactly one of this and strike is required.	None

build

build() -> YoYInflationCapFloor

Build the cap/floor, which already carries its engine when one was given.

Returns:

Name	Type	Description
YoYInflationCapFloor	YoYInflationCapFloor	The built instrument.

Raises:

Type	Description
ItofinError	If both strike and atm_strike are given or neither is; if the start date has to be derived and no evaluation date is set; and on whatever the leg construction and the at-the-money fill report.

YoYInflationCapFloor

A cap, floor or collar over a year-on-year inflation leg.

Built either through MakeYoYInflationCapFloor, the standard market builder, or through the raw constructors below, which take the coupon vector YoYInflationLeg.coupons() hands back (#848). The raw route is the only one that reaches a collar: the builder carries a single strike.

Unlike a nominal cap/floor this instrument keeps its first optionlet, so the strip spans its leg exactly and cap - floor is the year-on-year swap.

Pricing needs an engine: call set_engine before npv.

new staticmethod

new(cap_floor_type: CapFloorType, coupons: list[YoYInflationCoupon], cap_rates: list[float], floor_rates: list[float], settings: Settings) -> YoYInflationCapFloor

Build an instrument of cap_floor_type over coupons, struck at both vectors.

Each strike vector is padded to the leg length by repeating its last entry, so a single strike stands for every optionlet.

Parameters:

Name	Type	Description	Default
cap_floor_type	CapFloorType	Cap, Floor or Collar.	required
coupons	list[YoYInflationCoupon]	The leg the optionlets sit on.	required
cap_rates	list[float]	The cap strikes.	required
floor_rates	list[float]	The floor strikes.	required
settings	Settings	The explicit settings the instrument resolves its dates against.	required

Returns:

Name	Type	Description
YoYInflationCapFloor	YoYInflationCapFloor	The built instrument.

Raises:

Type	Description
ItofinError	On an empty leg, and on a strike vector the type needs and did not get: a cap or a collar needs cap rates, a floor or a collar floor rates.

cap staticmethod

cap(coupons: list[YoYInflationCoupon], strikes: list[float], settings: Settings) -> YoYInflationCapFloor

Build a cap over coupons struck at strikes.

Parameters:

Name	Type	Description	Default
coupons	list[YoYInflationCoupon]	The leg the optionlets sit on.	required
strikes	list[float]	The cap strikes, padded as new() pads.	required
settings	Settings	The explicit settings the instrument resolves its dates against.	required

Returns:

Name	Type	Description
YoYInflationCapFloor	YoYInflationCapFloor	The cap over that leg.

Raises:

Type	Description
ItofinError	On the same conditions new() reports.

floor staticmethod

floor(coupons: list[YoYInflationCoupon], strikes: list[float], settings: Settings) -> YoYInflationCapFloor

Build a floor over coupons struck at strikes.

Parameters:

Name	Type	Description	Default
coupons	list[YoYInflationCoupon]	The leg the optionlets sit on.	required
strikes	list[float]	The floor strikes, padded as new() pads.	required
settings	Settings	The explicit settings the instrument resolves its dates against.	required

Returns:

Name	Type	Description
YoYInflationCapFloor	YoYInflationCapFloor	The floor over that leg.

Raises:

Type	Description
ItofinError	On the same conditions new() reports.

collar staticmethod

collar(coupons: list[YoYInflationCoupon], cap_rates: list[float], floor_rates: list[float], settings: Settings) -> YoYInflationCapFloor

Build a collar: long the cap at cap_rates, short the floor at floor_rates.

Parameters:

Name	Type	Description	Default
coupons	list[YoYInflationCoupon]	The leg the optionlets sit on.	required
cap_rates	list[float]	The cap strikes, padded as new() pads.	required
floor_rates	list[float]	The floor strikes, padded the same way.	required
settings	Settings	The explicit settings the instrument resolves its dates against.	required

Returns:

Name	Type	Description
YoYInflationCapFloor	YoYInflationCapFloor	The collar over that leg.

Raises:

Type	Description
ItofinError	On the same conditions new() reports.

with_strikes staticmethod

with_strikes(cap_floor_type: CapFloorType, coupons: list[YoYInflationCoupon], strikes: list[float], settings: Settings) -> YoYInflationCapFloor

Build a cap or a floor from a single strike vector.

Parameters:

Name	Type	Description	Default
cap_floor_type	CapFloorType	Cap or Floor.	required
coupons	list[YoYInflationCoupon]	The leg the optionlets sit on.	required
strikes	list[float]	Cap rates for a Cap and floor rates for a Floor.	required
settings	Settings	The explicit settings the instrument resolves its dates against.	required

Returns:

Name	Type	Description
YoYInflationCapFloor	YoYInflationCapFloor	The built instrument.

Raises:

Type	Description
ItofinError	On an empty strikes, on a Collar - which needs two vectors, so collar() is its constructor - and on the same conditions new() reports.

cap_rates

cap_rates() -> list[float]

Return the cap strikes, one per coupon.

Returns:

Type	Description
list[float]	list[float]: The cap strikes; empty on a floor.

floor_rates

floor_rates() -> list[float]

Return the floor strikes, one per coupon.

Returns:

Type	Description
list[float]	list[float]: The floor strikes; empty on a cap.

coupon_count

coupon_count() -> int

Return the number of optionlets.

Returns:

Name	Type	Description
int	int	One per year-on-year coupon on the leg.

start_date

start_date() -> Date

Return the leg's earliest accrual start.

Returns:

Name	Type	Description
Date	Date	The first accrual start date.

Raises:

Type	Description
ItofinError	On an empty leg, which the constructors already refuse.

maturity_date

maturity_date() -> Date

Return the leg's latest accrual end.

Returns:

Name	Type	Description
Date	Date	The last accrual end date.

Raises:

Type	Description
ItofinError	On the same conditions start_date reports.

atm_rate

atm_rate(discount_curve: YieldTermStructure) -> float

Return the strike at which the leg reprices on discount_curve.

The core takes the curve itself rather than a handle, so the link is resolved for the call.

Parameters:

Name	Type	Description	Default
discount_curve	YieldTermStructure	The curve the leg reprices on.	required

Returns:

Name	Type	Description
float	float	The at-the-money rate.

Raises:

Type	Description
ItofinError	On an unlinked discount_curve, a curve with no reference date, and a leg with no basis-point sensitivity to solve over.

set_engine

set_engine(engine: YoYInflationCapFloorEngine) -> None

Attach an engine, replacing whatever the factory installed.

Parameters:

Name	Type	Description	Default
engine	YoYInflationCapFloorEngine	The engine, which must resolve its dates against the same Settings object this cap/floor was built with: two different ones would price the leg and the optionlets on different dates with no error raised.	required

calculate

calculate() -> None

Force the valuation. Idempotent.

Raises:

Type	Description
ItofinError	If no engine is attached, no evaluation date is set, or the engine refuses the instrument.

is_calculated

is_calculated() -> bool

Return whether the cached results are currently valid.

Returns:

Name	Type	Description
bool	bool	True when the next accessor reads the cache.

price

price(engine: YoYInflationCapFloorEngine) -> float

Attach engine and return the NPV.

Replaces whatever engine the factory installed.

Parameters:

Name	Type	Description	Default
engine	YoYInflationCapFloorEngine	The engine to install and price on.	required

Returns:

Name	Type	Description
float	float	The cap/floor value.

Raises:

Type	Description
ItofinError	On anything that makes the valuation fail.

results

results() -> Results

Return a frozen snapshot of the valuation, calculating first.

Returns:

Name	Type	Description
Results	Results	A copy of the valuation results.

Raises:

Type	Description
ItofinError	On anything that makes the valuation fail.

npv

npv() -> float

Return the cap/floor NPV under the attached engine.

Returns:

Name	Type	Description
float	float	The present value.

Raises:

Type	Description
ItofinError	If no engine is attached, which the core reports as "null pricing engine", and on whatever the engine reports.