"Vibe-Trading: Your Personal Trading Agent"
Python ai-agentalgorithmic-tradingbacktestingfintechllmmcpmulti-agentpythonquantitative-financetrading
"""Fixed-income primitives: day count conventions, bond pricing, risk metrics, and yield curve fitting.
All rates are decimals, maturities/horizons are in years, and duration/convexity
metrics are in years or years squared.
"""
from __future__ import annotations
import datetime as _dt
import math
from collections.abc import Callable, Sequence
from dataclasses import dataclass
import numpy as np
from scipy.optimize import brentq, minimize
__all__ = [
"DAY_COUNT_CONVENTIONS",
"DEFAULT_DAY_COUNT",
"COMPOUNDING_CONVENTIONS",
"DEFAULT_COMPOUNDING",
"DEFAULT_KEY_RATE_TENORS",
"CurveFit",
"year_fraction",
"accrued_interest",
"bond_cashflows",
"bond_price",
"ytm_solve",
"macaulay_duration",
"modified_duration",
"key_rate_duration",
"convexity",
"dv01",
"effective_duration",
"nelson_siegel",
"svensson",
"fit_yield_curve",
]
#: Day-count conventions understood by :func:`year_fraction`.
DAY_COUNT_CONVENTIONS: tuple[str, ...] = (
"ACT/365F",
"ACT/360",
"ACT/ACT",
"30/360",
"30E/360",
)
#: Convention assumed when the caller does not name one.
DEFAULT_DAY_COUNT: str = "ACT/365F"
#: Compounding conventions understood by the pricing functions.
COMPOUNDING_CONVENTIONS: tuple[str, ...] = ("discrete", "continuous")
#: Compounding assumed when the caller does not name one (the markdown's behaviour).
DEFAULT_COMPOUNDING: str = "discrete"
#: Standard benchmark tenors for Key Rate Duration decomposition.
DEFAULT_KEY_RATE_TENORS: tuple[float, ...] = (
0.5, 1.0, 2.0, 3.0, 5.0, 7.0, 10.0, 20.0, 30.0
)
def year_fraction(
start: _dt.date,
end: _dt.date,
day_count: str = DEFAULT_DAY_COUNT,
) -> float:
"""Accrual factor between two dates under a named day-count convention.
Args:
start: Period start (accrual runs from this date, inclusive).
end: Period end (accrual runs to this date, exclusive).
day_count: One of :data:`DAY_COUNT_CONVENTIONS`. ``ACT/ACT`` is the
ISDA variant: each calendar year contributes
``days_in_that_year / (365 or 366)``.
Returns:
Year fraction as a float. Negative if ``end`` precedes ``start``.
Raises:
ValueError: If ``day_count`` is not a recognised convention.
"""
if day_count not in DAY_COUNT_CONVENTIONS:
raise ValueError(
f"unknown day_count {day_count!r}; expected one of {DAY_COUNT_CONVENTIONS}"
)
if end < start:
return -year_fraction(end, start, day_count)
if day_count == "ACT/365F":
return (end - start).days / 365.0
if day_count == "ACT/360":
return (end - start).days / 360.0
if day_count in ("30/360", "30E/360"):
d1, d2 = start.day, end.day
if day_count == "30/360":
# US bond basis: clip D1 to 30, then clip D2 when adjusted D1 is 30.
if d1 == 31:
d1 = 30
if d2 == 31 and d1 == 30:
d2 = 30
else: # 30E/360 (Eurobond basis) clips both legs unconditionally.
d1 = min(d1, 30)
d2 = min(d2, 30)
months = 12 * (end.year - start.year) + (end.month - start.month)
return (30.0 * months + (d2 - d1)) / 360.0
# ACT/ACT (ISDA): accumulate each calendar year against its own basis.
total = 0.0
cursor = start
while cursor < end:
year_end = _dt.date(cursor.year + 1, 1, 1)
chunk_end = min(year_end, end)
basis = 366.0 if _is_leap(cursor.year) else 365.0
total += (chunk_end - cursor).days / basis
cursor = chunk_end
return total
def _require_finite(**values: float | np.ndarray) -> None:
"""Raise when a named numeric input holds NaN or an infinity.
Every range check in this module is a comparison (``face <= 0``) and a
comparison with NaN is False, so a NaN walked past each of them and came
out as a NaN price, duration or curve.
Raises:
ValueError: Naming the first non-finite input.
"""
for name, value in values.items():
if not np.all(np.isfinite(np.asarray(value, dtype=float))):
raise ValueError(f"{name} must be finite, got {value!r}")
def _is_leap(year: int) -> bool:
"""Report whether a Gregorian year is a leap year.
Args:
year: Four-digit calendar year.
Returns:
True when the year has 366 days.
"""
return year % 4 == 0 and (year % 100 != 0 or year % 400 == 0)
def accrued_interest(
face: float,
coupon_rate: float,
freq: int,
last_coupon: _dt.date,
settlement: _dt.date,
next_coupon: _dt.date,
day_count: str = DEFAULT_DAY_COUNT,
) -> float:
"""Interest earned by the seller between the last coupon and settlement.
Dirty price = clean price + accrued interest. :func:`bond_price` returns the
price on a coupon date, where accrued interest is zero by construction; use
this function to move a mid-period settlement onto that basis.
Args:
face: Par amount the coupon is computed on.
coupon_rate: Annual coupon rate as a decimal.
freq: Coupon payments per year (1 = annual, 2 = semi-annual).
last_coupon: Date of the most recent coupon payment.
settlement: Settlement date of the trade.
next_coupon: Date of the upcoming coupon payment.
day_count: One of :data:`DAY_COUNT_CONVENTIONS`.
Returns:
Accrued interest in the same currency units as ``face``.
Raises:
ValueError: If any numeric input is non-finite, if ``freq`` is not
positive, if the coupon dates are not ordered, if ``settlement``
falls outside the coupon period, or if ``day_count`` is not a
recognised convention.
"""
# Before the endpoint shortcuts: settling exactly on a coupon date returns
# a constant, which would otherwise launder a NaN face or rate into a
# clean-looking 0.0.
_require_finite(face=face, coupon_rate=coupon_rate, freq=freq)
if freq <= 0:
raise ValueError(f"freq must be positive, got {freq}")
if not last_coupon < next_coupon:
raise ValueError("last_coupon must precede next_coupon")
if not last_coupon <= settlement <= next_coupon:
raise ValueError("settlement must fall inside [last_coupon, next_coupon]")
# Checked here as well as in year_fraction: the endpoint returns below never
# reach year_fraction, so an unknown convention would otherwise pass there.
if day_count not in DAY_COUNT_CONVENTIONS:
raise ValueError(
f"unknown day_count {day_count!r}; expected one of {DAY_COUNT_CONVENTIONS}"
)
# 30/360 and 30E/360 clip the day-of-month, so distinct calendar dates
# (e.g. Jan 30 -> Jan 31) can still year_fraction to 0.0. last_coupon <
# next_coupon is already guaranteed above, so that can never mean a
# true zero-length period -- checking settlement's own position against
# the coupon dates keeps the endpoints correct regardless.
if settlement == last_coupon:
return 0.0
if settlement == next_coupon:
return face * coupon_rate / freq
period = year_fraction(last_coupon, next_coupon, day_count)
if period == 0.0:
return 0.0
elapsed = year_fraction(last_coupon, settlement, day_count)
return face * coupon_rate / freq * (elapsed / period)
def bond_cashflows(
face: float,
coupon_rate: float,
n_periods: int,
freq: int = 1,
) -> tuple[np.ndarray, np.ndarray]:
"""Coupon schedule of a bullet bond, in periods and amounts.
Args:
face: Redemption amount paid with the final coupon.
coupon_rate: Annual coupon rate as a decimal.
n_periods: Number of remaining coupon periods.
freq: Coupon payments per year.
Returns:
Tuple ``(periods, amounts)`` where ``periods`` is ``1..n_periods`` as
floats and ``amounts`` is the cash paid at each. Time in years is
``periods / freq``.
Raises:
ValueError: If any numeric input is non-finite, if ``face`` is not
positive, if ``n_periods`` is not a positive integer, or if
``freq`` is not positive.
"""
# freq too: with an infinite frequency every coupon collapses to zero and
# the schedule reprices to a plausible-looking par.
_require_finite(face=face, coupon_rate=coupon_rate, freq=freq)
if face <= 0:
raise ValueError(f"face must be positive, got {face}")
if isinstance(n_periods, bool) or not isinstance(n_periods, (int, np.integer)) or n_periods <= 0:
raise ValueError(f"n_periods must be a positive integer, got {n_periods!r}")
if freq <= 0:
raise ValueError(f"freq must be positive, got {freq}")
periods = np.arange(1, n_periods + 1, dtype=float)
amounts = np.full(n_periods, face * coupon_rate / freq, dtype=float)
amounts[-1] += face
return periods, amounts
def _discount_factors(
ytm: float,
periods: np.ndarray,
freq: int,
compounding: str,
) -> np.ndarray:
"""Compute discount factors for period indices under discrete or continuous compounding."""
_require_finite(ytm=ytm)
if compounding == "discrete":
periodic = 1.0 + ytm / freq
if periodic <= 0.0:
raise ValueError(
f"discrete compounding needs 1 + ytm/freq > 0, got {periodic}"
)
return periodic ** (-periods)
if compounding == "continuous":
return np.exp(-ytm * periods / freq)
raise ValueError(
f"unknown compounding {compounding!r}; expected one of {COMPOUNDING_CONVENTIONS}"
)
def bond_price(
face: float,
coupon_rate: float,
ytm: float,
n_periods: int,
freq: int = 1,
compounding: str = DEFAULT_COMPOUNDING,
) -> float:
"""Present value of a bullet bond settling on a coupon date.
The result is a *clean* price: settlement is assumed to sit on a coupon date
so no interest has accrued. Add :func:`accrued_interest` for a dirty price.
Args:
face: Par/redemption amount, conventionally 100.
coupon_rate: Annual coupon rate as a decimal (0.05 == 5%).
ytm: Annual yield to maturity as a decimal.
n_periods: Number of remaining coupon periods.
freq: Coupon payments per year (1 = annual, 2 = semi-annual).
compounding: One of :data:`COMPOUNDING_CONVENTIONS`.
Returns:
Present value in the same units as ``face``.
Raises:
ValueError: If the schedule arguments or ``compounding`` are invalid.
"""
periods, amounts = bond_cashflows(face, coupon_rate, n_periods, freq)
return float(amounts @ _discount_factors(ytm, periods, freq, compounding))
def ytm_solve(
price: float,
face: float,
coupon_rate: float,
n_periods: int,
freq: int = 1,
compounding: str = DEFAULT_COMPOUNDING,
bracket: tuple[float, float] = (-0.5, 10.0),
) -> float:
"""Invert :func:`bond_price` for the yield that reproduces a market price.
Args:
price: Observed price, on the same clean basis as :func:`bond_price`.
face: Par/redemption amount.
coupon_rate: Annual coupon rate as a decimal.
n_periods: Number of remaining coupon periods.
freq: Coupon payments per year.
compounding: One of :data:`COMPOUNDING_CONVENTIONS`.
bracket: ``(low, high)`` annual yield search interval as decimals.
Returns:
Annual yield to maturity as a decimal.
Raises:
ValueError: If ``price`` or a bracket bound is non-finite, or if the
price is not reachable inside ``bracket``.
"""
low, high = bracket
# NaN fails ``low >= high`` and every solver evaluation; name the input
# instead of reporting a bracket that "cannot reprice" it.
_require_finite(price=price, bracket_low=low, bracket_high=high)
if low >= high:
raise ValueError(f"bracket must be increasing, got {bracket}")
def pv_diff(y: float) -> float:
return bond_price(face, coupon_rate, y, n_periods, freq, compounding) - price
try:
return float(brentq(pv_diff, low, high))
except ValueError as exc:
raise ValueError(
f"no yield in {bracket} reprices this bond to {price}: {exc}"
) from exc
def macaulay_duration(
face: float,
coupon_rate: float,
ytm: float,
n_periods: int,
freq: int = 1,
compounding: str = DEFAULT_COMPOUNDING,
) -> float:
"""Present-value-weighted average time to the bond's cash flows.
Args:
face: Par/redemption amount.
coupon_rate: Annual coupon rate as a decimal.
ytm: Annual yield to maturity as a decimal.
n_periods: Number of remaining coupon periods.
freq: Coupon payments per year.
compounding: One of :data:`COMPOUNDING_CONVENTIONS`.
Returns:
Macaulay duration in **years**.
Raises:
ValueError: If the schedule arguments or ``compounding`` are invalid.
"""
periods, amounts = bond_cashflows(face, coupon_rate, n_periods, freq)
pv = amounts * _discount_factors(ytm, periods, freq, compounding)
return float((periods / freq) @ pv / pv.sum())
def modified_duration(
face: float,
coupon_rate: float,
ytm: float,
n_periods: int,
freq: int = 1,
compounding: str = DEFAULT_COMPOUNDING,
) -> float:
"""Semi-elasticity of price to yield, ``-(dP/dy)/P``.
Args:
face: Par/redemption amount.
coupon_rate: Annual coupon rate as a decimal.
ytm: Annual yield to maturity as a decimal.
n_periods: Number of remaining coupon periods.
freq: Coupon payments per year.
compounding: One of :data:`COMPOUNDING_CONVENTIONS`. Under continuous
compounding modified duration equals Macaulay duration.
Returns:
Modified duration in years, positive for a conventional bond.
Raises:
ValueError: If the schedule arguments or ``compounding`` are invalid.
"""
d_mac = macaulay_duration(face, coupon_rate, ytm, n_periods, freq, compounding)
if compounding == "continuous":
return d_mac
return d_mac / (1.0 + ytm / freq)
def key_rate_duration(
face: float,
coupon_rate: float,
ytm: float,
n_periods: int,
freq: int = 1,
key_rates: Sequence[float] = DEFAULT_KEY_RATE_TENORS,
compounding: str = DEFAULT_COMPOUNDING,
) -> dict[float, float]:
"""Decompose bond yield sensitivity into Key Rate Durations (KRD) across benchmark tenors.
Distributes cash flow sensitivities to adjacent key rates with triangular kernels.
Sum of key rate durations equals modified duration.
Args:
face: Par/redemption amount.
coupon_rate: Annual coupon rate as a decimal.
ytm: Annual yield to maturity as a decimal.
n_periods: Number of remaining coupon periods.
freq: Coupon payments per year.
key_rates: Sequence of key rate tenors in years (strictly increasing).
compounding: One of :data:`COMPOUNDING_CONVENTIONS`.
Returns:
Dict mapping each key rate tenor (float) to its Key Rate Duration (float in years).
Raises:
ValueError: If key_rates is empty, non-finite or not strictly
increasing, or schedule/compounding invalid.
"""
kr = np.asarray(key_rates, dtype=float)
if kr.size == 0:
raise ValueError("key_rates must contain at least one tenor")
# A NaN tenor is neither empty nor non-increasing, so it sailed past both
# checks and came back as a NaN key in the result dict.
_require_finite(key_rates=kr)
if (np.diff(kr) <= 0.0).any():
raise ValueError(f"key_rates must be strictly increasing, got {key_rates}")
periods, amounts = bond_cashflows(face, coupon_rate, n_periods, freq)
pv = amounts * _discount_factors(ytm, periods, freq, compounding)
price = float(pv.sum())
if price <= 0.0:
raise ValueError("bond price must be positive for key rate duration")
cf_times = periods / freq
# Modified discount factor weight per cash flow
if compounding == "continuous":
time_weights = cf_times
else:
time_weights = cf_times / (1.0 + ytm / freq)
cf_durations = time_weights * pv / price # Sums to modified duration
krd_result: dict[float, float] = {float(t): 0.0 for t in kr}
for t_cf, dur_cf in zip(cf_times, cf_durations):
if t_cf <= kr[0]:
krd_result[float(kr[0])] += float(dur_cf)
elif t_cf >= kr[-1]:
krd_result[float(kr[-1])] += float(dur_cf)
else:
# Find interval kr[k] <= t_cf <= kr[k+1]
idx = int(np.searchsorted(kr, t_cf))
t_left = kr[idx - 1]
t_right = kr[idx]
w_right = (t_cf - t_left) / (t_right - t_left)
w_left = 1.0 - w_right
krd_result[float(t_left)] += float(dur_cf * w_left)
krd_result[float(t_right)] += float(dur_cf * w_right)
return krd_result
def convexity(
face: float,
coupon_rate: float,
ytm: float,
n_periods: int,
freq: int = 1,
compounding: str = DEFAULT_COMPOUNDING,
) -> float:
"""Second-order price sensitivity to yield, ``(d2P/dy2)/P``.
Args:
face: Par/redemption amount.
coupon_rate: Annual coupon rate as a decimal.
ytm: Annual yield to maturity as a decimal.
n_periods: Number of remaining coupon periods.
freq: Coupon payments per year.
compounding: One of :data:`COMPOUNDING_CONVENTIONS`.
Returns:
Convexity in years squared. Positive for any bond without embedded
short optionality.
Raises:
ValueError: If the schedule arguments or ``compounding`` are invalid.
"""
periods, amounts = bond_cashflows(face, coupon_rate, n_periods, freq)
discounts = _discount_factors(ytm, periods, freq, compounding)
pv = amounts * discounts
price = pv.sum()
if compounding == "continuous":
return float(((periods / freq) ** 2) @ pv / price)
weights = periods * (periods + 1.0) / (freq**2)
return float(weights @ pv / price / (1.0 + ytm / freq) ** 2)
def dv01(
face: float,
coupon_rate: float,
ytm: float,
n_periods: int,
freq: int = 1,
par_amount: float = 1_000_000.0,
compounding: str = DEFAULT_COMPOUNDING,
) -> float:
"""Cash value of one basis point on a stated par position.
Args:
face: Par/redemption amount the quoted price is per, conventionally 100.
coupon_rate: Annual coupon rate as a decimal.
ytm: Annual yield to maturity as a decimal.
n_periods: Number of remaining coupon periods.
freq: Coupon payments per year.
par_amount: Par value held. The market value hedged is
``par_amount * price / face``.
compounding: One of :data:`COMPOUNDING_CONVENTIONS`.
Returns:
Price change, in currency units, for a 1bp rise in yield, reported as a
positive number.
Raises:
ValueError: If ``face`` is zero, if ``par_amount`` is non-finite, or
the schedule/compounding is invalid.
"""
if face == 0:
raise ValueError("face must be non-zero")
# face itself is admitted by the schedule checks downstream; par_amount
# never reaches them, so a NaN position size would scale into a NaN hedge.
_require_finite(par_amount=par_amount)
d_mod = modified_duration(face, coupon_rate, ytm, n_periods, freq, compounding)
price = bond_price(face, coupon_rate, ytm, n_periods, freq, compounding)
return d_mod * (price / face) * 1e-4 * par_amount
def effective_duration(
reprice: Callable[[float], float],
yield_level: float,
bump: float = 1e-4,
) -> float:
"""Duration by symmetric repricing, valid for bonds with embedded options.
Re-evaluates a custom pricing model at perturbed yields to compute duration.
Args:
reprice: Callable mapping a yield level to a price. It must contain the
option/prepayment logic; nothing here inspects it.
yield_level: Base yield to bump around.
bump: Half-width of the symmetric shock, as a decimal (1e-4 = 1bp).
Returns:
Effective duration in years, ``(P_down - P_up) / (2 * P_0 * bump)``.
Raises:
ValueError: If ``bump`` is not positive or the base price is zero.
"""
_require_finite(yield_level=yield_level, bump=bump)
if bump <= 0:
raise ValueError(f"bump must be positive, got {bump}")
base = reprice(yield_level)
if base == 0:
raise ValueError("base price is zero; effective duration is undefined")
down = reprice(yield_level - bump)
up = reprice(yield_level + bump)
return (down - up) / (2.0 * base * bump)
def _decay_factors(tau: np.ndarray, lam: float) -> tuple[np.ndarray, np.ndarray]:
"""Compute Nelson-Siegel slope and curvature loadings for decay parameter lam."""
_require_finite(decay=lam)
if lam <= 0:
raise ValueError(f"decay parameter must be positive, got {lam}")
x = tau / lam
safe = np.where(x > 0, x, 1.0)
slope = np.where(x > 0, (1.0 - np.exp(-safe)) / safe, 1.0)
return slope, slope - np.exp(-x)
def _as_tau(tau: float | Sequence[float] | np.ndarray) -> tuple[np.ndarray, bool]:
"""Normalise scalar or sequence maturity argument to a 1-D float array."""
arr = np.asarray(tau, dtype=float)
was_scalar = arr.ndim == 0
arr = np.atleast_1d(arr)
_require_finite(maturities=arr)
if np.any(arr < 0):
raise ValueError("maturities must be non-negative")
return arr, was_scalar
def nelson_siegel(
tau: float | Sequence[float] | np.ndarray,
beta0: float,
beta1: float,
beta2: float,
lambda1: float,
) -> float | np.ndarray:
"""Compute Nelson-Siegel zero rates for given maturities and parameters."""
_require_finite(beta0=beta0, beta1=beta1, beta2=beta2)
arr, was_scalar = _as_tau(tau)
slope, curve = _decay_factors(arr, lambda1)
out = beta0 + beta1 * slope + beta2 * curve
return float(out[0]) if was_scalar else out
def svensson(
tau: float | Sequence[float] | np.ndarray,
beta0: float,
beta1: float,
beta2: float,
beta3: float,
lambda1: float,
lambda2: float,
) -> float | np.ndarray:
"""Compute Svensson zero rates for given maturities and parameters."""
_require_finite(beta0=beta0, beta1=beta1, beta2=beta2, beta3=beta3)
arr, was_scalar = _as_tau(tau)
slope, curve1 = _decay_factors(arr, lambda1)
_, curve2 = _decay_factors(arr, lambda2)
out = beta0 + beta1 * slope + beta2 * curve1 + beta3 * curve2
return float(out[0]) if was_scalar else out
#: Search range, in years, for the Nelson-Siegel/Svensson decay parameters.
CURVE_DECAY_BOUNDS: tuple[float, float] = (0.05, 30.0)
#: Number of grid points per decay parameter used to seed the curve fit.
CURVE_DECAY_GRID: int = 48
@dataclass(frozen=True)
class CurveFit:
"""Result of :func:`fit_yield_curve`; call it to evaluate the fitted curve.
Attributes:
model: ``"nelson_siegel"`` or ``"svensson"``.
params: Fitted parameters. Nelson-Siegel is
``(beta0, beta1, beta2, lambda1)``; Svensson is
``(beta0, beta1, beta2, beta3, lambda1, lambda2)``.
rmse: Root-mean-square fitting error against input yields.
"""
model: str
params: tuple[float, ...]
rmse: float = math.nan
def __call__(
self, tau: float | Sequence[float] | np.ndarray
) -> float | np.ndarray:
"""Evaluate the fitted curve at one or more maturities.
Args:
tau: Maturity or maturities in years.
Returns:
Zero rate(s) as decimals.
Raises:
ValueError: If the stored model name is not recognised.
"""
if self.model == "nelson_siegel":
return nelson_siegel(tau, *self.params)
if self.model == "svensson":
return svensson(tau, *self.params)
raise ValueError(f"unknown curve model {self.model!r}")
def _curve_design(tau: np.ndarray, lambdas: Sequence[float]) -> np.ndarray:
"""Linear design matrix for a curve model with fixed decay parameters.
Args:
tau: Maturities in years.
lambdas: One decay parameter for Nelson-Siegel, two for Svensson.
Returns:
Matrix whose columns are the level, slope and curvature loadings.
Raises:
ValueError: If a decay parameter is not positive.
"""
slope, curve1 = _decay_factors(tau, lambdas[0])
columns = [np.ones_like(tau), slope, curve1]
for lam in lambdas[1:]:
columns.append(_decay_factors(tau, lam)[1])
return np.column_stack(columns)
def _profiled_ssr(
lambdas: Sequence[float], tau: np.ndarray, yields: np.ndarray
) -> tuple[float, np.ndarray]:
"""Best achievable squared error for fixed decay parameters.
Beta coefficients are solved via OLS; decay parameters are searched non-linearly.
Args:
lambdas: Decay parameters to condition on.
tau: Maturities in years.
yields: Observed zero rates aligned with ``tau``.
Returns:
Tuple ``(sum_of_squared_residuals, betas)``. The SSR is ``inf`` when the
decay parameters are outside the admissible range.
"""
if any(lam <= 0 for lam in lambdas):
return float("inf"), np.zeros(len(lambdas) + 2)
design = _curve_design(tau, lambdas)
betas, *_ = np.linalg.lstsq(design, yields, rcond=None)
residual = design @ betas - yields
return float(residual @ residual), betas
def fit_yield_curve(
maturities: Sequence[float] | np.ndarray,
yields: Sequence[float] | np.ndarray,
model: str = "svensson",
decay_bounds: tuple[float, float] = CURVE_DECAY_BOUNDS,
grid_points: int = CURVE_DECAY_GRID,
) -> CurveFit:
"""Fit a Nelson-Siegel or Svensson curve to observed zero rates.
Beta coefficients are solved via OLS; decay parameters are searched over
a geometric grid followed by Nelder-Mead simplex refinement.
Args:
maturities: Maturities in years, strictly positive.
yields: Zero rates as decimals, aligned with ``maturities``.
model: ``"nelson_siegel"`` or ``"svensson"``.
decay_bounds: ``(low, high)`` search range in years for each decay
parameter.
grid_points: Grid resolution per decay parameter for the coarse pass.
Returns:
A :class:`CurveFit`, callable at arbitrary maturities.
Raises:
ValueError: If ``model`` is unknown, the inputs disagree in length, or
there are fewer observations than free parameters.
"""
if model not in ("nelson_siegel", "svensson"):
raise ValueError(
f"unknown model {model!r}; expected 'nelson_siegel' or 'svensson'"
)
tau = np.asarray(maturities, dtype=float)
obs = np.asarray(yields, dtype=float)
if tau.shape != obs.shape or tau.ndim != 1:
raise ValueError("maturities and yields must be 1-D and the same length")
if not np.isfinite(tau).all() or not np.isfinite(obs).all():
raise ValueError("maturities and yields must contain only finite values")
if np.any(tau <= 0):
raise ValueError("maturities must be strictly positive")
n_decay = 1 if model == "nelson_siegel" else 2
n_params = n_decay + 2 + n_decay # betas + decay parameters
if tau.size < n_params:
raise ValueError(
f"{model} has {n_params} parameters but only {tau.size} observations"
)
low, high = decay_bounds
if not np.isfinite(low) or not np.isfinite(high):
raise ValueError("decay_bounds must contain only finite values")
if not 0 < low < high:
raise ValueError(f"decay_bounds must satisfy 0 < low < high, got {decay_bounds}")
grid = np.geomspace(low, high, grid_points)
best_ssr = float("inf")
best_lambdas: tuple[float, ...] = (grid[0],) * n_decay
if n_decay == 1:
candidates = [(lam,) for lam in grid]
else:
# lambda1 == lambda2 makes the two curvature columns identical, so the
# second hump carries no information; keep the pairs separated.
candidates = [
(short, long) for short in grid for long in grid if long > short * 1.05
]
for lambdas in candidates:
ssr, _ = _profiled_ssr(lambdas, tau, obs)
if ssr < best_ssr:
best_ssr, best_lambdas = ssr, lambdas
refined = minimize(
lambda p: _profiled_ssr(np.exp(p), tau, obs)[0],
np.log(best_lambdas),
method="Nelder-Mead",
bounds=[(math.log(low), math.log(high))] * n_decay,
options={"xatol": 1e-10, "fatol": 1e-18, "maxiter": 4000},
)
refined_lambdas = tuple(float(v) for v in np.exp(refined.x))
refined_ssr, refined_betas = _profiled_ssr(refined_lambdas, tau, obs)
if refined_ssr < best_ssr:
best_ssr, best_lambdas = refined_ssr, refined_lambdas
betas = refined_betas
else:
_, betas = _profiled_ssr(best_lambdas, tau, obs)
params = tuple(float(b) for b in betas) + tuple(float(x) for x in best_lambdas)
return CurveFit(
model=model,
params=params,
rmse=float(np.sqrt(max(best_ssr, 0.0) / tau.size)),
)