• 金融科技
• 科学计算

本文是 tf-quant-finance（TFF）实验性定价平台中市场数据模块的技术指南，核心讲解ProcessedMarketData接口的字典实现MarketDataDict：读者将掌握如何用嵌套 Python 字典描述利率曲线、历史 Fixings、波动率曲面/立方体与权益资产价格，理解curve_config/volatility_config中插值方法、Day Count 与营业日约定等配置项的实际语义，并能结合源码与测试用例编写可被定价引擎直接消费的市场数据。

一、背景：ProcessedMarketData 接口与 MarketDataDict 实现

TFF 定价平台中，ProcessedMarketData是定价库消费的"市场数据快照"抽象接口，定义在 processed_market_data.py 中。该对象包含工具定价所需的最小数据集：已校准的利率曲线（calibrated curves）、波动率曲面（volatility surfaces）以及历史 Fixings。接口约定如下能力：

• date/time：市场数据快照的日期与时间；
• yield_curve(curve_type)：按曲线类型返回收益率曲线对象；
• fixings(date, fixing_type)：返回指定日期的历史市场利率 Fixings 及 Day Count 约定；
• spot(currency, asset, date)：资产的即期价格；
• volatility_surface(currency, asset)：资产的波动率曲面对象；
• forward_curve(currency, asset)：资产价格的远期曲线（当前版本为占位实现）；
• supported_currencies/supported_assets/dtype：支持币种、资产与浮点 dtype。

MarketDataDict是上述接口的一种具体实现，位于 market_data_impl.py。用户只需把市场数据组织成嵌套字典传入构造函数即可，无需手动构造曲线与曲面对象：

from tf_quant_finance.experimental.pricing_platform.framework import market_data as md market = md.MarketDataDict( market_data_dict=my_dict, dtype=tf.float64) # dtype 可选，默认 tf.float64

构造函数内部会读取字典中的reference_date并转换为DateTensor（见 market_data_impl.py）。dtype默认tf.float64，所有 float 型 Tensor 均按此精度计算。

注意：文档与接口均处于开发阶段，可能随版本演进发生变化，使用时请以当前仓库代码为准。

二、市场数据字典的整体结构

字典的每个顶层键对应一个资产类别（rate、equity、commodity 等），当前规范覆盖rates（利率）与equities（权益）两类，另有reference_date表示数据快照日期。完整骨架如下：

{ # 利率市场数据，顶层为币种 'rates': { 'USD': { 'curves': { ... }, # 该币种的利率曲线 'historical_fixings': { ... }, # 历史 Fixings 'volatility_cube': { ... } # 波动率立方体 } }, # 权益市场数据，顶层为币种 'equities': { 'USD': { 'GOOG': { ... } # 具体标的 } }, # 快照日期 "reference_date": date }

MarketDataDict暴露supported_currencies属性：它会遍历rates下的所有键，只保留那些同时出现在currencies.Currency枚举中的币种（见 market_data_impl.py）。类似地，supported_assets从equities[currency]的键中去掉币种名后即为资产列表（market_data_impl.py）。这意味着资产键名不应与币种名冲突。

三、Rates 市场数据规范

rates的顶层键是币种名（如USD）。每个币种下挂三类数据：curves、historical_fixings与volatility_cube。

3.1 curves：利率曲线

curves是一个字典，包含定价所需的全部曲线规格。可用键名取自RateIndexTypeproto 的字段名（见 rate_indices.proto），当前支持 OIS、SOFR、SONIA、ESTER、SARON、LIBOR（OVERNIGHT/1W/1M/3M/6M/1Y）、EURIBOR、STIBOR 等指数类型。此外必须提供risk_free_curve，它是默认的贴现（discounting）曲线。

每条曲线通过贴现因子（discount factors）与对应日期表示（文档注明：未来将补充相对日期rdates的替代方案）。示例：

'curves': { # 默认贴现曲线 'risk_free_curve': { # 升序排序的日期 Tensor 'dates': [date1, date2], # 贴现因子 'discounts': [discount1, discount2], # 插值配置 'config': curve_config }, 'LIBOR_3M': { 'dates': [date1, date2], 'discounts': [discount1, discount2], # Fixing 来源 'fixings_source': 'LIBOR_3M', # 插值配置 'config': curve_config } }

若需要新增缺失的曲线类型，只需在RateIndexType中增加新字段即可。从源码看，yield_curve(curve_type)的取值逻辑是：当传入RiskFreeCurve时固定取键risk_free_curve，否则取curve_type.index.type.name（market_data_impl.py），并对不支持的币种抛出ValueError、对缺失曲线抛出KeyError。曲线数据随后被包装为RateCurve对象（rate_curve.py），该对象提供discount_factor、discount_rate、forward_rate等估值接口。

RateCurve内部的日期到时间转换使用曲线的daycount_convention，插值默认发生在贴现因子空间（interpolate_rates=True时等价于对贴现率空间插值后指数还原，细节见discount_factor/discount_rate实现，rate_curve.py）。

3.2 historical_fixings：历史 Fixings

每个曲线索引可通过fixing_dates、fixing_rates与fixing_daycount提供历史 Fixings：

'historical_fixings': { 'LIBOR_3M': { # 升序排序的 Fixing 日期 Tensor 'fixing_dates': [fixing_date1, fixing_date2, fixing_date3], # Fixing 利率，以年化单利（annualized simple rates）表示 'fixing_rates': [rate1, rate2, rate3], # Fixing 的 Day Count，必须是 core.DayCountConventions 之一， # 一旦指定了 fixings 则必须提供 'fixing_daycount': 'ACTUAL_360', # 营业日约定 'business_convention': 'FOLLOWING', # 假日日历 'holiday_calendar': 'US' } }

语义要点（见 market_data_impl.py 的fixings()实现）：

• 若某曲线未提供 fixings 数据，则任何日期的 Fixing 视为 0（源码中返回全零 Tensor 与Nonedaycount）；
• 否则 Fixings 被当作时间的左连续分段常数函数（left-continuous piecewise-constant），fixing_dates未覆盖的日期取最近一个已提供值；
• 实现通过tf.searchsorted在升序 fixing_dates 中定位查询日期，并tf.gather取出对应 Fixing 值；
• 若提供了fixing_dates/fixing_rates却缺少fixing_daycount，会抛出ValueError。

3.3 volatility_cube：波动率立方体

volatility_cube容纳不同波动率立方体类型，例如 'SWAPTION' 或 'CAP'（文档注明：立方体类型尚未标准化，属 TODO 项）。每个立方体包含期权到期、Swap 期限、Strikes 与对应隐含波动率：

'volatility_cube': { 'SWAPTION': { # 期权到期日 "expriries": [date1, date2], # 每个到期日对应的 Swap 期限，二维数组； # 每行末尾值可重复（表示期限网格边界） "tenors": 2d array, # 与每个 tenors 条目对应的 Strikes，三维数组 "strikes": 3d array, # 与每个 strikes 条目对应的隐含波动率，三维数组 "implied_volatilities": 3d array, # 插值配置 'config': volatility_config }, 'CAP': { ... } }

四、Equities 市场数据规范

equities的顶层是币种名，其下是各标的（如GOOG）。每个标的必须提供spot_price与volatility_surface，可选提供historical_spots历史价格：

'equities': { "USD": { "GOOG": { "spot_price": 1700, "historical_spot_prices": { "dates": [date1, date2], "values": [price1, price2] }, "currency": "USD", "volatility_surface": { "dates": [date1, date2], # 每个日期对应的 Strikes，二维数组；每行末尾值可重复，例如 # [[1650, 1700, 1750, 1800, 1800], # [1650, 1700, 1750, 1770, 1790]] "strikes": 2d array, # 与日期和 Strikes 对应的隐含波动率，二维数组 "implied_volatilities": 2d array, # 插值配置 'config': volatility_config } } } }

从源码看，MarketDataDict.spot()按币种/资产列表逐项取spot_price并转为self._dtype；volatility_surface()则逐资产收集dates、strikes、implied_volatilities，利用math.pad对齐不同资产的网格后构造VolatilitySurface对象（market_data_impl.py）。若资产缺失或未提供volatility_surface，会分别抛出ValueError。

VolatilitySurface（volatility_surface.py）内部将到期日期按 daycount 换算为到期时间，默认使用Interpolation2D（到期时间 × Strikes 的二维插值）对任意(strike, expiry)查询隐含波动率，提供volatility()、node_expiries()、node_strikes()、node_volatilities()等访问接口。

五、Market data config：插值与日历配置

市场数据配置用于指定插值方法与 Day Count 约定。曲线配置当前支持如下格式：

curve_config = {"interpolation_method": "LINEAR", "interpolate_rates": False, "daycount_convention": "ACTUAL_365", # 营业日约定 'business_convention': 'FOLLOWING', # 假日日历 'holiday_calendar': 'US'}

各字段语义：

Day Count 约定可选值：ACTUAL_ACTUAL_ISDA、ACTUAL_360、ACTUAL_365、CONVENTION_30_360。营业日约定可选值：NO_ADJUSTMENT、PREVIOUS、FOLLOWING、MODIFIED_PREVIOUS、MODIFIED_FOLLOWING、EOM_NO_ADJUSTMENT、EOM_PREVIOUS、EOM_FOLLOWING。这些约定在 utils.py 中被映射为dateslib的 daycount 函数与营业日调整函数（含月末EOM标志），未映射的约定会抛出KeyError。

默认行为：当曲线未提供config或未指定插值方法时，RateCurve默认采用贴现因子空间的三次样条（cubic）插值，Day Count 约定默认ACTUAL_365（见 rate_curve.py）；VolatilitySurface同样默认ACTUAL_365并使用二维插值（volatility_surface.py）。

波动率曲面/立方体的配置同样支持 daycount、营业日与日历规格，格式与曲线配置一致：

curve_config = {"daycount_convention": "ACTUAL_365", # 营业日约定 'business_convention': 'FOLLOWING', # 假日日历 'holiday_calendar': 'US'}

此外，market_data_config.py 定义了面向数据装配场景的RateConfigdataclass 与RateBootstrapOption/RateVolBootstrapOption枚举（FROM_CSV、FROM_JSON、FROM_BQ、BOOTSTRAP），其中RateConfig含file_id、bootstrap_instrumetns、interpolation_method（默认CUBIC）、interpolate_rates（默认True）、daycount_convention（默认ACTUAL_365）等字段，可用于描述从外部数据源引导曲线的方式。

六、Fixings：数据来源与更新机制

利率/即期的 Fixing 信息可以通过两条路径提供：市场数据（historical_fixings/ 曲线内嵌fixing_*字段），或工具定义本身。此外，Fixing 信息可在工具定价阶段通过 metadata 更新。

文档给出的典型流程如下（以 TikZ 图示意，原图见 market_data.md）：

market_data ──▶ market_data_1 ──▶ market_data_2 │ │ ▼ ▼ price_1 price_2 │ │ └──────▶ aggregate(price_1, price_2) ▲ │ metadata（price_1 ──▶ price_2 传递）

即：市场数据被逐步演化（例如模拟估值日期推进），每个阶段执行一次定价；Fixing 既可以是市场数据的组成部分，也可以通过定价config单独提供——例如config中可以包含障碍期权的敲出事件（knock-out event）。metadata 通过如下方式被定价方法使用：

Instrument.from_protos(proto_list, config=InstrumentConfig(**metadata))

Instrument.from_protos是工具接口的类方法（定义见 instrument.py），InstrumentConfig(**metadata)将 metadata 作为配置注入。默认规则：定价方法首先检查工具 metadata 中是否包含所需的 Fixing 数据；若没有，则回退到市场数据中提取 Fixings。这一"工具优先、市场数据兜底"的层级机制，正是 market_data_test.py 中test_fixings所验证的行为——未提供 fixings 的曲线（如 OIS）返回 0，而提供了fixing_dates/fixing_rates的 LIBOR_3M 则按分段常数规则返回对应值（market_data_test.py）。

七、端到端示例与测试验证

结合仓库测试用例（market_data_test.py），一个真实可用的市场数据字典形如：

valuation_date = [(2020, 6, 24)] fixing_dates = [(2020, 2, 24), (2020, 3, 12), (2020, 4, 14), (2020, 5, 21)] fixing_rates = [0.01, 0.02, 0.03, 0.025] dates = [[2021, 2, 8], [2022, 2, 8], [2023, 2, 8], [2025, 2, 8], [2027, 2, 8], [2030, 2, 8], [2050, 2, 8]] discounts = [0.97197441, 0.94022746, 0.91074031, 0.85495089, 0.8013675, 0.72494879, 0.37602059] market_data_dict = { "rates": { "USD": { "risk_free_curve": { "dates": [[2021, 2, 8], [2022, 2, 8], [2023, 2, 8], [2025, 2, 8], [2050, 2, 8]], "discounts": [0.97197441, 0.94022746, 0.91074031, 0.85495089, 0.37602059], }, "OIS": {"dates": dates, "discounts": discounts}, "LIBOR_3M": { "dates": dates, "discounts": discounts, "fixing_dates": fixing_dates, "fixing_rates": fixing_rates, "fixing_daycount": "ACTUAL_365", "config": { "interpolation_method": "LINEAR" } }, }, }, "equities": { "USD": { "GOOG": { "spot": 1500, "volatility_surface": { "dates": vol_dates, "strikes": strikes, "implied_volatilities": volatilities } } } }, "reference_date": valuation_date, }

测试覆盖了三类核心能力，可作为验证与二次开发的参考：

• test_discount_curve：通过MarketDataDict.yield_curve()分别取RiskFreeCurve(currency="USD")与RateIndexCurve(currency="USD", index=RateIndex(type="LIBOR_3M"))，断言discount_factor_nodes与输入贴现因子一致（market_data_test.py）；
• test_volatility：构造VolatilitySurface后以expiry_dates+strike查询插值波动率，与期望值对比（market_data_test.py）；
• test_fixings：验证 LIBOR_3M 的 Fixing 查询返回分段常数取值（如 2020-05-24 → 0.025、2020-03-24 → 0.03）及 OIS 默认返回 0（market_data_test.py）。

八、使用注意事项与当前限制

基于文档与源码，使用本模块时有几点值得注意：

1. 接口仍在演进：ProcessedMarketData及其实现标注为开发中，曲线日期暂只支持绝对日期（相对日期rdates为 TODO），波动率立方体类型标准化亦为 TODO；
2. 必须提供risk_free_curve：它是默认贴现曲线；curves的其他键需与RateIndexType枚举名一致，新增曲线类型需扩展 rate_indices.proto；
3. Fixings 语义：未提供时视为 0；提供fixing_dates/fixing_rates时必须同时提供fixing_daycount，否则抛ValueError；Fixing 查询日期需在估值日之前；
4. 网格对齐：volatility_surface中每行 strikes 的末尾值可重复填充，以对齐不同日期的网格宽度；多资产的曲面会在volatility_surface()内部通过 padding 统一形状；
5. 默认精度：未显式指定dtype时默认使用tf.float64，以保证金融计算精度；
6. 营业日与假日日历：business_convention与holiday_calendar的合法取值见 business_days.proto，未映射的约定在工具层会抛出KeyError。

掌握以上结构与配置细节后，你就可以把外部行情系统输出的曲线点、Fixing 时间序列与波动率网格，直接组织为MarketDataDict字典，交给 TFF 定价平台的工具（如 rate_instruments 下的现金流与掉期工具）进行批量估值。

• 金融科技
• 科学计算