Black & Bachelier Engines

The pricing engine module provides a set of functions from two cornerstone models in mathematical finance: the Black and Bachelier option pricing formulas, while also exposing their implied volatility inverses and related probabilities such as in-the-money (ITM) probabilities.

These functions are commonly used for pricing and risk analysis in derivatives models based on lognormal (Black) or normal (Bachelier) assumptions.

Black Related functions

ql.blackFormula(optionType: ql.Option.Type, strike: float, forward: float, stdDev: float, discount: float = 1.0, displacement: float = 0.0)

Computes the Black (1976) option price for a given forward, strike, and volatility.

Parameters:

• optionType (ql.Option.Type) – Type of the option (Option.Call or Option.Put).

• strike (float) – Strike price of the option.

• forward (float) – Forward price of the underlying.

• stdDev (float) – Standard deviation of log returns (σ√T).

• discount (float, optional) – Discount factor for the payoff. Defaults to 1.0.

• displacement (float, optional) – Displacement applied to avoid negative forwards/strikes. Defaults to 0.0.

Returns:

The Black option price.

Return type:

float

Black Implied Volatility (Standard and LiRS methods)

ql.blackFormulaImpliedStdDev(optionType: ql.Option.Type, strike: float, forward: float, blackPrice: float, discount: float = 1.0, displacement: float = 0.0, guess: float = None, accuracy: float = 1.0e-6, maxIterations: int = 100)

Computes the implied standard deviation (σ√T) from a given Black option price.

Parameters:

• optionType (ql.Option.Type) – Option type (Call or Put).

• strike (float) – Strike price.

• forward (float) – Forward price of the underlying.

• blackPrice (float) – Observed Black option price.

• discount (float, optional) – Discount factor. Defaults to 1.0.

• displacement (float, optional) – Displacement applied to forward/strike. Defaults to 0.0.

• guess (float, optional) – Initial guess for the implied standard deviation.

• accuracy (float, optional) – Root-finding tolerance. Defaults to 1.0e-6.

• maxIterations (int, optional) – Maximum number of iterations. Defaults to 100.

Returns:

Implied standard deviation.

Return type:

float

ql.blackFormulaImpliedStdDevLiRS(optionType: ql.Option.Type, strike: float, forward: float, blackPrice: float, discount: float = 1.0, displacement: float = 0.0, guess: float = None, omega: float = 1.0, accuracy: float = 1.0e-6, maxIterations: int = 100)

Computes the implied standard deviation using the LiRS (Li–Rydén–Ståhl) root-finding method, an accelerated variant for faster convergence.

Parameters:

omega (float, optional) – Relaxation factor for LiRS iterations (1.0 = standard Newton).

Other parameters are as in blackFormulaImpliedStdDev().

ql.blackFormulaImpliedStdDevLiRS(payoff: ql.PlainVanillaPayoff, forward: float, blackPrice: float, discount: float = 1.0, displacement: float = 0.0, guess: float = None, omega: float = 1.0, accuracy: float = 1.0e-6, maxIterations: int = 100)

Overload of the LiRS implied volatility solver that accepts a payoff object.

param payoff:

Plain-vanilla payoff describing strike and option type.

type payoff:

ql.PlainVanillaPayoff

Black ITM Probabilities

ql.blackFormulaCashItmProbability(optionType: ql.Option.Type, strike: float, forward: float, stdDev: float, displacement: float = 0.0)

Computes the probability (under the risk-neutral measure) that the option ends in the money, expressed in cash terms.

Returns:

The discounted probability that the option is in the money.

Return type:

float

ql.blackFormulaCashItmProbability(payoff: ql.PlainVanillaPayoff, forward: float, stdDev: float, displacement: float = 0.0)

Same as above, but accepts a payoff object.

ql.blackFormulaAssetItmProbability(optionType: ql.Option.Type, strike: float, forward: float, stdDev: float, displacement: float = 0.0)

Computes the asset-based ITM probability, used for delta and forward measure computations.

ql.blackFormulaAssetItmProbability(payoff: ql.PlainVanillaPayoff, forward: float, stdDev: float, displacement: float = 0.0)

Overload accepting a payoff object.

BlackCalculator

class ql.BlackCalculator(payoff: ql.StrikedTypePayoff, forward: float, stdDev: float, discount: float = 1.0)

The BlackCalculator computes the price and Greeks of European-style options under the Black (lognormal) model. It provides analytical results for option value, delta, gamma, vega, rho, and other sensitivities based on a given payoff, forward price, and volatility.

Parameters:

• payoff (ql.StrikedTypePayoff) – The option payoff (e.g., call or put) defining the strike and option type.

• forward (float) – The forward price of the underlying asset.

• stdDev (float) – The standard deviation of log returns (σ√T).

• discount (float, optional) – The discount factor applied to the payoff. Defaults to 1.0.

value() → float

Returns the option price under the Black model.

deltaForward() → float

Returns the forward delta, i.e., derivative of the option value with respect to the forward price.

delta(spot: float) → float

Returns the spot delta, i.e., derivative of the option price with respect to the current spot price.

elasticityForward() → float

Returns the forward elasticity, the percentage change in price for a 1% change in the forward price.

elasticity(spot: float) → float

Returns the spot elasticity, the percentage change in price for a 1% change in the spot price.

gammaForward() → float

Returns the forward gamma, the second derivative of the option value with respect to the forward price.

gamma(spot: float) → float

Returns the spot gamma, the second derivative of the option value with respect to the spot price.

theta(spot: float, maturity: float) → float

Computes the theta, the rate of change of the option value with respect to time to maturity.

thetaPerDay(spot: float, maturity: float) → float

Returns the theta per day, i.e., daily time decay of the option value.

vega(maturity: float) → float

Returns the vega, the sensitivity of the option price to volatility.

rho(maturity: float) → float

Returns the rho, the sensitivity of the option price to changes in the interest rate.

dividendRho(maturity: float) → float

Returns the dividend rho, the sensitivity to changes in the dividend yield.

itmCashProbability() → float

Returns the cash-based probability that the option ends in the money.

itmAssetProbability() → float

Returns the asset-based probability that the option ends in the money.

strikeSensitivity() → float

Returns the derivative of the option value with respect to the strike price.

strikeGamma() → float

Returns the second derivative of the option value with respect to strike.

alpha() → float

Returns the α (alpha) parameter of the Black model formula.

beta() → float

Returns the β (beta) parameter of the Black model formula.

Example usage:

payoff = ql.PlainVanillaPayoff(ql.Option.Call, 100)
calc = ql.BlackCalculator(payoff, forward=105, stdDev=0.2, discount=0.99)
price = calc.value()
delta = calc.delta(102)

Bachelier Related functions

ql.bachelierBlackFormula(optionType: ql.Option.Type, strike: float, forward: float, stdDev: float, discount: float = 1.0)

Computes the Bachelier (Normal) option price, assuming normal (additive) dynamics for the underlying.

Returns:

The Bachelier option price.

Return type:

float

Bachelier Implied Volatilities

ql.bachelierBlackFormulaImpliedVol(optionType: ql.Option.Type, strike: float, forward: float, tte: float, bachelierPrice: float, discount: float = 1.0)

Computes the implied normal volatility from a given Bachelier option price.

ql.bachelierBlackFormulaImpliedVolChoi(optionType: ql.Option.Type, strike: float, forward: float, tte: float, bachelierPrice: float, discount: float = 1.0)

Alternative implied volatility computation using Choi’s closed-form approximation for faster evaluation.

Bachelier ITM Probabilities

ql.bachelierBlackFormulaAssetItmProbability(optionType: ql.Option.Type, strike: float, forward: float, stdDev: float)

Computes the probability (under normal dynamics) that the option finishes in the money, expressed in asset terms.

ql.bachelierBlackFormulaAssetItmProbability(payoff: ql.PlainVanillaPayoff, forward: float, stdDev: float)

Overload accepting a payoff object.

BachelierCalculator

class ql.BachelierCalculator(payoff: ql.StrikedTypePayoff, forward: float, stdDev: float, discount: float = 1.0)

The BachelierCalculator computes the price and Greeks of European-style options under the Bachelier (normal) model. It is suitable for assets or rates that can take negative values (e.g., interest rates). All sensitivities are derived assuming additive (not lognormal) dynamics.

Parameters:

• payoff (ql.StrikedTypePayoff) – The option payoff defining the strike and option type.

• forward (float) – The forward price of the underlying asset.

• stdDev (float) – The standard deviation of the underlying (σ√T).

• discount (float, optional) – The discount factor for present value. Defaults to 1.0.

value() → float

Returns the option price under the Bachelier (normal) model.

deltaForward() → float

Returns the forward delta under the normal model.

delta(spot: float) → float

Returns the spot delta, i.e., sensitivity to the current spot price.

elasticityForward() → float

Returns the forward elasticity (percentage change with respect to the forward).

elasticity(spot: float) → float

Returns the spot elasticity (percentage change with respect to the spot).

gammaForward() → float

Returns the forward gamma, second derivative with respect to forward.

gamma(spot: float) → float

Returns the spot gamma, second derivative with respect to spot.

theta(spot: float, maturity: float) → float

Returns the theta, time decay of the option value.

thetaPerDay(spot: float, maturity: float) → float

Returns theta per day, the daily time decay.

vega(maturity: float) → float

Returns the vega, sensitivity to volatility under normal dynamics.

rho(maturity: float) → float

Returns the rho, sensitivity to the interest rate.

dividendRho(maturity: float) → float

Returns the dividend rho, the sensitivity to dividend yield.

itmCashProbability() → float

Returns the cash probability of finishing in the money.

itmAssetProbability() → float

Returns the asset probability of finishing in the money.

strikeSensitivity() → float

Returns the derivative of the option value with respect to strike.

strikeGamma() → float

Returns the second derivative of value with respect to strike.

alpha() → float

Returns the α (alpha) parameter of the Bachelier formula.

beta() → float

Returns the β (beta) parameter of the Bachelier formula.

Example usage:

payoff = ql.PlainVanillaPayoff(ql.Option.Put, 100)
calc = ql.BachelierCalculator(payoff, forward=98, stdDev=0.15, discount=0.995)
price = calc.value()
vega = calc.vega(1.0)