波动率曲面建模工具 (vol-surface)

基于 SVI (Stochastic Volatility Inspired) 参数化模型的隐含波动率曲面构建工具。
所有市场数据来自 akshare 真实接口 (50ETF / 300ETF 期权 T 型报价)，禁止任何伪造或随机生成数据。

核心能力

能力	模块	说明
期权数据获取	data.py	akshare 接口拉取 50ETF/300ETF 期权 T 型报价、标的现价、合约信息
隐含波动率反推	implied_vol.py	Black-Scholes 公式 + Newton-Raphson 迭代 (Brent 备选)
SVI 参数化	svi.py	五参数 SVI 模型, 单切片拟合 + 多切片曲面
曲面校准	calibration.py	端到端校准流程, 时间维度方差线性插值
无套利校验	arbitrage.py	日历套利 + 蝶式套利 + SVI 参数约束
3D 可视化	report.py	matplotlib 3D 曲面 + 自包含 HTML 报告

SVI 模型

对 log-moneyness k = ln(K/F)，总方差：

w(k) = a + b * [ rho*(k-m) + sqrt((k-m)^2 + sigma^2) ]

• a 整体方差水平
• b 倾斜幅度
• rho 倾斜方向 [-1, 1]
• m 中心偏移
• sigma 曲度 (>0)

安装与使用

pip install -r requirements.txt

# 默认: 50ETF 期权
python surface.py --underlying 510050

# 300ETF 期权
python surface.py --underlying 510300

# 指定到期日 + 利率 + IV 方法
python surface.py -u 510050 -e 2024-01-24,2024-02-28 -r 0.02 --iv-method brent

输出写入 output/ 目录：

• surface_3d.png / smiles.png / residuals.png / butterfly_g.png
• vol_surface_report_*.html 自包含 HTML 报告 (图片 base64 嵌入)
• calibration.json 校准结果 (含套利检验明细)

输出示例

控制台输出：

┌ Vol-Surface SVI ──────────────────────────────┐
│ 标的: 510050  利率: 2.50%  IV方法: newton      │
│ 微笑策略: otm  输出目录: output                │
└───────────────────────────────────────────────┘

SVI 拟合结果
┏━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━┳━━━━━━━━┳━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━┳━━━┓
┃ 到期日     ┃ T(年)  ┃ a       ┃ b      ┃ rho    ┃ m       ┃ sigma   ┃ RMSE    ┃ max_err ┃ N ┃
┡━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━╇━━━━━━━━╇━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━╇━━━┩
│ 2024-01-24 │ 0.0521 │ 0.00421 │ 0.1423 │-0.3210 │ 0.0123  │ 0.0821  │1.2e-04  │4.5e-04  │ 18│
│ 2024-02-28 │ 0.1507 │ 0.00583 │ 0.1654 │-0.2987 │ 0.0098  │ 0.0912  │2.1e-04  │7.2e-04  │ 22│
└────────────┴────────┴─────────┴────────┴────────┴─────────┴─────────┴─────────┴─────────┴───┘

无套利约束校验...
蝶式套利: 通过 (违反切片 0)    日历套利: 通过 (违反 0)    参数约束: 通过 (违反 0)

能力边界

能做：

• 50ETF / 300ETF / 159919 等 ETF 期权 (上交所 / 深交所) 的 IV 曲面构建
• 单日 (snapshot) 隐含波动率曲面的 SVI 参数化拟合
• 静态无套利约束 (日历 / 蝶式) 检验
• 3D 可视化与 HTML 报告

不能做：

• 美式期权 / 期货期权 / 个股期权 (仅支持欧式 ETF 期权)
• 动态波动率曲面 (时序预测、Heston 等动态模型)
• 高频 tick 级曲面 (依赖 akshare 日内快照频率)
• 实时交易信号 / 自动下单
• 标的股息率动态建模 (默认 q=0, 适合 ETF)
• 复杂局部波动率 Dupire 反演 (仅做辅助诊断)

FAQ

Q1: 报错 "未安装 akshare" 或 akshare 接口调用失败？
A: 执行 pip install -r requirements.txt。akshare 接口偶尔受东财数据源限流影响，建议稍后重试或更换网络环境。如 option_finance_board 接口名变化，可调整 UNDERLYING_REGISTRY 中的 board_symbols 候选列表。

Q2: Newton-Raphson 隐含波动率反推不收敛？
A: 代码已内置多重保护：(1) vega 过小时自动回退 Brent 方法；(2) 单步阻尼 0.5；(3) 价格低于内在价值时跳过；(4) 波动率边界 [1e-4, 5.0]。若仍失败，使用 --iv-method brent 切换为 Brent 方法。

Q3: SVI 拟合 RMSE 偏大怎么办？
A: (1) 检查样本数是否足够 (N >= 5)；(2) 尝试 --smile-prefer otm (默认, 价外期权流动性更好)；(3) 使用买卖中间价 (默认) 而非最新价；(4) 排除深度价外/价内异常合约。

Q4: 蝶式套利检验失败说明什么？
A: 表示某到期日切片存在负的隐含风险中性密度，存在静态套利机会。常见原因：SVI 参数越界 (b*(1+rho) 过大)、sigma 过小、样本噪声大。可调整 SVI 边界约束或剔除异常样本后重新拟合。

Q5: 日历套利检验失败说明什么？
A: 表示同一 log-moneyness 上远月总方差小于近月，存在日历价差套利。原因：相邻到期日 SVI 拟合独立进行未做联合约束。生产环境应使用 SSVI / Surface SVI 等联合校准方法，本工具采用线性插值方差作为简化方案。

Q6: 无风险利率应如何设置？
A: 默认 2.5% (近似 1 年期国债)。实际应使用 Shibor 或国债收益率曲线对应期限利率。通过 --rate 参数指定，如 --rate 0.022。

Q7: 是否支持个股期权？
A: 当前 UNDERLYING_REGISTRY 仅预置 50ETF/300ETF/159919。个股期权可参照注册表格式扩展，但需注意 akshare 个股期权接口名称差异。