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

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

AverageBMACoupon

AverageBMACoupon(payment_date: Date, nominal: float, start_date: Date, end_date: Date, index: BMAIndex, day_counter: DayCounter, gearing: float = 1.0, spread: float = 0.0, reference_start: Optional[Date] = None, reference_end: Optional[Date] = None)

Calendar-day weighted municipal coupon with its arithmetic-average pricer.

Create a calendar-day averaged coupon with explicit accrual conventions.

rate

rate() -> float

Weighted rate after gearing and spread.

amount

amount() -> float

Undiscounted coupon payment.

accrual_period

accrual_period() -> float

Coupon accrual year fraction, including explicit reference dates.

fixing_dates

fixing_dates() -> list[Date]

Copy of weekly fixing boundaries.

BlackIborCouponPricer

Black or normal ibor coupon pricer using an optional retained optionlet surface.

CPICashFlow

CPICashFlow(nominal: float, index: ZeroInflationIndex, base_cpi: float, observation_date: Date, observation_lag: Period, interpolation: CpiInterpolationType, payment_date: Date, growth_only: bool = True)

Principal scaled by a live CPI observation divided by a fixed explicit base.

Build without reading fixings; growth_only subtracts the uninflated nominal.

The explicit finite nonzero denominator stays fixed. Observation, index histories and linked curves remain live. Invalid dates and lags fail.

amount

amount() -> float

Undiscounted payment; missing fixings, curves or non-finite results fail.

base_fixing

base_fixing() -> float

The fixed explicit denominator supplied at construction.

index_fixing

index_fixing() -> float

The live lagged CPI level used in the numerator.

date

date() -> Date

Payment date; no fixing is read.

as_cashflow

as_cashflow() -> CashFlow

Return a retained generic flow; the original wrapper may be released.

as_leg

as_leg() -> Leg

Return a one-flow leg requiring the index's identical Settings for NPV.

CPICoupon

CPICoupon(base_cpi: float, payment_date: Date, nominal: float, start_date: Date, end_date: Date, index: ZeroInflationIndex, observation_lag: Period, interpolation: CpiInterpolationType, day_counter: DayCounter, fixed_rate: float, reference_start: Optional[Date] = None, reference_end: Optional[Date] = None, ex_coupon_date: Optional[Date] = None)

Explicit-base CPI-scaled fixed coupon. Attach a plain pricer before pricing.

Build a coupon using an explicit CPI denominator and lagged observation.

Attach a CPICouponPricer before rate or amount queries. The base CPI must be finite and nonzero; its interpolation convention is caller-owned.

Raises:

Type	Description
ItofinError	On invalid terms, dates, lags or a non-finite parameter.

from_base_date staticmethod

from_base_date(base_date: Date, payment_date: Date, nominal: float, start_date: Date, end_date: Date, index: ZeroInflationIndex, observation_lag: Period, interpolation: CpiInterpolationType, day_counter: DayCounter, fixed_rate: float, reference_start: Optional[Date] = None, reference_end: Optional[Date] = None, ex_coupon_date: Optional[Date] = None) -> CPICoupon

Build a coupon with a lazy, live CPI denominator observed from base_date. Existing explicit-base construction is unchanged. Use base_fixing(), not the native stored-base MAX sentinel, for the effective denominator.

base_fixing

base_fixing() -> float

Effective denominator, read live for a date-based coupon.

CPICouponPricer

CPICouponPricer(nominal_curve: Optional[YieldTermStructure] = None)

Plain CPI swaplet pricer. Discounted prices are per unit nominal.

Build a plain CPI swaplet pricer, optionally retaining a nominal curve.

Rate queries need no nominal curve; swaplet_price requires one and returns a discounted value per unit nominal, not a currency amount.

CPILeg

CPILeg(schedule: Schedule, index: ZeroInflationIndex, base_cpi: float, observation_lag: Period, notionals: Sequence[float], fixed_rates: Sequence[float], day_counter: DayCounter, payment_calendar: Calendar, payment_adjustment: BusinessDayConvention, interpolation: CpiInterpolationType = Flat, growth_only: bool = True, ex_coupon_period: Optional[Period] = None, ex_coupon_calendar: Optional[Calendar] = None, ex_coupon_adjustment: BusinessDayConvention = Unadjusted, ex_coupon_end_of_month: bool = False)

Plain CPI coupons and one terminal indexed principal payment.

Materialize plain CPI coupons and one indexed terminal payment.

Payment and ex-coupon dates are fixed at construction. CPI histories and linked curves remain live; build clones the retained cash-flow graph. A default plain pricer is attached, and growth_only selects whether the uninflated terminal principal is subtracted.

Raises:

Type	Description
ItofinError	On invalid terms, calendars, dates or leg parameters.

from_base_date staticmethod

from_base_date(schedule: Schedule, index: ZeroInflationIndex, observation_lag: Period, notionals: Sequence[float], fixed_rates: Sequence[float], day_counter: DayCounter, payment_calendar: Calendar, payment_adjustment: BusinessDayConvention, base_date: Optional[Date] = None, interpolation: CpiInterpolationType = Flat, growth_only: bool = True, ex_coupon_period: Optional[Period] = None, ex_coupon_calendar: Optional[Calendar] = None, ex_coupon_adjustment: BusinessDayConvention = Unadjusted, ex_coupon_end_of_month: bool = False) -> CPILeg

Build CPI coupons with a live base date and native terminal observation. Omitted base_date uses schedule start minus observation_lag. No fixings are read while constructing the retained, fixed-payment-date graph.

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.

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.

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.

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.

start_date

start_date() -> Date

Earliest coupon accrual start or non-coupon payment date; empty legs fail.

maturity_date

maturity_date() -> Date

Latest coupon accrual end or non-coupon payment date; empty legs fail.

previous_cash_flow_date

previous_cash_flow_date(settings: Settings, *, include_settlement_date_flows: Optional[bool] = None, settlement_date: Optional[Date] = None) -> Optional[Date]

Previous payment date, or None; date-only inspection needs no fixings.

next_cash_flow_date

next_cash_flow_date(settings: Settings, *, include_settlement_date_flows: Optional[bool] = None, settlement_date: Optional[Date] = None) -> Optional[Date]

Next payment date, or None; settlement-date policy follows Settings when omitted.

previous_cash_flow_amount

previous_cash_flow_amount(settings: Settings, *, include_settlement_date_flows: Optional[bool] = None, settlement_date: Optional[Date] = None) -> Optional[float]

Aggregate actual amount on the previous payment date, or None; includes principal.

next_cash_flow_amount

next_cash_flow_amount(settings: Settings, *, include_settlement_date_flows: Optional[bool] = None, settlement_date: Optional[Date] = None) -> Optional[float]

Aggregate actual amount on the next payment date, or None; includes principal.

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.

YoYInflationLeg

YoYInflationLeg(schedule: Schedule, payment_calendar: Calendar, index: YoYInflationIndex, observation_lag: Period, interpolation: CpiInterpolationType, payment_day_counter: DayCounter, notional: Optional[float] = None, notionals: Optional[Sequence[float]] = None, payment_adjustment: Optional[BusinessDayConvention] = None, fixing_days: Optional[int] = None, gearing: Optional[float] = None, gearings: Optional[Sequence[float]] = None, spread: Optional[float] = None, spreads: Optional[Sequence[float]] = None, caps: Optional[Sequence[float]] = None, floors: Optional[Sequence[float]] = 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().

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: Optional[YieldTermStructure] = 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: Optional[YieldTermStructure] = 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: Optional[YieldTermStructure] = 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.

ZeroInflationCashFlow

ZeroInflationCashFlow(nominal: float, index: ZeroInflationIndex, start_date: Date, end_date: Date, observation_lag: Period, interpolation: CpiInterpolationType, payment_date: Date, growth_only: bool = True)

Principal scaled by the ratio of two live lagged inflation observations.

Build without reading fixings; both lagged start and end CPI remain live.

Unlike CPICashFlow, historical base-fixing corrections change this flow. The observation lag is nonnegative and dates must remain within 1901-2199.

amount

amount() -> float

Undiscounted payment; missing fixings, curves or non-finite results fail.

base_fixing

base_fixing() -> float

Read the live lagged start-date denominator, without taking a snapshot.

index_fixing

index_fixing() -> float

Read the live lagged end-date numerator.

date

date() -> Date

Payment date; no fixing is read.

as_cashflow

as_cashflow() -> CashFlow

Return a retained finite-checked generic flow.

as_leg

as_leg() -> Leg

Return a one-flow leg requiring the index's identical Settings for NPV.

npv

npv(leg: Leg, discount_curve: YieldTermStructure, settings: Settings, include_settlement_date_flows: Optional[bool] = None, settlement_date: Optional[Date] = None, npv_date: Optional[Date] = 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.

npv_at_z_spread

npv_at_z_spread(leg: Leg, discount_curve: YieldTermStructure, z_spread: float, compounding: Compounding, frequency: Frequency, settings: Settings, *, include_settlement_date_flows: Optional[bool] = None, settlement_date: Optional[Date] = None, npv_date: Optional[Date] = None) -> float

Currency NPV of the surviving leg discounted with a parallel zero-rate spread.

z_spread

z_spread(leg: Leg, npv: float, discount_curve: YieldTermStructure, compounding: Compounding, frequency: Frequency, settings: Settings, *, include_settlement_date_flows: Optional[bool] = None, settlement_date: Optional[Date] = None, npv_date: Optional[Date] = None, accuracy: float = 1e-10, max_evaluations: int = 100, guess: float = 0.0) -> float

Solve the parallel zero-rate spread repricing a leg's currency NPV.