Struct FixedRateBond

pub struct FixedRateBond {Show 15 fields
    pub currency: Currency,
    pub schedule: Vec<NaiveDate>,
    pub coupon: f64,
    pub frequency: Frequency,
    pub day_count: DayCountFraction,
    pub face: f64,
    pub ex_div: Option<ExDivRule>,
    pub irregular_first: bool,
    pub irregular_last: bool,
    pub end_of_month: bool,
    pub outstanding: Vec<f64>,
    pub coupons: Leg,
    pub payment: PaymentRule,
    pub accrual_adjustment: Option<AccrualAdjustment>,
    pub settlement_lag: PaymentRule,
}

Expand description

A fixed-rate bullet bond. Every field is passive contract data.

Fields§

§currency: Currency

The currency the bond pays in.

§schedule: Vec<NaiveDate>

Coupon-period boundaries, ascending: issue first, maturity last.

Held rather than regenerated because ACT/ACT.ICMA measures time in the bond’s own periods — the schedule is part of the day count’s answer, not an input a caller can vary independently of it.

§coupon: f64

The annual coupon rate, as a decimal.

§frequency: Frequency

How often the coupon pays.

§day_count: DayCountFraction

The accrual and time-measure convention.

§face: f64

Face amount. Analytics are reported per 100 face regardless.

§ex_div: Option<ExDivRule>

The ex-dividend rule, when the market trades ex-div: a buyer settling strictly past a coupon’s detachment date forgoes that coupon and accrues negatively. None — the default — is always cum-dividend, and leaves every price bit-identical to a bond that never had the field.

§irregular_first: bool

Whether the first period is irregular — shorter or longer than a regular period — on a schedule this type generated. Under ACT/ACT ICMA such a period accrues over the notional regular periods ending on its first coupon date (the ISMA rule ISDA’s 1998 EMU and Market Conventions memo sets out) rather than against its own length.

Set only by the schedule builders (bullet, with_first_coupon); a schedule supplied whole — a day-chained market’s override — measures every period against its own length, and a caller replacing schedule by hand should clear it.

§irregular_last: bool

Whether the last period is irregular — shorter or longer than a regular period — on a schedule with_penultimate_coupon generated. Under ACT/ACT ICMA such a period accrues over the notional regular periods counted forward from its penultimate coupon date (ICMA Rule 251).

§end_of_month: bool

Whether the coupon grid rolls on the calendar end of the month.

Takes effect only when the maturity is the last day of its month: every regular boundary is then the last day of the month a whole number of periods before maturity (a 30 November maturity pays on 31 May; a 28 February one reaches 29 February in a leap year), where the clamped month shift keeps the maturity’s day. false from bullet; set by with_end_of_month.

§outstanding: Vec<f64>

The fraction of the original face outstanding in each coupon period, one entry per period — all ones for a bullet. An amortiser’s coupons accrue on the fraction alive in their period, the drop between two periods is paid as principal at the boundary, and the last fraction is the redemption. Every flow the bond reports stays per 100 of the original face; the market quotes per 100 of the face alive at settlement, and per_current_face and per_original_face convert between the two.

§coupons: Leg

The schedule as a leg: one fixed coupon per period on the street accrual, and the principal paid down at each period end, on the dates the bond pays. What legs() hands out and a cashflow table reads; the valuation reads dated_flows_per_100, and the two are the same flows.

§payment: PaymentRule

How an accrual end becomes a payment date. The street rolls the cash onto a business day while the period still accrues over its unadjusted boundaries, which is what keeps the clean price continuous across a coupon date.

PaymentRule::none() — the default — pays on the unadjusted accrual end, leaving every price, yield and spread bit-identical to a bond that never had the field.

§accrual_adjustment: Option<AccrualAdjustment>

How each schedule boundary rolls before it is accrued over — issue, coupon dates and maturity alike. Set by with_accrual_adjustment and applied wherever the grid is formed; None, the default, keeps the street’s unadjusted accrual.

§settlement_lag: PaymentRule

How a trade date becomes the date it settles on: a lag in business days on a calendar, set by with_settlement_lag and read by settlement_date. PaymentRule::none(), the default, settles on the trade date.

Implementations§

§

impl FixedRateBond

pub fn bullet( currency: Currency, issue: NaiveDate, maturity: NaiveDate, coupon: f64, frequency: Frequency, day_count: DayCountFraction, face: f64, ) -> Result<Self, CurveError>

A bullet bond paying coupon from issue to maturity.

The schedule is generated backwards from maturity at the coupon frequency, unadjusted — a yield-space quote is measured on the nominal schedule, not on rolled payment dates.

§Errors

CurveError::Malformed if maturity does not follow issue, or if the frequency does not divide the year into whole months.

§Panics

If the schedule needs more periods than fit an i32, which no bond does.

pub fn with_end_of_month(self, end_of_month: bool) -> Self

This bond with its coupon grid rolled on the calendar end of the month (see end_of_month), regenerated from issue to maturity as a bullet: the notional profile resets, so this precedes with_amortisation, and with_first_coupon reads the flag whichever order the two are applied in.

§Panics

Never for a bond bullet built: the frequency was checked there.

fn rebuild_grid(&mut self, months: i32)

The bullet grid from the schedule’s issue and maturity: backwards from maturity, so the regular periods anchor on the redemption date and any stub lands at the front — the street convention for a bullet — on the end-of-month grid where the flag asks for it.

pub fn with_payment_calendar( self, calendar: Arc<dyn Calendar>, convention: BusinessDayConvention, ) -> Self

The same bond paying on calendar under convention — a payment calendar and payment convention, both separate from the accrual schedule.

The accrual does not move: every period still accrues over its unadjusted boundaries. Only the date each flow is paid and discounted on rolls, which is the street’s unadjusted-accrual, rolled-payment bond.

pub fn with_accrual_adjustment( self, calendar: Arc<dyn Calendar>, convention: BusinessDayConvention, ) -> Self

The same bond accruing over boundaries rolled on calendar under convention: issue, every coupon date and maturity. A weekend coupon date accrues to the business day it rolls to, and the next period starts there. Opt-in: the default accrues unadjusted, which keeps the clean price continuous across a coupon.

Kept on the bond, so a schedule built afterwards rolls too. Set it before with_amortisation: two boundaries rolling onto one date merge, and a profile counts periods.

fn unadjusted(&self) -> &[NaiveDate]

The boundaries before any accrual roll: schedule itself for a bond accruing unadjusted.

fn rolled(&mut self, boundaries: Vec<NaiveDate>) -> Vec<NaiveDate>

boundaries rolled under the accrual adjustment, any two landing on one date merged, and the unadjusted grid kept beside them.

pub fn with_settlement_lag(self, days: i32, calendar: Arc<dyn Calendar>) -> Self

The same bond settling days business days on calendar after it trades.

pub fn settlement_date(&self, trade_date: NaiveDate) -> NaiveDate

The date a trade on trade_date settles on: the settlement lag walked from it, and never before issue.

pub fn payment_date(&self, accrual_end: NaiveDate) -> NaiveDate

The date an accrual ending on accrual_end is paid.

fn compile_leg(&self) -> Leg

The schedule as a leg — the flows dated_flows_per_100 materialises, as coupons: each period’s fixed coupon on the street accrual and the face alive in it, and a redemption on every period end where the profile steps down. A bullet redeems once, at maturity.

pub fn with_amortisation( self, outstanding: Vec<f64>, ) -> Result<Self, CurveError>

This bond with a notional profile: outstanding[k] is the fraction of the original face alive in coupon period k.

§Errors

CurveError::Malformed unless there is exactly one entry per period, the first is 1.0, and every entry is finite, positive and no greater than the one before it — a bond fully repaid before maturity has an earlier maturity, and a rising profile is not an amortiser.

pub fn is_amortising(&self) -> bool

Whether any principal is repaid before maturity.

pub fn outstanding_fraction(&self, date: NaiveDate) -> f64

The fraction of the original face alive on date: the first period’s before issue, zero at or after maturity, the containing period’s otherwise. A repayment at a period boundary has happened on the boundary date itself.

pub fn current_face(&self, date: NaiveDate) -> f64

The face alive on date: the original face times outstanding_fraction.

pub fn per_current_face( &self, per_100_original: f64, date: NaiveDate, ) -> Option<f64>

An amount per 100 of the original face restated per 100 of the face alive on date — the market’s quoting basis for an amortiser, and the identity for a bullet. None at or after maturity, when nothing is alive to quote against.

Every price this module reports is per 100 of the original face, so this is the one step between a reported price and a screen price.

pub fn per_original_face(&self, per_100_current: f64, date: NaiveDate) -> f64

The inverse of per_current_face: an amount per 100 of the face alive on date restated per 100 of the original face, which is what every pricing body here takes. Zero at or after maturity, when the quoted face is zero.

fn principal_per_100(&self, k: usize) -> f64

The principal per 100 of the original face paid at the end of period k: the drop to the next period’s fraction, or the whole remaining fraction at maturity.

pub fn with_ex_div(self, rule: ExDivRule) -> Self

This bond trading ex-dividend under rule.

fn ex_div_calendar(&self) -> Arc<dyn Calendar>

The calendar a business-day ex-div rule steps on: the currency’s settlement centre, or weekends only for a currency with no modelled centre.

pub fn ex_div_date(&self, coupon_date: NaiveDate) -> Option<NaiveDate>

The ex-dividend date of the coupon paying at coupon_date: the coupon date stepped back by the rule’s lag — business days on the currency’s settlement calendar, or calendar days. None without a rule.

pub fn forgone_coupon_date(&self, settlement: NaiveDate) -> Option<NaiveDate>

The coupon date a buyer settling on settlement forgoes: the end of the period containing it, when settlement is strictly past that coupon’s ex-div date. Settlement on the ex-div date is still cum (the UK DMO boundary). None without a rule, for a zero coupon, or outside the schedule.

pub fn is_ex_div(&self, settlement: NaiveDate) -> bool

Whether the bond trades ex-dividend at settlement.

pub fn from_static(stat: &BondStatic) -> Result<Self, CurveError>

The bullet a security-master static describes: its coupon, frequency, day count and face on the schedule generated from issue to maturity — or the static’s explicit schedule when it carries one.

§Errors

CurveError::Malformed if the static is not a fixed-coupon bond, its currency code is not a currency, or bullet rejects its dates or frequency.

pub fn with_first_coupon( self, first_coupon: NaiveDate, ) -> Result<Self, CurveError>

This bond with its first coupon paid on first_coupon: the schedule regenerated backwards from maturity to it, issue in front — a long first period where first_coupon is more than a period after issue (a gilt or Bund issued weeks before a coupon date and first paying a period later), a short one otherwise. Under ACT/ACT ICMA the period accrues over the notional regular periods ending on first_coupon.

Resets the notional profile to a bullet’s, so it precedes with_amortisation.

§Errors

CurveError::Malformed unless first_coupon lies strictly between issue and maturity on the maturity’s coupon grid.

pub fn with_penultimate_coupon( self, penultimate: NaiveDate, ) -> Result<Self, CurveError>

This bond with its last regular coupon paid on penultimate: the coupon grid anchored there — run back to issue, or to the first coupon where with_first_coupon stated one — and the final period from it to maturity, short or long as the maturity falls (FpML’s lastRegularPeriodEndDate). Under ACT/ACT ICMA the final period accrues over the notional regular periods counted forward from penultimate; under any other day count, the day count over it.

Resets the notional profile to a bullet’s, so it precedes with_amortisation.

§Errors

CurveError::Malformed unless penultimate lies strictly between issue and maturity.

fn splits_last_period(&self) -> bool

Whether the last period accrues by the ICMA split.

fn last_period_fraction(&self, from: NaiveDate, to: NaiveDate) -> f64

The ACT/ACT ICMA fraction of [from, to] in the last period: each part over the notional regular period it falls in, those periods counted forward from the penultimate coupon date — one for a short final period, two for a long one.

fn months_per_period(&self) -> Option<i32>

Months in one regular period, where the frequency divides the year. /// Months in one regular period, where the frequency divides the year.

fn splits_first_period(&self) -> bool

Whether the first period accrues by the ICMA split.

fn first_period_fraction(&self, from: NaiveDate, to: NaiveDate) -> f64

The ACT/ACT ICMA fraction of [from, to] in the first period: each part over the notional regular period it falls in, those periods counted back from the first coupon date — one of them for a short stub, two for a long first coupon.

pub fn issue(&self) -> NaiveDate

The issue date.

pub fn maturity(&self) -> NaiveDate

The maturity date.

fn icma_anchor(&self, settlement: NaiveDate) -> Option<(usize, f64)>

The index of the period containing settlement, and the ICMA time fraction from settlement to the end of it.

None once settlement is at or past maturity, where there is no containing period.

pub fn timed_flows_per_100( &self, settlement: NaiveDate, day_count: Option<DayCountFraction>, ) -> Vec<(f64, f64)>

The flows after settlement as (time, amount) pairs, with the time axis measured on day_count rather than on the bond’s own accrual basis — the yield basis’s day count, where it names one.

A named day count measures every flow’s time directly, so the ACT/ACT.ICMA anchor scheme is not used: the anchor is a reading of the bond’s own convention, and a caller who names another is asking for that one. The amounts are untouched — a day count changes when a flow is discounted from, never what it pays.

§Panics

If the schedule holds more periods than fit a u32, which no bond does.

fn step_time( &self, measure: DayCountFraction, start: NaiveDate, end: NaiveDate, last: NaiveDate, to: NaiveDate, ) -> f64

The yield time from last to to on measure, inside the accrual period [start, end] — one step of a stepwise yield-time axis.

From the period’s start it is the fraction start → to. From a date inside the period — a settlement, or a payment rolled past the start — it is the period’s fraction less the part already run, f(start, to) − f(start, last): the whole coupon period’s time less the accrued part, so a settlement on the 31st is measured as the accrual measures it. From before the start (a settlement before the issue) it is f(last, start) + f(start, to).

Only 30U/360 is told the period’s schedule context, as everywhere on the yield axis.

pub(crate) fn yield_time_to( &self, settlement: NaiveDate, date: NaiveDate, day_count: Option<DayCountFraction>, ) -> f64

The yield time from settlement to an arbitrary date on the axis timed_flows_per_100 builds: a redemption date (a call) that need not be a coupon date.

Stepwise where the measure does not split additively; otherwise the measure from settlement directly, as before.

pub(crate) fn period_accrual(&self, start: NaiveDate, end: NaiveDate) -> f64

The accrual fraction of the period [start, end], under the same contextual day-count call accrued uses — so the coupon paid at end is exactly the amount accrued converges to as settlement approaches it, stub periods included.

fn period_context(&self, start: NaiveDate, end: NaiveDate) -> PeriodContext

The schedule context of the period [start, end]: its end, the frequency, the maturity, whether the grid rolls on the month end (the flag set and the maturity a month end — the SIFMA “end-of-month security” 30U/360 reads), and the period’s own length as the ICMA reference.

pub fn accrued(&self, settlement: NaiveDate) -> f64

Accrued interest per 100 face at settlement.

§

impl FixedRateBond

pub fn dated_flows_per_100(&self, cut: NaiveDate) -> Vec<(NaiveDate, f64)>

The dated future flows per 100 face strictly after cut: each coupon (its own period’s accrual, stubs prorated) and the redemption at maturity. The dated sibling of timed_flows_per_100, for engines that place flows on calendar dates rather than year fractions.

pub fn accrued_flows_per_100( &self, cut: NaiveDate, ) -> Vec<(NaiveDate, NaiveDate, f64)>

As dated_flows_per_100, each flow also carrying the accrual end its coupon was earned to.

The two dates differ only under a payment calendar, and they answer different questions: the payment date says when the flow is paid and discounted, the accrual end says which period earned it. A reading that depends on the period — an inflation linker’s index observation, say — takes the second, so that rolling a payment off a holiday does not quietly re-observe the flow.

pub(crate) fn accrued_coupons_and_principal_per_100( &self, cut: NaiveDate, ) -> Vec<(NaiveDate, NaiveDate, f64, f64)>

accrued_flows_per_100 with each period’s coupon and principal apart: (accrual end, payment date, coupon, principal), both per 100 of the original face. The principal is the paydown at the period’s end, or the remaining face at maturity. A reading that treats principal differently from coupon — a linker’s par floor — takes this.

§

impl FixedRateBond

pub fn coupon(&self) -> f64

The coupon rate per year, as a fraction of face.

pub fn face(&self) -> f64

The face amount.

pub fn currency(&self) -> Currency

The currency the bond pays in.

pub fn price( &self, y: f64, settlement: NaiveDate, basis: PriceBasis, convention: YieldQuoteConvention, day_count: Option<DayCountFraction>, ) -> f64

The price at y on settlement: clean or dirty by basis, under the kernel convention names on this bond’s frequency, re-based on day_count where one is given. The verb the Python price forwards to, argument for argument.

pub fn yield_( &self, price: f64, settlement: NaiveDate, basis: PriceBasis, convention: YieldQuoteConvention, day_count: Option<DayCountFraction>, ) -> Result<f64, YieldSolveError>

The yield at price on settlement — the inverse of price on the same axes. Spelled with the trailing underscore on both surfaces, yield being a keyword in both languages.

§Errors

YieldSolveError where the price cannot be bracketed.

pub fn yield_moments( &self, y: f64, settlement: NaiveDate, convention: YieldQuoteConvention, day_count: Option<DayCountFraction>, ) -> Result<YieldMoments, NoSingleBasis>

The price and its first two yield derivatives at y, under the single compounding basis convention resolves to.

§Errors

NoSingleBasis for a convention whose kernel is not one discounting.

pub fn modified_duration( &self, y: f64, settlement: NaiveDate, convention: YieldQuoteConvention, day_count: Option<DayCountFraction>, ) -> Result<f64, NoSingleBasis>

Modified duration at y: −(1/P)·dP/dy under the named convention.

§Errors

As yield_moments.

pub fn macaulay_duration( &self, y: f64, settlement: NaiveDate, convention: YieldQuoteConvention, day_count: Option<DayCountFraction>, ) -> Result<f64, NoSingleBasis>

Macaulay duration at y: the PV-weighted time of the remaining flows.

§Errors

As yield_moments.

pub fn convexity( &self, y: f64, settlement: NaiveDate, convention: YieldQuoteConvention, day_count: Option<DayCountFraction>, ) -> Result<f64, NoSingleBasis>

Convexity at y: (1/P)·d²P/dy² under the named convention.

§Errors

As yield_moments.

pub fn dv01( &self, y: f64, settlement: NaiveDate, convention: YieldQuoteConvention, day_count: Option<DayCountFraction>, ) -> Result<f64, NoSingleBasis>

DV01 per 100 face at y.

§Errors

As yield_moments.

pub fn money_dv01( &self, y: f64, settlement: NaiveDate, convention: YieldQuoteConvention, day_count: Option<DayCountFraction>, ) -> Result<f64, NoSingleBasis>

DV01 in money at the bond’s own face.

§Errors

As yield_moments.

pub fn money_duration( &self, y: f64, settlement: NaiveDate, convention: YieldQuoteConvention, day_count: Option<DayCountFraction>, ) -> Result<f64, NoSingleBasis>

Money duration at the bond’s own face: modified duration times the money price.

§Errors

As yield_moments.

pub fn flows( &self, settlement: NaiveDate, day_count: Option<DayCountFraction>, ) -> Records

Every flow paying after settlement as a table — accrual_end (the period that earned it), payment_date, time from settlement on the bond’s own axis (under day_count where one is given) and amount per 100 — such that discounting the amounts over the times at a yield reproduces the dirty price at that yield. What the Python flows returns.

§Panics

Never for a well-formed bond: the timed and dated readings walk one schedule, and a disagreement between them is a defect, not an input.

pub fn instrument(&self) -> AnyInstrument

This bond as an instrument — the callable with an empty exercise schedule, which is the bullet under the same lattice — so it books, values and tables without naming the callable.

pub fn issued_by(&self, issuer: CreditCurveId) -> AnyInstrument

This bond as an instrument valued risky on issuer’s credit: each promised flow weighted by survival, plus a recovery-of-face leg. The empty callable, issued by issuer.