API reference

Term structure

Discount curve construction and interpolation.

Provides the DiscountCurve used as the market input to no-arbitrage short-rate models (Ho-Lee, Hull-White, G2++) and to the full-curve models (HJM, LMM).

Curve mathematics and interpolation details: https://interest-rate-models.readthedocs.io/en/latest/termstructure.html

class interest_rate_models.termstructure.DiscountCurve(times, discount_factors)[source]

Bases: object

Zero-coupon discount curve with smooth instantaneous forwards.

The curve interpolates the cumulative log-discount (equivalently the integral of the instantaneous forward rate) with a shape-preserving monotone cubic (PCHIP), so discount factors stay positive and decreasing whenever the input forwards are positive, and the instantaneous forward curve is continuous. Beyond the last pillar the curve extrapolates with a constant instantaneous forward rate.

See https://interest-rate-models.readthedocs.io/en/latest/termstructure.html for the interpolation scheme and the quantities defined on the curve.

Parameters:
  • times (array_like) – Strictly increasing pillar maturities in years, all positive.

  • discount_factors (array_like) – Zero-coupon bond prices P(0, t) at the pillar maturities, each strictly positive. Values above one are allowed (negative rates).

Raises:

ValueError – If pillars are not strictly increasing and positive, or discount factors are not strictly positive.

classmethod from_zero_rates(times, zero_rates)[source]

Build a curve from continuously-compounded zero rates.

Parameters:
  • times (array_like) – Strictly increasing pillar maturities in years, all positive.

  • zero_rates (array_like) – Continuously-compounded zero rates at the pillars.

Return type:

DiscountCurve

classmethod flat(rate)[source]

Build a flat curve with constant zero and forward rate.

Parameters:

rate (float) – The constant continuously-compounded rate.

Return type:

DiscountCurve

discount(t)[source]

Discount factor P(0, t).

Parameters:

t (array_like) – Maturities in years, non-negative.

Returns:

Discount factors; scalar input returns a scalar.

Return type:

ndarray or float

zero_rate(t)[source]

Continuously-compounded zero rate R(0, t).

At t = 0 the short-end limit (the instantaneous forward at zero) is returned.

Parameters:

t (array_like) – Maturities in years, non-negative.

Returns:

Zero rates; scalar input returns a scalar.

Return type:

ndarray or float

inst_forward(t)[source]

Instantaneous forward rate f(0, t).

Parameters:

t (array_like) – Maturities in years, non-negative.

Returns:

Instantaneous forwards; scalar input returns a scalar.

Return type:

ndarray or float

forward_rate(t1, t2)[source]

Simply-compounded forward rate F(0; t1, t2).

Parameters:
  • t1 (float) – Accrual start and end in years, 0 <= t1 < t2.

  • t2 (float) – Accrual start and end in years, 0 <= t1 < t2.

Returns:

The simple forward rate over [t1, t2].

Return type:

float

Base classes

Abstract base classes and model taxonomy.

The library groups models into two structural families:

  • Short-rate models (ShortRateModel) describe the instantaneous short rate. Equilibrium models (Vasicek, CIR) imply a curve from their parameters; no-arbitrage models (Ho-Lee, Hull-White, G2++) take the observed curve as an input and reproduce it exactly.

  • Full-curve models (CurveModel) describe the evolution of the whole forward curve (HJM) or a set of market forward rates (LMM).

Taxonomy and model selection guidance: https://interest-rate-models.readthedocs.io/en/latest/models/index.html

class interest_rate_models.base.ModelCategory(*values)[source]

Bases: Enum

Structural category of a model.

EQUILIBRIUM

Short-rate model whose initial curve is an output of the model parameters (Vasicek, CIR). Fitting the market curve is a least-squares calibration, generally inexact.

NO_ARBITRAGE

Model that takes the observed discount curve as an input and reproduces it exactly by construction (Ho-Lee, Hull-White, G2++, HJM, LMM).

class interest_rate_models.base.ShortRateModel[source]

Bases: ABC

Base class for models of the instantaneous short rate.

Concrete models provide analytic zero-coupon bond prices where the model admits them, Monte Carlo simulation of the short rate (exact transition sampling where available), and, for the Gaussian and CIR models, closed-form European options on zero-coupon bonds.

abstractmethod bond_price(t, T, r=None)[source]

Zero-coupon bond price P(t, T) given the short rate at t.

Parameters:
  • t (float) – Valuation time in years.

  • T (float) – Bond maturity in years, T >= t.

  • r (float, optional) – Short rate at time t. Models fitted to a curve allow omitting it at t = 0; equilibrium models fall back to their configured initial short rate.

Returns:

The bond price P(t, T).

Return type:

float

zero_rate(t, T, r=None)[source]

Continuously-compounded zero rate R(t, T) implied by the model.

Parameters:
  • t (float) – Valuation time in years.

  • T (float) – Maturity in years, T > t.

  • r (float, optional) – Short rate at time t; see bond_price().

Returns:

The zero rate over [t, T].

Return type:

float

caplet_price(T_start, T_end, strike, notional=1.0)[source]

Caplet on the simple forward rate over [T_start, T_end].

Uses the model-independent static replication of a caplet as a European put on a zero-coupon bond, so it is available for every model that implements bond_option. The rate fixes at T_start and the caplet pays at T_end.

Parameters:
  • T_start (float) – Rate fixing time in years, positive.

  • T_end (float) – Payment time in years, T_end > T_start.

  • strike (float) – Cap rate (simple compounding).

  • notional (float, optional) – Contract notional, default 1.

Returns:

The caplet price.

Return type:

float

floorlet_price(T_start, T_end, strike, notional=1.0)[source]

Floorlet on the simple forward rate over [T_start, T_end].

The mirror image of caplet_price(), replicated as a European call on a zero-coupon bond.

Parameters:
  • T_start (float) – Rate fixing time in years, positive.

  • T_end (float) – Payment time in years, T_end > T_start.

  • strike (float) – Floor rate (simple compounding).

  • notional (float, optional) – Contract notional, default 1.

Returns:

The floorlet price.

Return type:

float

cap_price(strike, maturity, tenor=0.5, notional=1.0)[source]

Interest rate cap as a sum of caplets on a regular schedule.

The first caplet fixes at tenor (the first period’s rate is already known and is excluded, per market convention) and the last pays at maturity.

Parameters:
  • strike (float) – Cap rate (simple compounding).

  • maturity (float) – Final payment time in years; must be an integer multiple of the tenor.

  • tenor (float, optional) – Accrual period length in years, default 0.5.

  • notional (float, optional) – Contract notional, default 1.

Returns:

The cap price.

Return type:

float

floor_price(strike, maturity, tenor=0.5, notional=1.0)[source]

Interest rate floor as a sum of floorlets on a regular schedule.

Same schedule conventions as cap_price().

Parameters:
  • strike (float) – Floor rate (simple compounding).

  • maturity (float) – Final payment time in years; must be an integer multiple of the tenor.

  • tenor (float, optional) – Accrual period length in years, default 0.5.

  • notional (float, optional) – Contract notional, default 1.

Returns:

The floor price.

Return type:

float

abstractmethod simulate(T, n_steps, n_paths, r0=None, seed=None)[source]

Simulate short-rate paths on a uniform time grid.

Parameters:
  • T (float) – Horizon in years.

  • n_steps (int) – Number of time steps; the grid has n_steps + 1 points.

  • n_paths (int) – Number of Monte Carlo paths.

  • r0 (float, optional) – Initial short rate. Defaults to the model’s configured or curve-implied initial rate.

  • seed (int, optional) – Seed for the random number generator.

Returns:

  • times (ndarray, shape (n_steps + 1,)) – The simulation grid.

  • paths (ndarray, shape (n_paths, n_steps + 1)) – Simulated short-rate paths.

Return type:

tuple[NDArray[float64], NDArray[float64]]

class interest_rate_models.base.CurveModel[source]

Bases: ABC

Base class for models of the full forward curve.

Concrete models (HJM, LMM) are constructed from a DiscountCurve and price by Monte Carlo simulation of the whole curve, with closed-form formulas where the model admits them.

abstractmethod simulate(n_paths, seed=None)[source]

Simulate the model’s curve state forward in time.

Parameters:
  • n_paths (int) – Number of Monte Carlo paths.

  • seed (int, optional) – Seed for the random number generator.

Returns:

Model-specific arrays; see the concrete model.

Return type:

tuple of ndarray

Short-rate models

Vasicek (1977) mean-reverting Gaussian short-rate model.

Model dynamics, bond-pricing and option formulas, and calibration notes: https://interest-rate-models.readthedocs.io/en/latest/models/vasicek.html

class interest_rate_models.short_rate.vasicek.Vasicek(kappa, theta, sigma, r0=None)[source]

Bases: ShortRateModel

Vasicek (1977) equilibrium short-rate model.

The short rate follows a mean-reverting Ornstein-Uhlenbeck process with constant volatility, so the model is Gaussian and admits closed-form zero-coupon bond prices, closed-form European options on zero-coupon bonds, and exact Monte Carlo transition sampling. Rates can go negative.

Dynamics and all formulas used here are documented at https://interest-rate-models.readthedocs.io/en/latest/models/vasicek.html

Parameters:
  • kappa (float) – Speed of mean reversion, positive.

  • theta (float) – Long-run mean level of the short rate.

  • sigma (float) – Absolute (normal) volatility of the short rate, positive.

  • r0 (float, optional) – Initial short rate, used as the default state in pricing and simulation.

bond_price(t, T, r=None)[source]

Zero-coupon bond price P(t, T).

Parameters:
  • t (float) – Valuation time in years.

  • T (float) – Bond maturity in years, T >= t.

  • r (float, optional) – Short rate at t; defaults to the configured r0.

Returns:

The bond price.

Return type:

float

bond_option(T, S, strike, kind='call', r=None)[source]

European option, expiring at T, on a zero-coupon bond maturing at S.

Priced at time 0 with the closed-form Gaussian formula; see the model documentation page for the expression.

Parameters:
  • T (float) – Option expiry in years, positive.

  • S (float) – Bond maturity in years, S > T.

  • strike (float) – Strike price of the bond, positive.

  • kind ({'call', 'put'}) – Option type.

  • r (float, optional) – Short rate at time 0; defaults to the configured r0.

Returns:

The option price.

Return type:

float

mean(t, r0=None)[source]

Expected short rate at time t.

Parameters:
  • t (float) – Horizon in years, non-negative.

  • r0 (float, optional) – Initial short rate; defaults to the configured r0.

Return type:

float

variance(t)[source]

Variance of the short rate at time t.

Parameters:

t (float) – Horizon in years, non-negative.

Return type:

float

simulate(T, n_steps, n_paths, r0=None, seed=None)[source]

Simulate short-rate paths by exact transition sampling.

The Ornstein-Uhlenbeck transition is Gaussian with known mean and variance, so there is no discretization error at the grid points.

Parameters:
  • T (float) – Horizon in years, positive.

  • n_steps (int) – Number of steps; the grid has n_steps + 1 points.

  • n_paths (int) – Number of paths.

  • r0 (float, optional) – Initial short rate; defaults to the configured r0.

  • seed (int, optional) – Seed for the random number generator.

Returns:

  • times (ndarray, shape (n_steps + 1,))

  • paths (ndarray, shape (n_paths, n_steps + 1))

Return type:

tuple[NDArray[float64], NDArray[float64]]

calibrate(curve, r0)[source]

Least-squares fit of (kappa, theta, sigma) to a market curve.

Minimizes squared differences between model and market zero rates at the curve pillars. As an equilibrium model, Vasicek generally cannot reproduce an arbitrary curve exactly; the fit is a best approximation. The instance parameters are updated in place with the fitted values.

Parameters:
  • curve (DiscountCurve) – Market curve to fit.

  • r0 (float) – Initial short rate to use during fitting; stored on the instance.

Returns:

The fitted parameters {'kappa', 'theta', 'sigma', 'r0'}.

Return type:

dict

Cox-Ingersoll-Ross (1985) square-root short-rate model.

Model dynamics, bond-pricing and option formulas, and the Feller condition are documented at https://interest-rate-models.readthedocs.io/en/latest/models/cir.html

class interest_rate_models.short_rate.cir.CIR(kappa, theta, sigma, r0=None)[source]

Bases: ShortRateModel

Cox-Ingersoll-Ross (1985) equilibrium short-rate model.

The short rate follows a mean-reverting square-root diffusion, which keeps rates non-negative (strictly positive when the Feller condition holds). Bond prices are exponential-affine, European options on zero-coupon bonds have a closed form in terms of the noncentral chi-square distribution, and the exact transition law is a scaled noncentral chi-square, enabling exact Monte Carlo sampling.

Dynamics and all formulas used here are documented at https://interest-rate-models.readthedocs.io/en/latest/models/cir.html

Parameters:
  • kappa (float) – Speed of mean reversion, positive.

  • theta (float) – Long-run mean level of the short rate, positive.

  • sigma (float) – Volatility coefficient of the square-root diffusion, positive.

  • r0 (float, optional) – Initial short rate, used as the default state in pricing and simulation. Must be positive when given.

Warns:

UserWarning – If the Feller condition fails, in which case the process can touch zero.

feller()[source]

Whether the Feller condition holds (the origin is unattainable).

Return type:

bool

bond_price(t, T, r=None)[source]

Zero-coupon bond price P(t, T).

Parameters:
  • t (float) – Valuation time in years.

  • T (float) – Bond maturity in years, T >= t.

  • r (float, optional) – Short rate at t; defaults to the configured r0.

Returns:

The bond price.

Return type:

float

bond_option(T, S, strike, kind='call', r=None)[source]

European option, expiring at T, on a zero-coupon bond maturing at S.

Priced at time 0 with the closed-form formula in terms of the noncentral chi-square distribution; see the model documentation page for the expression.

Parameters:
  • T (float) – Option expiry in years, positive.

  • S (float) – Bond maturity in years, S > T.

  • strike (float) – Strike price of the bond, in (0, 1) for meaningful exercise.

  • kind ({'call', 'put'}) – Option type.

  • r (float, optional) – Short rate at time 0; defaults to the configured r0.

Returns:

The option price.

Return type:

float

mean(t, r0=None)[source]

Expected short rate at time t.

Parameters:
  • t (float) – Horizon in years, non-negative.

  • r0 (float, optional) – Initial short rate; defaults to the configured r0.

Return type:

float

variance(t, r0=None)[source]

Variance of the short rate at time t.

Parameters:
  • t (float) – Horizon in years, non-negative.

  • r0 (float, optional) – Initial short rate; defaults to the configured r0.

Return type:

float

simulate(T, n_steps, n_paths, r0=None, seed=None)[source]

Simulate short-rate paths by exact transition sampling.

The CIR transition law is a scaled noncentral chi-square, so paths are sampled without discretization error at the grid points and are non-negative by construction.

Parameters:
  • T (float) – Horizon in years, positive.

  • n_steps (int) – Number of steps; the grid has n_steps + 1 points.

  • n_paths (int) – Number of paths.

  • r0 (float, optional) – Initial short rate; defaults to the configured r0.

  • seed (int, optional) – Seed for the random number generator.

Returns:

  • times (ndarray, shape (n_steps + 1,))

  • paths (ndarray, shape (n_paths, n_steps + 1))

Return type:

tuple[NDArray[float64], NDArray[float64]]

calibrate(curve, r0)[source]

Least-squares fit of (kappa, theta, sigma) to a market curve.

Minimizes squared differences between model and market zero rates at the curve pillars. As an equilibrium model, CIR generally cannot reproduce an arbitrary curve exactly; the fit is a best approximation. The instance parameters are updated in place with the fitted values.

Parameters:
  • curve (DiscountCurve) – Market curve to fit.

  • r0 (float) – Initial short rate to use during fitting, positive; stored on the instance.

Returns:

The fitted parameters {'kappa', 'theta', 'sigma', 'r0'}.

Return type:

dict

Ho-Lee (1986) no-arbitrage Gaussian short-rate model.

Model dynamics, the curve-fitting drift, and pricing formulas: https://interest-rate-models.readthedocs.io/en/latest/models/ho-lee.html

class interest_rate_models.short_rate.ho_lee.HoLee(curve, sigma)[source]

Bases: ShortRateModel

Ho-Lee no-arbitrage short-rate model.

The short rate is a Brownian motion with a time-dependent drift chosen so the model reproduces the input discount curve exactly. The model is Gaussian with no mean reversion: zero-coupon bond prices, European bond options, and caps/floors are closed-form, and simulation is exact.

Dynamics and all formulas used here are documented at https://interest-rate-models.readthedocs.io/en/latest/models/ho-lee.html

Parameters:
  • curve (DiscountCurve) – Market discount curve to fit.

  • sigma (float) – Absolute (normal) volatility of the short rate, positive.

bond_price(t, T, r=None)[source]

Zero-coupon bond price P(t, T).

At t = 0 this reproduces the input curve exactly. For t > 0 the price is a closed-form function of the short rate at t.

Parameters:
  • t (float) – Valuation time in years.

  • T (float) – Bond maturity in years, T >= t.

  • r (float, optional) – Short rate at t. Required for t > 0; ignored at t = 0 when omitted.

Returns:

The bond price.

Return type:

float

bond_option(T, S, strike, kind='call')[source]

European option, expiring at T, on a zero-coupon bond maturing at S.

Priced at time 0 with the closed-form Gaussian formula; see the model documentation page for the expression.

Parameters:
  • T (float) – Option expiry in years, positive.

  • S (float) – Bond maturity in years, S > T.

  • strike (float) – Strike price of the bond, positive.

  • kind ({'call', 'put'}) – Option type.

Returns:

The option price.

Return type:

float

simulate(T, n_steps, n_paths, r0=None, seed=None)[source]

Simulate short-rate paths by exact sampling.

Under the risk-neutral measure the Ho-Lee short rate is the initial forward curve plus a deterministic convexity term plus a scaled Brownian motion, so paths are exact at the grid points.

Parameters:
  • T (float) – Horizon in years, positive.

  • n_steps (int) – Number of steps; the grid has n_steps + 1 points.

  • n_paths (int) – Number of paths.

  • r0 (float, optional) – Ignored; the initial rate is implied by the curve. Present for interface compatibility.

  • seed (int, optional) – Seed for the random number generator.

Returns:

  • times (ndarray, shape (n_steps + 1,))

  • paths (ndarray, shape (n_paths, n_steps + 1))

Return type:

tuple[NDArray[float64], NDArray[float64]]

Hull-White (1990) one-factor no-arbitrage short-rate model.

Model dynamics, the curve-fitting drift, and pricing formulas: https://interest-rate-models.readthedocs.io/en/latest/models/hull-white.html

class interest_rate_models.short_rate.hull_white.HullWhite(curve, a, sigma)[source]

Bases: ShortRateModel

Hull-White one-factor model (extended Vasicek).

Mean-reverting Gaussian short rate with a time-dependent drift chosen so the model reproduces the input discount curve exactly. Zero-coupon bonds, European bond options, and caps/floors are closed-form; simulation uses exact Gaussian transitions of the zero-mean factor.

Dynamics and all formulas used here are documented at https://interest-rate-models.readthedocs.io/en/latest/models/hull-white.html

Parameters:
  • curve (DiscountCurve) – Market discount curve to fit.

  • a (float) – Speed of mean reversion, positive.

  • sigma (float) – Absolute (normal) volatility of the short rate, positive.

alpha(t)[source]

Deterministic shift alpha(t) of the short rate.

The short rate decomposes as a zero-mean Ornstein-Uhlenbeck factor plus this curve-dependent function; see the model documentation page.

Parameters:

t (float) – Time in years, non-negative.

Return type:

float

bond_price(t, T, r=None)[source]

Zero-coupon bond price P(t, T).

At t = 0 this reproduces the input curve exactly. For t > 0 the price is exponential-affine in the short rate at t.

Parameters:
  • t (float) – Valuation time in years.

  • T (float) – Bond maturity in years, T >= t.

  • r (float, optional) – Short rate at t. Required for t > 0; ignored at t = 0 when omitted.

Returns:

The bond price.

Return type:

float

bond_option(T, S, strike, kind='call')[source]

European option, expiring at T, on a zero-coupon bond maturing at S.

Priced at time 0 with the closed-form Gaussian formula; see the model documentation page for the expression.

Parameters:
  • T (float) – Option expiry in years, positive.

  • S (float) – Bond maturity in years, S > T.

  • strike (float) – Strike price of the bond, positive.

  • kind ({'call', 'put'}) – Option type.

Returns:

The option price.

Return type:

float

mean(t)[source]

Expected short rate at time t under the risk-neutral measure.

Parameters:

t (float) – Horizon in years, non-negative.

Return type:

float

variance(t)[source]

Variance of the short rate at time t.

Parameters:

t (float) – Horizon in years, non-negative.

Return type:

float

simulate(T, n_steps, n_paths, r0=None, seed=None)[source]

Simulate short-rate paths by exact transition sampling.

The zero-mean factor is an Ornstein-Uhlenbeck process with Gaussian transitions, sampled exactly; the deterministic shift alpha() is added at each grid point.

Parameters:
  • T (float) – Horizon in years, positive.

  • n_steps (int) – Number of steps; the grid has n_steps + 1 points.

  • n_paths (int) – Number of paths.

  • r0 (float, optional) – Ignored; the initial rate is implied by the curve. Present for interface compatibility.

  • seed (int, optional) – Seed for the random number generator.

Returns:

  • times (ndarray, shape (n_steps + 1,))

  • paths (ndarray, shape (n_paths, n_steps + 1))

Return type:

tuple[NDArray[float64], NDArray[float64]]

G2++ two-factor Gaussian no-arbitrage short-rate model.

Model dynamics, the curve-fitting shift, and pricing formulas: https://interest-rate-models.readthedocs.io/en/latest/models/g2pp.html

class interest_rate_models.short_rate.g2pp.G2PP(curve, a, b, sigma, eta, rho)[source]

Bases: ShortRateModel

G2++ two-factor additive Gaussian model.

The short rate is the sum of two correlated zero-mean Ornstein-Uhlenbeck factors and a deterministic shift that fits the input discount curve exactly. Two factors decorrelate rates at different maturities, giving realistic curve movements (twists) that one-factor models cannot produce. Zero-coupon bonds, European bond options, and caps/floors are closed-form; simulation uses exact joint-Gaussian factor transitions.

Dynamics and all formulas used here are documented at https://interest-rate-models.readthedocs.io/en/latest/models/g2pp.html

Parameters:
  • curve (DiscountCurve) – Market discount curve to fit.

  • a (float) – Mean-reversion speed of the first factor, positive.

  • b (float) – Mean-reversion speed of the second factor, positive.

  • sigma (float) – Volatility of the first factor, positive.

  • eta (float) – Volatility of the second factor, positive.

  • rho (float) – Instantaneous correlation between the factors, in [-1, 1].

phi(t)[source]

Deterministic shift phi(t) of the short rate.

The short rate is the sum of the two zero-mean factors and this curve-dependent function; see the model documentation page.

Parameters:

t (float) – Time in years, non-negative.

Return type:

float

bond_price(t, T, r=None)[source]

Zero-coupon bond price P(t, T).

At t = 0 this reproduces the input curve exactly. For t > 0 the price is exponential-affine in the two factor values at t, which are passed as the state instead of the short rate itself.

Parameters:
  • t (float) – Valuation time in years.

  • T (float) – Bond maturity in years, T >= t.

  • r (tuple of float, optional) – Factor state (x, y) at time t. Required for t > 0; ignored at t = 0 when omitted (the factors start at zero).

Returns:

The bond price.

Return type:

float

bond_option(T, S, strike, kind='call')[source]

European option, expiring at T, on a zero-coupon bond maturing at S.

Priced at time 0 with the closed-form Gaussian formula; see the model documentation page for the expression.

Parameters:
  • T (float) – Option expiry in years, positive.

  • S (float) – Bond maturity in years, S > T.

  • strike (float) – Strike price of the bond, positive.

  • kind ({'call', 'put'}) – Option type.

Returns:

The option price.

Return type:

float

simulate(T, n_steps, n_paths, r0=None, seed=None, return_factors=False)[source]

Simulate short-rate paths by exact joint-Gaussian sampling.

The two zero-mean factors have jointly Gaussian transitions with known covariance, sampled exactly; the deterministic shift phi() is added at each grid point.

Parameters:
  • T (float) – Horizon in years, positive.

  • n_steps (int) – Number of steps; the grid has n_steps + 1 points.

  • n_paths (int) – Number of paths.

  • r0 (float, optional) – Ignored; the initial rate is implied by the curve. Present for interface compatibility.

  • seed (int, optional) – Seed for the random number generator.

  • return_factors (bool, optional) – If True, also return the factor paths.

Returns:

  • times (ndarray, shape (n_steps + 1,))

  • paths (ndarray, shape (n_paths, n_steps + 1)) – Short-rate paths.

  • x, y (ndarray, shape (n_paths, n_steps + 1)) – Factor paths, only when return_factors is True.

Return type:

tuple[NDArray[float64], …]

Full-curve models

Heath-Jarrow-Morton forward curve framework (Gaussian factors).

The framework, its no-arbitrage drift condition, and the discretization used here are documented at https://interest-rate-models.readthedocs.io/en/latest/models/hjm.html

class interest_rate_models.full_curve.hjm.HJM(curve, vols, T_max, n_steps)[source]

Bases: CurveModel

Heath-Jarrow-Morton model with deterministic factor volatilities.

The instantaneous forward curve evolves under the risk-neutral measure with user-supplied factor volatility functions; the drift is fully determined by them through the HJM no-arbitrage condition and is computed internally by quadrature on the maturity grid. With deterministic volatilities the model is Gaussian; a constant factor volatility reproduces Ho-Lee and an exponentially damped one reproduces Hull-White, which is how the implementation is validated.

The framework, drift condition, and discretization are documented at https://interest-rate-models.readthedocs.io/en/latest/models/hjm.html

Parameters:
  • curve (DiscountCurve) – Market discount curve providing the initial forward curve.

  • vols (float, callable, or sequence of callables) – Factor volatility specification. A float means one constant factor. A callable must have signature vol(t, T_array) -> array returning the factor volatility for calendar time t at each maturity in T_array. A sequence of callables defines a multi-factor model.

  • T_max (float) – Longest maturity carried on the grid; also the simulation horizon.

  • n_steps (int) – Number of uniform time steps on [0, T_max].

classmethod constant_vol(curve, sigma, T_max, n_steps)[source]

One-factor HJM with constant volatility (Ho-Lee dynamics).

Parameters:
  • curve (DiscountCurve) – Market discount curve.

  • sigma (float) – Constant forward-rate volatility, positive.

  • T_max (float) – Longest maturity on the grid.

  • n_steps (int) – Number of time steps.

Return type:

HJM

classmethod exponential_vol(curve, sigma, lam, T_max, n_steps)[source]

One-factor HJM with exponentially damped volatility (Hull-White).

Parameters:
  • curve (DiscountCurve) – Market discount curve.

  • sigma (float) – Short-end volatility level, positive.

  • lam (float) – Damping (mean-reversion) rate, positive.

  • T_max (float) – Longest maturity on the grid.

  • n_steps (int) – Number of time steps.

Return type:

HJM

simulate(n_paths, seed=None)[source]

Evolve the forward curve and return the realized short rate.

Uses an Euler scheme in calendar time on the fixed maturity grid, with the no-arbitrage drift recomputed each step by trapezoidal quadrature.

Parameters:
  • n_paths (int) – Number of Monte Carlo paths.

  • seed (int, optional) – Seed for the random number generator.

Returns:

  • times (ndarray, shape (n_steps + 1,)) – Simulation grid (equal to the maturity grid).

  • short_rates (ndarray, shape (n_paths, n_steps + 1)) – The realized short rate r(t) = f(t, t) along each path.

Return type:

tuple[NDArray[float64], NDArray[float64]]

mc_bond_price(T, n_paths=20000, seed=None)[source]

Monte Carlo zero-coupon bond price via the simulated bank account.

A direct check of the drift condition: the result must equal the input curve’s discount factor up to Monte Carlo error.

Parameters:
  • T (float) – Bond maturity; must be a grid point.

  • n_paths (int, optional) – Number of paths.

  • seed (int, optional) – Seed for the random number generator.

Returns:

The Monte Carlo estimate of P(0, T).

Return type:

float

mc_bond_option(T, S, strike, kind='call', n_paths=20000, seed=None)[source]

Monte Carlo European option on a zero-coupon bond.

The bond price at expiry is computed from the simulated forward curve by trapezoidal integration over maturities in [T, S].

Parameters:
  • T (float) – Option expiry; must be a grid point.

  • S (float) – Bond maturity, S > T; must be a grid point.

  • strike (float) – Strike price, positive.

  • kind ({'call', 'put'}) – Option type.

  • n_paths (int, optional) – Number of paths.

  • seed (int, optional) – Seed for the random number generator.

Returns:

The Monte Carlo option price.

Return type:

float

LIBOR Market Model (Brace-Gatarek-Musiela) for forward market rates.

Model dynamics, the spot-measure drift, Black caplet pricing, and the Rebonato swaption approximation are documented at https://interest-rate-models.readthedocs.io/en/latest/models/lmm.html

class interest_rate_models.full_curve.lmm.LiborMarketModel(curve, tenor, n_periods, vol, corr_beta=0.0)[source]

Bases: CurveModel

LIBOR Market Model with lognormal forwards and constant volatilities.

Models the simply-compounded forward rates spanning a regular tenor structure. Each forward is lognormal under its own forward measure, so caplets price by Black’s formula exactly; the joint evolution under the spot measure carries the state-dependent no-arbitrage drift and is simulated with a log-Euler scheme. Instantaneous correlation between forwards is exponentially decaying in tenor distance. European swaptions price approximately by Rebonato’s formula and exactly by Monte Carlo.

Dynamics and all formulas used here are documented at https://interest-rate-models.readthedocs.io/en/latest/models/lmm.html

Parameters:
  • curve (DiscountCurve) – Market discount curve providing the initial forwards.

  • tenor (float) – Accrual period length in years (e.g. 0.5), positive.

  • n_periods (int) – Number of forward rates; the tenor dates are 0, tenor, …, n_periods * tenor. At least 2.

  • vol (float or array_like) – Black volatility of each forward: a scalar applies to all, an array gives one per forward (length n_periods).

  • corr_beta (float, optional) – Decay rate of the instantaneous correlation between forwards with tenor-date distance; 0 (default) means perfectly correlated forwards (a one-factor model).

caplet_price(i, strike, notional=1.0)[source]

Black caplet price on forward i.

The caplet fixes at the forward’s start date and pays at its end date. Forward 0 fixes immediately, so its caplet is the discounted intrinsic value.

Parameters:
  • i (int) – Forward index in [0, n_periods).

  • strike (float) – Cap rate (simple compounding).

  • notional (float, optional) – Contract notional, default 1.

Returns:

The caplet price.

Return type:

float

cap_price(strike, maturity, notional=1.0)[source]

Cap as a sum of Black caplets on the tenor schedule.

The first period’s caplet is excluded (its rate is already fixed), matching the short-rate models’ convention.

Parameters:
  • strike (float) – Cap rate (simple compounding).

  • maturity (float) – Final payment date; must be a tenor date, at least two periods out.

  • notional (float, optional) – Contract notional, default 1.

Returns:

The cap price.

Return type:

float

annuity(alpha, beta)[source]

Present value of the fixed-leg annuity for a swap over [T_alpha, T_beta].

Parameters:
  • alpha (int) – Index of the swap start tenor date.

  • beta (int) – Index of the final payment tenor date, beta > alpha.

Return type:

float

swap_rate(alpha, beta)[source]

Par swap rate for a swap spanning tenor dates alpha to beta.

Parameters:
  • alpha (int) – Index of the swap start tenor date.

  • beta (int) – Index of the final payment tenor date, beta > alpha.

Return type:

float

swaption_price(alpha, beta, strike)[source]

European payer swaption by Rebonato’s approximation.

Approximates the swap-rate Black volatility from the forward volatilities and correlations, then applies Black’s formula on the annuity numeraire. Accurate to well within a percent for typical parameters; validate against mc_swaption_price().

Parameters:
  • alpha (int) – Expiry tenor-date index (swap starts at T_alpha), alpha >= 1.

  • beta (int) – Final payment tenor-date index, beta > alpha.

  • strike (float) – Fixed rate of the underlying swap, positive.

Returns:

The payer swaption price.

Return type:

float

simulate(n_paths, seed=None, n_substeps=4)[source]

Simulate the forwards under the spot measure.

Uses a log-Euler scheme with the state-dependent spot-measure drift recomputed at every substep. Each forward is frozen at its fixing date; the numeraire is the discretely rebalanced bank account.

Parameters:
  • n_paths (int) – Number of Monte Carlo paths.

  • seed (int, optional) – Seed for the random number generator.

  • n_substeps (int, optional) – Euler substeps per tenor period, default 4.

Returns:

  • tenor_dates (ndarray, shape (n_periods + 1,)) – The tenor structure.

  • forwards (ndarray, shape (n_paths, n_periods, n_periods)) – forwards[p, k, i] is forward i observed at tenor date T_k on path p (frozen at its fixed value for i < k).

  • numeraire (ndarray, shape (n_paths, n_periods + 1)) – The bank-account numeraire at each tenor date.

Return type:

tuple[NDArray[float64], NDArray[float64], NDArray[float64]]

mc_caplet_price(i, strike, n_paths=50000, seed=None, n_substeps=4)[source]

Monte Carlo caplet price under the spot measure.

A consistency check for the simulation: must converge to caplet_price().

Parameters:
  • i (int) – Forward index in [1, n_periods).

  • strike (float) – Cap rate.

  • n_paths (int, optional) – Number of paths.

  • seed (int, optional) – Seed for the random number generator.

  • n_substeps (int, optional) – Euler substeps per tenor period.

Return type:

float

mc_swaption_price(alpha, beta, strike, n_paths=50000, seed=None, n_substeps=4)[source]

Monte Carlo European payer swaption price under the spot measure.

Reconstructs the discount curve at expiry from the simulated forwards, computes the swap rate and annuity, and discounts the payoff with the bank-account numeraire.

Parameters:
  • alpha (int) – Expiry tenor-date index, alpha >= 1.

  • beta (int) – Final payment tenor-date index, beta > alpha.

  • strike (float) – Fixed rate of the underlying swap.

  • n_paths (int, optional) – Number of paths.

  • seed (int, optional) – Seed for the random number generator.

  • n_substeps (int, optional) – Euler substeps per tenor period.

Return type:

float

Factory

Model factory: instantiate any model of the library by name.

Available names and per-model configuration: https://interest-rate-models.readthedocs.io/en/latest/models/index.html

interest_rate_models.factory.get_model(name, **kwargs)[source]

Instantiate a model by (case-insensitive) name.

Parameters:
  • name (str) – Model name or alias: 'vasicek', 'cir' ('cox-ingersoll-ross'), 'ho-lee' ('holee'), 'hull-white' ('hullwhite', 'hw'), 'g2++' ('g2pp'), 'hjm' ('heath-jarrow-morton'), 'lmm' ('libor-market-model', 'bgm').

  • **kwargs – Passed to the model constructor; see each model’s documentation for its parameters.

Returns:

The instantiated model.

Return type:

ShortRateModel or CurveModel

Raises:

ValueError – If the name is not recognized.