波动率曲面建模工具 (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 个股期权接口名称差异。
