Today’s post was originally published in the November 2025 issue of Wilmott Magazine. What if you could make it a lot easier for readers to replicate your paper? That was the idea I followed when Wilmott called for articles to be published in a special issue on the replication crisis.

Subscribe now

The software side of replication

What if you could make it a lot easier for readers to replicate your paper?

Some years ago, I replicated the results of a paper on bootstrapping interest-rate curves and published my code; first as a book chapter, later as a blog post, and recently—for this very article, actually—as live code that you can execute in your browser.

You can do the same, if you want. In this article, I’ll describe some issues you might encounter and the tools you can throw at them until your paper is live on the Internet.

The first step

But first, a problem that’s not technical. Can you provide the data and the code for replicating your results? And if so, are you willing to do it?

The first is a legal problem, and of course it is what it is; you might not have the license to redistribute the data, or the permission to publish the code. I understand, I have a day job too. If that’s the case, the rest of this article won’t help you much (unless it’s only the data that you can’t share; in that case, you might share the code and tell people to input their own data into it).

However, I’ve seen cases in which the data and the code might have been shared, and in the end they weren’t. There were two different reasons for this.

Sometimes, I’ve seen people reason that if they published their code, someone else might take it and use it to beat them to the next paper. Of course, this can be a legitimate concern in a publish-or-perish environment. In this time and age, though, someone might feed your paper into an A.I. prompt and ask it to turn it into code anyway. Which, now that I think of it, raises an interesting question: can A.I. help with replication? It might be the subject of another article; feel free to beat me to it.

Some other times, people had every intention to publish their code, but they said: “it’s not clean code; let me polish it first, and then I’ll publish it”. Friend, let me tell you: you won’t. Other things will get in the way. Publish it, and let other people make it better. It has served me well for these 25 years of open-source work on QuantLib.

Once last consideration: if you publish your code, take a bit of time to choose a license. It might be an open-source license or not, that’s up to you; but people need to know what they can do with the code.

The paper

The paper I replicated is Ametrano and Bianchetti, Everything You Always Wanted to Know About Multiple Interest Rate Curve Bootstrapping but Were Afraid to Ask, published in 2013 and available from SSRN. It described how to bootstrap interest-rate curves in a multi-curve setting (not yet common knowledge at the time) using as a case study the EONIA and EURIBOR curves for different tenors. The authors used QuantLib for their calculations; to be precise, QuantLibXL, an Excel plugin wrapping it.

This made it a good showcase for the capabilities of the library, which is why I set up to replicate their calculations using the QuantLib wrappers for Python. I published the resulting code in 2016 in QuantLib Python Cookbook, which I co-authored, and in 2023 on my blog, Implementing QuantLib, for the ten years of the paper.

The paper provided the full set of market data used in the calculations, as well as some of the intermediate results.

Making code and data available

And now, we can start talking about actually publishing your code.

This will come as no surprise for most of you; nowadays, the preferred place to host code is GitHub, hands down. (Yes, I know: who would have said 20 years ago that the place where most open-source code lives would be operated by Microsoft?)

I’m assuming, of course, that you’re using version control for your code: GitHub hosts Git repositories, not just any bunch of files (the same goes for other alternatives like GitLab or Bitbucket). If you’re not, please, please do. You’re bound to get hurt otherwise.

And since I’m putting my code where my mouth is, GitHub is also where the code for my replication of the paper is hosted. The address is https://github.com/lballabio/ab-notebook (where ab stands for Ametrano and Bianchetti, of course, but I also couldn’t resist a tip of the hat to the Abby Normal bit in Young Frankenstein). I’ll refer to a few things in there, so please go open it in a browser now; I’ll wait.

Done? Good.

Languages and tooling

In my case, the choice of Python was straightforward, since it’s the language I’m more comfortable with among the ones in which QuantLib is available (the others being C# and Java, besides the native C++). You probably have your own preferred language, and that’s perfectly fine.

In any case, and depending on the ecosystem offered by the language, I would suggest using some tooling that makes your code available in a notebook-like environment. For an example, you can go back to the browser tab where you opened my repository and click on the index.ipynb file; GitHub will open it in a static viewer.

As you can see, it’s a notebook that mixes documentation, code, and the output of running the code; it also has specific formatting facilities for when the output is a data table or a plot. In this case, the tool I used to produce it was Jupyter, a notebook-like environment that can host Julia, Python or R code natively (hence the name). Other extensions give it the possibility of adding SQL queries into the mix, or of using other languages such as C++, C#, Java and possibly others that I’m not aware of.

Of course, Jupyter is not the only tool that does that. I think Mathematica was the first such environment (if we don’t count Donald Knuth’s work on literate programming), MATLAB has a Live Editor that provides a similar experience, and lately a bunch of tools have been created or extended to replicate the Jupyter interface, for instance Google Colab or even Visual Studio Code. Another strong contender is Observable, which uses JavaScript as its language, leverages excellent visualization libraries such as D3, and takes a different approach in which code cells are not executed sequentially but keeping track of their dependencies.

Taken to the extreme, using notebooks might allow you to write your paper and embed your code into it. If you’re interested, you can look into other tools such as Quarto, a publishing system that takes Jupyter notebooks and turns them into books, both PDF and online. It’s what I’m using to write my latest book, A QuantLib Guide; you’re welcome to visit it and see what the result can look like.

Replicating the environment

Once we start talking about tooling, we’re faced with a problem. Our code is going to depend on tools and external modules whose development we don’t control; for instance, if you look near the top of my notebook, you can see that I’m importing QuantLib, NumPy, pandas and Matplotlib, plus the datetime module from the Python standard library. And of course, I need Jupyter itself.

To recreate the environment for running my code, you’ll need to install all of those. The problem is that, if you come back in five or ten years, the interface or the behavior of those modules might have changed and my notebook might not run anymore (or might run and give different results). We need to use the same versions of the modules.

Moreover, those modules depend in turn on other modules, directly or indirectly; installing the five modules above (not counting datetime, that comes with Python) results in the installation of a whopping ninety-six additional dependencies, all of which release new versions regularly. How do we ensure that you and I run the code in the same environment?

In the past few years, a number of tools have been built around the same idea. Well, two ideas: as I wrote this, I realized that I was taking the first one for granted.

The first idea is that you need to have a separate environment for each project. If you need NumPy for a project, you don’t just run pip install and add it to your system installation; if you do that, eventually you’ll run into a wall when you try to install some module and find out that it requires fonttools version 4 or later, but you already have another module installed that requires fonttools to be at most version 3.8. Nowadays, tooling for virtual environments is available for most languages if not for all; for instance, Python distributes the virtualenv module in its standard library, but you’ll probably find something similar for your language, or at least a way to specify the directory where to search for modules.

Once we have the basics, the second idea comes into play: instead of installing modules manually, do it through some tool that records the exact versions of all the dependencies that get installed. Again, it’s an idea that’s been implemented for most languages; for example, Paket for C#, Bundler for Ruby or Cargo for Rust are three such tools.

The Python community has not standardized around a single tool; there are a few to choose from, such as Pipenv, Poetry, uv and probably others I’m not aware of. In this case, I chose Pipenv because it plays well with another tool I’ll mention later.

All these tools, for Python or otherwise, work by producing two files: a simpler file that lists the modules you specified directly, and a larger and more detailed file, usually called a lock file, in which all the dependencies and their versions are listed. If you look at my repository, you can see (and examine, if you want) the specification file Pipfile and the lock file Pipfile.lock. They are both supposed to be checked into version control, thus enabling reproducible builds; if you clone my repository on your machine and run pipenv install, the tool will notice the presence of the lock file, read it, check that you have the correct version of Python, and install the pinned versions of the dependencies.

If you’re looking at making your build reproducible for the long term, you might notice a possible problem with the above. What if I do all correctly, use a dependency tool to specify that my code needs traitlets 5.14.3, and ten years from now you try to recreate my environment only to find that that version, or even that module, is no longer available online? A possibility is to freeze the entire environment; for instance with Docker, a tool to create lightweight virtual machines. The resulting environment image can be published so that others can run calculations inside it.

Pinning your code

After the environment is locked, the other variable that remains is your own code. It will change, too, as you work on your next paper and add features: you might decide that some function needs a new parameter, or that a calculation can be done in a different way that accommodates old and new features. And as you do that, you might not have the time to go back and update your old notebooks, or you might find that your time is better spent elsewhere.

That’s ok. We have version control.

When you finalize your paper, tag the version of the code you used. The tag doesn’t need to be in a particular format, so it can be a mnemonic for the paper; if you plan to make further changes to the code, though, it might be a good idea to use some kind of version number such as 1.0.

Once the tag is created and pushed to your online repository, it makes it possible for people to find that specific version of the code; just mention the tag in your paper. If you want, you can stop there and start working on further changes to your code.

However, GitHub added some features around it that you might want to use: for instance, you can turn your tag into a release. This creates a specific page for the tag and gives you the possibility to add release notes that will be displayed there. If you look at my repository on GitHub, you’ll see a “Releases” heading on the right side giving easy access to the latest released version of the code; you can click it to see what a release looks like.

GitHub releases can also be integrated with other sites, such as CERN’s Zenodo. If you get a free account there and set up the integration with your GitHub repository, creating a release will automatically cause Zenodo to download and store it; as it does so, it will also generate a unique Digital Object Identifier (DOI) through which your code can be cited.

And while we’re on the subject of citations: adding a CITATION.cff file to your repository with the relevant information will make it easier for people to cite your work correctly. If you do so, GitHub will add a link under the “About” heading in your repository page from which people can copy the APA text or BibTeX code for the citation, ready to paste in their bibliography. Again, you can see an example in my repository.

An online playground

I’ll finish by mentioning a possible way to make it even easier for people to experiment with your code.

All of the above (pinning the dependencies and the code) make it possible to reproduce your exact build on one’s local machine. However, there are tools that allow you to set up an online environment so that people can run your code directly in their browser.

Some of the tools I mentioned above (Colab or Observable, to name two) run natively on the Internet. Jupyter doesn’t, per se; but it can be run remotely by using Binder. Strictly speaking, Binder is a server that anyone can host; however, thanks to sponsorships from a few scientific institutes, it also provides mybinder.org as a service.

Simply put, you can tell Binder the address of a GitHub repository that contains Jupyter notebooks and it will spawn a Jupyter server where you can run them, no installation required on your part. If you want to try my notebook, I provided a shortcut: look at the README file displayed on my Github repository page and you’ll find there a “launch binder” badge that you can click to start the process.

It will take a couple of minutes to create the environment and start it. While you wait, and especially if you plan to use Binder with your code, consider clicking the “Donate” button on the top right. Unlike GitHub, which has a free tier but also a subscription model for enterprises, the Jupyter project lives on sponsorships and contributions alone.

Conclusion

I don’t expect this article to be exhaustive—which would be pointless, anyway, as the list of available tools is always growing. What I hope is that it gives you a vista on some of the possibilities that the current landscape offers, that it will make you play with a few of these tools, and maybe that it will make you consider using them next time you publish a paper. Have fun experimenting!

Subscribe now

(And before I forget, let me remind you that the Internet Archive provides a great service and you should donate if you can. I just did.)

Now, as I was saying: using A.I. for coding. In the past few months I started receiving pull requests for QuantLib that were developed using it, and I’m not saying that to disparage them: the authors made no mystery about it, and the quality was good. I might have been lucky. Anyway, this got me thinking: is there any way (ranging from a simple AGENTS.md to a more elaborate harness) in which we can make it easier for people to use A.I. when contributing to QuantLib?

I don’t have definitive answers myself: I’ve been using Claude for just a few months now on proprietary code at work, I like what I’m seeing so far, but I’m not an expert. Instead, I’m hoping to start a discussion about this: I opened an issue on GitHub to host it, and you’re welcome to contribute your experience, suggestions, caveats, or whatever you think useful.

That’s all for today; I’ll get out of the way now and let you think about it. Thanks, and see you next time—or, hopefully, on GitHub.

Subscribe now

This is actually not the notebook I wanted to write this time, but the one I did want to write needs some enhancements in the library first. They will be included in version 1.42, out in April with lots of other goodies from contributors old and new. Stay tuned.

Spread calculations

import QuantLib as ql

today = ql.Date(16, ql.March, 2026)
ql.Settings.instance().evaluationDate = today

bps = 1e-4

We have already seen an example of z-spread calculation in the first notebook of the guide. In this notebook, we’ll show how to calculate a few other spreads, as well as a couple of functions that can be used in the particular case of a fixed-rate bond.

I’ll start by building a simple bond.

schedule = ql.MakeSchedule(
    effectiveDate=ql.Date(26, ql.May, 2020),
    terminationDate=ql.Date(26, ql.May, 2040),
    frequency=ql.Annual,
    calendar=ql.UnitedStates(ql.UnitedStates.GovernmentBond),
    convention=ql.Following,
    backwards=True,
)

settlement_days = 3
face_amount = 1_000_000.0
coupons = [0.02]
day_counter = ql.Thirty360(ql.Thirty360.BondBasis)

bond = ql.FixedRateBond(
    settlement_days,
    face_amount,
    schedule,
    coupons,
    day_counter,
)

The i-spread

The i-spread of the bond is the difference between its yield and an interpolated swap rate corresponding to its maturity date. There is no built-in function in QuantLib that returns it, but it can be calculated as follows.

Given a quoted price, the yield can be calculated without having to define a discount curve:

price = ql.BondPrice(98.08, ql.BondPrice.Clean)

y = bond.bondYield(
    price,
    day_counter,
    ql.SimpleThenCompounded,
    ql.Annual,
)
print(y)

0.021578895425796538

The interpolated swap rate can also be calculated from simple market data. Here we have a series of quoted OIS rates:

ois_data = dict(
    [
        ("1Y", 0.137),
        ("2Y", 0.409),
        ("3Y", 0.674),
        ("5Y", 1.004),
        ("8Y", 1.258),
        ("10Y", 1.359),
        ("12Y", 1.420),
        ("15Y", 1.509),
        ("20Y", 1.574),
        ("25Y", 1.586),
        ("30Y", 1.579),
        ("35Y", 1.559),
        ("40Y", 1.514),
        ("45Y", 1.446),
        ("50Y", 1.425),
    ]
)

Given the maturity of the bond (a bit more than 14 years) we’ll have to interpolate linearly between the 12-years and the 15-years rate—assuming, of course, that no other quoted rates are available in this range.

t1 = day_counter.yearFraction(today, today + ql.Period("12Y"))
t2 = day_counter.yearFraction(today, today + ql.Period("15Y"))

r1 = ois_data["12Y"] / 100
r2 = ois_data["15Y"] / 100

f = ql.LinearInterpolation([t1, t2], [r1, r2])

T = day_counter.yearFraction(today, bond.maturityDate())
print(T)

14.202777777777778

R = f(T)
print(R)

0.01485349074074074

And here is our spread, shown in basis points for convenience:

i_spread = y - R
i_spread / bps

67.25404685055797

The z-spread

The calculation of the z-spread requires a base interest-rate curve. In this case, we’ll use a risk-free curve derived from the quoted OIS shown in the previous section…

index = ql.Sofr()

settlement_days = 2

ois_helpers = []
for tenor in ois_data:
    q = ql.SimpleQuote(ois_data[tenor] / 100)
    ois_helpers.append(
        ql.OISRateHelper(
            settlement_days,
            ql.Period(tenor),
            ql.QuoteHandle(q),
            index,
            paymentFrequency=ql.Annual,
        )
    )

sofr_curve = ql.PiecewiseLogCubicDiscount(
    0,
    ql.UnitedStates(ql.UnitedStates.GovernmentBond),
    ois_helpers,
    ql.Actual360(),
)

sofr_handle = ql.YieldTermStructureHandle(sofr_curve)

…but the base curve might be any other one; for instance, a government curve fitted on quoted bond prices.

In the case of fixed-rate bonds, the library provides a function to calculate the z-spread directly:

z = ql.BondFunctions.zSpread(
    bond,
    price,
    sofr_curve,
    day_counter,
    ql.SimpleThenCompounded,
    ql.Annual,
)
z / bps

64.75673883414345

However, there’s a snag. The function above takes the day-count convention we want to use for the spread, but due to limitations of the implementation the argument is ignored: passing a different convention returns the same result.

ql.BondFunctions.zSpread(
    bond,
    price,
    sofr_curve,
    ql.Actual360(),
    ql.SimpleThenCompounded,
    ql.Annual,
) / bps

64.75673883414345

In fact, we’re in the process of deprecating the signature above and replacing it with one that doesn’t include the day-count convention.

The returned rate uses the same day-count convention of the base curve. If we want to express it according to a different convention, we can use the methods of the InterestRate class to convert it into an equivalent rate, given a start and end date; for instance, today and one year from now.

ql.InterestRate(
    z,
    sofr_curve.dayCounter(),
    ql.SimpleThenCompounded,
    ql.Annual,
).equivalentRate(
    day_counter,
    ql.SimpleThenCompounded,
    ql.Annual,
    today,
    today + ql.Period("1Y"),
).rate() / bps

65.65908427374367

In the case of a less simple bond (for instance, a floater), the function above won’t work and we’ll have to resort to a more generic calculation; that is, create a discount curve by adding a spread over the base curve…

spread = ql.SimpleQuote(0.0)
discount_curve = ql.ZeroSpreadedTermStructure(
    sofr_handle,
    ql.QuoteHandle(spread),
    ql.SimpleThenCompounded,
    ql.Annual,
)

bond.setPricingEngine(
    ql.DiscountingBondEngine(
        ql.YieldTermStructureHandle(discount_curve)
    )
)

…and using a root solver to find the spread for which the bond price (as calculated off this curve) equals the quoted price.

def discrepancy(s):
    spread.setValue(s)
    return bond.cleanPrice() - price.amount()


solver = ql.Brent()
accuracy = 1e-5
guess = 0.015
step = 1e-4

solver.solve(discrepancy, accuracy, guess, step) / bps

64.75637679007006

In this case, the bond was a fixed-rate one so we can compare the result with the one returned by the zSpread function shown above. As you can see, this calculation returns the same rate within numerical accuracy; this shows that this calculation, too, uses the same day-count convention as the base curve.

The option-adjusted spread

Finally, we have a third kind of spread, which is defined for bonds that include optionality. In the case of callable bonds, the library provides an OAS method that returns the option-adjusted spread. In order to use it, you’ll have to set the bond up so that it’s priced on a trinomial tree based on a short-rate model: Hull-White, for instance.

bond = ql.CallableFixedRateBond(
    settlement_days,
    face_amount,
    schedule,
    coupons,
    day_counter,
    ql.Following,
    100.0,
    schedule[0],
    [
        ql.Callability(
            ql.BondPrice(100.0, ql.BondPrice.Clean),
            ql.Callability.Call,
            schedule[15],
        )
    ],
)

bond.setPricingEngine(
    ql.TreeCallableFixedRateBondEngine(
        ql.HullWhite(sofr_handle, a=0.1, sigma=0.01), 100
    )
)

As expected, the same target price returns a tighter spread.

bond.OAS(
    price.amount(),
    sofr_handle,
    day_counter,
    ql.SimpleThenCompounded,
    ql.Annual,
) / bps

48.39174863100259

See you next time!

Subscribe now

Let me mention again that, if you find the guide useful and want to support the effort, you can do so by buying a PDF version. It’s published on Leanpub, which means that you’ll have free access to any future updates.

So, here is the list:

• there’s a new notebook on interest-rate indexes that shows how they behave and how to create custom ones;

• there’s a corresponding new section on creating custom indexes in the notebook on inflation indexes and curves;

• the notebook on numerical Theta has a new note making a connection between the calculated Theta and fixed-income calculations such as roll-down and pull-to-par.

And since we’re talking about new goodies, QuantLib 1.41 was released a couple of days ago with quite a few contributions, so check it out in case you missed it. Enjoy!

Subscribe now

Inflation bonds

import QuantLib as ql
import pandas as pd

today = ql.Date(19, ql.September, 2021)
ql.Settings.instance().evaluationDate = today

For the purposes of this notebook, I’ll create an inflation curve by interpolating a few zero rates, which could also happen in actual practice if rates are provided by an external system. Alternatively, it can be bootstrapped as already shown.

As usual, since inflation indexes are published with a lag, the curve starts in the past; in this case, we’ll assume we already have August’s fixing, but the base date would go as far back as July otherwise.

base_date = ql.Date(1, ql.August, 2021)
dates = [
    base_date,
    base_date + ql.Period(5, ql.Years),
    base_date + ql.Period(10, ql.Years),
]
rates = [0.02, 0.023, 0.025]

inflation_curve = ql.ZeroInflationTermStructureHandle(
    ql.ZeroInflationCurve(
        today,
        dates,
        rates,
        ql.Monthly,
        ql.Actual360(),
    )
)

I’ll also create an inflation index; its historical fixings will be stored, while the curve above will be used to forecast future fixings.

index = ql.EUHICP(inflation_curve)

index.addFixing(ql.Date(1, 1, 2019), 102.2)
index.addFixing(ql.Date(1, 2, 2019), 102.3)
index.addFixing(ql.Date(1, 3, 2019), 102.5)
index.addFixing(ql.Date(1, 4, 2019), 102.6)
index.addFixing(ql.Date(1, 5, 2019), 102.7)
index.addFixing(ql.Date(1, 6, 2019), 102.7)
index.addFixing(ql.Date(1, 7, 2019), 102.7)
index.addFixing(ql.Date(1, 8, 2019), 103.2)
index.addFixing(ql.Date(1, 9, 2019), 102.5)
index.addFixing(ql.Date(1, 10, 2019), 102.4)
index.addFixing(ql.Date(1, 11, 2019), 102.3)
index.addFixing(ql.Date(1, 12, 2019), 102.5)
index.addFixing(ql.Date(1, 1, 2020), 102.7)
index.addFixing(ql.Date(1, 2, 2020), 102.5)
index.addFixing(ql.Date(1, 3, 2020), 102.6)
index.addFixing(ql.Date(1, 4, 2020), 102.5)
index.addFixing(ql.Date(1, 5, 2020), 102.3)
index.addFixing(ql.Date(1, 6, 2020), 102.4)
index.addFixing(ql.Date(1, 7, 2020), 102.3)
index.addFixing(ql.Date(1, 8, 2020), 102.5)
index.addFixing(ql.Date(1, 9, 2020), 101.9)
index.addFixing(ql.Date(1, 10, 2020), 102)
index.addFixing(ql.Date(1, 11, 2020), 102)
index.addFixing(ql.Date(1, 12, 2020), 102.3)
index.addFixing(ql.Date(1, 1, 2021), 102.9)
index.addFixing(ql.Date(1, 2, 2021), 103)
index.addFixing(ql.Date(1, 3, 2021), 103.3)
index.addFixing(ql.Date(1, 4, 2021), 103.7)
index.addFixing(ql.Date(1, 5, 2021), 103.6)
index.addFixing(ql.Date(1, 6, 2021), 103.8)
index.addFixing(ql.Date(1, 7, 2021), 104.2)
index.addFixing(ql.Date(1, 8, 2021), 104.7)

Simple inflation bonds

Currently, the library only provides the CPIBond class. It models bonds paying inflation-based coupons and redemption. The i-th coupon pays an amount given by (apologies, Substack won’t let me inline a formula in a paragraph)

where N is the notional, ∆T is the accrual period of the coupon, r is a given fixed rate, I(0) (again, apologies) is a base CPI value, the same for all coupons, and I(i) is the value of the index at the end of the coupon minus an observation lag. The redemption is

where I(N) is the value of the index at the maturity of the bond minus the observation lag.

The parameter of the constructor are those of most bonds (a schedule, a day-count convention, the notional, the settlement days) plus the base CPI value, the fixed rate, the observation lag, and the interpolation type (flat of linear.)

schedule = ql.Schedule(
    ql.Date(8, ql.May, 2020),
    ql.Date(8, ql.May, 2026),
    ql.Period(6, ql.Months),
    ql.TARGET(),
    ql.Following,
    ql.Following,
    ql.DateGeneration.Backward,
    False,
)

settlement_days = 3
face_amount = 100.0
growth_only = False
base_cpi = 102.0
observation_lag = ql.Period(3, ql.Months)
fixed_rate = 0.02

bond = ql.CPIBond(
    settlement_days,
    face_amount,
    growth_only,
    base_cpi,
    observation_lag,
    index,
    ql.CPI.Flat,
    schedule,
    [fixed_rate],
    ql.Thirty360(ql.Thirty360.BondBasis),
)

(Never mind the growth_only parameter; it’s already deprecated in the underlying C++ library, so you can omit it if you’re using it from that language, and will be removed in one of the next releases of the Python module. You can always set it to False).

As usual, we can use a helper function (as_cpi_coupon) to downcast the bond coupons and get additional information:

coupon_data = []

for cf in bond.cashflows():
    c = ql.as_cpi_coupon(cf)
    if c is not None:
        coupon_data.append(
            (
                c.date(),
                c.rate(),
                c.indexFixing(),
                c.amount()
            )
        )
    else:
        coupon_data.append(
            (
                cf.date(),
                None,
                None,
                cf.amount()
            )
        )

df = pd.DataFrame(
    coupon_data,
    columns=(
        ”date”,
        “rate”,
        “index fixing”,
        “amount”
    )
)
df.style.format(
    {
        ”rate”: “{:.4%}”,
        “index fixing”: “{:.2f}”,
        “amount”: “{:.4f}”
    }
)

And as usual, we can set a discounting engine to the bond and ask for its price:

discount_curve = ql.YieldTermStructureHandle(
    ql.FlatForward(today, 0.01, ql.Actual365Fixed())
)
bond.setPricingEngine(
    ql.DiscountingBondEngine(discount_curve)
)

print(bond.cleanPrice())
print(bond.dirtyPrice())
print(bond.accruedAmount())

118.368287509748
119.11456201955193
0.7462745098039215

Pricing conventions

Note that the price of the bond is returned as the discounted sum of the cash flows as defined above. In some markets, though, the convention is to quote as bond price the value above divided by the increase I(S)/I(0) of the inflation from the start of the bond to its current settlement date. The CPIBond class still doesn’t provide this feature; if that’s the required convention, we’ll have to adjust for the inflation factor manually, as in:

current_cpi = ql.CPI.laggedFixing(
    index,
    bond.settlementDate(),
    observation_lag,
    ql.CPI.Flat
)
inflation_factor = current_cpi / base_cpi

print(bond.cleanPrice() / inflation_factor)

116.3156582465732

More exotic bonds

Bonds other than simple CPI bonds (as defined above) can be built using the basic facilities provided by the library; but as we’ll see, this has drawbacks.

As an example, let’s take an Italian inflation bond I happened to come across a while ago. At each coupon maturity, it pays

that is, a fixed rate multiplied by the increase of the inflation over the life of the coupon (with an observation lag, as usual), and it also pays a principal payment

However, if the inflation decreases over the life of the coupon, the payoff changes: there is no principal payment, and the coupon is simply a fixed-rate coupon paying r. In this case, the base value I(i-1) will be used for the next coupon instead.

There is no such bond in the library, but we can try building its cash flows. Here are the basic bond parameters:

schedule = ql.Schedule(
    ql.Date(11, 4, 2019),
    ql.Date(11, 4, 2026),
    ql.Period(6, ql.Months),
    ql.TARGET(),
    ql.Unadjusted,
    ql.Unadjusted,
    ql.DateGeneration.Backward,
    False,
)

settlement_days = 2
face_amount = 100000
observation_lag = ql.Period(3, ql.Months)
fixed_rate = 0.004
day_counter = ql.Thirty360(ql.Thirty360.BondBasis)

First, the coupons. The base CPI value for the first coupon is the interpolated fixing of the index at its start; for the ones after that, it’s the fixing at the end of the previous coupon. However, if the fixing at the end is lower than the fixing at the start, we replace the coupon with a fixed-rate one and keep the base CPI value so it can be used for the next coupon.

coupons = []
base_cpi = ql.EUHICP(inflation_curve).fixing(
    schedule[0] - observation_lag
)
interpolation = ql.CPI.Linear
cpi_pricer = ql.CPICouponPricer()

for i in range(1, len(schedule)):
    start_date = schedule[i - 1]
    end_date = schedule[i]
    payment_date = ql.TARGET().adjust(end_date)

    c = ql.CPICoupon(
        base_cpi,
        payment_date,
        face_amount,
        start_date,
        end_date,
        index,
        observation_lag,
        interpolation,
        day_counter,
        fixed_rate,
    )
    c.setPricer(cpi_pricer)

    if c.baseCPI() <= c.indexFixing():
        # normal case
        coupons.append(c)
        base_cpi = c.indexFixing()
    else:
        # use a fixed-rate coupon with the
        # same dates; also don’t update base CPI
        cf = ql.FixedRateCoupon(
            c.date(),
            face_amount,
            fixed_rate,
            day_counter,
            c.accrualStartDate(),
            c.accrualEndDate(),
            c.referencePeriodStart(),
            c.referencePeriodEnd(),
        )
        coupons.append(cf)

Next, the principal payments. We can model them using the ZeroInflationCashFlow class;. Again, we have to keep track of whether the inflation increases or decreases over the period and adjust the cash flows accordingly.

redemptions = []

growth_only = True
skipped_months = 0

for i in range(len(coupons) - 1):
    start_date = schedule[i - skipped_months]
    end_date = schedule[i + 1]
    payment_date = coupons[i].date()

    cf = ql.ZeroInflationCashFlow(
        face_amount,
        index,
        interpolation,
        start_date,
        end_date,
        observation_lag,
        payment_date,
        growth_only,
    )

    if cf.amount() > 0:
        redemptions.append(cf)
        skipped_months = 0
    else:
        redemptions.append(
            ql.SimpleCashFlow(0.0, payment_date)
        )
        skipped_months = skipped_months + 1

The final principal payment includes the redemption:

growth_only = False
payment_date = coupons[-1].date()

cf = ql.ZeroInflationCashFlow(
    face_amount,
    index,
    interpolation,
    schedule[-2 - skipped_months],
    schedule[-1],
    observation_lag,
    payment_date,
    growth_only,
)

if cf.amount() > face_amount:
    redemptions.append(cf)
else:
    redemptions.append(
        ql.SimpleCashFlow(face_amount, payment_date)
    )

We can now build the bond by passing the cash flows we created:

cashflows = sorted(
    coupons + redemptions, key=lambda c: c.date()
)

issue_date = ql.Date(11, 4, 2019)
maturity_date = cashflows[-1].date()

bond = ql.Bond(
    settlement_days,
    ql.TARGET(),
    face_amount,
    maturity_date,
    issue_date,
    cashflows,
)

The following shows the cashflows of the bond. You can see a few cases (that is, in April and October 2020) where the inflation decreased with respect to the base CPI, and therefore the principal payments reverted to 0 and the interest payment reverted to a fixed-rate coupon.

coupon_data = []
for cf in bond.cashflows():
    c = ql.as_cpi_coupon(cf)
    if c is not None:
        coupon_data.append(
            (
                c.date(),
                c.rate(),
                c.baseCPI(),
                c.indexFixing(),
                c.amount(),
                “interest”,
            )
        )
    else:
        c = ql.as_fixed_rate_coupon(cf)
        if c is not None:
            index_fixing = ql.CPI.laggedFixing(
                index,
                c.date(),
                observation_lag,
                interpolation
            )
            coupon_data.append(
                (
                    c.date(),
                    c.rate(),
                    None,
                    None,
                    c.amount(),
                    “interest”
                )
            )
        else:
            coupon_data.append(
                (
                    cf.date(),
                    None,
                    None,
                    None,
                    cf.amount(),
                    “principal”
                )
            )

df = pd.DataFrame(
    coupon_data,
    columns=(
        ”date”,
        “rate”,
        “base CPI”,
        “fixing”,
        “amount”,
        “type”
    ),
)
df.style.format(
    {
        “rate”: “{:.4%}”,
        “base CPI”: “{:.2f}”,
        “fixing”: “{:.2f}”,
        “amount”: “{:.2f}”,
    }
)

An important drawback

Unfortunately, building a bond this way goes against the grain of the library. By creating coupons this way, we’re freezing their base CPI values — even for future coupons, whose base CPI are just a forecast that depend on the inflation curve — and we’re pre-determining whether a given principal payment will or won’t happen. Thus, the bond we’re building won’t work with the usual bump-and-reprice methods we’re used to; these half-predetermined coupons won’t react properly to the change in the inflation curve. If the latter changes, we’ll need to rebuild the coupons and the bond from scratch instead.

To work properly, these kind of coupon should be implemented in the library; they should determine their base CPI from the curve, and should somehow be linked to the previous coupon so they can know whether they should reuse its base CPI.

See you next time!

Subscribe now

Bonds and CDS curves

import QuantLib as ql

today = ql.Date(27, ql.April, 2025)
ql.Settings.instance().evaluationDate = today

What if you don’t have a sensible discount curve available for a corporate issue, but you have a CDS curve instead?

That’s not optimal, of course. There can be a significant basis between the CDS and bond markets (for instance, because of their different liquidity); make sure that you’re aware of any such issues before doing your calculations.

This said, let’s take a sample fixed-rate bond:

schedule = ql.Schedule(
    ql.Date(8, ql.February, 2024),
    ql.Date(8, ql.February, 2034),
    ql.Period(6, ql.Months),
    ql.UnitedStates(ql.UnitedStates.GovernmentBond),
    ql.Following,
    ql.Following,
    ql.DateGeneration.Backward,
    False,
)

settlement_days = 3
face_amount = 10_000
coupons = [0.03]
payment_day_counter = ql.Thirty360(
    ql.Thirty360.BondBasis
)

bond = ql.FixedRateBond(
    settlement_days,
    face_amount,
    schedule,
    coupons,
    payment_day_counter
)

A risky bond engine

The RiskyBondEngine class makes it possible to calculate a price by discounting its coupons at the risk-free rate, but also weighing them by the probability that they are actually paid; that is, the probability that the issuer doesn’t default. We’ll need a risk-free curve…

dates, rates = zip(
    *[
        (ql.Date(27, 4, 2025), 0.02022),
        (ql.Date(27, 7, 2025), 0.02064),
        (ql.Date(27, 10, 2025), 0.02041),
        (ql.Date(27, 4, 2026), 0.02163),
        (ql.Date(27, 4, 2027), 0.02463),
        (ql.Date(27, 4, 2028), 0.02718),
        (ql.Date(27, 4, 2029), 0.02905),
        (ql.Date(27, 4, 2030), 0.03067),
        (ql.Date(27, 4, 2031), 0.03161),
        (ql.Date(27, 4, 2032), 0.03232),
        (ql.Date(27, 4, 2033), 0.03305),
        (ql.Date(27, 4, 2034), 0.03358),
        (ql.Date(27, 4, 2035), 0.03402),
        (ql.Date(27, 4, 2040), 0.03565),
        (ql.Date(27, 4, 2045), 0.03619),
        (ql.Date(27, 4, 2050), 0.03619),
        (ql.Date(27, 4, 2055), 0.03620),
    ]
)

risk_free_curve = ql.ZeroCurve(
    dates, rates, ql.Actual365Fixed()
)

…and a default probability curve, that can be bootstrapped from CDS quotes.

cds_data = [
    (ql.Period(1, ql.Years), 0.004),
    (ql.Period(2, ql.Years), 0.008),
    (ql.Period(3, ql.Years), 0.013),
    (ql.Period(5, ql.Years), 0.021),
    (ql.Period(7, ql.Years), 0.027),
    (ql.Period(10, ql.Years), 0.034),
]

fixed_rate = 0.01
recovery_rate = 0.4
cds_settlement_days = 1
upfront_settlement_days = 3
calendar = ql.UnitedStates(
    ql.UnitedStates.GovernmentBond
)

helpers = [
    ql.UpfrontCdsHelper(
        quote,
        fixed_rate,
        tenor,
        cds_settlement_days,
        calendar,
        ql.Quarterly,
        ql.ModifiedFollowing,
        ql.DateGeneration.CDS2015,
        ql.Actual360(),
        recovery_rate,
        ql.YieldTermStructureHandle(risk_free_curve),
        upfront_settlement_days,
    )
    for tenor, quote in cds_data
]

probability_curve = ql.PiecewiseFlatHazardRate(
    today, helpers, ql.Actual360()
)

Once we have those, we can instantiate the engine, set it to the bond, and retrieve the results we want:

bond.setPricingEngine(
    ql.RiskyBondEngine(
        ql.DefaultProbabilityTermStructureHandle(
            probability_curve
        ),
        recovery_rate,
        ql.YieldTermStructureHandle(risk_free_curve),
    )
)

bond.cleanPrice()

87.59096931191402

Back to rates

If we want to translate this into a corresponding credit spread to be applied on top of the risk-free curve, we can create a discount curve with a spread yet to be determined:

credit_spread = ql.SimpleQuote(0.0)

discount_curve = ql.ZeroSpreadedTermStructure(
    ql.YieldTermStructureHandle(risk_free_curve),
    ql.QuoteHandle(credit_spread),
)

Then, we can use the CDS-based price as a target…

target_price = bond.cleanPrice()

…and set a new engine to the bond. Next we define a function that, given a value for the spread, calculates the corresponding bond price and returns its difference from the target price; we can then pass it to a solver that finds its zero, i.e., the spread for which the bond price is the same as the CDS-based price.

bond.setPricingEngine(
    ql.DiscountingBondEngine(
        ql.YieldTermStructureHandle(discount_curve)
    )
)

def objective_function(s):
    credit_spread.setValue(s)
    return bond.cleanPrice() - target_price

solver = ql.Brent()
spread = solver.solve(
    objective_function, 1e-7, 0.005, 0.0001
)
spread

0.013749869755662938

We can check that the price is indeed the same, within numerical tolerance:

credit_spread.setValue(spread)
bond.cleanPrice()

87.59096931265552

We can also express the spread as a difference between bond yields; namely, the yield that we can calculate based on the target price…

y0 = bond.bondYield(
    ql.BondPrice(target_price, ql.BondPrice.Clean),
    payment_day_counter,
    ql.Compounded,
    ql.Semiannual,
)
y0

0.047452630996704104

…and the one we can obtain from a risk-free bond price, that we can obtain by using the risk-free curve for discounting:

bond.setPricingEngine(
    ql.DiscountingBondEngine(
        ql.YieldTermStructureHandle(risk_free_curve)
    )
)
risk_free_price = bond.cleanPrice()
risk_free_price

97.4066704451667

y1 = bond.bondYield(
    ql.BondPrice(
        risk_free_price, ql.BondPrice.Clean
    ),
    payment_day_counter,
    ql.Compounded,
    ql.Semiannual,
)
y1

0.03343150448799134

The difference between the two yields is comparable to the z-spread we calculated earlier; given the different conventions (the z-spread is continuously compounded) we didn’t expect them to be the same.

y0 - y1

0.014021126508712761

See you next time!

Subscribe now

On the whole, yes; it is still a valid look inside the architecture of the library and the train of thought that went into it. The main way that the book shows its age is that it still refers to C++11 in multiple places as a language standard we wanted to adopt in the future; we made the switch in 2021 and we’re now well beyond that, using C++17 as the minimum required language version.

This said, there were some changes in the library, hopefully for the better. Given the five-years anniversary, I thought it would be a good idea for me to re-read the book and look at some of them to see how they affect its content.

Of course, these notes also apply to the digital version of Implementing QuantLib available on Leanpub. But I should warn you: you can’t leave the digital edition nonchalantly on your coffee table to show your guests that you’re a discerning quant.

Chapter 1: introduction

This is still a valid introduction to the book, and it is also proof that I’ve been using em-dashes for years—well before people started to associate them with AI-generated content. So don’t worry if you see me sprinkle some of them here. This content is still 100% organic.

Chapter 2: financial instruments and pricing engines

No relevant changes here: notifications and lazy calculations, with their pros and cons, continue to be the main design feature of the library, and I don’t have reasons to think that this will change in the future, even if I would have liked a better separation between the core math formulas and the rest of the framework. As they say in Italy, chi nasce tondo non può morire quadrato.

Chapter 3: term structures

There are no architectural changes in the classes described here, but we were able to take advantage of later C++ versions and simplify some of the code. For instance, I describe here a BootstrapError class which is instantiated and passed to the solver during bootstrapping: you can still see it in our GitHub repository. The whole class is now replaced by a much simpler lambda:

auto error = [&](Rate guess) {
    Traits::updateGuess(ts_->data_, guess, i);
    ts_->interpolation_.update();
    return helper->quoteError();
};

On the other hand, in recent years there were a number of notable changes in classes that I only described in passing: inflation term structures. The book mentions that they contain a nominal term structure; this is no longer the case. Other changes (such as moving the interpolation into coupons where it belongs, or replacing a base lag with an explicit base date) touch features not covered in the book. You can see the updated inflation term structures used in A QuantLib Guide.

Chapter 4: cash flows and coupons

A notable change here is that the CashFlow class now inherits from LazyObject. Therefore, most of the calculations that were previously performed directly in methods like amount were moved into performCalculations instead, with amount usually implemented as, for instance,

Real FixedRateCoupon::amount() const {
    calculate();
    return amount_;
}

User-defined classes don’t need to be changed to adapt to this; the old implementation will still work, but it won’t take advantage of lazy calculations.

Because of this change, the cash-flow implementations shown in the book no longer reflect those in the library; however, the hierarchy of the classes and the reasoning behind it remained the same.

Another change I might mention is the attempt to move towards fewer overloaded constructors for bonds. For instance, the book shows an example of fixed-rate bond where the constructor takes all the parameters needed to build the cash-flow schedule and builds the latter internally; the library also provided an overloaded constructor taking a pre-built schedule, not shown in the example. Other constructors where also provided for convenience. The library now provides just one constructor, namely, the one taking a schedule, mostly so that it’s possible to enable keyword arguments in Python (which would be prevented if the constructor were overloaded).

The upgrade to C++17 allowed us to use fewer overloaded constructors in other classes, as well; for instance, the constructors of some bootstrap helpers that used to take either a simple Rate or a Handle<Quote> can now declare a single constructor taking a std::variant<Rate, Handle<Quote>> and sort it out internally.

Finally, a smaller change: some methods like Bond::yield that used to take a price as a simple number now take it as a small Bond::Price structure containing both the price and an enum specifying the type (clean or dirty).

Chapter 5: parameterized models and calibration

No major changes here; instead, we managed to fix a number of smaller things I complained about in the book. The base class BlackCalibrationHelper no longer stores a yield term structure; its inner class ImpliedVolatilityHelper was replaced by a lambda; the HestonModelHelper class moved all its calculations in the performCalculations method instead of spreading them around the class; and using a later C++ standard allowed the inner class CalibrationFunction to avoid being declared as a friend of CalibratedModel.

Chapter 6: the Monte Carlo framework

The most relevant change here is that the Disposable class template disappeared, since its purpose was to implement move semantics and we have direct support for it in the language now. This makes the interface (and sometimes the implementation) of the various stochastic processes a lot more readable.

One change we might make in the future is to replace the default random-number generator: the library now also provides the xoshiro256** generator, which provides higher speed than the Mersenne Twister without loss of quality.

Chapter 7: the tree framework

No change here, almost literally: in the past five years, the only commits in this part of the code were automated changes by clang-tidy (like replacing type declarations with auto or replacing pass-by-reference and copy with pass-by-value and move).

Chapter 8: the finite-difference framework

Here the new framework is replacing the old one, as I hoped. The classes in the old framework are slowly being deprecated and removed; we’re probably more than halfway across the process, and the last traces of the old framework might disappear in two or three years (apart from a couple of class templates like BoundaryCondition and StepCondition that are also used in the new one). At that point, that part of the book might still be useful as a comparison between design choice; but it would no longer describe actual library code.

There were no relevant changes in the new framework.

Chapter 9: conclusion

Like the intro, it is still valid—except for the part where I describe writing a book as a daunting task. After Implementing QuantLib, QuantLib Python Cookbook and A QuantLib Guide, it seems clear that I’ll write one at the slightest provocation.

Appendices

No relevant changes here, apart from the disappearance of Disposable that I have already mentioned. You can find more about the Observer pattern in A QuantLib Guide, but it adds to the description in Implementing QuantLib rather than replacing it.

The verdict

In short, I was happy to find that Implementing QuantLib still holds its own surprisingly well. If you’re curious about the architecture of the library, it’s still the book to read.

See you next time!

Subscribe now

Default-probability curves

As usual, we’ll import the required modules and set the evaluation date. For convenience, we also define a constant that will let us write spreads more readably as 15 * bps instead of 0.0015.

import QuantLib as ql
import pandas as pd

today = ql.Date(27, ql.August, 2025)
ql.Settings.instance().evaluationDate = today

bps = 1e-4

Like for other types of curves, QuantLib provides a few classes to bootstrap default-probability term structures based on market data. Nowadays, the most common way to quote a credit default swap (CDS) is to assume a standard spread (100 bps or 500 bps, based on the market) and to quote an additional upfront payment as a fraction of the notional. The sign of the upfront is seen as paid by the protection buyer; in the data below, a negative quote means that the buyer would receive 0.2% of the notional when entering into a 1-year CDS and a positive quote means the buyer would pay 1.1% of the notional when entering a 10-years one.

cds_data = [
    (ql.Period(1, ql.Years), -0.002),
    (ql.Period(2, ql.Years), -0.005),
    (ql.Period(3, ql.Years), -0.008),
    (ql.Period(5, ql.Years), -0.004),
    (ql.Period(7, ql.Years), 0.007),
    (ql.Period(10, ql.Years), 0.011),
]

cds_spread = 100 * bps
recovery_rate = 0.4
cds_settlement_days = 1
upfront_settlement_days = 3

calendar = ql.UnitedStates(
    ql.UnitedStates.GovernmentBond
)

The bootstrap process also needs an interest-rate curve as an input, in order to discount the CDS payments; a risk-free one, since the credit risk will be expressed by the default-probability curve itself. Here, for simplicity, I’m using a constant one.

risk_free_curve = ql.YieldTermStructureHandle(
    ql.FlatForward(
        0, calendar, 0.03, ql.Actual365Fixed()
    )
)

As we’ve already seen for other kinds of bootstrapped curves, each of the market quotes is wrapped into a helper; in this case, the class to use is UpfrontCdsHelper. The helpers are then passed to the curve constructor. In C++, templates give us a choice of the interpolation method and of the underlying quantity to model; for instance, we might declare types such as PiecewiseDefaultCurve<SurvivalProbability,Linear>, PiecewiseDefaultCurve<HazardRate,BackwardFlat>, PiecewiseDefaultCurve<DefaultDensity,LogLinear> or any other combination. In Python, at the time of this writing, only PiecewiseFlatHazardRate is available.

helpers = [
    ql.UpfrontCdsHelper(
        quote,
        cds_spread,
        tenor,
        cds_settlement_days,
        calendar,
        ql.Quarterly,
        ql.ModifiedFollowing,
        ql.DateGeneration.CDS2015,
        ql.Actual360(),
        recovery_rate,
        risk_free_curve,
        upfront_settlement_days,
    )
    for tenor, quote in cds_data
]

probability_curve = ql.PiecewiseFlatHazardRate(
    0, calendar, helpers, ql.Actual365Fixed()
)

Once we have the curve, we can show its nodes. I’ll extract the corresponding probabilities of default, too.

pd.DataFrame(
    [
        (
             date,
             rate,
             probability_curve.defaultProbability(date)
        )
        for date, rate in probability_curve.nodes()
    ],
    columns=[
        "date",
        "hazard rate",
        "default probability"
    ],
).style.format(
    {
        "hazard rate": "{:.2%}",
        "default probability": "{:.2%}"
    }
)

One thing to note: the modern convention for CDS is to have standardized maturity dates, rolling twice a year; you can see that by looking at the node dates, which don’t correspond to a whole number of years after the reference date. This means that, as the evaluation date rolls forward, the nodes of the curve stay fixed…

today = ql.Date(19, ql.September, 2025)
ql.Settings.instance().evaluationDate = today

pd.DataFrame(
    [
        (
             date,
             rate,
             probability_curve.defaultProbability(date)
        )
        for date, rate in probability_curve.nodes()
    ],
    columns=[
        "date",
        "hazard rate",
        "default probability"
    ],
).style.format(
    {
        "hazard rate": "{:.2%}",
        "default probability": "{:.2%}"
    }
)

…until they suddenly jump ahead 6 months, when the CDS maturities roll.

today = ql.Date(22, ql.September, 2025)
ql.Settings.instance().evaluationDate = today

pd.DataFrame(
    [
        (
             date,
             rate,
             probability_curve.defaultProbability(date)
        )
        for date, rate in probability_curve.nodes()
    ],
    columns=[
        "date",
        "hazard rate",
        "default probability"
    ],
).style.format(
    {
        "hazard rate": "{:.2%}",
        "default probability": "{:.2%}"
    }
)

Older conventions

Years ago, when CDS were less standardized, the convention was to quote the CDS spread instead of the upfront. If you need to deal with this kind of data, you can use the SpreadCdsHelper class:

old_cds_data = [
    (ql.Period(1, ql.Years), 70 * bps),
    (ql.Period(2, ql.Years), 80 * bps),
    (ql.Period(3, ql.Years), 100 * bps),
    (ql.Period(5, ql.Years), 140 * bps),
    (ql.Period(7, ql.Years), 170 * bps),
    (ql.Period(10, ql.Years), 210 * bps),
]

helpers = [
    ql.SpreadCdsHelper(
        quote,
        tenor,
        cds_settlement_days,
        calendar,
        ql.Quarterly,
        ql.ModifiedFollowing,
        ql.DateGeneration.CDS,
        ql.Actual360(),
        recovery_rate,
        risk_free_curve,
    )
    for tenor, quote in old_cds_data
]

old_probability_curve = ql.PiecewiseFlatHazardRate(
    0, calendar, helpers, ql.Actual360()
)

pd.DataFrame(
    [
        (
             date,
             rate,
             old_probability_curve.defaultProbability(date)
        )
        for date, rate in old_probability_curve.nodes()
    ],
    columns=[
        "date",
        "hazard rate",
        "default probability"
    ],
).style.format(
    {
        "hazard rate": "{:.2%}",
        "default probability": "{:.2%}"
    }
)

Checking the correctness of the curve

In order to verify that the bootstrap process results in a consistent curve, we can choose one of the quotes (the 3-years one, for example), create the corresponding CDS, and check that it is fair; i.e., that its NPV is close to 0 within numerical accuracy.

test_tenor, test_upfront = cds_data[2]
test_tenor, test_upfront

(Period("3Y"), -0.008)

There are a few conventions to consider if we want to get the correct result. Usually, and in the parameters we passed to the helpers, the CDS settle at T+1 and the upfront is paid at T+3. As I mentioned, the maturity date is standardized and can be retrieved using the cdsMaturity function.

trade_date = today
start_date = calendar.advance(
    trade_date, cds_settlement_days, ql.Days
)
upfront_date = calendar.advance(
    trade_date, upfront_settlement_days, ql.Days
)

maturity_date = ql.cdsMaturity(
    start_date, test_tenor, ql.DateGeneration.CDS2015
)
print(maturity_date)

December 20th, 2028

To get the correct schedule, we need to use this maturity date and to specify the CDS2015 convention for date generation:

schedule = ql.MakeSchedule(
    effectiveDate=today,
    terminationDate=maturity_date,
    frequency=ql.Quarterly,
    calendar=calendar,
    rule=ql.DateGeneration.CDS2015,
)

And finally, we can create the CDS itself—which, as of now, is a bit awkward to do. If we don’t pass the trade date explicitly, it seems to calculate it in a way that doesn’t match the one in the helper: something that we’ll need to investigate. And unfortunately, the trade date comes after a whole bunch of other parameters; C++ doesn’t provide a syntax to skip them, and even in Python the wrappers for the constructor don’t support keyword arguments (another thing that we’ll need to look into). This leads to the call below, which in my opinion has way too many parameters:

cds = ql.CreditDefaultSwap(
    ql.Protection.Buyer,
    10_000,
    test_upfront,
    100 * bps,
    schedule,
    ql.ModifiedFollowing,
    ql.Actual360(),
    True,
    True,
    start_date,
    upfront_date,
    ql.FaceValueClaim(),
    ql.Actual360(),
    True,
    trade_date,
)

As usual, in order to price the CDS, we need to provide an engine. For consistency with the default calculation in the helpers, we’ll build and set an engine based on the mid-point approximation, in which the default event (if any) is assumed to happen only at exactly half of the coupon life. The engine needs the default-probability curve we just bootstrapped, plus a risk-free curve for discounting and the recovery rate.

probability_handle = ql.RelinkableDefaultProbabilityTermStructureHandle(
    probability_curve
)

engine = ql.MidPointCdsEngine(
    probability_handle,
    recovery_rate,
    risk_free_curve,
)

cds.setPricingEngine(engine)

As expected, the quoted CDS is fair (within numerical accuracy):

cds.NPV()

3.699818229563334e-13

As a further check, we can also ask for the fair upfront, which returns the quoted value:

cds.fairUpfront()

-0.007999999999999964

Different models

As I mentioned, the helpers use the mid-point calculation unless told otherwise. However, it is also possible to choose the ISDA model by passing them an additional optional parameter:

helpers = [
    ql.UpfrontCdsHelper(
        quote,
        cds_spread,
        tenor,
        cds_settlement_days,
        calendar,
        ql.Quarterly,
        ql.ModifiedFollowing,
        ql.DateGeneration.CDS2015,
        ql.Actual360(),
        recovery_rate,
        risk_free_curve,
        upfront_settlement_days,
        model=ql.CreditDefaultSwap.ISDA,
    )
    for tenor, quote in cds_data
]

probability_curve = ql.PiecewiseFlatHazardRate(
    0, calendar, helpers, ql.Actual365Fixed()
)

pd.DataFrame(
    [
        (
             date,
             rate,
             probability_curve.defaultProbability(date)
        )
        for date, rate in probability_curve.nodes()
    ],
    columns=[
        "date",
        "hazard rate",
        "default probability"
    ],
).style.format(
    {
        "hazard rate": "{:.2%}",
        "default probability": "{:.2%}"
    }
)

The curve is now slightly different, and if we use it to price our sample CDS (which still uses the mid-point engine) its value is no longer zero:

probability_handle.linkTo(probability_curve)

cds.NPV()

-0.20866157093615761

However, using the IsdaCdsEngine provides a consistent calculation and, again, causes the CDS to be fair:

engine = ql.IsdaCdsEngine(
    probability_handle,
    recovery_rate,
    risk_free_curve,
)

cds.setPricingEngine(engine)

cds.NPV()

-2.8371749394295875e-13

cds.fairUpfront()

-0.00800000000000003

Curve interface

Usually, you’ll pass the curve to an engine and let it sort it out. However, if you want to inspect the curve or use it to write some different calculation, the curve provides a few different methods you can use. As we’ve already seen, it can return the default probability P up to a given date:

probability_curve.defaultProbability(
    ql.Date(12, ql.May, 2027)
)

0.021722225513824633

The survival probability is simply 1-P, but there’s also a convenience method to obtain it directly:

probability_curve.survivalProbability(
    ql.Date(12, ql.May, 2027)
)

0.9782777744861754

And if you’re so inclined, you can also ask for the default density,

probability_curve.defaultDensity(
    ql.Date(12, ql.May, 2027)
)

0.011182632606748252

…and the hazard rate,

probability_curve.hazardRate(
    ql.Date(12, ql.May, 2027)
)

0.011430938020258867

Different kinds of curves

As I mentioned, bootstrapped curves are currently based only on piecewise-flat hazard rates. If you have some pre-calculated data, though, you have a few more possibilities. For instance, you can use linear interpolation between survival probabilities at some given nodes:

survival_curve = ql.SurvivalProbabilityCurve(
    [
        today,
        today + ql.Period("1Y"),
        today + ql.Period("2Y"),
        today + ql.Period("5Y"),
        today + ql.Period("10Y"),
    ],
    [1.0, 0.995, 0.985, 0.97, 0.93],
    ql.Actual365Fixed(),
)

survival_curve.nodes()

((Date(22,9,2025), 1.0),
 (Date(22,9,2026), 0.995),
 (Date(22,9,2027), 0.985),
 (Date(22,9,2030), 0.97),
 (Date(22,9,2035), 0.93))

You can also use DefaultDensityCurve to interpolate linearly between default densities. In C++, you can also choose different interpolations. All these curves present the same interface and therefore can be used in the same way:

survival_curve.defaultProbability(
    ql.Date(12, ql.May, 2027)
)

0.011356164383561684

survival_curve.hazardRate(
    ql.Date(12, ql.May, 2027)
)

0.010114866081944281

See you next time!

Subscribe now

As usual, this notebook is also included in A QuantLib Guide.

Cash-flow analysis

I’ve already shown in some other notebook that we can extract and display information on the cash flows of, e.g., a bond; but it was somewhat in passing. Let’s have a better look at that.

import QuantLib as ql
import pandas as pd

today = ql.Date(28, ql.July, 2025)
ql.Settings.instance().evaluationDate = today

A complicated family

The diagram below shows part of the hierarchy starting from the CashFlow class (which in turn inherits from Event, but let’s ignore it here). There are all kinds of different cash flows there, including some sub-hierarchies like the one with its base in the Coupon class.

Depending on their actual class, they might provide multiple different pieces of information. The only things that they all have in common, though, are those declared in the interface of the base CashFlow class: a payment date and an amount. Other methods don’t belong there, since they’re not applicable to all cash flows. A redemption doesn’t have a rate; a fixed-rate coupon doesn’t have an observation lag.

Lost in translation

This poses a problem. Let’s take a sample fixed-rate bond as an example.

schedule = ql.MakeSchedule(
    effectiveDate=ql.Date(8, ql.April, 2025),
    terminationDate=ql.Date(8, ql.April, 2030),
    frequency=ql.Semiannual,
    calendar=ql.TARGET(),
    convention=ql.Following,
    backwards=True,
)

settlement_days = 3
face_amount = 10_000
coupon_rates = [0.03]

bond = ql.FixedRateBond(
    settlementDays=3,
    faceAmount=10_000,
    schedule=schedule,
    coupons=[0.03],
    paymentDayCounter=ql.Thirty360(
        ql.Thirty360.BondBasis
    ),
)

We can extract its cash flows and use the CashFlow interface to display their dates and amounts:

cashflows = bond.cashflows()

data = []
for cf in cashflows:
    data.append((cf.date(), cf.amount()))

pd.DataFrame(
    data, columns=["date", "amount"]
).style.format(
    {"amount": "{:.2f}"}
)

We can see from the table above that the returned cash flows contain the interest-paying coupons as well as the redemption; the latter is returned a separate cash flow, even though it has the same date as the last coupon.

The problem surfaces when we try to extract additional information from, say, the first coupon. If we ask it for its rate, it’s going to complain loudly.

try:
    print(cashflows[0].rate())
except Exception as e:
    print(f"{type(e).__name__}: {e}")

AttributeError: 'CashFlow' object has no attribute 'rate'

That’s because, even though we’re working in Python here, we’re wrapping a C++ library and we’re subject to the constraints of the latter language. To return the set of its cash flows, the Bond class needs to collect them in a vector, which is homogeneous in C++: all elements must belong to a common type, and that would be the base CashFlow class. For polymorphism to work properly, the library also needs to work with pointers (smart pointers, usually). This results in the following return type:

typedef std::vector<ext::shared_ptr<CashFlow> > Leg;

We can confirm it by asking the Python interpreter to visualize the first coupon in the list; the SWIG-generated message contains its type.

cashflows[0]

<QuantLib.QuantLib.CashFlow; proxy of <Swig Object of type 'ext::shared_ptr< CashFlow > *' at 0x10d8c1050> >

How can we retrieve additional info, then? In C++, we could use a cast; something like

auto coupon =
    ext::dynamic_pointer_cast<Coupon>(
        cashflows[0]
    );

resulting in a pointer to a Coupon instance (possibly a null one, if the cast didn’t succeed because the type didn’t match). From that pointer, we can access the additional interface of the Coupon class. The same goes for any other specific class.

However, there is no such cast operation in Python, where objects retain the type they’re created with. What we had to do was add to the wrappers a set of small functions performing the cast, such as

ext::shared_ptr<Coupon>
as_coupon(ext::shared_ptr<CashFlow> cf) {
    return ext::dynamic_pointer_cast<Coupon>(cf);
}

Once exported to the Python module, they give us the possibility to downcast the cash flows and ask for more specific information:

c = ql.as_coupon(cashflows[0])
print(f"{c.rate(): .2%}")

 3.00%

Like the underlying cast operation, the function above returns a null pointer if the cast is not possible; for instance, if we try to convert the redemption (the last cash flow in the sequence) into a coupon. In Python, that translates into a None.

print(ql.as_coupon(cashflows[-1]))

None

As I mentioned, the QuantLib module provides a number of these functions for different classes:

[
    getattr(ql, x)
    for x in dir(ql)
    if x.startswith("as_")
    and (x.endswith("coupon") or
         x.endswith("cash_flow"))
]

[<function QuantLib.QuantLib.as_capped_floored_yoy_inflation_coupon(cf)>,
 <function QuantLib.QuantLib.as_coupon(cf)>,
 <function QuantLib.QuantLib.as_cpi_coupon(cf)>,
 <function QuantLib.QuantLib.as_fixed_rate_coupon(cf)>,
 <function QuantLib.QuantLib.as_floating_rate_coupon(cf)>,
 <function QuantLib.QuantLib.as_inflation_coupon(cf)>,
 <function QuantLib.QuantLib.as_multiple_resets_coupon(cf)>,
 <function QuantLib.QuantLib.as_overnight_indexed_coupon(cf)>,
 <function QuantLib.QuantLib.as_sub_periods_coupon(cf)>,
 <function QuantLib.QuantLib.as_yoy_inflation_coupon(cf)>,
 <function QuantLib.QuantLib.as_zero_inflation_cash_flow(cf)>]

Cash-flow analysis, at last

Given the functions above, we can collect a lot more information when cycling over cash flows. For instance, here we detect the coupons by trying to cast them and use their specialized interface to extract nominal, rate and accrual period; when the cast fail (that is, for the redemption) we fall back to extracting date and amount. By selecting the correct casting function, we can analyze cash flows from other kinds of bonds and collect the relevant information in each case.

data = []
for cf in cashflows:
    c = ql.as_coupon(cf)
    if c is not None:
        data.append(
            (
                c.date(),
                c.nominal(),
                c.rate(),
                c.accrualPeriod(),
                c.amount(),
            )
        )
    else:
        data.append(
            (
                cf.date(),
                None,
                None,
                None,
                cf.amount(),
            )
        )

pd.DataFrame(
    data, columns=[
        "date",
        "nominal",
        "rate",
        "accrual period",
        "amount",
    ]
).style.format(
    {
        "nominal": "{:.0f}",
        "rate": "{:.1%}",
        "accrual period": "{:.4f}",
        "amount": "{:.2f}",
    }
)

Other functions

QuantLib provides a few other functions that act on a sequence of cash flows, rather than a single one. They are grouped as static methods of the CashFlows class; for instance, they include functions to calculate the present value and basis-point sensitivity, given a discount curve.

discount_curve = ql.YieldTermStructureHandle(
    ql.FlatForward(
        0,
        ql.TARGET(),
        0.04,
        ql.Actual360(),
    )
)

ql.CashFlows.npv(cashflows, discount_curve, False)

9625.543550654686

ql.CashFlows.bps(cashflows, discount_curve, False)

4.535150508988854

The last False parameter in the two calls above specifies that, if one of the cash flows were paid on the evaluation date, it should not be included.

Of course, these functions can also be used on a single cash flow by passing them a list with a single element; below, they are used to augment the analysis we performed earlier.

def npv(c):
    return ql.CashFlows.npv(
        [c], discount_curve, False
    )


def bps(c):
    return ql.CashFlows.bps(
        [c], discount_curve, False
    )


data = []
for cf in cashflows:
    c = ql.as_coupon(cf)
    if c is not None:
        data.append(
            (
                c.date(),
                c.nominal(),
                c.rate(),
                c.amount(),
                npv(c),
                bps(c),
            )
        )
    else:
        data.append(
            (
                cf.date(),
                None,
                None,
                cf.amount(),
                npv(cf),
                None,
            )
        )

pd.DataFrame(
    data,
    columns=[
        "date",
        "nominal",
        "rate",
        "amount",
        "NPV",
        "BPS",
    ],
).style.format(
    {
        "nominal": "{:.0f}",
        "rate": "{:.1%}",
        "amount": "{:.2f}",
        "NPV": "{:.2f}",
        "BPS": "{:.2f}",
    }
)

One last note: the BPS function could have been called also on the redemption, since it has an internal mechanism to detect different kinds of coupons (based on the Acyclic Visitor pattern, if you’re curious; I explain it in Implementing QuantLib) and would have returned 0.0. Here, I chose to call it only on coupons, resulting in a nan being displayed for the redemption.

Both choices would have been correct, I guess: I’m preferring the latter because I’m seeing BPS as the question “How much does the present value of the redemption changes if we increase its rate by 1 bp?” to which my answer would be “The redemption doesn’t have a rate to increase”. It would also be ok to answer “It doesn’t change” instead.

Thanks for reading. See you next time!

Subscribe now

And if you find A QuantLib Guide useful and want to support the effort, you can do so by buying a PDF version on Leanpub, which also gives you free access to future updates.

But first, a PSA

Recent versions of the Visual C++ 2022 compiler (at least versions 17.14.2 through 17.14.7) have a known bug that, unfortunately, affects QuantLib heavily and makes it basically unusable. A fix has been implemented and will be released at some point; I still have had no feedback on whether the fix is included in the latest version, 17.14.8, which was just released as I write this.

Hopefully, this will be sorted out before I release QuantLib 1.39—but in the meantime, if you’re compiling QuantLib on Windows, either use the Visual C++ 2019 toolset (you can do that from VC++ 2022, as well) or downgrade your compiler to an earlier version.

And now, the actual changes

• there are a couple of new sections in the notebook on inflation indexes and curves; namely, a section on adding seasonality to inflation curves and another section on perturbing the curves to calculate inflation DV01;

• the notebooks on cash flows and bonds, fitted bond curves and vanilla bonds were updated to avoid deprecated method calls that will be removed in the upcoming QuantLib 1.39; more precisely, the calls to the bondYield method no longer take a price as a simple number but as a BondPrice structure containing the price and its type (clean or dirty);

• finally, this is not actually a change in the guide; but while we’re on the subject of version 1.39 and deprecated methods, you can also look at this pull request to see what other methods and classes were removed in C++ and this other one to see the corresponding deletions in the SWIG interfaces (and therefore in Python, Java and C#).

See you next time!

Subscribe now

As usual, this notebook is also published in A QuantLib Guide.

Different approaches to numerical Theta

The idea of calculating the Theta numerically seems a simple one; change the time to maturity (which, in the case of QuantLib, means moving the evaluation date) while keeping everything else the same, and reprice the instrument. However, there are different ways of “keeping everything else the same”, and they lead to slightly different results. Let’s look at them.

import QuantLib as ql
import pandas as pd

today = ql.Date(29, ql.October, 2021)
ql.Settings.instance().evaluationDate = today

Setting a baseline

For the purposes of this notebook, we’ll look at a floating-rate bond on Euribor. For brevity, we’ll use a single curve for forecasting Euribor fixings and for discounting, and we’ll boostrap it over a set of interest-rate swaps. The argument I’ll make would remain the same if we were to use two different curves, as we should, or if we used a more diverse set of instruments for bootstrapping (including, for instance, a few interest-rate futures). Here is the construction of the curve: note that we’re not specifying its reference date explicitly, but as a number of business days and a calendar (in this case, 0 days, meaning that the reference date of the curve should equal the global evaluation date).

swap_data = [
    ("1Y", 0.137),
    ("2Y", 0.409),
    ("3Y", 0.674),
    ("5Y", 1.004),
    ("8Y", 1.258),
    ("10Y", 1.359),
    ("12Y", 1.420),
    ("15Y", 1.509),
    ("20Y", 1.574),
    ("25Y", 1.586),
    ("30Y", 1.579),
    ("35Y", 1.559),
    ("40Y", 1.514),
    ("45Y", 1.446),
    ("50Y", 1.425),
]

swap_helpers = [
    ql.SwapRateHelper(
        quote / 100.0,
        ql.Period(tenor),
        ql.TARGET(),
        ql.Annual,
        ql.Following,
        ql.Thirty360(ql.Thirty360.BondBasis),
        ql.Euribor6M(),
    )
    for tenor, quote in swap_data
]

swap_curve = ql.PiecewiseKrugerZero(
    0,
    ql.TARGET(),
    swap_helpers,
    ql.Actual360(),
)

Here are the resulting zero rates at the curve nodes, corresponding to the maturities of the input swaps.

todays_rates = pd.DataFrame(
    swap_curve.nodes(), columns=["node", "rate"]
)
todays_rates.style.format({"rate": "{:.4%}"})

Next, we build the bond. As I mentioned, we’re passing the same handle to the index for forecasting and to the engine for discounting; this is just to avoid repeating code in the rest of the notebook. We should use two different curves instead.

curve_handle = \
    ql.RelinkableYieldTermStructureHandle(swap_curve)

index = ql.Euribor6M(curve_handle)
index.addFixing(ql.Date(7, ql.May, 2021), 0.01)

schedule = ql.MakeSchedule(
    effectiveDate=ql.Date(11, ql.May, 2021),
    terminationDate=ql.Date(11, ql.May, 2025),
    frequency=ql.Semiannual,
)

bond = ql.FloatingRateBond(
    settlementDays=3,
    faceAmount=10_000,
    schedule=schedule,
    index=index,
    paymentDayCounter=ql.Thirty360(
        ql.Thirty360.BondBasis
    ),
    paymentConvention=ql.Following,
)

bond.setPricingEngine(
    ql.DiscountingBondEngine(curve_handle)
)

The price of the bond will work as the reference against which variations (and thus the Theta) will be measured.

P0 = bond.cleanPrice()
P0

99.98927601247395

Same market quotes

One way of “keeping everything else the same” is to simply move the evaluation date to the next business day; since the current date is a Friday, we’ll jump three days to the next Monday.

next_day = ql.TARGET().advance(today, 1, ql.Days)
next_day

Date(1,11,2021)

ql.Settings.instance().evaluationDate = next_day

Now, if we ask the bond for its price, the bond will reach for the curve and this will cause the latter to re-bootstrap. The reference date will move to the new evaluation date, the maturities of the input swaps will be recalculated accordingly, and the corresponding zero rates will be recalculated so that the curve once again reprices exactly the quoted swap rates—that have not changed. The bond price will change accordingly, and we can estimate the Theta (the Theta per day, to be exact) as the difference between the new price and the reference one.

bond.cleanPrice()

99.98208800779048

theta_per_day = bond.cleanPrice() - P0
theta_per_day

-0.0071880046834706945

We can also check the nodes of the new curve and compare them with the old ones. The dates have moved as expected, and some of the zero rates have changed.

new_rates = pd.DataFrame(
    swap_curve.nodes(), columns=["node", "rate"]
)
pd.concat(
    [todays_rates, new_rates], axis=1
).style.format(
    {"rate": "{:.4%}"}
)

The changes are due to the adjustments of the nodes around weekends and holidays; for instance, you can see that the distance between the 2023 and 2024 nodes changed from 368 days to 367, or that the distance between the 2029 and 2031 nodes changed from 731 to 728. This is perfectly fine: is a consequence of having chosed to keep the market quotes constant. However, we might decide to interpret the requirements in a different way.

Same zero rates

In particular, we might choose to keep the curve the same in the sense of translating it rigidly from the old evaluation date to the new one. This means taking the nodes of the old curve, shifting all the dates by the same three days, and keeping the rates the same; finally, we’ll pass them to a curve that uses the same interpolation between rates as the bootstrapped one.

shift = next_day - today

new_curve = ql.KrugerZeroCurve(
    [d + shift for d in todays_rates["node"]],
    todays_rates["rate"],
    swap_curve.dayCounter(),
)

If we check the new nodes, we can see that the zero rates are the same and so are the distances between nodes. Note that this curve won’t reprice the input swaps exactly; but again, this is ok: it’s a consequence of the legitimate choice of interpreting “keeping everything else the same” as a rigid translation of the curve.

new_rates = pd.DataFrame(
    new_curve.nodes(), columns=["node", "rate"]
)
pd.concat(
    [todays_rates, new_rates], axis=1
).style.format(
    {"rate": "{:.4%}"}
)

If we link this new curve to the handle we’re using, we can get a new bond price and thus a new Theta:

curve_handle.linkTo(new_curve)

bond.cleanPrice()

99.98218981727182

theta_per_day = bond.cleanPrice() - P0
theta_per_day

-0.007086195202134604

Same coupon rates

There is a third possibility. Both approaches so far will cause the expected coupon rates to change, because the curve will shift while the coupon period remains the same. We can check this by going back to the old evaluation date and curve, extracting the rates by using a small helper function, and then going back to the new ones and doing the same.

ql.Settings.instance().evaluationDate = today
curve_handle.linkTo(swap_curve)

def cashflows():
    data = []
    for cf in bond.cashflows():
        c = ql.as_coupon(cf)
        if c is None:
            data.append(
                (cf.date(), None, cf.amount())
            )
        else:
            data.append(
                (c.date(), c.rate(), c.amount())
            )
    return pd.DataFrame(
        data, columns=["date", "rate", "amount"]
    )

base_cf = cashflows()
base_cf.style.format(
    {"rate": "{:.4%}", "amount": "{:.4f}"}
)

ql.Settings.instance().evaluationDate = next_day
curve_handle.linkTo(new_curve)

new_cf = cashflows()
pd.concat(
    [base_cf, new_cf[["rate", "amount"]]], axis=1
).style.format(
    {"rate": "{:.4%}", "amount": "{:.4f}"}
)

As expected, some of the coupon rates change. What if we built a curve with the new reference date but that returns the same forward rates as the old one over a given period? This would be a third interpretation of “keeping everything else the same”, and an equally sensible one.

To do that, we first create a curve which is the same as the old one but with a reference date that doesn’t move…

base_curve = new_curve = ql.KrugerZeroCurve(
    todays_rates["node"],
    todays_rates["rate"],
    swap_curve.dayCounter()
)

…and then we use the ImpliedTermStructure class, which returns a curve with a new reference date but with the same expected rates between two dates.

new_curve = ql.ImpliedTermStructure(
    ql.YieldTermStructureHandle(base_curve),
    next_day
)

We can link this new curve to our handle and check that the coupons remain unchanged:

curve_handle.linkTo(new_curve)

new_cf = cashflows()
pd.concat(
    [base_cf, new_cf[["rate", "amount"]]], axis=1
).style.format(
    {"rate": "{:.4%}", "amount": "{:.4f}"}
)

And finally, we can reprice the bond and recalculate a third version of the Theta:

bond.cleanPrice()

99.98207313531329

theta_per_day = bond.cleanPrice() - P0
theta_per_day

-0.007202877160665366

Note that, while the forward rates stay the same, the zero rates corresponding to the coupon dates—that is, the numbers going into the exp⁡(−rT) formula to give you discount factors—must change. As the saying goes in Italy, the blanket is short: you can cover your shoulders or your feet, but not both.

data = []
for cf in bond.cashflows():
    if cf.date() > bond.settlementDate():
        data.append(
            (
                cf.date(),
                base_curve.zeroRate(
                    cf.date(),
                    base_curve.dayCounter(),
                    ql.Continuous
                ).rate(),
                new_curve.zeroRate(
                    cf.date(),
                    new_curve.dayCounter(),
                    ql.Continuous
                ).rate(),
            )
        )
pd.DataFrame(
    data,
    columns=["date", "zero rate", "new zero rate"]
).style.format(
    {
        "zero rate": "{:.5%}",
        "new zero rate": "{:.5%}"
    }
)

Choices, choices

So, which one is the right Theta? Well, I’m not sure there is one; the choice will be yours, probably based on how the Theta will be used in your application or on your desks, or on whether it should be compared to figures coming from elsewhere. As usual, any choice will likely be a trade-off.

See you next time!

Subscribe now

Oh, and forgive me for mentioning from time to time that I’m available for training, both online and (when possible) on-site: visit my Training page for more information.

Cross-currency curve bootstrapping

Cross-currency curves can be bootstrapped over a set of quotes for the relevant instruments; mostly, cross-currency swaps.

import QuantLib as ql
import pandas as pd

today = ql.Date(27, ql.April, 2025)
ql.Settings.instance().evaluationDate = today

In this case, the bootstrap process also requires a few other interest-rate curves to be available. For the purposes of this notebook, we’ll use pre-built curves; the data frame below holds made-up zero rates from a few different curves at a number of nodes…

sample_rates = pd.DataFrame(
    [
        (ql.Date(27, 10, 2021), 2.0229, 1.4510, 1.5131, 2.6893),
        (ql.Date(27, 1, 2022), 2.0645, 1.4416, 1.4943, 2.6919),
        (ql.Date(27, 4, 2022), 2.0414, 1.4520, 1.4764, 2.7306),
        (ql.Date(27, 10, 2022), 2.1630, 1.4344, 1.4969, 2.8107),
        (ql.Date(27, 10, 2023), 2.4638, 1.5635, 1.6532, 3.1354),
        (ql.Date(27, 10, 2024), 2.7187, 1.6500, 1.7510, 3.3850),
        (ql.Date(27, 10, 2025), 2.9055, 1.6959, 1.8410, 3.5358),
        (ql.Date(27, 10, 2026), 3.0673, 1.7660, 1.9268, 3.6438),
        (ql.Date(27, 10, 2027), 3.1615, 1.8310, 1.9669, 3.7127),
        (ql.Date(27, 10, 2028), 3.2325, 1.8959, 2.0346, 3.7374),
        (ql.Date(27, 10, 2029), 3.3049, 1.9930, 2.1263, 3.7842),
        (ql.Date(27, 10, 2030), 3.3584, 2.0272, 2.1832, 3.7844),
        (ql.Date(27, 10, 2031), 3.4023, 2.0744, 2.2599, 3.7927),
        (ql.Date(27, 10, 2036), 3.5657, 2.3011, 2.4406, 3.8902),
        (ql.Date(27, 10, 2041), 3.6191, 2.3882, 2.5331, 3.9043),
        (ql.Date(27, 10, 2046), 3.6199, 2.3762, 2.5225, 3.8677),
        (ql.Date(27, 10, 2051), 3.6208, 2.3401, 2.4926, 3.8204),
    ],
    columns=[
        "date",
        "SOFR",
        "ESTR",
        "Euribor3M",
        "CORRA",
    ],
)

…and this helper function uses them to create corresponding interest-rate curves. Depending on the context, these curves will be used for forecasting, discounting or both.

def sample_curve(tag):
    curve = ql.ZeroCurve(
        sample_rates["date"],
        sample_rates[tag] / 100,
        ql.Actual365Fixed()
    )
    return ql.YieldTermStructureHandle(curve)

sofr_curve = sample_curve("SOFR")
estr_curve = sample_curve("ESTR")
euribor_curve = sample_curve("Euribor3M")
corra_curve = sample_curve("CORRA")

A common case

As for other curves we have already seen, the process consists of creating a set of bootstrap helpers, each modeling one of the quoted instruments, and passing them to the constructor of one of the available piecewise curves.

We’ll bootstrap over quoted swaps paying compounded SOFR and receiving 3-months Euribor. Thus, we need to create instances of the corresponding indexes and associate them with their respective forecast curves.

sofr = ql.Sofr(sofr_curve)
euribor = ql.Euribor3M(euribor_curve)

The swaps are quoted as a basis over Euribor: here is a made-up set of such quotes for different maturities.

basis_quotes = [
    (ql.Period(1, ql.Years), -14.5),
    (ql.Period(18, ql.Months), -18.5),
    (ql.Period(2, ql.Years), -20.5),
    (ql.Period(3, ql.Years), -23.75),
    (ql.Period(4, ql.Years), -25.5),
    (ql.Period(5, ql.Years), -26.5),
    (ql.Period(7, ql.Years), -26.75),
    (ql.Period(10, ql.Years), -26.25),
    (ql.Period(15, ql.Years), -24.75),
    (ql.Period(20, ql.Years), -23.25),
    (ql.Period(25, ql.Years), -20.50),
]

Building the curve requires us to specify some familiar conventions…

fixing_days = 2
calendar = ql.TARGET()
convention = ql.Following
end_of_month = True

…as well as some less common ones which are specific to cross-currency swap helpers.

To begin with, we define one of the indexes (in this example, SOFR) as the “base” index; the other conventions are specified depending on this choice. In this case, we want to bootstrap a curve for discounting EUR cash flows when the collateral is in USD. This means we already know the collateral curve used for discounting USD cash flows, namely, the SOFR curve. The other parameters we’re passing to the helpers specify that the currency of the collateral is the one that corresponds to the base index, that the quoted basis is not applied to the base index but to the other, and that the base-index leg is not the one that resets its notionals.

base_index = sofr
other_index = euribor
collateral_curve = sofr_curve
base_is_collateral = True
basis_on_base = False
base_resets = False
frequency = ql.Quarterly

helpers = [
    ql.MtMCrossCurrencyBasisSwapRateHelper(
        ql.makeQuoteHandle(basis / 10000),
        tenor,
        fixing_days,
        calendar,
        convention,
        end_of_month,
        base_index,
        other_index,
        collateral_curve,
        base_is_collateral,
        basis_on_base,
        base_resets,
        frequency,
    )
    for tenor, basis in basis_quotes
]

Now we can finally create the curve and inspect its nodes:

discount_curve = ql.PiecewiseLinearZero(
    today, helpers, ql.Actual365Fixed()
)

pd.DataFrame(
    discount_curve.nodes(), columns=["date", "rate"]
).style.format({"rate": "{:.4%}"})

What? No FX rate?

You might have noticed that the current EUR/USD rate was not among the inputs of the calculation. Shouldn’t it matter?

Well, yes, if you’re calculating the value of the swaps. But during the bootstrap, what we’re calculating and matching for each swap is the fair basis between the floating rates. If you work out the math, you’ll see that the current FX rate cancels out.

An alternate view

The same swap can be seen from the other side if we swap the role of the indexes and choose Euribor as the base index. Note that the collateral remains in USD, and therefore the collateral curve remains the same and the boolean parameters (referring now to Euribor) are inverted; the base index is not in the collateral currency, the basis is on the base index, and the base-index leg resets.

base_index = euribor
other_index = sofr
collateral_curve = sofr_curve
base_is_collateral = False
basis_on_base = True
base_resets = True
frequency = ql.Quarterly

helpers = [
    ql.MtMCrossCurrencyBasisSwapRateHelper(
        ql.makeQuoteHandle(basis / 10000),
        tenor,
        fixing_days,
        calendar,
        convention,
        end_of_month,
        base_index,
        other_index,
        collateral_curve,
        base_is_collateral,
        basis_on_base,
        base_resets,
        frequency,
    )
    for tenor, basis in basis_quotes
]

The resulting curve, as expected, is the same.

discount_curve = ql.PiecewiseLinearZero(
    today, helpers, ql.Actual365Fixed()
)

pd.DataFrame(
    discount_curve.nodes(), columns=["date", "rate"]
).style.format({"rate": "{:.4%}"})

A slightly more complex case

The previous case involved two known curves (namely, the forecast curves for SOFR and 3-months Euribor) as well as the curve being bootstrapped. The SOFR curve was also used for discounting USD cash flows.

Let’s now say that we want to bootstrap over EUR/CAD cross-currency swaps paying 3-months Euribor vs CORRA, with the collateral being in EUR. Besides the curve being bootstrapped, this is going to require three different known curves: the forecast curves for Euribor and CORRA, and the ESTR curve used for discounting EUR cash flows.

euribor = ql.Euribor3M(euribor_curve)
corra = ql.Corra(corra_curve)

We’ll choose Euribor as the base index and set the other parameters accordingly; as I mentioned, the collateral curve will be the ESTR curve. For brevity I’ll use the same set of basis quotes as before, and I’ll assume they’re added on Tibor.

base_index = euribor
other_index = corra
collateral_curve = estr_curve
base_is_collateral = True
basis_on_base = False
base_resets = False
frequency = ql.Quarterly

helpers = [
    ql.MtMCrossCurrencyBasisSwapRateHelper(
        ql.makeQuoteHandle(basis / 10000),
        tenor,
        fixing_days,
        calendar,
        convention,
        end_of_month,
        base_index,
        other_index,
        collateral_curve,
        base_is_collateral,
        basis_on_base,
        base_resets,
        frequency,
    )
    for tenor, basis in basis_quotes
]

Here is the resulting curve:

discount_curve = ql.PiecewiseLinearZero(
    today, helpers, ql.Actual365Fixed()
)

pd.DataFrame(
    discount_curve.nodes(), columns=["date", "rate"]
).style.format({"rate": "{:.4%}"})

See you next time!

Subscribe now

The global evaluation date

If you already used QuantLib, chances are that you know about the global evaluation date. By default, it is set to the current date, which is why you might have ignored it if you only performed calculations as of today; but as soon as you try to calculate figures at some past date, you’ll have to set it properly.

A simple example

import QuantLib as ql

Let’s say you have a bond which has already matured; for instance, this one.

bond = ql.ZeroCouponBond(
    settlementDays=3,
    calendar=ql.TARGET(),
    faceAmount=10_000,
    maturityDate=ql.Date(8, ql.February, 2025),
)

As I write this, it’s April 2025; but let’s say you’re checking some end-of-year figures, and want to reprice the bond as of that date:

as_of_date = ql.Date(31, ql.December, 2024)

Next, you set up a discount curve with the correct reference date and use it to price the bond by passing it to the usual engine.

discount_curve = ql.YieldTermStructureHandle(
    ql.FlatForward(as_of_date, 0.02, ql.Actual360())
)
engine = ql.DiscountingBondEngine(discount_curve)
bond.setPricingEngine(engine)

You already know where this is going: you ask for the price, and you get a null one.

bond.cleanPrice()

0.0

This is because the bond methods don’t rely on the reference date of the curve (which doesn’t always equal the evaluation date) but on the global evaluation date. If we ask the bond, it’s going to tell us that it has matured.

bond.isExpired()

True

The correct way to get its end-of-year price, of course, is to set the evaluation date:

ql.Settings.instance().evaluationDate = as_of_date

At which point the calculations work as expected.

bond.cleanPrice()

99.80574447629698

In C++, which uses :: for calling class methods and doesn’t have properties, the syntax to use is

Settings::instance().evaluationDate() = as_of_date;

Other possible points of failure

In a real-world case, you might have found that something was amiss even before asking the bond for its price. If you had tried to create the discount curve by bootstrapping it over the end-of-year quoted rates, you’d have probably failed to do so; the bootstrap algorithm would have considered the 5-years swap rate as starting from today, not from the reference date passed to the curve. Why this inconsistence inside the curve itself? Because, as I mentioned, the reference date of the curve might not equal the evaluation date (I’ve seen desks where the reference date of the swap curve would be the spot date, two business days from the evaluation date) and thus the algorithm can’t rely on it.

Term structures

Term structures can be set up so that their reference date moves with the global evaluation date; I talk about this in more detail in another notebook.

Fixings

Another case where the evaluation date plays a role is determining whether the fixing of an interest-rate index should be calculated. Let’s create an index and give it a flat 1% forecast curve:

forecast_curve = ql.YieldTermStructureHandle(
    ql.FlatForward(
        0, ql.NullCalendar(), 0.01, ql.Actual360()
    )
)

index = ql.Euribor3M(forecast_curve)

The evaluation date is still at the end of 2024. If we try to ask the index for a fixing at a past date, it’s going to gently but firmly rebuke us:

try:
    index.fixing(ql.Date(15, ql.February, 2021))
except Exception as e:
    print(f"{type(e).__name__}: {e}")

RuntimeError: Missing Euribor3M Actual/360 fixing for February 15th, 2021

That’s because the fixing is in the past with respect to the evaluation date, and therefore it can’t be forecast off the curve: it must have been stored instead (here I’ll use a bogus 2% value). Once we do this, the index returns the stored value.

index.addFixing(ql.Date(15, ql.February, 2021), 0.02)

index.fixing(ql.Date(15, ql.February, 2021))

0.02

If I move the evaluation date before that fixing date, though, the behavior of the index changes. Now the fixing date is in the future with respect to the evaluation date, and therefore the fixing is forecast from the 1% curve we set previously, even though the stored value is still there:

ql.Settings.instance().evaluationDate = ql.Date(
    1, ql.February, 2021
)

index.fixing(ql.Date(15, ql.February, 2021))

0.010012371303880592

Why a global evaluation date anyway?

Yes, sensible question. In this age of multithreading, it feels weird to have a feature that prevents us from perform two parallel calculations as of two different evaluation dates.

The historical reason is that QuantLib was started in 2000, and multi-core computers were not yet the norm at the time. This wouldn’t prevent us to redesign it, per se; but as I wrote in Implementing QuantLib, we don’t really have a workable alternative.

The obvious idea (that is, the idea that quite a few smart people had when we talked about it) was to use some kind of context object that should replace the global settings. But how would one select a context for any given calculation?

It would be appealing to add a setContext method to the Instrument class, and to arrange things so that during calculation the instrument propagates the context to its engine and in turn to any term structures that need it. However, this can’t be implemented easily.

To begin with, the instrument and its engine are not always directly aware of all the term structures that are involved in the calculation. For instance, a swap contains a number of coupons, any of which might or might not reference a forecast curve. We’re not going to reach them unless we add the relevant machinery to all the classes involved. I’m not sure that we want to set a context to a coupon.

Another problem is that there are some kinds of data sharing that just feel natural in the library. For instance, all instruments based on the Euribor index can share the same index instance and depend on a single forecast curve. Trying to price two such instruments in two different contexts in parallel wouldn’t work. Using contexts would force us to duplicate the index and curve objects, at which point it would be simpler to use a thread-local evaluation date (see below).

Also, I’m skipping over the scenario in which the context is threaded through the various method calls during calculations instead of being set. It would lead to method calls like

termStructure->discount(t, context);

which would completely break caching, would cause discomfort to all parties involved, and if we wanted stuff like this we’d write in Haskell.

Not just globals, unfortunately

Truth be told, sharing the same curve between instruments is ok in a single-threaded calculation, but would be dangerous when multi-threading, even if the evaluation date or the context were the same. A number of calculations in the library are lazy; that is, they’re performed when required but not earlier. For instance, an interest-rate curve would not be bootstrapped when created, but only when actually asked for rates or discount factors. This means that passing the same curve to two instruments and asking them for their values in parallel might trigger the bootstrap of the curve on two different threads. It wouldn’t end well.

Thread-local evaluation date

The library has a setting that can cause the evaluation date (and other globals) to be thread-local. Unfortunately, it requires recompiling, which rules out a simple pip install QuantLib for all you Pythonistas.

One still needs to be careful, though; you better not share of objects between threads, since the bootstrap example above still applies. And it’s somewhat inconvenient, as well; for instance, index fixings would also be saved in a thread-local object and would have to be reloaded in each thread.

Living in the present

What if you’re doing calculations as of today—I mean, the actual current date? Should you still set the evaluation date?

All in all, yes, I’d advise doing that. There’s no harm in it, whereas leaving the evaluation date unset has two (possibly quite minor) disadvantages.

The first: every time the calculations will ask for the evaluation date, it will be retrieved by calling some system or library facility; that’s slower than returning the stored date that you set. Granted, this might be negligible compared to the time taken by the rest of the calculation, but it’s still a waste that can be avoided with no effort.

The second, not very probable but possible: if your calculations ever run beyond midnight, the evaluation date will change and your objects won’t receive any notifications. This would leave them in an inconsistent state.

See you next time!

Subscribe now

Of course, if you want to receive this kind of updates, subscribing to this Substack is a good idea. And if you find A QuantLib Guide useful and want to support the effort, you can do so by buying a PDF version on Leanpub. Don’t worry about its being a work in progress; you’ll have free access to new versions any time the book is updated.

And now, as Leporello said, il catalogo è questo:

• there’s a new short notebook on the common interface of interest-rate term structures, showing a few ways you can use them regardless of the way they’re modeled;

• the notebook on curve bootstrapping has a new bit on checking the correctness of the bootstrap, as well as a new section on adding jumps;

• the notebook on vanilla bonds has more details on the difference between the dirtyPrice and NPV methods;

• the notebook on different kinds of swaps now also shows the MakeOIS utility, as well as the new optional parameters recently added to OIS such as lookback days and lockout days;

• and finally, the notebook on numerical Greeks now has a comparison with analytic Greeks, in a case where they’re available.

I’ll leave you to it now. Enjoy!

Subscribe now

The QuantLib ecosystem

Welcome back! In my previous articles, I tried to look at QuantLib from a number of different perspectives such as features, usability, design, or extensibility.

In this article, I’ll widen my net and list a number of satellite projects and ports in other languages which spawned from QuantLib (mostly through no effort of ours, I must say.) Let’s have a look.

Different languages, same library.

The same C++ library we know and love can also be called from other languages through bindings. We officially provide some of those: others are independent efforts.

Official bindings

If you happened to read my article from the September 2023 issue of Wilmott, or if you bought the QuantLib Python Cookbook, you already know that QuantLib can be used from Python and interact with Jupyter and the rest of the language’s impressive ecosystem. If you’re a Python user and you don’t need to modify the library, you don’t even need to compile it; it’s already available on PyPI.

What if you prefer another language? And by “prefer”, of course, I mean that the rest of your system is implemented in another language, or that the expertise of your development team leans that way. Well, SWIG (the same program we use to semi-automatically generate the Python bindings) can also be used for other languages; currently, we support two enterprise languages, C# and Java, and a more niche one, R. As for Python, a precompiled C# binary is available on NuGet; you’re welcome to try it and report any problems on the QuantLib mailing list.

If you want to use QuantLib from Java, I’m afraid you’ll have to compile it; and you’ll have to pass a compiler flag that enables a thread-safe implementation of the Observer pattern, because (as I mentioned in passing in the November 2023 issue; see how everything comes together?) the garbage collector might otherwise interfere.

Bindings for an older version of QuantLib are also available for the most used functional language of all—Microsoft Excel. Their maintainer (hi, Eric) did an excellent job making it possible to use an object-oriented library from a spreadsheet. Unfortunately, the project is currently dormant and could use some help because, well, life doesn’t always give one a chance to maintain an open-source project. For the record, I’m forever grateful to my employers for giving me some company time to do it.

Unofficial alternatives

The advantage of using SWIG to generate bindings is that the same set of input files can be used for different languages. The disadvantage is that using the same set of input files gives you little leeway to tailor the interfaces for idiomatic language use.

A few projects address this issue by providing alternative idiomatic bindings for a single language each.

First and eldest, RQuantLib provides idiomatic bindings for R and is available via CRAN. It also provides a nice example of serendipity, because RQuantLib spawned a much more relevant package for the R ecosystem: Rcpp, which can be used to integrate C++ code into R and is currently used by over 2500 packages on CRAN.

Also for R and from the same maintainer (hi, Dirk), the lighter-weight qlcal project provides just the calendaring functionality of QuantLib. You might remember that I already mentioned it in the January 2024 issue. Do you see a pattern here? Pick up your back issues of Wilmott or hit the Tutorials page on my site.

In the Python camp, PyQL provides more idiomatic bindings by using Cython, a tool specialized for the language. This makes it easier to support niceties like keyword arguments and snake_case method names (as opposed to the camelCase names we have in the C++ library.) Like RQuantLib, PyQL provides fewer classes and methods than the official bindings are able to support. As a general rule, all the open-source projects I’m mentioning in this article will be glad to have your help if you’re so inclined.

Different languages, different library

Other projects tried to avoid the impedance mismatch between C++ and their target language by porting the library rather than wrapping it; that is, by rewriting it in the target language. A few of them are listed on the QuantLib site. By using the target language directly, they are able to integrate better with it and to use its existing patterns and facilities.

Not surprisingly, though, it’s difficult for them to keep up with the sheer quantity of code in the original QuantLib. One port that seems to have reached critical mass and to be still developed is the C# port, called QLNet; the Java port JQuantLib also has decent coverage but seems to have been dormant for a while.

Same library, different types

A long time ago, in a rare display of foresight, we hid native C++ types behind a few typedefs; for instance, we added Real as an alias to double, or Integer as an alias to int. These typedefs give us the possibility to redefine the types we’re using in the whole code with a single localized change.

Our thinking at the time was that one might have wanted to replace the default double with, say, long double for added precision, or float for higher speed. As often happens, we were wrong. But it all turned out fine in the end, because in more recent years this provided the required hook for adding Adjoint Algorithmic Differentiation (AAD) to the library.

The idea (which I’m oversimplifying here) is that by replacing the built-in double type with an instrumented class that overloads arithmetic operators, it’s possible to keep track of a given calculation and provide simultaneously the result and its derivatives with respect to all the input variables, without changing the existing code and with a cost in performance which is a lot less than the cost of getting the same derivatives by bumping the inputs and redoing the calculation.

The first implementation of the idea was provided a few years ago by CompatibL, and now seems dormant. Nowadays, there are two very active implementations by Matlogica and XAD (in strictly alphabetical order), both of which provide other goodies besides AAD.

A lot more of the same

Finally, another project builds on QuantLib and adds more complex functionality. The Open-Source Risk Engine, or ORE for short, is a number of things. It contains a recent version of QuantLib, extends it with further instruments and models, and wraps it in an application through which you can provide your input market data and portfolio specifications and perform tasks such as exposure calculation and XVA.

A note: the people behind ORE would be completely cool about taking some of their additional instruments and adding them to QuantLib, but like all of us they’re short on time to do it themselves. Again, help would be appreciated.

See you next time!

Subscribe now

Coupons with multiple resets

(Originally based on a question on the QuantLib mailing list; thanks, Jack.)

Some bonds and swaps have coupons whose reset frequency is different than the payment frequency; for instance, a coupon might pay quarterly but its rate would be the combination of three 1-month fixings occurring during its life.

There is no specific instrument in QuantLib to instantiate such a bond; but as we’ve seen in other cases, it’s possible to use the constructor of the base Bond or Swap class once we have built the coupons. We can do this by means of the MultipleResetsCoupon class and the MultipleResetsLeg utility (a class in C++ or a function in Python.)

Let’s take some initialization out of the way.

import QuantLib as ql
import pandas as pd
import numpy as np

today = ql.Date(9, ql.September, 2024)
ql.Settings.instance().evaluationDate = today

The underlying index

As an example, I’ll use a an Euribor1M index. To avoid constant fixings, I’ll use a mock curve with zero rates increasing linearly over the next 20 years.

forecast_curve = ql.ZeroCurve(
    [today, today + ql.Period(20, ql.Years)],
    [0.035, 0.06],
    ql.Actual365Fixed(),
)
forecast_handle = ql.YieldTermStructureHandle(
    forecast_curve
)

index = ql.Euribor(
    ql.Period(1, ql.Months), forecast_handle
)

And as usual, depending on the coupon schedule we might have to add some past fixings to the index.

index.addFixing(
    ql.Date(30, ql.July, 2024), 0.03611
)
index.addFixing(
    ql.Date(29, ql.August, 2024), 0.03602
)

Multiple-resets coupons

As I mentioned, we can use the MultipleResetsLeg function to build a sequence of coupons for a bond; and as usual, we need to build the corresponding schedule first. Other parameters may include a payment lag (2 days in this example), the method used to combine the underlying index fixings (compounding or averaging, defaulting to the former), and other not shown here such as ex-coupon information, a multiplier or an additional spread.

However, MultipleResetsLeg differs in one important respect from other similar functions such as FixedRateLeg or IborLeg. The schedule we need to pass is not the schedule of the coupons, but the full schedule of the underlying multiple fixings over the whole leg. In order to derive the coupon schedule, we’ll also pass the number of underlying fixings periods per coupon. In this example, I’ll specify 3 monthly fixings per coupon, resulting in quarterly payments.

reset_schedule = ql.MakeSchedule(
    effectiveDate=ql.Date(1, ql.August, 2024),
    terminationDate=ql.Date(1, ql.August, 2025),
    frequency=ql.Monthly,
    calendar=ql.TARGET(),
)

nominal = 100.0
resets_per_coupon = 3
coupons = ql.MultipleResetsLeg(
    reset_schedule,
    index,
    resets_per_coupon,
    [nominal],
    paymentLag=2,
    averagingMethod=ql.RateAveraging.Compound,
)

settlement_days = 3
calendar = ql.TARGET()
bond = ql.Bond(
    settlement_days,
    calendar,
    reset_schedule[0],
    coupons,
)

First of all, I’ll use a constant-rate discount curve to check that everything works:

discount_curve = ql.FlatForward(
    today, 0.03, ql.Actual365Fixed()
)
discount_handle = ql.YieldTermStructureHandle(
    discount_curve
)

bond.setPricingEngine(
    ql.DiscountingBondEngine(discount_handle)
)
bond.cleanPrice()

100.51555336316565

And now, let’s look under the hood.

Cash-flow analysis

As in previous notebooks, we can examine the coupons we created to retrieve various bits of information. Calling bond.cashflows() returns the coupons we created, plus the redemption inferred by the Bond constructor. Since we’re calling from the underlying C++ library, the coupons are returned as instances of the base CashFlow class and need to go through a dynamic_pointer_cast to give them their original type and access the corresponding methods. In Python, the C++ cast is exported as the as_sub_periods_coupon function; if the cast fails (as for the redemption) it returns None.

Once we have the coupon, we can ask (for instance) for its multiple fixings dates or its final rate besides its payment date and amount. For the redemption, payment date and amount are all we can get.

Pardon all the Nones I’m adding to the info and my formatting code; it’s to get a decent-looking table in the end.

def coupon_info(c):
    info = []
    for d in c.fixingDates():
        info.append(
            (d, index.fixing(d), None, None, None)
        )
    info.append(
        (None, None, c.rate(), c.date(), c.amount())
    )
    return info

def redemption_info(cf):
    return [
        (None, None, None, cf.date(), cf.amount())
    ]

data = []
for cf in bond.cashflows():
    c = ql.as_multiple_resets_coupon(cf)
    if c is not None:
        data += coupon_info(c)
    else:
        data += redemption_info(cf)

df = pd.DataFrame(
    data,
    columns=[
        "fixing date",
        "fixing",
        "coupon rate",
        "payment date",
        "amount",
    ],
)
df.style.format(
    {
        "fixing date":
          lambda d:
            "" if d is None else d.ISO(),
        "fixing":
          lambda f:
            "" if np.isnan(f) else f"{f:.2%}",
        "coupon rate":
          lambda r:
            "" if np.isnan(r) else f"{r:.2%}",
        "payment date":
          lambda d:
            d.ISO() if d is not None else "",
        "amount":
          lambda x:
            "" if np.isnan(x) else f"{x:.4}",
    }
).hide(axis="index")

And by the way, if you see that a SubPeriodsLeg function is also available (it’s deprecated, and it might be removed by the time you read this), don’t use it. It’s an older version of the above, and sometimes it calculated the wrong schedule.

What did we get?

The table above shows the coupon dates (including the payment lag), the underlying fixings, the resulting compounded coupon rates, and the coupon amounts. What you might still be asking yourselves is, didn’t we specify a reset schedule rolling on the first of the month? Why are all the fixings a few days before that?

The thing is, what I called the reset schedule doesn’t give us the sequence of the fixing dates; instead, it gives us the schedule of the periods underlying each of the fixings. To see if I can make more sense, let’s take the first coupon and ask it for its start and end dates.

first = ql.as_multiple_resets_coupon(
    bond.cashflows()[0]
)
print(first.accrualStartDate())
print(first.accrualEndDate())

August 1st, 2024
November 1st, 2024

If this were a floating-rate coupon, it would have a single fixing date. Since the Euribor index has two fixing days…

print(index.fixingDays())

2

…the fixing date would be as follows:

print(
    calendar.advance(
        first.accrualStartDate(),
        -index.fixingDays(),
        ql.Days,
    )
)

July 30th, 2024

that is, the first fixing date in the table above. Since the coupon has multiple resets, its period is divided into three sub-periods specified by the first dates of the reset schedule:

print(f"{reset_schedule[0]} to {reset_schedule[1]}")
print(f"{reset_schedule[1]} to {reset_schedule[2]}")
print(f"{reset_schedule[2]} to {reset_schedule[3]}")

August 1st, 2024 to September 2nd, 2024
September 2nd, 2024 to October 1st, 2024
October 1st, 2024 to November 1st, 2024

These roll on the first of the month, as specified, and when the fixing days are taken into account we find the dates in the table:

for i in [0,1,2]:
    print(
        calendar.advance(
            reset_schedule[i],
            -index.fixingDays(),
            ql.Days
        )
    )

July 30th, 2024
August 29th, 2024
September 27th, 2024

See you next time!

Subscribe now

Adding a new cash flow to QuantLib, part II

Welcome back. So, where were we?

A quick recap

In the article in the previous issue, I described part of the class hierarchy that has CashFlow at its root and models different types of cash flows and coupons; in particular, and more to our purpose, floating-rate coupons.

And in case I need to refresh said purpose in your memory: we want to implement a coupon whose rate must be interpolated between the fixings of two quoted indexes; such a stub can be sometimes found at the beginning of a floating-rate bond or an interest-rate swap. For instance, it might be a four-months coupon whose rate should be interpolated between the quoted three-months and six-months Euribor fixings, followed by semiannual coupons paying the six-months Euribor rate.

Now, given the coupon we want to interpolate and given the existing hierarchy (sketched in the figure below), the question becomes: where in this hierarchy can we find a peg on which to hang the new class?

A sample case

Instead of just pondering the possibilities, we can write some sample code and try them out. Since, as I said, you can download the complete code, here I’ll skip a couple of utility functions in the interest of brevity (the first displays data on a series of cash flows and the second calculates the interpolated rate between two fixings) and show instead the contents of the main function, which sets up the example I mentioned above: it creates a semiannual schedule with an initial short stub spanning four months, from April to August 2023, as well as instances of the three-months and six-months Euribor indexes, each with its forecast curve and a few past fixings stored in memory.

   auto today = Date(18, March, 2024);
   Settings::instance().evaluationDate() = today;
   IborCoupon::Settings::instance()
      .createIndexedCoupons();

   Schedule schedule =
      MakeSchedule()
         .from(Date(8, April, 2023))
         .withFirstDate(Date(8, August, 2023))
         .to(Date(8, February, 2028))
         .withFrequency(Semiannual)
         .withCalendar(TARGET())
         .backwards();

   auto forecastCurve3m =
      ext::make_shared<FlatForward>(
         today, 0.030, Actual360());

   auto index3m = ext::make_shared<Euribor3M>(
      Handle<YieldTermStructure>(forecastCurve3m));
   index3m->addFixing(Date(5, April, 2023), 0.03055);

   auto forecastCurve6m =
      ext::make_shared<FlatForward>(
         today, 0.035, Actual360());

   auto index6m = ext::make_shared<Euribor6M>(
      Handle<YieldTermStructure>(forecastCurve6m));
   index6m->addFixing(Date(5, April, 2023), 0.03339);
   index6m->addFixing(Date(4, August, 2023), 0.0394);
   index6m->addFixing(Date(6, February, 2024), 0.03922);

How not to do it

The first bond we create based on those objects, bond0, is not correct. The code builds it by creating a sequence of coupons paying six-months Euribor and passing them unchanged to the bond constructor.

   int settlementDays = 3;
   double faceAmount = 1000000.0;
   auto dayCounter = index6m->dayCounter();

   Leg coupons =
      IborLeg(schedule, index6m)
         .withNotionals(faceAmount)
         .withPaymentDayCounter(dayCounter);

   Date issueDate = schedule[0];

   Bond bond0(settlementDays, schedule.calendar(),
              issueDate, coupons);

Inspecting the bond coupons we get the results below: the coupons from the second onwards are correct, but the first coupon needs to be changed so that it interpolates between the three-months and six-months index fixings.

First try: a special IBOR coupon

Your first thought, and a perfectly reasonable one, might be that this coupon is irregular but still a Euribor coupon after all. I won’t argue with that; in fact, I’ll go ahead and implement a new class inheriting from IborCoupon. Let’s call it InterpolatedIborCoupon1.

   class InterpolatedIborCoupon1 : public IborCoupon {
      shared_ptr<IborIndex> otherIndex_;
    public:
      InterpolatedIborCoupon1(
         const Date& paymentDate,
         Real nominal,
         const Date& startDate,
         const Date& endDate,
         Natural fixingDays,
         const shared_ptr<IborIndex>& shorterIndex,
         const shared_ptr<IborIndex>& longerIndex)
      : IborCoupon(paymentDate,
                   nominal,
                   startDate,
                   endDate,
                   fixingDays,
                   longerIndex),
        otherIndex_(shorterIndex) {
         registerWith(otherIndex_);
      }
      Rate indexFixing() const override {
         return interpolatedRate(
            fixingDate(),
            accrualStartDate(),
            accrualEndDate(),
            otherIndex_,
            iborIndex());
      }
      shared_ptr<IborIndex> shorterIndex() const {
         return otherIndex_;
      }
      shared_ptr<IborIndex> longerIndex() const {
         return iborIndex();
      }
   };

The implementation turns out to be simple: we need to declare a constructor and to override the indexFixing method from the base class so that it returns the interpolated fixing (the other methods delegate to this one).

However, there are a couple of issues with this. Mind you, the class works: when we create another bond (bond1 in the code) after replacing the first coupon and print out its cash flows, we get the results in the next table, where the amount paid by the first coupon is the one we wanted. But there are hints that our mental model might not be solid.

   auto stub =
      ext::dynamic_pointer_cast<IborCoupon>(
         coupons[0]);

   auto newStub1 =
      ext::make_shared<InterpolatedIborCoupon1>(
         stub->date(), stub->nominal(),
         stub->accrualStartDate(),
         stub->accrualEndDate(),
         stub->fixingDays(), index3m, index6m);
   newStub1->setPricer(
      ext::make_shared<BlackIborCouponPricer>());

   coupons[0] = newStub1;

   Bond bond1(settlementDays, schedule.calendar(),
              issueDate, coupons);

A shaky implementation?

First: the constructor takes the date information for the coupon, as well as the two indexes we need to interpolate. The base-class constructor? It asks for the same date information, and for the index it’s supposed to pay. We have two, and which one we should pass is anybody’s guess; I’m passing the longer one here, but it’s entirely arbitrary.

This causes some of the methods in the class interface to return an answer which doesn’t make a lot of sense, or is just wrong. In our example, calling the index() method of the coupon will return the 6-months Euribor and fail to mention the second index and the interpolation being performed; other methods will fail in a similar way. And unfortunately, overriding index is not possible; it is virtual, but its signature declares that it returns a single index instance, so we can’t return two.

The problem, as I mentioned in the previous article, is that the IborCoupon class and its base FloatingRateCoupon class assume a single underlying index. Our coupon looks a lot like an IBOR coupon, but it doesn’t match its interface.

For a deeper discussion on this, search the Internet for “circle-ellipse problem”. Is a circle also an ellipse? The answer is not obvious in object-oriented programming. It’s all about the interfaces, both declared and inherited, that an object is supposed to provide.

The issue can be mitigated somehow by declaring other methods, like shorterIndex and longerIndex in the example, that match the coupon better. But the other methods remain.

I mentioned a couple of issues. The second is that this coupon works because the pricer we’re using doesn’t happen to call any of its methods besides indexFixing. If someone wrote another pricer that did, the problem above would suddenly become a lot less abstract.

Second try: an entire new kind of coupon

Ok, what if we choose not to consider this as an IBOR coupon? In this case, we have to go up the inheritance chain (shown in the figure at the beginning of the post) to find another base class. The next class up is FloatingRateCoupon, but it relies on a single index and would have the same interface mismatch we found with IborCoupon. This leaves us with Coupon.

As I’m fond of saying, designing software is about tradeoffs. The Coupon class is high enough in the hierarchy—that is, it’s generic enough—that it doesn’t force on us any interface choice, as IborCoupon did. However, this also means that we’ll have to implement quite a bit of functionality that IborCoupon already provided.

Let’s call our second attempt InterpolatedIborCoupon2.

   class InterpolatedIborCoupon2 : public Coupon {
      shared_ptr<IborIndex> shorterIndex_;
      shared_ptr<IborIndex> longerIndex_;
      mutable Rate rate_;
      Date fixingDate_;
    public:
      InterpolatedIborCoupon2(
         const Date& paymentDate,
         Real nominal,
         const Date& startDate,
         const Date& endDate,
         Natural fixingDays,
         const shared_ptr<IborIndex>& shorterIndex,
         const shared_ptr<IborIndex>& longerIndex)
      : Coupon(paymentDate, nominal,
               startDate, endDate),
        shorterIndex_(shorterIndex),
        longerIndex_(longerIndex) {
         registerWith(shorterIndex_);
         registerWith(longerIndex_);
         fixingDate_ =
            shorterIndex_->fixingCalendar().advance(
               startDate, -fixingDays, Days);
      }
      void performCalculations() const override {
         rate_ = interpolatedRate(
            fixingDate_,
            accrualStartDate(),
            accrualEndDate(),
            shorterIndex_,
            longerIndex_);
      }
      Rate rate() const override {
         calculate();
         return rate_;
      }
      Real amount() const override {
         return nominal() * rate() * accrualPeriod();
      }
      Real accruedAmount(const Date& d)
      const override {
         return nominal() * rate() *
                dayCounter().yearFraction(
                   accrualStartDate(), d);
      }
      DayCounter dayCounter() const override {
         return shorterIndex_->dayCounter();
      }
      shared_ptr<IborIndex> shorterIndex() const {
         return shorterIndex_;
      }
      shared_ptr<IborIndex> longerIndex() const {
         return longerIndex_;
      }
   };

Not surprisingly, its constructor takes the same arguments as our previous class; but this time, we’re only passing some of the information (the nominal and the coupon dates) to the base class constructor. The two indexes are stored in data members of this class, which allows it to provide two reasonable inspectors for them.

We also need to implement a number of calculations. First of all, the rate, which (as before) is given by a call to the interpolateRate function. It is calculated in the performCalculation method, because cash flows participate in the Observer pattern (remember the November 2023 issue?) and this is how we ensure that they are cached between notifications. If you want details, chapter 2 of Implementing QuantLib has plenty of them. The rate method ensures that calculations are up to date and then returns the rate.

Besides the rate, though, there are other calculations required by the interface of Coupon; namely, the total amount and the accrued amount at a given date, returned in the obvious way. We also need to return the day counter, but we delegate that to one of the indexes.

And once we have the class, we can use it to replace the first coupon and create another bond (bond2 in the code); printing out its cash flows gives the same results already shown for the previous bond. The class works as we wanted.

   auto newStub2 =
      ext::make_shared<InterpolatedIborCoupon2>(
         stub->date(), stub->nominal(),
         stub->accrualStartDate(),
         stub->accrualEndDate(),
         stub->fixingDays(),
         index3m, index6m);

   coupons[0] = newStub2;

   Bond bond2(settlementDays, schedule.calendar(),
              issueDate, coupons);

So, is it better or worse than the first? It’s not easy to say, and as a matter of fact we might be going into matters of mere taste. The advantage of this class is an interface that won’t risk confusing the users and returning wrong results. The disadvantage is that it needs to reimplement a bunch of virtual methods; and also, do we really want this coupon not to be an IBOR coupon? Your mileage might vary.

Third try: a special IBOR index

But wait, what if we think laterally? What if we circle back to IborCoupon and provide a single index which is the interpolation of the two given indexes? This results in the InterpolatedIborIndex class; but (spoiler alert) it doesn’t turn out to be a great idea.

   class InterpolatedIborIndex : public IborIndex {
      Date couponStartDate_, couponEndDate_;
      shared_ptr<IborIndex> shorterIndex_;
      shared_ptr<IborIndex> longerIndex_;
    public:
      InterpolatedIborIndex(
         const Date& couponStartDate,
         const Date& couponEndDate,
         const shared_ptr<IborIndex>& shorterIndex,
         const shared_ptr<IborIndex>& longerIndex)
      : IborIndex(*longerIndex),
        couponStartDate_(couponStartDate),
        couponEndDate_(couponEndDate),
        shorterIndex_(shorterIndex),
        longerIndex_(longerIndex) {
         registerWith(shorterIndex_);
         registerWith(longerIndex_);
      }
      Rate fixing(const Date& fixingDate,
                  bool = false) const override {
         return interpolatedRate(
            fixingDate,
            couponStartDate_, couponEndDate_,
            shorterIndex_, longerIndex_);
      }
      Rate forecastFixing(
         const Date& fixingDate) const override {
            return fixing(fixingDate);
      }
      Rate pastFixing(
         const Date& fixingDate) const override {
            return fixing(fixingDate);
      }
   };

It is inherited from IborIndex, which makes it possible to pass it with IborCoupon, and overrides its relevant methods so that they return the interpolated rate. Its constructor takes the two indexes, stores them, and sets things up so that any notifications from them are forwarded. However, that’s not all the information that the constructor must take. The start and end date of the coupon are also needed for the calculation, and since they can’t be passed to the fixing method (whose interface is defined in the base class) they must be passed to the constructor and stored.

This makes the index not quite as generic as I would like; that is, we can’t create an instance of this index based on, say, 3-months and 6-months Euribor and use it for different bonds or coupons. Any instance is tied to a specific coupon and can only be used with it.

The real deal breaker, though, is that this class doesn’t always work. It does in this case: after creating an instance of the index and the corresponding Euribor coupon, the code builds yet another bond (bond3). If we print its cash flows, we get again the results in the last table above.

   auto newIndex =
      ext::make_shared<InterpolatedIborIndex>(
         stub->accrualStartDate(),
         stub->accrualEndDate(),
         index3m, index6m);

   auto newStub3 = ext::make_shared<IborCoupon>(
      stub->date(), stub->nominal(),
      stub->accrualStartDate(),
      stub->accrualEndDate(),
      stub->fixingDays(), newIndex);
   newStub3->setPricer(
      ext::make_shared<BlackIborCouponPricer>());

   coupons[0] = newStub3;

   Bond bond3(settlementDays, schedule.calendar(),
              issueDate, coupons);

However, this only happens because the coupon was fixed in the past. If it was to be fixed in the future and therefore forecast, it would give the wrong result, because IborCoupon cheats. For the sake of performance, it’s declared as a friend of IborIndex and calls a private, non-virtual method forecastFixing instead of the one we could override in this code. (Years ago, this was necessary to be able to bootstrap a curve in real time from Excel. It might not be necessary now, but for the time being it’s in the code.)

Summary

Among the three alternatives I described, there seems to be a clear loser (the interpolated index) but not a clear winner. The one objective consideration might be that the first class is less robust against changes in the pricer implementation; other differences might be more subjective. So, as usual, no definitive design answers from yours truly except “it depends.”

Thanks for reading, and see you next time!

Subscribe now

Adding a new cash flow to QuantLib, part I

Welcome back. In the May 2024 issue, we looked at generating bond cash flows with a given schedule. It was from the point of view of using the existing features of the library.

This post changes focus and discusses the internal design of the library with the purpose to extend it. Is QuantLib’s reputation for over-engineering well deserved? You’ll be the judge, dear reader.

A new kind of coupon

As I write this, in late March 2024, some QuantLib contributors are discussing one particular kind of coupon which is not currently implemented: a short stub at the beginning of a floating-rate bond (or an interest-rate swap) whose rate must be interpolated between the fixings of two quoted indexes. Just to make an example, it might be a four-months coupon whose rate should be interpolated between the quoted three-months and six-months Euribor fixings.

By the time you read this, the library might have an implementation available. On this side of the publication lag, though, that didn’t happen yet; which made me think of writing this article as a way to clear my own ideas. First, I’ll describe the existing structure in which it should be inserted. In the next article, I’ll list a few possible ways to do it and comment on the pros and cons of each.

Will we find a sensible implementation? Will the current design bite us back? Since Wilmott Magazine doesn’t provide audio features, I’ll leave it to you to insert an appropriately suspenseful chord here.

The status quo

The implementation of cash flows is the subject of a full chapter in my Implementing QuantLib book, and you can find drafts of it in my blog if you don’t feel like heading to Amazon. Here are the Cliff’s notes.

There is a whole hierarchy of cash flows in the library, and you can see a sketch of part of it in the following figure.

The parent class, CashFlow, has only a minimal interface; it can return the date and the amount of the payment—I’m glossing over a few other methods, coming from the fact that CashFlow in turn inherits from other classes (for instance, the LazyObject class I described in the November 2023 issue in the context of the Observer pattern) and that it participates in the Acyclic Visitor pattern, too.

Simple cash flows

For some cash flows, date and amount are all there is; that’s the case for the Redemption class, modeling the final payment of a bond. The same goes for any amortizing payments during the life of a bond.

More interesting cash flows

A number of other cash flows can be implemented under the umbrella of the Coupon base class, modeling any payment that comes from accruing an interest rate over a period. Yes, that was a dad joke in the heading above. Force of habit.

The Coupon class adds several other methods to the interface of CashFlow. Some of them return information on the rate, the nominal upon which the interest is paid, the start and end date of the coupon, the day-count convention used to calculate the corresponding accrual time, and any ex-coupon period if that’s the case; and others return calculated results such as the accrued amount at any given date. They are a mixture of virtual and non-virtual methods; there is some method in the madness, but I’m not going into it in this article. Cliff’s notes, as I said.

The simplest class that derives from Coupon is probably FixedRateCoupon. The interest rate is a given, so there’s no particular calculation to do in order to return the total coupon amount or the accrued amount at a given date. However, the implementation is not as simple as I would like (a common theme in the library, unfortunately) in order to allow some more outlandish coupons in which the rate is specified as a compounded or continuous rate.

The sorrows of floating-rate coupons

In Implementing QuantLib, I wrote: “The FloatingRateCoupon class is emblematic of the life of most software. It started simple, became more complex as time went by, and might now need some refactoring; its current implementation has a number of issues that I’ll point out as I describe it.”

As you can see, I would have made a very poor salesman.

This class models coupons that pay an interest rate based on the fixing of some index. The most common case used to be some kind of LIBOR-like index, but it could also be, for instance, a quoted swap rate in the case of the floating coupons of a constant-maturity swap. You’re surely thinking of another example right now, aren’t you?

To generalize over all of these cases, its constructor takes an instance (ok, a pointer to an instance) of the abstract InterestRateIndex base class, from which actual indexes are inherited; the index is responsible for providing its fixings, either by forecasting future ones or by storing past ones.

The FloatingRateCoupon class adds a number of methods to the interface of Coupon; you can see some of them in the figure above, but they’re by no means the only ones. The interested reader—that mythical figure—can find them in the library code or in Implementing QuantLib. Derived classes such as IborCoupon (a coupon that pays the fixing of an index such as Euribor, or LIBOR until the recent past) implement them using the relevant conventions, and their constructors restrict the kind of interest-rate index they can accept.

Now, FloatingRateCoupon looks harmless at first, but it already has some assumptions baked in; some of those might bite back, and a few have already done so. For instance, it has a fixingDate method and an indexFixing method; their signature assumes that the coupon rate is fixed at one single date, based on a single index fixing. As you can imagine, this hasn’t aged well now that coupons based on average SOFR fixings are the new normal. In fact, as shown in the diagram, the OvernightIndexedCoupon class (which models such coupons) had to ignore the inherited interface and declare a new, sensible one for its use case.

And of course, the other big assumption is that the coupon is based on the fixing of one single index. It doesn’t look good when you remember that we need to interpolate between two of them, does it?

An example: a floating-rate bond

I don’t want to be a downer, though. These coupon work, after all: in the following code, you can see an example where most of the complexity is hidden behind the scenes: we can instantiate a simple floating-rate bond by building its coupon schedule, creating an instance of the index to be paid, and passing everything to the constructor of the FloatingRateBond class.

   auto today = Date(18, March, 2024);
   Settings::instance().evaluationDate() = today;
   IborCoupon::Settings::instance()
       .createIndexedCoupons();

   auto forecastCurve =
       ext::make_shared<FlatForward>(
           today, 0.04, Actual360());

   auto index6m = ext::make_shared<Euribor6M>(
      Handle<YieldTermStructure>(forecastCurve));
   index6m->addFixing(
       Date(6, February, 2023), 0.03008);
   index6m->addFixing(
       Date(4, August, 2023), 0.0394);
   index6m->addFixing(
       Date(6, February, 2024), 0.03922);

   Schedule schedule =
      MakeSchedule()
         .from(Date(8, February, 2023))
         .to(Date(8, February, 2028))
         .withFrequency(Semiannual)
         .withCalendar(TARGET())
         .backwards();

   int settlementDays = 3;
   double faceAmount = 1000000.0;
   auto dayCounter = index6m->dayCounter();

   FloatingRateBond bond(settlementDays, faceAmount,
                         schedule, index6m,
                         dayCounter);

The index needs a forecast curve to return estimates of future fixings, and needs to store the past fixings we need (or, if you’re not writing a self-contained example, their whole history loaded from a DB.) Once everything is set up, the resulting bond can give you the cash flows shown in the following table, and can be priced given a discount curve or a yield (not shown here).

Adding a floor

Unfortunately, sometimes we have to get a bit more under the hood. For instance, if we want our coupons to have a floor, we need (as shown in the next bit of code) first to create them and then to give them a pricer. The latter knows how to deal with the optionality and contains the required additional market data, such as the volatility of the rate in this case.

   Leg coupons =
       IborLeg(schedule, index6m)
       .withNotionals(faceAmount)
       .withPaymentDayCounter(dayCounter)
       .withFloors(0.01);

   auto volatility =
       ext::make_shared<ConstantOptionletVolatility>(
           today, TARGET(), Following, 0.25,
           Actual360(), ShiftedLognormal, 0.01);

   auto pricer =
       ext::make_shared<BlackIborCouponPricer>(
           Handle<OptionletVolatilityStructure>(
               volatility));

   setCouponPricer(coupons, pricer);

   Date issueDate = schedule[0];

   Bond floored(settlementDays,
                schedule.calendar(),
                issueDate,
                coupons);

The cash flows of the resulting bond are shown in the next table; you can see that the expected rate increases due to the floor and no longer equals the index fixing.

This doesn’t add a lot of code to the example, compared to the simpler case; but supporting this case adds complexity to the cash flow hierarchy. As you can see from the figure above, a separate class deals with capped and/or floored coupons. This makes me itch every time I see it, because it means that a floored LIBOR coupon is not (in the sense of inheritance) a LIBOR coupon.

And of course, we need to introduce a hierarchy of pricers. But I won’t go in any detail about them; again, you know where to look if you’re interested.

Next time: interpolated stub coupons

Now, to go back to our desired new coupon: where should we place it in the cash flow hierarchy? The answer will have to wait for the next installment; and as I mentioned, it’s not entirely clear to me as of now. The seemingly obvious choices might have it inherit the wrong interface, or the wrong constraints. It might turn out to be a study in picking the lesser evil. Such is the interesting life of the library writer.

See you next time!

Why a new book, you ask? It tries to fill a gap in the documentation available for QuantLib. It’s a gap that, unfortunately, I contributed to create; Implementing QuantLib is aimed more at developers wanting to extend the library and less at library users, and the material I contributed to QuantLib Python Cookbook is a decent catalog of use cases but lacks a bit of direction.

This new guide includes some updated material from those two books, as well as some later material I published on this blog or on Wilmott Magazine; the idea is to collect, update and present it all in a sequence that makes it suitable as a tutorial for someone approaching QuantLib or trying to get more fluent in its usage.

It’s a work in progress; please let me know if it goes in the right direction. I’ll be grateful for any corrections, suggestions or comments. And if you find this guide useful and want to support the effort, you can do so by buying a PDF version of this book on Leanpub. As usual on Leanpub, you’ll have free access to new versions when the book is updated.

And of course, if you haven’t already, you can subscribe to this Substack to get my content in your email inbox as soon as I publish it. It’s free. Bye for now!

Subscribe now

Pricing over a range of days

Based on questions on Stack Exchange from Charles, bob.jonst, MCM and lcheng.

import QuantLib as ql
import pandas as pd
from matplotlib import pyplot as plt

Let’s say we have an instrument (a fixed-rate bond, for instance) that we want to price on a number of dates. I assume we also have the market quotes, or the curves, corresponding to each of the dates; in this case we only need interest rate information, but the library works the same way for any quotes.

We’ll store the resulting prices in a dictionary, with the date as the key.

prices = {}

Producing a single price

To price the bond on a single date, we set the evaluation date…

today = ql.Date(3, ql.May, 2021)
ql.Settings.instance().evaluationDate = today

…and we create the instrument itself…

start_date = ql.Date(8, ql.February, 2019)
maturity_date = start_date + ql.Period(5, ql.Years)
schedule = ql.Schedule(
    start_date,
    maturity_date,
    ql.Period(ql.Semiannual),
    ql.TARGET(),
    ql.Following,
    ql.Following,
    ql.DateGeneration.Backward,
    False,
)
coupons = [0.01]
bond = ql.FixedRateBond(
    3, 100, schedule, coupons,
    ql.Thirty360(ql.Thirty360.BondBasis)
)

…and the required discount curve. Here, I’m interpolating it over a set of tabulated rates, such as those I might have available from an external curve service.

data = [
    (ql.Period(0, ql.Months), 0.04),
    (ql.Period(6, ql.Months), 0.04),
    (ql.Period(1, ql.Years), 0.06),
    (ql.Period(2, ql.Years), 0.16),
    (ql.Period(3, ql.Years), 0.33),
    (ql.Period(5, ql.Years), 0.84),
    (ql.Period(7, ql.Years), 1.29),
    (ql.Period(10, ql.Years), 1.63),
    (ql.Period(20, ql.Years), 2.18),
    (ql.Period(30, ql.Years), 2.30),
]

dates = [today + p for p, _ in data]
rates = [r / 100 for _, r in data]

discount_curve = ql.ZeroCurve(
    dates, rates, ql.Actual365Fixed()
)

Given the bond and the curve, we link them together through an engine and get the result.

discount_handle = (
    ql.RelinkableYieldTermStructureHandle(
        discount_curve
    )
)
bond.setPricingEngine(
    ql.DiscountingBondEngine(discount_handle)
)

prices[today] = bond.cleanPrice()
print(prices[today])

101.94609091386468

Pricing on multiple days

Now, let’s say for instance that we have rates for each day from January to April and we want to get the corresponding prices. For this notebook, they’re stored in a file so I don’t need to show you pages of numbers in order to define them. In the real world, they will probably be stored in a DB or some other resource.

df = pd.read_csv(
    "./data/multiple-yields.txt",
    delimiter="\t", parse_dates=["Date"]
)
df

We could repeat the whole calculation for all dates, but it goes against the grain of the library. The architecture (see chapter 2 of Implementing QuantLib for details) was designed so that the instrument can react to changing market conditions; therefore, we can at least avoid recreating the instrument. We’ll still have change the discount curve and the evaluation date.

For instance, here I’ll calculate the price for the first row of data. As I mentioned, I need to set the new evaluation date:

d = ql.Date.from_date(df["Date"][0])
ql.Settings.instance().evaluationDate = d

Then I’ll pick the corresponding rates and rebuild a discount curve:

tenors = list(df.columns[1:])

dates = []
rates = []
for tenor in tenors:
    dates.append(d + ql.Period(tenor))
    rates.append(df[tenor][0] / 100)

discount_curve = ql.ZeroCurve(
    dates, rates, ql.Actual365Fixed()
)

Now I can link the handle in the engine to the new discount curve…

discount_handle.linkTo(discount_curve)

…after which the bond returns the updated price.

print(bond.cleanPrice())

102.55592512367953

By repeating the process, I can generate prices for the whole data set.

for _, row in df.iterrows():
    d = ql.Date.from_date(row["Date"])
    ql.Settings.instance().evaluationDate = d

    dates = []
    rates = []
    for tenor in tenors:
        dates.append(d + ql.Period(tenor))
        rates.append(row[tenor] / 100)
    discount_curve = ql.ZeroCurve(
        dates, rates, ql.Actual365Fixed()
    )

    discount_handle.linkTo(discount_curve)

    prices[d] = bond.cleanPrice()

Here are the results.

dates, values = zip(*sorted(prices.items()))

ax = plt.figure(figsize=(9, 4)).add_subplot(1, 1, 1)
ax.plot([d.to_date() for d in dates], values, "-");

Using quotes

If we work with quotes, we can also avoid rebuilding the curve. Let’s say our discount curve is defined as a risk-free curve with an additional credit spread. The risk-free curve is bootstrapped from a number of market rates; for simplicity, here I’ll use a set of overnight interest-rate swaps, but you’ll use whatever makes sense in your case.

index = ql.Estr()
tenors = [
    ql.Period(i, ql.Years) for i in range(1, 11)
]
rates = [
    0.010,
    0.012,
    0.013,
    0.014,
    0.016,
    0.017,
    0.018,
    0.020,
    0.021,
    0.022,
]

quotes = []
helpers = []
for tenor, rate in zip(tenors, rates):
    q = ql.SimpleQuote(rate)
    h = ql.OISRateHelper(
        2, tenor, ql.QuoteHandle(q), index
    )
    quotes.append(q)
    helpers.append(h)

One thing to note: I’ll setup the curve so that it moves with the evaluation date. This means that I won’t pass an explicit reference date, but a number of business days and a calendar. Passing 0, as in this case, will cause the reference date of the curve to always equal the evaluation date, whatever it happens to be at any given moment; while passing 2, for instance, would cause it to equal the corresponding spot date.

risk_free_curve = ql.PiecewiseFlatForward(
    0, ql.TARGET(), helpers, ql.Actual360()
)

Finally, I’ll manage credit as an additional spread over the curve:

spread = ql.SimpleQuote(0.01)
discount_curve = ql.ZeroSpreadedTermStructure(
    ql.YieldTermStructureHandle(risk_free_curve),
    ql.QuoteHandle(spread)
)

Now we can recalculate today’s price:

ql.Settings.instance().evaluationDate = today
discount_handle.linkTo(discount_curve)

prices[today] = bond.cleanPrice()
print(prices[today])

96.48182194290018

Multiple days again

As before, I’ll now assume to have quotes stored for the past four months; and again, I’ll read the quotes from a file.

df = pd.read_csv(
    "./data/multiple-quotes.txt",
    delimiter="\t", parse_dates=["date"]
)
df

Now that we created the curve based on quotes, we don’t need to build a new one at each step. Instead, we can set new values to the quotes and they will trigger the necessary recalculations in the curve and the instrument.

prices = {}

for _, row in df.iterrows():
    date = ql.Date.from_date(row["date"])

    for q, tenor in zip(
        quotes,
        ["1Y", "2Y", "3Y", "4Y", "5Y",
         "6Y", "7Y", "8Y", "9Y", "10Y"],
    ):
        q.setValue(row[tenor] / 100)

    spread.setValue(row["spread"] / 100)

    ql.Settings.instance().evaluationDate = date

    prices[date] = bond.cleanPrice()

Note that we didn’t create any new object in the loop; we’re only settings new values to the quotes.

Again, here are the results:

dates, values = zip(*sorted(prices.items()))

ax = plt.figure(figsize=(9, 4)).add_subplot(1, 1, 1)
ax.plot([d.to_date() for d in dates], values, "-");

A complication: past fixings

For instruments that depend on the floating rate, we might need some past fixings. This is not necessarily related to pricing on a range of dates: even on today’s date, we need the fixing for the current coupon. Let’s set the instrument up…

forecast_handle = ql.YieldTermStructureHandle(
    risk_free_curve
)
index = ql.Euribor6M(forecast_handle)

bond = ql.FloatingRateBond(
    3, 100, schedule, index,
    ql.Thirty360(ql.Thirty360.BondBasis)
)
bond.setPricingEngine(
    ql.DiscountingBondEngine(discount_handle)
)

ql.Settings.instance().evaluationDate = today
for q, r in zip(quotes, rates):
    q.setValue(r)
spread.setValue(0.01)

…and try to price it. No joy.

try:
    print(bond.cleanPrice())
except Exception as e:
    print(f"{type(e).__name__}: {e}")

RuntimeError: Missing Euribor6M Actual/360 fixing for February 4th, 2021

Being in the past, the fixing can’t be retrieved from the curve. We have to store it into the index, after which the calculation works:

index.addFixing(ql.Date(4, ql.February, 2021), 0.005)

print(bond.cleanPrice())

97.09258058529258

When pricing on a range of dates, though, we need to take into account the fact that the current coupon changes as we go back in time. These two dates will work…

ql.Settings.instance().evaluationDate = (
    ql.Date(1, ql.March, 2021)
)
print(bond.cleanPrice())

ql.Settings.instance().evaluationDate = (
    ql.Date(15, ql.February, 2021)
)
print(bond.cleanPrice())

96.84054989393012
96.78778930005275

…but this one causes the previous coupon to be evaluated, and that requires a new fixing:

ql.Settings.instance().evaluationDate = (
    ql.Date(1, ql.February, 2021)
)
try:
    print(bond.cleanPrice())
except Exception as e:
    print(f"{type(e).__name__}: {e}")

RuntimeError: Missing Euribor6M Actual/360 fixing for August 6th, 2020

Once we add it, the calculation works again.

index.addFixing(ql.Date(6, ql.August, 2020), 0.004)
print(bond.cleanPrice())

96.97859587521839

(If you’re wondering how the calculation worked before, since this coupon belonged to the bond: on the other evaluation dates, this coupon was expired and the engine could skip it without needing to calculate its amount. Thus, its fixing didn’t need to be retrieved.)

More complications: future past fixings

What if we go forward in time, instead of pricing on past dates?

For one thing, we’ll need to forecast curves in some way. One way is to imply them from today’s curves: I talk about implied curves in another notebook, so I won’t repeat myself here. Let’s assume we have implied rates and we can set them. Once we do, we can price in the future just as easily as we do in the past.

ql.Settings.instance().evaluationDate = (
    ql.Date(1, ql.June, 2021)
)

print(bond.cleanPrice())

97.2097212826188

However, there’s another problem, as pointed out by Mariano Zeron in a post to the QuantLib mailing list. If we go further in the future, the bond will require—so to speak—future past fixings.

ql.Settings.instance().evaluationDate = (
    ql.Date(1, ql.September, 2021)
)
try:
    print(bond.cleanPrice())
except Exception as e:
    print(f"{type(e).__name__}: {e}")

RuntimeError: Missing Euribor6M Actual/360 fixing for August 5th, 2021

Here the curve starts on September 1st 2021, and cannot retrieve the fixing at the start of the corresponding coupon.

One way out of this might be to forecast fixings off the current curve and store them:

ql.Settings.instance().evaluationDate = today

fixing_date = ql.Date(5, ql.August, 2021)
future_fixing = index.fixing(fixing_date)
print(future_fixing)
index.addFixing(fixing_date, future_fixing)

0.009974987403789588

This way, they will be retrieved in the same way as real past fixings.

ql.Settings.instance().evaluationDate = (
    ql.Date(1, ql.September, 2021)
)

print(bond.cleanPrice())

97.55258650460641

Of course, you might forecast them in a better way: that’s up to you. And if you’re worried that this might interfere with pricing on today’s date, don’t: stored fixings are only used if they’re in the past with respect to the evaluation date. The fixing I’m storing below for February 3rd 2022 will be retrieved if the evaluation date is later…

index.addFixing(ql.Date(3, ql.February, 2022), 0.02)

ql.Settings.instance().evaluationDate = (
    ql.Date(1, ql.June, 2022)
)
print(index.fixing(ql.Date(3, ql.February, 2022)))

0.02

…but it will be forecast from the curve when it’s after the evaluation date:

ql.Settings.instance().evaluationDate = today
print(index.fixing(ql.Date(3, ql.February, 2022)))

0.012063742194402307