tf-quant-finance 实战:基于欧式 Swaption 价格校准多因子 HJM 模型(calibration_from_swaptions 全解)
tf-quant-finance 实战:基于欧式 Swaption 价格校准多因子 HJM 模型(calibration_from_swaptions 全解)
本篇技术指南以 tf-quant-finance 的 tff.models.hjm.calibration_from_swaptions 函数为核心,系统讲解如何利用一组欧式 Swaption(European Swaption)价格,通过最小二乘优化校准多因子 HJM(Heath-Jarrow-Morton)利率模型中的均值回归速率(mean-reversion)、波动率(volatility)与因子间相关系数(correlation)。读完本文,你将掌握该函数的完整参数语义、两因子模型的端到端校准实操、底层校准流程与边界约束实现,并了解如何用校准结果在 swaption_pricing.py 中回定价验证。
函数定位:用市场 Swaption 价格反解 HJM 模型参数
在利率衍生品定价中,HJM 模型直接刻画瞬时远期利率 f(t, T) 的动力学。tf-quant-finance 的 QuasiGaussianHJM 实现了带马尔可夫化(Markovian)形式的多因子 HJM 模型,其漂移项由风险中性测度下的 HJM 无套利条件唯一确定,模型中需要从市场校准的参数主要是均值回归速率 k、瞬时波动率 sigma(t) 以及各因子 Brownian 运动之间的相关系数矩阵 Rho。
calibration_from_swaptions 正是为此设计的批量校准入口:它接收一批欧式 Swaption 的市场价格作为目标值,利用最小二乘优化,最小化"目标价格(或隐含波动率)"与"模型隐含价格(或隐含波动率)"之间的平方误差,从而估计模型参数。当前实现支持常数的均值回归、波动率与相关系数。函数定义于 calibration.py,并随 hjm/init.py 一并导出,即 tff.models.hjm.calibration_from_swaptions 与 tff.models.hjm.CalibrationResult。
函数完整签名如下(均为关键字参数):
tf_quant_finance.models.hjm.calibration_from_swaptions(
*, prices, expiries, floating_leg_start_times, floating_leg_end_times,
fixed_leg_payment_times, floating_leg_daycount_fractions,
fixed_leg_daycount_fractions, fixed_leg_coupon, reference_rate_fn,
num_hjm_factors, mean_reversion, volatility, notional=None,
is_payer_swaption=None, swaption_valuation_method=None, num_samples=1,
random_type=None, seed=None, skip=0, times=None, time_step=None,
num_time_steps=None, curve_times=None, time_step_finite_difference=None,
num_grid_points_finite_difference=101, volatility_based_calibration=True,
calibrate_correlation=True, optimizer_fn=None, mean_reversion_lower_bound=0.001,
mean_reversion_upper_bound=0.5, volatility_lower_bound=1e-05,
volatility_upper_bound=0.1, tolerance=1e-06, maximum_iterations=50, dtype=None,
name=None
)
快速上手:两因子 HJM 模型校准完整示例
以下示例(与官方文档一致)展示如何用 14 个欧式 Swaption 价格校准一个常数均值回归、常数波动率的两因子 HJM 模型。示例同时出现在 calibration.py 的 docstring 与 calibration_test.py 的测试中,可直接运行复现。
import numpy as np
import tensorflow.compat.v2 as tf
import tf_quant_finance as tff
dtype = tf.float64
# 14 个 Swaption 的到期时间
expiries = np.array(
[0.5, 0.5, 1.0, 1.0, 2.0, 2.0, 3.0, 3.0, 4.0, 4.0, 5.0, 5.0, 10., 10.])
float_leg_start_times = np.array([
[0.5, 1.0, 1.5, 2.0, 2.5, 2.5, 2.5, 2.5, 2.5, 2.5], # 6M x 2Y swap
[0.5, 1.0, 1.5, 2.0, 2.5, 3.0, 3.5, 4.0, 4.5, 5.0], # 6M x 5Y swap
[1.0, 1.5, 2.0, 2.5, 3.0, 3.0, 3.0, 3.0, 3.0, 3.0], # 1Y x 2Y swap
[1.0, 1.5, 2.0, 2.5, 3.0, 3.5, 4.0, 4.5, 5.0, 5.5], # 1Y x 5Y swap
[2.0, 2.5, 3.0, 3.5, 4.0, 4.0, 4.0, 4.0, 4.0, 4.0], # 2Y x 2Y swap
[2.0, 2.5, 3.0, 3.5, 4.0, 4.5, 5.0, 5.5, 6.0, 6.5], # 2Y x 5Y swap
[3.0, 3.5, 4.0, 4.5, 5.0, 5.0, 5.0, 5.0, 5.0, 5.0], # 3Y x 2Y swap
[3.0, 3.5, 4.0, 4.5, 5.0, 5.5, 6.0, 6.5, 7.0, 7.5], # 3Y x 5Y swap
[4.0, 4.5, 5.0, 5.5, 6.0, 6.0, 6.0, 6.0, 6.0, 6.0], # 4Y x 2Y swap
[4.0, 4.5, 5.0, 5.5, 6.0, 6.5, 7.0, 7.5, 8.0, 8.5], # 4Y x 5Y swap
[5.0, 5.5, 6.0, 6.5, 7.0, 7.0, 7.0, 7.0, 7.0, 7.0], # 5Y x 2Y swap
[5.0, 5.5, 6.0, 6.5, 7.0, 7.5, 8.0, 8.5, 9.0, 9.5], # 5Y x 5Y swap
[10.0, 10.5, 11.0, 11.5, 12.0, 12.0, 12.0, 12.0, 12.0,
12.0], # 10Y x 2Y swap
[10.0, 10.5, 11.0, 11.5, 12.0, 12.5, 13.0, 13.5, 14.0,
14.5] # 10Y x 5Y swap
])
float_leg_end_times = float_leg_start_times + 0.5
max_maturities = np.array(
[2.5, 5.5, 3.0, 6.0, 4., 7., 5., 8., 6., 9., 7., 10., 12., 15.])
for i in range(float_leg_end_times.shape[0]):
float_leg_end_times[i] = np.clip(
float_leg_end_times[i], 0.0, max_maturities[i])
fixed_leg_payment_times = float_leg_end_times
float_leg_daycount_fractions = (
float_leg_end_times - float_leg_start_times)
fixed_leg_daycount_fractions = float_leg_daycount_fractions
fixed_leg_coupon = 0.01 * np.ones_like(fixed_leg_payment_times)
# 恒定零利率曲线(连续复利零息利率)
zero_rate_fn = lambda x: 0.01 * tf.ones_like(x, dtype=dtype)
notional = 1.0
# 14 个 Swaption 的市场价格(名义本金 1.0 下的价格)
prices = np.array([
0.42919881, 0.98046542, 0.59045074, 1.34909391, 0.79491583,
1.81768802, 0.93210461, 2.13625342, 1.05114573, 2.40921088,
1.12941064, 2.58857507, 1.37029637, 3.15081683])
(calibrated_mr, calibrated_vol, calibrated_corr), _, _ = (
tff.models.hjm.calibration_from_swaptions(
prices=prices,
expiries=expiries,
floating_leg_start_times=float_leg_start_times,
floating_leg_end_times=float_leg_end_times,
fixed_leg_payment_times=fixed_leg_payment_times,
floating_leg_daycount_fractions=float_leg_daycount_fractions,
fixed_leg_daycount_fractions=fixed_leg_daycount_fractions,
fixed_leg_coupon=fixed_leg_coupon,
reference_rate_fn=zero_rate_fn,
notional=100.,
mean_reversion=[0.01, 0.01], # Initial guess for mean reversion rate
volatility=[0.005, 0.004], # Initial guess for volatility
volatility_based_calibration=True,
calibrate_correlation=True,
num_samples=2000,
time_step=0.1,
random_type=random.RandomType.STATELESS_ANTITHETIC,
seed=[0,0],
maximum_iterations=50,
dtype=dtype))
# Expected calibrated_mr: [0.00621303, 0.3601772]
# Expected calibrated_vol: [0.00586125, 0.00384013]
# Expected correlation: 0.65126492
# Prices using calibrated model: [
0.42939121, 0.95362327, 0.59186236, 1.32622752, 0.79575526,
1.80457544, 0.93909176, 2.14336776, 1.04132595, 2.39385229,
1.11770416, 2.58809336, 1.39557389, 3.29306317]
示例中的 14 个 Swaption 覆盖了 6M x 2Y、6M x 5Y、1Y x 2Y、1Y x 5Y、2Y x 2Y、2Y x 5Y、3Y x 2Y、3Y x 5Y、4Y x 2Y、4Y x 5Y、5Y x 2Y、5Y x 5Y、10Y x 2Y、10Y x 5Y 等期限组合("X x Y" 表示 Swaption 在 X 年后到期、标的互换期限为 Y 年),浮息腿为每半年付息一次(0.5 间隔),并用 max_maturities 对 float_leg_end_times 做了截断以保持腿期限一致。
校准完成后,可以用 swaption_pricing.py 中的 tff.models.hjm.swaption_price 按相同参数回定价,与原始市场价格对比验证拟合效果——calibration_test.py 中的测试正是以 assertAllClose(prices, self.prices, rtol=0.1, atol=0.1) 的方式完成闭环验证。
参数详解:从市场数据到优化控制
市场数据输入(标的互换结构)
| 参数 | 类型 / 形状 | 说明 |
|---|---|---|
prices |
N-D 实数 Tensor,形状 batch_shape + [k] |
用于校准的 Swaption 市场价格。batch_shape 是待校准模型的批次形状,k 是每个模型对应的 Swaption 数量。 |
expiries |
与 prices 同形状同 dtype |
各 Swaption 的到期时间(距现在的年数)。 |
floating_leg_start_times |
与 prices 同 dtype,形状 expiries.shape + [m] |
浮息腿每笔付款的计息起始时间;m 为每条腿的浮动付款笔数。 |
floating_leg_end_times |
与 prices 同 dtype,形状 expiries.shape + [m] |
浮息腿每笔付款的计息结束时间。 |
fixed_leg_payment_times |
与 prices 同 dtype,形状 expiries.shape + [n] |
固息腿每笔付款的支付时间;n 为固定付款笔数。 |
floating_leg_daycount_fractions |
与 floating_leg_start_times 同 dtype、形状兼容 |
浮息腿每笔付款的计息天数因子(daycount fractions)。 |
fixed_leg_daycount_fractions |
与 fixed_leg_payment_times 同 dtype、形状兼容 |
固息腿每笔付款的计息天数因子。 |
fixed_leg_coupon |
与 fixed_leg_payment_times 同 dtype、形状兼容 |
固息腿每笔付款的固定利率(即互换的固定票息)。 |
notional |
可选 Tensor,与 prices 同 dtype、形状兼容 |
标的互换的名义本金。默认 None,此时名义本金取 1。 |
is_payer_swaption |
布尔 Tensor,形状与 expiries 兼容 |
True 表示 payer swaption(支付固定、收取浮动),False 表示 receiver swaption(收取固定、支付浮动)。不提供时默认按 payer swaption 处理。 |
模型结构与估值方法
| 参数 | 类型 / 默认值 | 说明 |
|---|---|---|
reference_rate_fn |
Python callable | 接受到期时间(实数 Tensor)并返回同形状 Tensor,表示当前时点对应到期期限的连续复利零息利率(zero rate)。它是校准与定价共同依赖的初始利率曲线。 |
num_hjm_factors |
Python 标量 | 待校准 HJM 模型的因子个数。 |
mean_reversion |
正实数 Tensor,形状 batch_shape + [num_hjm_factors] |
各因子均值回归速率的初始猜测值(用于优化起点)。 |
volatility |
正实数 Tensor,与 mean_reversion 同 dtype 同形状 |
各因子瞬时波动率的初始猜测值。 |
swaption_valuation_method |
valuation_method.ValuationMethod 枚举 |
校准过程中 Swaption 的估值方式,支持 MONTE_CARLO 与 FINITE_DIFFERENCE。有限差分估值仅支持 Gaussian HJM 模型(常数均值回归、时变波动率)。默认 ValuationMethod.MONTE_CARLO。该枚举定义于 valuation_method.py。 |
num_samples |
正 int32 Tensor |
Monte Carlo 估值的模拟路径数,解析估值时忽略。默认 1。 |
random_type |
RandomType 枚举 |
模拟路径使用的(准)随机数生成器类型,仅对 Monte Carlo 估值相关。默认 None(标准伪随机数)。 |
seed |
int 或形状 [2] 的整数 Tensor |
随机数种子。对 STATELESS、PSEUDO、HALTON_RANDOMIZED、PSEUDO_ANTITHETIC、STATELESS_ANTITHETIC 有效:PSEUDO/PSEUDO_ANTITHETIC/HALTON_RANDOMIZED 用 Python 整数,STATELESS/STATELESS_ANTITHETIC 须为形状 [2] 的整数 Tensor。默认 None。 |
skip |
int32 0-d Tensor |
Sobol 或 Halton 序列跳过的初始点数,仅当 random_type 为 SOBOL/HALTON/HALTON_RANDOMIZED 时使用。默认 0。 |
时间网格参数
| 参数 | 类型 / 默认值 | 说明 |
|---|---|---|
times |
可选 rank-1 Tensor(递增正实数) |
Monte Carlo 模拟的执行时间点。默认 None,此时按 time_step 或 num_time_steps 自动生成。 |
time_step |
标量实数 Tensor |
Euler 格式时间网格的最大间距。默认 None。 |
num_time_steps |
可选标量整数 Tensor |
Monte Carlo 模拟总时间步数,网格最大间距受 times[-1] / (num_time_steps - times.shape[0]) 约束。使用 Monte Carlo 估值时必须提供 time_step 或 num_time_steps 之一。默认 None。 |
curve_times |
可选 rank-1 Tensor(正实数) |
模拟期间计算即期折现曲线的到期期限。默认 None,此时根据 Swaption 到期时间与 fixed_leg_payment_times 自动计算(见下文源码分析)。 |
time_step_finite_difference |
标量实数 Tensor |
有限差分离散化的时间网格间距,仅对有限差分估值相关。默认 None,此时采用约 100 个离散步对应的时间步。 |
num_grid_points_finite_difference |
标量整数 Tensor |
有限差分的空间网格点数。默认 101(注意 docstring 中写 100,源码默认值为 101)。 |
校准行为控制
| 参数 | 类型 / 默认值 | 说明 |
|---|---|---|
volatility_based_calibration |
Python 布尔 | True 时将 Swaption 价格先转换为 normal 隐含波动率,再最小化输入隐含波动率与模型隐含波动率的误差;False 时直接以价格为优化目标。默认 True。 |
calibrate_correlation |
Python 布尔 | 是否校准 HJM 因子间的相关系数矩阵。False 时假定因子不相关。默认 True。 |
optimizer_fn |
可选 Python callable | 自定义优化算法,接口为 result = optimizer_fn(value_and_gradients_function, initial_position, tolerance, max_iterations)。返回的 namedtuple 须包含:position(最优位置)、converged(是否按准则收敛)、failed(是否失败)、num_iterations(迭代次数)、objective_value(最优目标值)。默认 None,此时使用共轭梯度算法 conjugate_gradient_minimize。 |
mean_reversion_lower_bound / mean_reversion_upper_bound |
标量 Tensor |
均值回归速率的校准边界。默认 0.001 / 0.5。 |
volatility_lower_bound / volatility_upper_bound |
标量 Tensor |
波动率的校准边界。默认 0.00001(0.1 个基点)/ 0.1。 |
tolerance |
实数标量 Tensor |
迭代终止的绝对容差。默认 1e-6。 |
maximum_iterations |
正 int32 Tensor |
优化最大迭代次数。默认 50。 |
dtype |
tf.DType |
数值转换使用的默认 dtype。默认 None(沿用 TensorFlow 推断)。 |
name |
Python 字符串 | 运算名称。默认 None,对应名称 hjm_swaption_calibration。 |
返回值与 CalibrationResult
函数返回一个三元组:
CalibrationResult实例:包含校准后的模型参数。该 dataclass 定义于 calibration.py,三个属性分别为:mean_reversion:rank-1Tensor,校准后的均值回归参数;volatility:rank-1Tensor,校准后的波动率参数;corr_matrix:rank-1Tensor,校准后的相关系数矩阵参数。
- 优化状态
Tensor:每个 batch 元素是否已按指定收敛准则找到最优点(布尔)。 - 迭代次数
Tensor:优化算法实际执行的迭代次数。
调用时通常直接解包:(calibrated_mr, calibrated_vol, calibrated_corr), converged, num_iter = tff.models.hjm.calibration_from_swaptions(...)。
源码级原理:校准内部到底发生了什么
1. 目标值构造:价格转 normal 隐含波动率
当 volatility_based_calibration=True 时,源码通过 calibration.py 中的 _price_to_normal_vol 先把市场价格转为波动率目标:先用 swap.ir_swap_par_rate_and_annuity 计算各 Swaption 标的互换的平价互换利率(par rate)与年金(annuity),再调用 implied_vol.py 的反解函数,并以 UnderlyingDistribution.NORMAL 指定 normal 波动率假设(而非 lognormal),将价格 prices / annuity / notional 反解为隐含波动率,strike 取 fixed_leg_coupon<a href="https://link.gitcode.com/i/59e926da5ae0b5e4abfd4187a00d8275" target="_blank">..., 0]。若转换失败,代码会通过 tf.debugging.assert_all_finite 抛出明确错误提示([calibration.py)。
2. 无约束化:把有界参数映射到无约束空间
优化问题要求均值回归与波动率都落在用户给定的边界内。源码采用 logit(sigmoid 反函数)变换实现"约束参数 ↔ 无约束参数"的双向映射(calibration.py):
def _scale(x, lb, ub):
return (x - lb) / (ub - lb)
def _to_unconstrained(x, lb, ub): # 用于构造初始猜测
x = _scale(x, lb, ub)
return -tf.math.log((1.0 - x) / x)
def _to_constrained(x, lb, ub): # 优化结束后还原参数
x = tf.math.exp(x) / (1.0 + tf.math.exp(x))
return x * (ub - lb) + lb
初始猜测 initial_guess 由 mean_reversion、volatility 与(可选)相关矩阵角度拼接而成,并全部转换到无约束空间(calibration.py)。
3. 相关矩阵:Rebonato-Jaeckel 超球面分解
当 calibrate_correlation=True 时,相关系数并非直接作为优化变量,而是通过超球面分解(hypersphere decomposition,即 Rebonato-Jaeckel 方法)构造:优化变量是 num_hjm_factors * (num_hjm_factors - 1) 个角度 thetas,经余弦、正弦累积乘积的组合后做 matmul(corr_matrix, corr_matrix, transpose_b=True) 得到合法的相关矩阵(calibration.py)。角度上界 _THETA_UB = 2 * np.pi + 0.01(calibration.py),优化中对角度还施加了 tfp.math.clip_by_value_preserve_gradient(thetas, -25.0, 25.0) 以保证数值稳定(calibration.py)。这保证了优化过程中任何中间点对应的相关矩阵都数学上有效(正定且对角为 1)。
4. 损失函数与估值循环
损失函数(calibration.py)的核心流程为:
- 将无约束变量还原为
mean_reversion、volatility与相关矩阵; - 构造波动率函数
_make_hjm_volatility_fn(当前实现即返回常数波动率,calibration.py); - 调用 swaption_pricing.py 中的
swaption_price计算模型隐含价格——内部根据valuation_method分支:FINITE_DIFFERENCE构建GaussianHJM模型并走_european_swaption_fd,MONTE_CARLO构建QuasiGaussianHJM模型并走_european_swaption_mc(swaption_pricing.py); - 若为波动率校准,再把模型价格同样转换为 normal 隐含波动率(NaN 替换为
1e-7防崩); - 最终损失为"缩放后的模型值 − 缩放后的目标值"的平方和沿最后一维求和,缩放统一到
[0, 1]区间便于优化。
5. 优化与结果还原
默认优化器为 optimizer.conjugate_gradient_minimize(calibration.py,定义于 math/optimizer 模块),也可传入 tfp.optimizer.bfgs_minimize 等满足接口的自定义优化器。优化结束后,把最优位置反变换回约束空间,必要时再次用超球面分解还原相关矩阵,最后组装成 CalibrationResult 并连同 converged、num_iterations 一起返回(calibration.py)。
测试覆盖与批量能力
calibration_test.py 对校准功能提供了多维度验证:
- 参数化用例(
test_calibration):覆盖两因子/三因子模型、价格校准(vol_based_calib=False)与波动率校准(vol_based_calib=True)、默认共轭梯度与tfp.optimizer.bfgs_minimize两种优化器,用time_step=0.25的 Monte Carlo 估值在 10 次迭代内完成校准,并通过swaption_price回定价与原始价格对比(rtol=0.1, atol=0.1)验证; - 批量校准(
test_calibration_batch):通过把输入在首维重复两次构造batch_shape=[2]的模型批次,验证输出calibrated_mr与calibrated_vol形状为[2, 2],并支持calibrate_correlation=False时仅校准均值回归与波动率、相关矩阵传None的用法; - XLA 兼容性:另有 calibration_xla_test.py 验证校准流程可在
tf.function(jit_compile=True)的 XLA 编译环境下运行。
从实现看,prices 的 batch_shape 决定了可同时校准的模型个数,mean_reversion 与 volatility 亦支持 batch_shape + [num_hjm_factors] 的批量初始值,因此该 API 天然支持一次调用校准多个模型(如多个币种/多条曲线场景)。
实践要点总结
- 数据准备:
floating_leg_start_times、floating_leg_end_times、fixed_leg_payment_times需严格按expiries.shape + [m]/expiries.shape + [n]构造;fixed_leg_daycount_fractions应与付款时间对应(示例中直接取时间差,等价于 Act/Act 简化形式)。 - 初始猜测与边界:
mean_reversion、volatility提供优化起点,其上下界(默认[0.001, 0.5]、[1e-5, 0.1])同时约束了搜索空间;若先验更宽可自行调整。 - 估值方法选择:Monte Carlo 需要设置
num_samples与time_step/num_time_steps,并推荐显式指定random_type与seed(如STATELESS_ANTITHETIC)保证可复现;有限差分仅适用于 Gaussian HJM(常数均值回归),且当前不支持批量模型估值,需相应配置time_step_finite_difference与num_grid_points_finite_difference。 - 波动率 vs 价格校准:
volatility_based_calibration=True时目标与模型输出都转换为 normal 隐含波动率,对短端/长端权重的处理更接近市场惯例;改为False则直接拟合价格。 - 结果闭环:务必用
tff.models.hjm.swaption_price以校准参数回定价并与输入价格对比,校验拟合残差是否落在可接受范围内(测试采用 10% 相对容差)。 - 批次扩展:需要同时校准多条曲线时,为所有输入增加一致的 batch 维度即可,输出参数将自动带上
batch_shape。