Understanding the Exercise Class in QuantLib Python: From Concept to Practice

How option exercise styles — European, American, and Bermudan — are modeled in QuantLib, with a practical VanillaOption pricing example.

Introduction for Exercise Class in QuantLib Python

Not a paid member yet? Click here to read this article for FREE!

Introduction

When working with option derivatives pricing in QuantLib, one of the fundamental questions is:

When can the holder of an option exercise it?

The Exercise class provides a unified way to describe the timing of exercise rights for an option or any exercise-style instrument. It doesn’t define the payoff itself — rather, it defines when the payoff can be realized.

From a design standpoint, Exercise is an abstract base class. It acts as the “when” component in QuantLib’s modular option architecture, which consists of three key parts:

This separation allows QuantLib to flexibly model many derivatives — from simple European calls to complex callable bonds or Bermudan swaptions.

Key Features of Exercise Subclasses

QuantLib provides several subclasses of the abstract Exercise class, each representing a common option style in the market:

• **EuropeanExercise**

Exercise is allowed only once, on a specific date (usually the maturity date). Commonly used for vanilla options traded on exchanges.

• **AmericanExercise**

Exercise is allowed at any time between a start and an end date. Used in American-style options and early-exercise securities.

• **BermudanExercise**

Exercise is allowed only on a predefined set of discrete dates. Common for callable or cancellable products like Bermudan swaptions.

Each subclass shares the same interface but implements its own rule for valid exercise times.

Visual Reference — Exercise Timelines

The following diagram illustrates how these three exercise styles differ in terms of exercise opportunities over time:

The VanillaOption Class — How Exercise Works in Practice

The VanillaOption class is a concrete implementation of QuantLib’s Option base class. It encapsulates three essential components:

1. Payoff — determines the payout if the option is exercised.
2. Exercise — determines when exercise can occur.
3. Pricing Engine — calculates the fair value based on the underlying process and market data.

Its constructor looks like this:

VanillaOption(payoff: Payoff, exercise: Exercise)

The VanillaOption doesn’t perform pricing itself. Instead, once you attach a pricing engine using .setPricingEngine(engine), the valuation is delegated to that engine, which interprets the exercise rules and payoff definition. By swapping different engines (e.g., analytical, tree-based, or Monte Carlo), the same option can be priced under various models without changing its structure.

Practical Example: Defining and Pricing Options

Here’s a practical Python example demonstrating how to construct and price European, American, and Bermudan-style options:

import QuantLib as ql

# --- Basic setup ---
today = ql.Date(15, 4, 2025)
ql.Settings.instance().evaluationDate = today
expiry = today + ql.Period(6, ql.Months)

# --- Define different exercise types ---
european_exercise = ql.EuropeanExercise(expiry)
american_exercise = ql.AmericanExercise(today, expiry)
bermudan_dates = [today + ql.Period(3, ql.Months), expiry]
bermudan_exercise = ql.BermudanExercise(bermudan_dates)

# --- Market data setup ---
spot = ql.SimpleQuote(100.0)
underlying = ql.QuoteHandle(spot)
dividend = ql.YieldTermStructureHandle(ql.FlatForward(today, 0.02, ql.Actual365Fixed()))
rate = ql.YieldTermStructureHandle(ql.FlatForward(today, 0.05, ql.Actual365Fixed()))
vol = ql.BlackVolTermStructureHandle(ql.BlackConstantVol(today, ql.NullCalendar(), 0.20, ql.Actual365Fixed()))
bsm_process = ql.BlackScholesMertonProcess(underlying, dividend, rate, vol)

# --- Payoff definition for Call Option ---
payoff = ql.PlainVanillaPayoff(ql.Option.Call, 100)

# --- Build VanillaOption objects ---
european_option = ql.VanillaOption(payoff, european_exercise)
american_option = ql.VanillaOption(payoff, american_exercise)
bermudan_option = ql.VanillaOption(payoff, bermudan_exercise)

# --- Define pricing engines ---
european_engine = ql.AnalyticEuropeanEngine(bsm_process)
american_engine = ql.BaroneAdesiWhaleyApproximationEngine(bsm_process)
bermudan_engine = ql.BinomialJRVanillaEngine(bsm_process, 100)

# --- Attach pricing engines ---
european_option.setPricingEngine(european_engine)
american_option.setPricingEngine(american_engine)
bermudan_option.setPricingEngine(bermudan_engine)

# --- Results ---
print("European Option NPV:", european_option.NPV())
print("American Option NPV:", american_option.NPV())
print("Bermudan Option NPV:", bermudan_option.NPV())

European Option NPV: 6.317050442936141
American Option NPV: 6.317063695752475
Bermudan Option NPV: 6.3191617584624264

Conclusion

The Exercise class is a cornerstone of QuantLib’s option architecture, defining when an option can be exercised.

Meanwhile, the VanillaOption class brings together the payoff, exercise, and pricing engine into a cohesive and extensible framework.

Key takeaways:

• Exercise → controls timing (European, American, Bermudan).
• Payoff → defines cashflow logic.
• VanillaOption → unifies these components and connects to pricing engines.

This modular design allows financial engineers to model a wide range of derivatives — from basic vanilla options to complex callable or Bermudan-style structures — with just a few lines of QuantLib Python code.

If you found this article helpful or have thoughts to share, feel free to leave a comment or reach out. I’ll be publishing more posts in this QuantLib Python series, so follow along if you’re interested in practical applications of financial engineering. Thanks for reading!

Reference

1. John C. Hull, Options, Futures, and Other Derivatives, 11th Edition, Pearson, 2022.
2. Ballabio, Luigi. Implementing QuantLib. Online resource
3. Goutham Balaraman, Luigi Ballabio. QuantLib Python Cookbook. Leanpub, 2020. https://leanpub.com/quantlibpythoncookbook

A message from our Founder

Hey, Sunil here. I wanted to take a moment to thank you for reading until the end and for being a part of this community.

Did you know that our team run these publications as a volunteer effort to over 3.5m monthly readers? We don’t receive any funding, we do this to support the community. ❤️

If you want to show some love, please take a moment to follow me on LinkedIn, TikTok, **Instagram. You can also subscribe to our [weekly newsletter](https://newsletter.plainenglish.io/)**.

And before you go, don’t forget to clap and follow the writer️!