QuantLib Bond Analytics Tutorial

1. QuantLib for Fixed Income
Products
-Jun Hong

2. Fixed income refers to any type of investment under which the borrower(issuer) is
obliged to make payments of a fixed amount (coupons and face value) on a fixed
schedule.
Up front, the investor longs the bond and pay 8,500. The sellor has to pay her the coupons by a fixed
schedule. At the maturity, the last coupon and the principal are paid.

3. Basic Business Knowledge
• Bonds and notes are quoted by clean prices and settled by dirty prices
• Dirty price is also called full price or invoice price
• Dirty price = clean price + accrued interest
• Accrued interest (AI) is the interest that has accumulated since the previous coupon payment
date
• Why don’t we quote the dirty prices? AI will arise and drop to zero basing on the coupon schedule
and that will distort the price
• Note that bonds are settled by dirty price and compared by yield to maturity because the
coupons are bonds different
• US treasury products consists of bills (12m and less), notes (<10 Year), and bonds (10 to 30 Year).
In addition we have STRIPS and TIPS.
• Bills are zero coupon products quoted by discount rate

4. Major QuantLib Classes for Fixed Income Analytics
• Cashflows and Cashflow: fixed income is mainly about cash flows. Cashflows is a tool box for Cashflow handling
• Schedule: helps to find out the dates for the cash flows
• DayCounter: for day count method. e.g. ACT/ACT
• BusinessDayConvention: for cash flow date adjustment
• Coupon: coupon is a subclass of Cashflow class
• Calendar: help to figure out holidays and business days
• InterestRate: has methods for rates related calculation
• Bond and FixedRateBond: fixed rate bond is a basic one we need to focus on
• We have classes for floaters, zero coupons, and inflation linked bonds (CPIBond)
• BondFuctions: helper class for cash flow related calculation
• BondHelper: helper class to link bond and curve together
• There are examples over QuantLib 1.7test-suitebonds.cpp and QuantLib1.7ExamplesBondsBonds.cpp

5. CashFlow, Coupon, and FixedRateCoupon
• CashFlow: it has information about the date and amount of cash flow
• Leg: It is a vector of CashFlow
typedef std::vector<boost::shared_ptr<CashFlow> > Leg;
• Coupon: implements part of the CashFlow interface but it is still abstract. It
provides derived classes with methods related to accrued interest calculation.
• FixedRateCoupon:
• FixedRateLeg: helper class building a sequence of fixed rate coupons

6. Class Calendar.hpp
• This class provides methods for determining whether a date is a business day or a
holiday for a given market.
• It is used for incrementing/decrementing a date of a given number of business
days e.g. T+1
• Evaluation date is not that important for most calculations and we care more
about the settlement date.
• Period class is a time unit we frequently use and it could be year, month, week, or
day.

7. Settlement Day
Settlement is more important than evaluation day. For example, a bond with
different evaluation days but the same settlement day would have the same price if
you pass different yield to maturity.

8. BusinessDayConvention.hpp
• These conventions specify the methods used to adjust a date in case it is not a
business day
Method Description
Following Choose the first business day after the given holiday.
Preceding Choose the first business day before the given holiday
Modified Following Choose the first business day after the given holiday unless it belongs to a different month, in
which case choose the first business day before the holiday.
Modified Preceding Choose the first business day before the given holiday unless it belongs to a different month, in
which case choose the first business day after the holiday.
Unadjusted Do not adjust
Nearest Choose the nearest business day to the given holiday. If both the preceding and following
business days are equally far away, default to following business day
Half Month Modified Following Choose the first business day after the given holiday unless that day crosses the mid-month
(15th) or the end of month, in which case choose the first business day before the holiday

9. Reference Data for a Fixed Income Products
• Straight forward concepts like maturity or coupon will not be explained here.
• Settlement Date: The is the date on which a trade is cleared. Namely, money and
product change hands.
• Issue Date: This is the earliest date on which the settlement can occur.
• Dated Date: This is the date from which the interest starts to accrue. It can be on,
before, or after the issue date. The dated date must be less than two normal
coupon periods before the first coupon date.
• Last Coupon Date: This is the last coupon date prior to maturity date. Note there
is a coupon payment on the maturity date but that is not called the last coupon
date.

10. About the Cash Flows
• First coupon period, regular coupon period, and last coupon period
• The first coupon period and last coupon period could be short, long,
or normal. The regular coupon periods are always normal.
First
Coupon
Period
Last
Coupon
Period
Regular
Coupon
Periods

11. About the Irregular First Coupon Period
• Normally the dated date is the same as issue date
• Short first coupon period
• Long first coupon period
Pseudo
Issue
Date
Normal
Issue
Date
First
Coupon
Date
Dated
Date
Normal
Issue
Date
First
Coupon
Date
Dated
Date

12. About the Irregular Last Coupon Period
• In most case normal maturity date is the same as maturity date
• Short first coupon period
LCF = (MD – LCD)/(NMD – LCD)
• Long first coupon period
LCF = 1+(MD – NMD)/(PMD – NMD)
Last
Coupon
Date
Normal
Maturity
Date
Pseudo
Maturity
Date
Maturity
Date
Last
Coupon
Date
Normal
Maturity
Date
Maturity
Date

13. Day Count Methods (DCM)
• QuantLib has the above DCM under QuntLib-1.7qltimedaycounters folder
• ACT/ACT
• ACT/365
• ACT(NL)/365: Feb 29 is not counted
• ACT/365(366 in a leap year)
• ACT/360
• 30/360
• 30/365 and 30E/360 are added to QuantLib yet

14. Some Examples for DCM
• ACT/ACT
D2-D1
Mar 1 to Mar 31 -> 30 days
Mar 1 to Apr 1 -> 31 days
• 30/360: each month counts as 30 days
Number od days = (Y2-Y1)360+(M2-M1)30+(D2-D1)
D2-D1
Mar 1 to Mar 31 -> 30 days
Mar 1 to Mar 30 -> 29 days
Mar 1 to Apr 1 -> 30 days
• 30E/360: the 31st is treated as if it was the 30th
D2-D1
Mar 1 to Mar 31 -> 29 days
Mar 1 to Mar 30 -> 29 days
Mar 1 to Apr 1 -> 30 days

15. Accrued Interest and DCM
• Accrued Interest is affected by the day count method
Previous Cpn
1/15/2016
Next Cpn
7/15/2016
Settlement
5/31/2016
DCM Jan 15 to May 31 Jan 15 to Jul 15 AIF
Act/Act 137 182 137/182
Act/365 137 365/2 137/182.5
Act(NL)/365 136 (Feb 29 not counted) 365/2 136/182.5
Act/360 137 360/2 137/180
30/360 136: (5-1)30+31-15 360/2 136/180
30/365 136 365/2 136/182.5
30E/360 136: (5-1)30+30-15 360/2 135/180

16. Ex-Dividend Trading
• Exist in some countries such as Australia and South Afarica
• Happens when the settlement date is on or after ex-dividend date and before the
next coupon date

17. Schedule.hpp
• This class is used to generate cash flow schedule. Fixed income is all about cash flows and
discounting.
• The date from the first to the last coupon period is very predictable except the end of month
adjustment. The first and last coupon period could be long or short. That is why the first coupon
date and the last coupon date are important. Issue date and maturity dates help on defining the
first and last coupon periods.
• End of month adjustment:
• If the
• QuantLib terminologies in this class may not match the bond products that well and here is a few
I noticed …
• effectiveDate: dated date
• terminationDate: maturity date
• firstDate: first coupon date
• nextToLastDate: last coupon date

18. CashFlows.hpp
• Note CashFlows is different from CashFlow and it is a tool box for Cashflow
handling
• It provides methods for cash flow iteration, accrued interest, net present value
(yield to price), price to yield conversion, dv01, duration, modified duration,
convexity, z-spread, and par rates calculations.
• Net present value (npv) could also be done via a curve discounting
• Fixed income pricing is all about discount the cash flows using a curve.
• Price and Yield conversion doesn’t depend on a yield curve and a formula is
sufficient.

19. Class InterestRate.hpp
• This class encapsulates the interest rate compounding algebra.
• It manages day count conventions, frequency, compounding conventions, and conversion
between different conventions.
• It handles compound (discount) factor calculations, and implied and equivalent rate
calculations.
• Supports simple, compounded, continuous, simple then compounded methods to
calculate discount factor
Simple: 1+(r/f)*fraction
Compounded: (1+r/f)^(n+ fraction)
Continuous: e^(rt)
Simple then compounded: use simple for the first period and compounded
for the rest of cash flows
fraction = number of days / period length

20. When Settlement Date is not in the Last Coupon Period
𝐂𝐥𝐞𝐚𝐧 𝐏𝐫𝐢𝐜𝐞 =
𝟏
(𝟏 +
𝒀
𝒇
) 𝑫𝑭
× {
𝒄
𝒇
+
𝒄
𝒀
𝟏 −
𝟏
𝟏 +
𝒀
𝒇
𝐧 + (𝐏𝐚𝐫 +
𝒄
𝒇
× 𝑳𝑪𝑭) ×
𝟏
𝟏 +
𝒀
𝒇
𝐧+𝐋𝐃𝐅} −
𝒄
𝒇
× 𝑨𝑰𝑭
Y: yield to maturity
f: frequency of coupon. 2 for semiannual
c: coupon
Par: redemption
LCF: last coupon factor is used to calculate the cpn on maturity date
LDF: used to discount cash flow at the maturity to last coupon date
n: number of coupon remaining – 2
AIF: accrued interest factor

21. Price Yield Formula Explained
𝐂𝐥𝐞𝐚𝐧 𝐏𝐫𝐢𝐜𝐞 =
𝟏
(𝟏 +
𝒀
𝒇
) 𝑫𝑭
× {
𝒄
𝒇
+
𝒄
𝒀
𝟏 −
𝟏
𝟏 +
𝒀
𝒇
𝐧 + (𝐏𝐚𝐫 +
𝒄
𝒇
× 𝑳𝑪𝑭) ×
𝟏
𝟏 +
𝒀
𝒇
𝐧+𝐋𝐃𝐅} −
𝒄
𝒇
× 𝑨𝑰𝑭
𝐂𝐥𝐞𝐚𝐧 𝐏𝐫𝐢𝐜𝐞 = 𝑫𝒊𝒔𝒄𝒐𝒖𝒏𝒕 𝒇𝒓𝒐𝒎 𝑪 𝒕𝒐 𝑩 × 𝑪𝒑𝒏 𝒂𝒕 𝑪 + 𝑪𝒑𝒏 𝒇𝒓𝒐𝒎 𝑫 𝒕𝒐 𝑬 + 𝑷𝒂𝒓 𝒂𝒏𝒅 𝑳𝒂𝒔𝒕 𝑪𝒑𝒏 − 𝑨𝑰

22. When Settlement Date is in the Last Coupon Period
It is quite common to use simple interest rate when only one period is left

23. Bond Inheritance Tree
The current bond tree
Bond interface defines methods such as accrued interest not meaningful for zero coupon bond. In the future, it makes
more sense to have a tree like this.
CPIBond is essentially a floating rate via adjusting the principal. We might want to put it together with floaters.
Bond
ZeroCouponBond FloatingRateBond FixedRateBond CPIBond
CouponBond
ZeroCouponBond FloatingRateBond FixedRateBondCPIBond
Bond

24. Class Bond.hpp
• Constructor
• accruedAmount(): calculate the accrued interest
• cleanPrice() and yield() methods: price and yield conversion
• Provide access to cashflow

25. It is quite natural to use schedule to specify the cash flow dates and pass the
settlement date, face value, coupon rate, DCM, payment convention, notional, and
issue date to build a bond.
Class FixedRateBond.cpp – Construct a Bond

26. Some thoughts to share
• Reading the code without any background knowledge is doable but time
consuming. That is why I prepared this document.
• Product knowledge is indispensable and there a lot of books and web sites for
that. Learning product knowledge by reading the QuantLib code is not
productive. I found myself in most case have a big picture and end up finding the
practical details in the code.
• It would be helpful to use a spread sheet to work out the details and then
implement it in QuantLib. It is indirect but effective.

27. Here is a Spread Sheet Example for Chinese Government Bond

28. To be continued …
• I am going to write about index lined bond like TIPS
• If you see any error in this document, please email me at
jhong111@yahoo.com and I will correct it accordingly