Cashflows

Coupons, legs and cashflow analytics.

cashflows

Runtime source shim for the native itofin.cashflows submodule.

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

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

YoYInflationCoupon

One coupon of a year-on-year inflation leg.

Built only through YoYInflationLeg, which attaches the pricer rate() and amount() need.

rate

rate() -> float

Return the rate the coupon accrues at: the geared index fixing plus the spread.

Returns:

Name	Type	Description
float	float	The pricer's swaplet rate.

Raises:

Type	Description
ItofinError	If no pricer is attached, or resolving the fixing fails - a missing history entry, or a forecast off an index with no curve linked.

amount

amount() -> float

Return what the coupon pays on its payment date, undiscounted.

Returns:

Name	Type	Description
float	float	rate() * accrual_period() * nominal().

Raises:

Type	Description
ItofinError	As rate().

fixing_date

fixing_date() -> Date

Return the date the observation is published on.

The reference-period end moved back by the observation lag, then back the fixing days. This is not the date the rate resolves at: an inflation index has no fixing calendar, so with no fixing days the roll is inert.

Returns:

Name	Type	Description
Date	Date	The publication date.

index_fixing

index_fixing() -> float

Return the year-on-year rate observed, before gearing and spread.

It lags off accrual_end_date(), not off fixing_date(): a year-on-year coupon overrides the base rule that reads the index at its fixing date.

Returns:

Name	Type	Description
float	float	The observed rate.

Raises:

Type	Description
ItofinError	As rate(), bar the missing pricer.

nominal

nominal() -> float

Return the nominal the coupon accrues on.

Returns:

Name	Type	Description
float	float	The nominal.

accrual_start_date

accrual_start_date() -> Date

Return the start of the accrual period.

Returns:

Name	Type	Description
Date	Date	The accrual start.

accrual_end_date

accrual_end_date() -> Date

Return the end of the accrual period, which is also where the observation lags from.

Returns:

Name	Type	Description
Date	Date	The accrual end.

accrual_period

accrual_period() -> float

Return the whole accrual period as a fraction of a year.

Measured with day_counter() over the reference period.

Returns:

Name	Type	Description
float	float	The year fraction.

date

date() -> Date

Return the payment date: the accrual end rolled on the leg's payment calendar.

Returns:

Name	Type	Description
Date	Date	The payment date.

day_counter

day_counter() -> DayCounter

Return the day counter the accrual is measured with.

Returns:

Name	Type	Description
DayCounter	DayCounter	The coupon day count.

gearing

gearing() -> float

Return the multiplicative coefficient applied to the index fixing.

Returns:

Name	Type	Description
float	float	The gearing.

spread

spread() -> float

Return the spread paid over the geared fixing.

Returns:

Name	Type	Description
float	float	The spread.

observation_lag

observation_lag() -> Period

Return how far back the coupon observes the index.

Returns:

Name	Type	Description
Period	Period	The observation lag.

interpolation

interpolation() -> CpiInterpolationType

Return how the observation interpolates between index fixings.

Returns:

Name	Type	Description
CpiInterpolationType	CpiInterpolationType	Flat or Linear.

fixing_days

fixing_days() -> int

Return the number of business days the fixing date rolls back by.

Returns:

Name	Type	Description
int	int	The fixing days.

YoYInflationOptionletCouponPricer

Values a capped or floored year-on-year coupon's optionlets off a volatility surface.

The distribution is chosen by the constructor: black is lognormal, unit_displaced lognormal in 1 + rate and bachelier normal. The settings behind volatility and behind the priced coupons' index must be the same object. nominal_ts is optional: only the discounted price path reads it.

black staticmethod

black(volatility: ConstantYoYOptionletVolatility, nominal_ts: YieldTermStructure | None = None) -> YoYInflationOptionletCouponPricer

Build a pricer valuing optionlets under the lognormal model.

Parameters:

Name	Type	Description	Default
volatility	ConstantYoYOptionletVolatility	The surface optionlet volatilities are read off.	required
nominal_ts	YieldTermStructure | None	The discount curve; only the discounted price path reads it.	None

Returns:

Name	Type	Description
YoYInflationOptionletCouponPricer	YoYInflationOptionletCouponPricer	The lognormal pricer.

unit_displaced staticmethod

unit_displaced(volatility: ConstantYoYOptionletVolatility, nominal_ts: YieldTermStructure | None = None) -> YoYInflationOptionletCouponPricer

Build a pricer valuing optionlets under the unit-displaced lognormal model.

Lognormal in 1 + rate, the usual quoting convention for an inflation rate that may go negative.

Parameters:

Name	Type	Description	Default
volatility	ConstantYoYOptionletVolatility	The surface optionlet volatilities are read off.	required
nominal_ts	YieldTermStructure | None	The discount curve; only the discounted price path reads it.	None

Returns:

Name	Type	Description
YoYInflationOptionletCouponPricer	YoYInflationOptionletCouponPricer	The unit-displaced pricer.

bachelier staticmethod

bachelier(volatility: ConstantYoYOptionletVolatility, nominal_ts: YieldTermStructure | None = None) -> YoYInflationOptionletCouponPricer

Build a pricer valuing optionlets under the normal model.

Parameters:

Name	Type	Description	Default
volatility	ConstantYoYOptionletVolatility	The surface optionlet volatilities are read off.	required
nominal_ts	YieldTermStructure | None	The discount curve; only the discounted price path reads it.	None

Returns:

Name	Type	Description
YoYInflationOptionletCouponPricer	YoYInflationOptionletCouponPricer	The normal pricer.

CappedFlooredYoYInflationCoupon

A year-on-year inflation coupon with a cap and/or floor on its rate.

Built only through YoYInflationLeg.capped_floored_coupons. A negative gearing swaps the two roles, so is_capped and effective_cap answer off the stored level rather than off what the leg was given.

rate

rate() -> float

Return the rate the coupon accrues at.

The underlying's swaplet rate plus the floorlet, less the caplet.

Returns:

Name	Type	Description
float	float	The capped and floored rate.

Raises:

Type	Description
ItofinError	If no pricer is attached, if resolving the fixing fails, or if the surface refuses the volatility - a strike outside its domain, or an observation before its base date.

amount

amount() -> float

Return what the coupon pays on its payment date, undiscounted.

Returns:

Name	Type	Description
float	float	rate() * accrual_period() * nominal().

Raises:

Type	Description
ItofinError	As rate().

is_capped

is_capped() -> bool

Return whether a cap applies.

Returns:

Name	Type	Description
bool	bool	True if the stored cap level is set.

is_floored

is_floored() -> bool

Return whether a floor applies.

Returns:

Name	Type	Description
bool	bool	True if the stored floor level is set.

effective_cap

effective_cap() -> float

Return the de-spread, de-geared cap the caplet is struck at.

Read off the stored level, so a negative gearing has already swapped the two roles.

Returns:

Name	Type	Description
float	float	(cap - spread) / gearing.

effective_floor

effective_floor() -> float

Return the de-spread, de-geared floor the floorlet is struck at.

Read off the stored level, so a negative gearing has already swapped the two roles.

Returns:

Name	Type	Description
float	float	(floor - spread) / gearing.

YoYInflationLeg

YoYInflationLeg(schedule: Schedule, payment_calendar: Calendar, index: YoYInflationIndex, observation_lag: Period, interpolation: CpiInterpolationType, payment_day_counter: DayCounter, notional: float | None = None, notionals: list[float] | None = None, payment_adjustment: BusinessDayConvention | None = None, fixing_days: int | None = None, gearing: float | None = None, gearings: list[float] | None = None, spread: float | None = None, spreads: list[float] | None = None, caps: list[float] | None = None, floors: list[float] | None = None)

Builds a sequence of year-on-year inflation coupons from a schedule.

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 coupons(). An unset optional leaves the core default in place: a ModifiedFollowing payment roll, no fixing days, a unit gearing and no spread.

The caps and floors lists select which of the two coupon types the leg produces: given either, coupons() hands back coupons the core deliberately leaves unpriced and capped_floored_coupons is the intended entry.

Configure a leg over schedule paying index, observed observation_lag back.

payment_day_counter is required here although the core takes it through a setter, so a missing one is a build-time error rather than one raised from coupons(). A notional is just as required by the core but stays optional, since the per-coupon notionals list is the other way to supply it; giving neither surfaces that error from coupons().

Parameters:

Name	Type	Description	Default
schedule	Schedule	The accrual schedule, one coupon per period.	required
payment_calendar	Calendar	The calendar payment dates roll on.	required
index	YoYInflationIndex	The index the coupons observe.	required
observation_lag	Period	How far back each coupon observes it.	required
interpolation	CpiInterpolationType	How the observation interpolates between index fixings.	required
payment_day_counter	DayCounter	The day count the accruals are measured with.	required
notional	float | None	One nominal for every coupon.	None
notionals	list[float] | None	A per-coupon nominal, the alternative to notional.	None
payment_adjustment	BusinessDayConvention | None	The payment roll; the core default is ModifiedFollowing.	None
fixing_days	int | None	The business days the fixing date rolls back by; the core default is none.	None
gearing	float | None	One gearing for every coupon; the core default is unit.	None
gearings	list[float] | None	A per-coupon gearing.	None
spread	float | None	One spread for every coupon; the core default is none.	None
spreads	list[float] | None	A per-coupon spread.	None
caps	list[float] | None	A per-coupon cap level; given either list, capped_floored_coupons is the intended entry.	None
floors	list[float] | None	A per-coupon floor level.	None

coupons

coupons() -> list[YoYInflationCoupon]

Return the coupons, each carrying the default swaplet pricer.

Every call rebuilds the leg, so the coupons handed back are fresh objects each time: bind the list once rather than calling this per read, or two reads compare different objects. Given caps or floors the coupons come back unpriced, and capped_floored_coupons is the intended entry.

Returns:

Type	Description
list[YoYInflationCoupon]	list[YoYInflationCoupon]: The freshly built coupons.

Raises:

Type	Description
ItofinError	If the leg has no notional, the schedule holds fewer than two dates, or there are more notionals, gearings or spreads than the schedule has periods.

capped_floored_coupons

capped_floored_coupons(pricer: YoYInflationOptionletCouponPricer) -> list[CappedFlooredYoYInflationCoupon]

Return the coupons wrapped in the leg's caps and floors, each carrying pricer.

The pricer is required rather than optional: the core withholds its default swaplet pricer from a capped leg, and a swaplet pricer could not value the optionlets anyway. One pricer is installed across every coupon. Rebuilt on every call, as coupons() is.

Parameters:

Name	Type	Description	Default
pricer	YoYInflationOptionletCouponPricer	The pricer installed across every coupon.	required

Returns:

Type	Description
list[CappedFlooredYoYInflationCoupon]	list[CappedFlooredYoYInflationCoupon]: The freshly built coupons.

Raises:

Type	Description
ItofinError	As coupons(), plus more caps or floors than the schedule has periods, and a cap sitting below its floor.

build

build() -> Leg

Return the leg with its coupon type erased, the form npv() sums.

The plain path erases coupons already carrying the default swaplet pricer. With a caps or floors list the erased coupons carry NO pricer, and because every call rebuilds the leg a pricer installed through capped_floored_coupons() does not reach them: a capped erased leg reports "pricer not set" from CashFlow.amount(), and the priced capped path stays capped_floored_coupons(). Rebuilt on every call.

Returns:

Name	Type	Description
Leg	Leg	The freshly built erased leg.

Raises:

Type	Description
ItofinError	As coupons().

CashFlow

One erased flow of a Leg, read-only.

It answers what it pays and when, which is all the leg-summing npv() needs; the concrete coupon accessors stay on the typed coupon wrappers.

amount

amount() -> float

Return what the flow pays on its date, undiscounted.

Returns:

Name	Type	Description
float	float	The undiscounted payment amount.

Raises:

Type	Description
ItofinError	On a coupon with no pricer attached, and on whatever resolving its fixing reports - a missing history entry, or a forecast off an index with no curve linked.

date

date() -> Date

Return the date the flow pays on.

Returns:

Name	Type	Description
Date	Date	The payment date.

Leg

A sequence of erased cash flows, built by a leg builder's build().

Indexable and sized, which with CashFlow's two accessors is enough to hand-check what npv() sums.

IborLeg

IborLeg(schedule: Schedule, index: IborIndex)

Builds a sequence of floating ibor coupons from a schedule.

The setters keep the core's fluent shape: each returns a NEW leg carrying the extra setting, so a leg bound to a name never changes under a later call. An unset optional leaves the core default in place: a Following payment roll and the index's own fixing days and day counter.

The coupons themselves are not exposed: they are consumed by the raw CapFloor.cap / floor / collar constructors, which is the reason this leg exists. No caps/floors setter is offered either - a capped leg withholds the default coupon pricer in the core, so the strikes belong on the cap/floor constructor.

Configure a leg over schedule paying index, on the schedule's own calendar.

Parameters:

Name	Type	Description	Default
schedule	Schedule	The accrual schedule, one coupon per period.	required
index	IborIndex	The index the floating coupons fix off.	required

with_notional

with_notional(notional: float) -> IborLeg

Return the leg with notional on every coupon.

Required: a leg built without one reports "no notional given" from coupon_count().

Parameters:

Name	Type	Description	Default
notional	float	The nominal every coupon accrues on.	required

Returns:

Name	Type	Description
IborLeg	IborLeg	A new leg carrying the notional.

with_payment_day_counter

with_payment_day_counter(day_counter: DayCounter) -> IborLeg

Return the leg accruing with day_counter, overriding the index's.

Parameters:

Name	Type	Description	Default
day_counter	DayCounter	The day count the accruals are measured with.	required

Returns:

Name	Type	Description
IborLeg	IborLeg	A new leg carrying the day counter.

with_payment_adjustment

with_payment_adjustment(convention: BusinessDayConvention) -> IborLeg

Return the leg rolling its payment dates with convention.

Parameters:

Name	Type	Description	Default
convention	BusinessDayConvention	The payment roll, overriding the core default of Following.	required

Returns:

Name	Type	Description
IborLeg	IborLeg	A new leg carrying the convention.

with_fixing_days

with_fixing_days(fixing_days: int) -> IborLeg

Return the leg fixing fixing_days business days before each accrual start.

Overrides the index's own count.

Parameters:

Name	Type	Description	Default
fixing_days	int	The business days each coupon fixes ahead of its accrual start.	required

Returns:

Name	Type	Description
IborLeg	IborLeg	A new leg carrying the fixing days.

coupon_count

coupon_count() -> int

Return the number of coupons the leg builds, one per schedule period.

The leg is rebuilt on every call, here and in the cap/floor constructors, so this counts the coupons a construction would produce rather than a stored list.

Returns:

Name	Type	Description
int	int	The coupon count.

Raises:

Type	Description
ItofinError	If the leg has no notional, the schedule holds fewer than two dates, or a coupon's own preconditions reject.

npv

npv(leg: Leg, discount_curve: YieldTermStructure, settings: Settings, include_settlement_date_flows: bool | None = None, settlement_date: Date | None = None, npv_date: Date | None = None) -> float

Return the NPV of leg: every surviving flow discounted on discount_curve.

Parameters:

Name	Type	Description	Default
leg	Leg	The erased flows to sum.	required
discount_curve	YieldTermStructure	The curve the flows discount on.	required
settings	Settings	The evaluation context deciding which flows have occurred.	required
include_settlement_date_flows	bool | None	Whether a flow paying exactly on the settlement date counts; None defers to the settings' include_todays_cash_flows policy.	None
settlement_date	Date | None	The date deciding which flows have occurred; None uses the evaluation date, which must then be set.	None
npv_date	Date | None	The date the sum is discounted to; None uses settlement_date.	None

Returns:

Name	Type	Description
float	float	The discounted sum; exactly 0.0 for an empty leg.

Raises:

Type	Description
ItofinError	On a flow or curve lookup failure, and without a settlement_date when the evaluation date is unset.