Bond Class Reference

Base bond class. More...

#include <ql/instruments/bond.hpp>

Inheritance diagram for Bond:

Classes
class	Price
	Bond price information. More...

Public Member Functions
	Bond (Natural settlementDays, Calendar calendar, const Date &issueDate=Date(), const Leg &coupons=Leg())
	constructor for amortizing or non-amortizing bonds.
	Bond (Natural settlementDays, Calendar calendar, Real faceAmount, const Date &maturityDate, const Date &issueDate=Date(), const Leg &cashflows=Leg())
	old constructor for non amortizing bonds.
Instrument interface
bool	isExpired () const override
	returns whether the instrument might have value greater than zero.
Observable interface
void	deepUpdate () override
Inspectors
Natural	settlementDays () const
const Calendar &	calendar () const
const std::vector< Real > &	notionals () const
virtual Real	notional (Date d=Date()) const
const Leg &	cashflows () const
const Leg &	redemptions () const
const ext::shared_ptr< CashFlow > &	redemption () const
Date	startDate () const
Date	maturityDate () const
Date	issueDate () const
bool	isTradable (Date d=Date()) const
Date	settlementDate (Date d=Date()) const
Public Member Functions inherited from Instrument
Real	NPV () const
	returns the net present value of the instrument.
Real	errorEstimate () const
	returns the error estimate on the NPV when available.
const Date &	valuationDate () const
	returns the date the net present value refers to.
template<typename T>
T	result (const std::string &tag) const
	returns any additional result returned by the pricing engine.
const std::map< std::string, ext::any > &	additionalResults () const
	returns all additional result returned by the pricing engine.
void	setPricingEngine (const ext::shared_ptr< PricingEngine > &)
	set the pricing engine to be used.
Public Member Functions inherited from LazyObject
void	update () override
bool	isCalculated () const
void	forwardFirstNotificationOnly ()
void	alwaysForwardNotifications ()
void	recalculate ()
void	freeze ()
void	unfreeze ()
Public Member Functions inherited from Observable
	Observable (const Observable &)
Observable &	operator= (const Observable &)
	Observable (Observable &&)=delete
Observable &	operator= (Observable &&)=delete
void	notifyObservers ()
Public Member Functions inherited from Observer
	Observer (const Observer &)
Observer &	operator= (const Observer &)
std::pair< iterator, bool >	registerWith (const ext::shared_ptr< Observable > &)
void	registerWithObservables (const ext::shared_ptr< Observer > &)
Size	unregisterWith (const ext::shared_ptr< Observable > &)
void	unregisterWithAll ()

Calculations
Natural	settlementDays_
Calendar	calendar_
std::vector< Date >	notionalSchedule_
std::vector< Real >	notionals_
Leg	cashflows_
Leg	redemptions_
Date	maturityDate_
Date	issueDate_
Real	settlementValue_
Real	cleanPrice () const
	theoretical clean price
Real	dirtyPrice () const
	theoretical dirty price
Real	settlementValue () const
	theoretical settlement value
Rate	yield (const DayCounter &dc, Compounding comp, Frequency freq, Real accuracy=1.0e-8, Size maxEvaluations=100, Real guess=0.05, Bond::Price::Type priceType=Bond::Price::Clean) const
	theoretical bond yield
Real	cleanPrice (Rate yield, const DayCounter &dc, Compounding comp, Frequency freq, Date settlementDate=Date()) const
	clean price given a yield and settlement date
Real	dirtyPrice (Rate yield, const DayCounter &dc, Compounding comp, Frequency freq, Date settlementDate=Date()) const
	dirty price given a yield and settlement date
Real	settlementValue (Real cleanPrice) const
	settlement value as a function of the clean price
Rate	yield (Bond::Price price, const DayCounter &dc, Compounding comp, Frequency freq, Date settlementDate=Date(), Real accuracy=1.0e-8, Size maxEvaluations=100, Real guess=0.05) const
	yield given a price and settlement date
virtual Real	accruedAmount (Date d=Date()) const
	accrued amount at a given date
virtual Rate	nextCouponRate (Date d=Date()) const
Rate	previousCouponRate (Date d=Date()) const
	Previous coupon already paid at a given date.
Date	nextCashFlowDate (Date d=Date()) const
Date	previousCashFlowDate (Date d=Date()) const
void	setupExpired () const override
void	setupArguments (PricingEngine::arguments *) const override
void	fetchResults (const PricingEngine::results *) const override
void	addRedemptionsToCashflows (const std::vector< Real > &redemptions=std::vector< Real >())
void	setSingleRedemption (Real notional, Real redemption, const Date &date)
void	setSingleRedemption (Real notional, const ext::shared_ptr< CashFlow > &redemption)
void	calculateNotionalsFromCashflows ()

Additional Inherited Members
Public Types inherited from Observer
typedef set_type::iterator	iterator
Protected Member Functions inherited from Instrument
void	calculate () const override
void	performCalculations () const override
Protected Attributes inherited from Instrument
Real	NPV_
Real	errorEstimate_
Date	valuationDate_
std::map< std::string, ext::any >	additionalResults_
ext::shared_ptr< PricingEngine >	engine_
bool	calculated_ = false
bool	frozen_ = false
bool	alwaysForward_

Detailed Description

Base bond class.

Derived classes must fill the uninitialized data members.

Warning

Most methods assume that the cash flows are stored sorted by date, the redemption(s) being after any cash flow at the same date. In particular, if there's one single redemption, it must be the last cash flow,

Tests

• price/yield calculations are cross-checked for consistency.
• price/yield calculations are checked against known good values.

Examples

FittedBondCurve.cpp.

Constructor & Destructor Documentation

Bond() [1/2]

Bond	(	Natural	settlementDays,
		Calendar	calendar,
		const Date &	issueDate = Date(),
		const Leg &	coupons = Leg() )

constructor for amortizing or non-amortizing bonds.

Redemptions and maturity are calculated from the coupon data, if available. Therefore, redemptions must not be included in the passed cash flows.

Bond() [2/2]

Bond	(	Natural	settlementDays,
		Calendar	calendar,
		Real	faceAmount,
		const Date &	maturityDate,
		const Date &	issueDate = Date(),
		const Leg &	cashflows = Leg() )

old constructor for non amortizing bonds.

Warning

The last passed cash flow must be the bond redemption. No other cash flow can have a date later than the redemption date.

Member Function Documentation

isExpired()

bool isExpired ( ) const

overridevirtual

returns whether the instrument might have value greater than zero.

Implements Instrument.

deepUpdate()

void deepUpdate ( )

overridevirtual

This method allows to explicitly update the instance itself and nested observers. If notifications are disabled a call to this method ensures an update of such nested observers. It should be implemented in derived classes whenever applicable

Reimplemented from Observer.

cashflows()

const Leg & cashflows

(

)

const

Note

returns all the cashflows, including the redemptions.

Examples

Bonds.cpp.

redemptions()

const Leg & redemptions

(

)

const

returns just the redemption flows (not interest payments)

redemption()

const ext::shared_ptr< CashFlow > & redemption

(

)

const

returns the redemption, if only one is defined

cleanPrice() [1/2]

Real cleanPrice

(

)

const

theoretical clean price

The default bond settlement is used for calculation.

Warning

the theoretical price calculated from a flat term structure might differ slightly from the price calculated from the corresponding yield by means of the other overload of this function. If the price from a constant yield is desired, it is advisable to use such other overload.

Examples

Bonds.cpp.

dirtyPrice() [1/2]

Real dirtyPrice

(

)

const

theoretical dirty price

The default bond settlement is used for calculation.

Warning

the theoretical price calculated from a flat term structure might differ slightly from the price calculated from the corresponding yield by means of the other overload of this function. If the price from a constant yield is desired, it is advisable to use such other overload.

Examples

Bonds.cpp.

settlementValue() [1/2]

Real settlementValue

(

)

const

theoretical settlement value

The default bond settlement date is used for calculation.

yield() [1/2]

Rate yield	(	const DayCounter &	dc,
		Compounding	comp,
		Frequency	freq,
		Real	accuracy = 1.0e-8,
		Size	maxEvaluations = 100,
		Real	guess = 0.05,
		Bond::Price::Type	priceType = Bond::Price::Clean ) const

theoretical bond yield

The default bond settlement and theoretical price are used for calculation.

Examples

Bonds.cpp.

cleanPrice() [2/2]

Real cleanPrice	(	Rate	yield,
		const DayCounter &	dc,
		Compounding	comp,
		Frequency	freq,
		Date	settlementDate = Date() ) const

clean price given a yield and settlement date

The default bond settlement is used if no date is given.

dirtyPrice() [2/2]

Real dirtyPrice	(	Rate	yield,
		const DayCounter &	dc,
		Compounding	comp,
		Frequency	freq,
		Date	settlementDate = Date() ) const

dirty price given a yield and settlement date

The default bond settlement is used if no date is given.

settlementValue() [2/2]

Real settlementValue

(

Real

cleanPrice

)

const

settlement value as a function of the clean price

The default bond settlement date is used for calculation.

yield() [2/2]

Rate yield	(	Bond::Price	price,
		const DayCounter &	dc,
		Compounding	comp,
		Frequency	freq,
		Date	settlementDate = Date(),
		Real	accuracy = 1.0e-8,
		Size	maxEvaluations = 100,
		Real	guess = 0.05 ) const

yield given a price and settlement date

The default bond settlement is used if no date is given.

accruedAmount()

virtual Real accruedAmount ( Date d = Date() ) const

virtual

accrued amount at a given date

The default bond settlement is used if no date is given.

Reimplemented in BTP, and CCTEU.

Examples

Bonds.cpp.

nextCouponRate()

virtual Rate nextCouponRate ( Date d = Date() ) const

virtual

Expected next coupon: depending on (the bond and) the given date the coupon can be historic, deterministic or expected in a stochastic sense. When the bond settlement date is used the coupon is the already-fixed not-yet-paid one.

The current bond settlement is used if no date is given.

Examples

Bonds.cpp.

previousCouponRate()

Rate previousCouponRate

(

Date

d = Date()

)

const

Previous coupon already paid at a given date.

Expected previous coupon: depending on (the bond and) the given date the coupon can be historic, deterministic or expected in a stochastic sense. When the bond settlement date is used the coupon is the last paid one.

The current bond settlement is used if no date is given.

Examples

Bonds.cpp.

setupExpired()

void setupExpired ( ) const

overrideprotectedvirtual

This method must leave the instrument in a consistent state when the expiration condition is met.

Reimplemented from Instrument.

setupArguments()

void setupArguments ( PricingEngine::arguments * ) const

overrideprotectedvirtual

When a derived argument structure is defined for an instrument, this method should be overridden to fill it. This is mandatory in case a pricing engine is used.

Reimplemented from Instrument.

Reimplemented in CallableBond, and ConvertibleBond.

fetchResults()

void fetchResults ( const PricingEngine::results * r ) const

overrideprotectedvirtual

When a derived result structure is defined for an instrument, this method should be overridden to read from it. This is mandatory in case a pricing engine is used.

Reimplemented from Instrument.

addRedemptionsToCashflows()

void addRedemptionsToCashflows ( const std::vector< Real > & redemptions = std::vector< Real >() )

protected

This method can be called by derived classes in order to build redemption payments from the existing cash flows. It must be called after setting up the cashflows_ vector and will fill the notionalSchedule_, notionals_, and redemptions_ data members.

If given, the elements of the redemptions vector will multiply the amount of the redemption cash flow. The elements will be taken in base 100, i.e., a redemption equal to 100 does not modify the amount.

Precondition

The cashflows_ vector must contain at least one coupon and must be sorted by date.

setSingleRedemption() [1/2]

void setSingleRedemption ( Real notional, Real redemption, const Date & date )

protected

This method can be called by derived classes in order to build a bond with a single redemption payment. It will fill the notionalSchedule_, notionals_, and redemptions_ data members.

setSingleRedemption() [2/2]

void setSingleRedemption ( Real notional, const ext::shared_ptr< CashFlow > & redemption )

protected

This method can be called by derived classes in order to build a bond with a single redemption payment. It will fill the notionalSchedule_, notionals_, and redemptions_ data members.

calculateNotionalsFromCashflows()

void calculateNotionalsFromCashflows ( )

protected

used internally to collect notional information from the coupons. It should not be called by derived classes, unless they already provide redemption cash flows (in which case they must set up the redemptions_ data member independently). It will fill the notionalSchedule_ and notionals_ data members.