QuantLib: Bond Class Reference

A free/open-source library for quantitative finance Reference manual - version 1.6

- Main Page
- Related Pages
- Modules
- Classes
- Examples

- Class List
- Class Index
- Class Hierarchy
- Class Members

Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
Bond Class Reference
Financial instruments

Base bond class. More...

`#include <ql/instruments/bond.hpp>`

Inheritance diagram for Bond:
[legend]

## Public Member Functions
| Bond (Natural settlementDays, const Calendar &calendar, const Date &issueDate=Date(), const Leg &coupons=Leg())
| constructor for amortizing or non-amortizing bonds. More...
| Bond (Natural settlementDays, const Calendar &calendar, Real faceAmount, const Date &maturityDate, const Date &issueDate=Date(), const Leg &cashflows=Leg())
| old constructor for non amortizing bonds. More...
virtual Rate | nextCouponRate (Date d=Date()) const
Rate | previousCouponRate (Date d=Date()) const
| Previous coupon already paid at a given date. More...
Date | nextCashFlowDate (Date d=Date()) const
Date | previousCashFlowDate (Date d=Date()) const
Instrument interface
bool | isExpired () const
| returns whether the instrument might have value greater than zero.
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 boost::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
Calculations
Real | cleanPrice () const
| theoretical clean price More...
Real | dirtyPrice () const
| theoretical dirty price More...
Real | settlementValue () const
| theoretical settlement value More...
Rate | yield (const DayCounter &dc, Compounding comp, Frequency freq, Real accuracy=1.0e-8, Size maxEvaluations=100) const
| theoretical bond yield More...
Real | cleanPrice (Rate yield, const DayCounter &dc, Compounding comp, Frequency freq, Date settlementDate=Date()) const
| clean price given a yield and settlement date More...
Real | dirtyPrice (Rate yield, const DayCounter &dc, Compounding comp, Frequency freq, Date settlementDate=Date()) const
| dirty price given a yield and settlement date More...
Real | settlementValue (Real cleanPrice) const
| settlement value as a function of the clean price More...
Rate | yield (Real cleanPrice, const DayCounter &dc, Compounding comp, Frequency freq, Date settlementDate=Date(), Real accuracy=1.0e-8, Size maxEvaluations=100) const
| yield given a (clean) price and settlement date More...
virtual Real | accruedAmount (Date d=Date()) const
| accrued amount at a given date More...
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, boost::any > & | additionalResults () const
| returns all additional result returned by the pricing engine.
void | setPricingEngine (const boost::shared_ptr< PricingEngine > &)
| set the pricing engine to be used. More...
Public Member Functions inherited from LazyObject
void | update ()
void | recalculate ()
void | freeze ()
void | unfreeze ()
Public Member Functions inherited from Observable
| Observable (const Observable &)
Observable & | operator= (const Observable &)
void | notifyObservers ()
Public Member Functions inherited from Observer
| Observer (const Observer &)
Observer & | operator= (const Observer &)
std::pair< std::set< boost::shared_ptr< Observable > >::iterator, bool > | registerWith (const boost::shared_ptr< Observable > &)
void | registerWithObservables (const boost::shared_ptr< Observer > &)
Size | unregisterWith (const boost::shared_ptr< Observable > &)
void | unregisterWithAll ()

## Protected Member Functions
void | setupExpired () const
void | setupArguments (PricingEngine::arguments *) const
void | fetchResults (const PricingEngine::results *) const
void | addRedemptionsToCashflows (const std::vector< Real > &redemptions=std::vector< Real >())
void | setSingleRedemption (Real notional, Real redemption, const Date &date)
void | setSingleRedemption (Real notional, const boost::shared_ptr< CashFlow > &redemption)
void | calculateNotionalsFromCashflows ()
Protected Member Functions inherited from Instrument
void | calculate () const
virtual void | performCalculations () const
Protected Member Functions inherited from LazyObject

## Protected Attributes
Natural | settlementDays_
Calendar | calendar_
std::vector< Date > | notionalSchedule_
std::vector< Real > | notionals_
Leg | cashflows_
Leg | redemptions_
Date | maturityDate_
Date | issueDate_
Real | settlementValue_
Protected Attributes inherited from Instrument
boost::shared_ptr< PricingEngine > | engine_
Real | NPV_
Real | errorEstimate_
Date | valuationDate_
std::map< std::string, boost::any > | additionalResults_
Protected Attributes inherited from LazyObject
bool | calculated_
bool | frozen_

## 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 | ( | Natural | settlementDays,
|  | const 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 | ( | Natural | settlementDays,
|  | const 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

const Leg & cashflows | ( |  | ) | const

Note
  returns all the cashflows, including the redemptions.

const Leg & redemptions | ( |  | ) | const

returns just the redemption flows (not interest payments)

const boost::shared_ptr<CashFlow>& redemption | ( |  | ) | const

returns the redemption, if only one is defined

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.

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.

Real settlementValue | ( |  | ) | const

theoretical settlement value

The default bond settlement date is used for calculation.

Rate yield | ( | const DayCounter & | dc,
|  | Compounding | comp,
|  | Frequency | freq,
|  | Real | accuracy = `1.0e-8`,
|  | Size | maxEvaluations = `100`
| ) |  | const

theoretical bond yield

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

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.

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.

Real settlementValue | ( | Real | cleanPrice | ) | const

settlement value as a function of the clean price

The default bond settlement date is used for calculation.

Rate yield | ( | Real | cleanPrice,
|  | const DayCounter & | dc,
|  | Compounding | comp,
|  | Frequency | freq,
|  | Date | settlementDate = `Date()`,
|  | Real | accuracy = `1.0e-8`,
|  | Size | maxEvaluations = `100`
| ) |  | const

yield given a (clean) price and settlement date

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

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.

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.

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.

void setupExpired | ( |  | ) | const
| protectedvirtual

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

Reimplemented from Instrument.

void setupArguments | ( | PricingEngine::arguments * |  | ) | const
| protectedvirtual

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.

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

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.

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.

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.

void setSingleRedemption | ( | Real | notional,
|  | const boost::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.

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.