gs-quant 外汇 TARF 产品建模：FXTarfScheduleLeg 单腿数据结构与实战指南

gs-quant 外汇 TARF 产品建模FXTarfScheduleLeg 单腿数据结构与实战指南【免费下载链接】gs-quantPython toolkit for quantitative finance项目地址: https://gitcode.com/GitHub_Trending/gs/gs-quantTARFTarget Accrual Redemption Forward目标累计赎回远期是外汇市场常见的一款结构性远期产品投资者设定一个目标汇率区间只有当即期汇率落入区间内时才累积收益一旦累计收益达到目标水平产品提前终止。本文聚焦 gs-quant 开源仓库中 docs/classes/gs_quant.instrument.FXTarfScheduleLeg.rst 所定义的FXTarfScheduleLeg类系统讲解其属性含义、与父类FXTarf的组合关系以及如何结合定价上下文完成风险计量帮助读者直接上手在 gs-quant 中构造并分析外汇 TARF 结构。一、认识 TARF 与 ScheduleLeg 在 gs-quant 中的定位在 gs-quant 的金融产品模型中外汇类结构性产品被建模为若干顶层 Instrument与**腿Leg**的组合。FXTarfScheduleLeg正是FXTarf产品内部排期腿的数据载体一个FXTarf通过其schedules字段持有一组FXTarfScheduleLeg逐条描述每个观察/支付周期的定价参数。在仓库源码 gs_quant/target/instrument.py 中FXTarfScheduleLeg被定义为class FXTarfScheduleLeg(Instrument): profit_strike: Optional[Union[float, str]] field(defaultNone, metadatafield_metadata) loss_strike: Optional[Union[float, str]] field(defaultNone, metadatafield_metadata) fixing_date: Optional[Union[datetime.date, str]] field(defaultNone, metadatafield_metadata) payment_date: Optional[Union[datetime.date, str]] field(defaultNone, metadatafield_metadata) notional_amount: Optional[Union[float, str]] field(defaultNone, metadatafield_metadata) european_knock_in: Optional[Union[float, str]] field(defaultNone, metadatafield_metadata) leverage_ratio: Optional[Union[float, str]] field(defaultNone, metadatafield_metadata) asset_class: Optional[AssetClass] field(initFalse, defaultAssetClass.FX, metadatafield_metadata) type_: Optional[AssetType] field(initFalse, defaultAssetType.TarfScheduleLeg, metadataconfig(field_nametype, excludeexclude_none)) name: Optional[str] field(defaultNone, metadataname_metadata)与之配套FXTarf在 同一文件的第 2198 行起 定义其中通过schedules: Optional[tuple[FXTarfScheduleLeg, ...]]字段直接持有多个排期腿。两个类的asset_class都固定为AssetClass.FXtype字段分别固定为AssetType.Tarf与AssetType.TarfScheduleLeg见 gs_quant/target/common.py且二者均通过dataclass_json(letter_caseLetterCase.CAMEL)与handle_camel_case_args装饰这意味着字段在序列化为 JSON 时自动转换为驼峰命名例如profit_strike→profitStrike构造时既支持 Python 风格的下划线参数也支持 API 风格的驼峰参数。二、FXTarfScheduleLeg 属性全解依据文档 gs_quant.instrument.FXTarfScheduleLeg.rst 中列出的属性结合源码类型定义可将每个字段归入以下五类2.1 基础标识属性属性类型说明nameOptional[str]该腿的可选名称用于在多腿结构中区分不同排期metadata使用name_metadata序列化时即使为 None 也会保留键名metadataOptional[dict]附属于该腿的自定义元数据用于携带业务侧额外信息providerOptional[str]定价服务提供方标识由基类Instrument.PROVIDER GsRiskApi提供见 gs_quant/instrument/core.pyresolution_keyOptional[RiskKey]解析resolve后生成的定价键记录市场数据来源与参数供风险缓存使用unresolvedOptional[Instrument]指向解析前的原始腿对象用于在解析前后保留未填充字段的原始状态resolution_key、unresolved、metadata、provider等属性在基类InstrumentBase中定义见 gs_quant/base.py它们共同支撑了 gs-quant先构造未解析 instrument、再批量 resolve 并缓存的定价工作流。2.2 价格与方向属性属性类型说明profit_strikeOptional[Union[float, str]]盈利触发价位profit strike。该腿进入盈利档的汇率边界既支持数值也支持相对表达式的字符串loss_strikeOptional[Union[float, str]]亏损触发价位loss strike。该腿进入亏损档的汇率边界notional_amountOptional[Union[float, str]]该腿的名义本金。TARF 中通常按每期固定名义滚动也可设为目标减少型见下方leverage_ratio的配合注意profit_strike与loss_strike均为Union[float, str]类型仓库全局注册了对应的解码器decode_float_or_str见 gs_quant/base.py因此在传参时可以放心使用字符串形式的相对 strike如ATMF、Spot-0.02之类的表达式由后端定价引擎解析。2.3 日期属性属性类型说明fixing_dateOptional[Union[datetime.date, str]]该腿的汇率观察fixing日即决定本期盈利/亏损归属的即期汇率采样日payment_dateOptional[Union[datetime.date, str]]该腿的支付日即结算现金流实际到账日日期同样支持datetime.date对象或字符串两种形式仓库为Optional[Union[datetime.date, str]]注册了encode_date_or_str/decode_date_or_str编解码器见 gs_quant/base.py字符串可写成1m、2024-12-20等格式。2.4 结构条款属性属性类型说明european_knock_inOptional[Union[float, str]]欧式敲入价位。该腿在整个观察期采用欧式判定仅在到期观察时刻若汇率触及该水平则敲入并激活后续赔付条款leverage_ratioOptional[Union[float, str]]杠杆比率。当 TARF 采用目标累积模式时未达目标期数的名义可按该倍数放大实现加速累计instrument_quantityOptional[float]工具数量由InstrumentBase的quantity_暴露的只读属性见 gs_quant/base.py用于组合层面的持仓数量管理quantity_InitVar[float]底层数量变量默认值为 1是instrument_quantity的承载字段2.5 序列化与类型属性属性类型说明dataclass_json_configdictdataclass-json 序列化配置驼峰命名、忽略 None 字段由dataclass_json装饰器自动注入type_Optional[AssetType]固定为AssetType.TarfScheduleLegJSON 字段名为type序列化时若为 None 则自动排除三、与父类 FXTarf 的组合关系FXTarfScheduleLeg不会单独定价它始终作为FXTarf的一部分出现。FXTarf的完整字段见 gs_quant/target/instrument.py与腿直接相关的组合方式如下class FXTarf(Instrument): pair: Optional[str] field(defaultNone, metadatafield_metadata) notional_amount: Optional[Union[float, str]] field(defaultNone, metadatafield_metadata) notional_currency: Optional[Currency] field(defaultNone, metadatafield_metadata) profit_strike: Optional[Union[float, str]] field(defaultNone, metadatafield_metadata) loss_strike: Optional[Union[float, str]] field(defaultNone, metadatafield_metadata) settlement_date: Optional[Union[datetime.date, str]] field(defaultNone, metadatafield_metadata) settlement_currency: Optional[Currency] field(defaultNone, metadatafield_metadata) fixing_rate_option: Optional[str] field(defaultNone, metadatafield_metadata) method_of_settlement: Optional[OptionSettlementMethod] field(defaultNone, metadatafield_metadata) expiration_date: Optional[Union[datetime.date, str]] field(defaultNone, metadatafield_metadata) premium: Optional[Union[float, str]] field(defaultNone, metadatafield_metadata) premium_currency: Optional[Currency] field(defaultNone, metadatafield_metadata) premium_payment_date: Optional[str] field(defaultNone, metadatafield_metadata) long_or_short: Optional[LongShort] field(defaultNone, metadatafield_metadata) european_knock_in: Optional[Union[float, str]] field(defaultNone, metadatafield_metadata) number_of_expiry: Optional[Union[float, str]] field(defaultNone, metadatafield_metadata) coupon_frequency: Optional[str] field(defaultNone, metadatafield_metadata) first_fixing_date: Optional[Union[datetime.date, str]] field(defaultNone, metadatafield_metadata) leverage_ratio: Optional[Union[float, str]] field(defaultNone, metadatafield_metadata) target_type: Optional[TargetType] field(defaultNone, metadatafield_metadata) target: Optional[Union[float, str]] field(defaultNone, metadatafield_metadata) schedules: Optional[tuple[FXTarfScheduleLeg, ...]] field(defaultNone, metadatafield_metadata) target_adj_notional_or_strike: Optional[NotionalOrStrike] field(defaultNone, metadatafield_metadata) payment_on_hitting_target: Optional[TargetPaymentType] field(defaultNone, metadatafield_metadata) settlement_rate_option: Optional[str] field(defaultNone, metadatafield_metadata) asset_class: Optional[AssetClass] field(initFalse, defaultAssetClass.FX, metadatafield_metadata) type_: Optional[AssetType] field(initFalse, defaultAssetType.Tarf, metadataconfig(field_nametype, excludeexclude_none)) name: Optional[str] field(defaultNone, metadataname_metadata)从源码结构看可以得出如下组合规律顶层参数覆盖腿级默认值FXTarf自身也带有profit_strike、loss_strike、european_knock_in、leverage_ratio、notional_amount等字段当腿FXTarfScheduleLeg显式指定了某字段时以腿为准未指定时则可推断由顶层同名字段向下传导排期驱动的多周期结构number_of_expiry与coupon_frequency描述总观察期数与频率first_fixing_date指定首个 fixing 日而每个周期的细节各自 fixing/payment 日、strike、名义落在schedules元组的对应FXTarfScheduleLeg上目标条款在顶层target_type、target、target_adj_notional_or_strike、payment_on_hitting_target四个字段描述 TARF 的目标累积/赎回机制本身与腿的逐期条款正交互补。四、构造一个完整的外汇 TARF综合以上字段一个典型的多期外汇 TARF 构造示例如下所有字段均可按需省略省略项在 resolve 时由后端补齐from datetime import date from gs_quant.instrument import FXTarf, FXTarfScheduleLeg leg1 FXTarfScheduleLeg( fixing_datedate(2024, 12, 20), payment_datedate(2024, 12, 24), profit_strike0.92, loss_strike0.88, notional_amount1_000_000, leverage_ratio2.0, european_knock_in0.95, nameleg-1, ) leg2 FXTarfScheduleLeg( fixing_date1m, # 支持相对日期字符串 payment_date1m2b, # 1 个月后加 2 个工作日 profit_strikeATMF, # 支持相对 strike 表达式 loss_strikeATMF-0.02, notional_amount1_000_000, leverage_ratio2.0, nameleg-2, ) tarf FXTarf( pairEURUSD, notional_currencyUSD, notional_amount1_000_000, first_fixing_datedate(2024, 12, 20), number_of_expiry2, coupon_frequency1m, settlement_currencyUSD, target_type..., # 从 gs_quant.common 导入 TargetType target0.03, target_adj_notional_or_strike..., payment_on_hitting_target..., schedules(leg1, leg2), nameEURUSD TARF, )几点实操说明导入路径FXTarf、FXTarfScheduleLeg均通过gs_quant/target/instrument.py导出并被gs_quant/instrument/__init__.py的from gs_quant.target.instrument import *gs_quant/instrument/init.py统一暴露因此可直接from gs_quant.instrument import FXTarf, FXTarfScheduleLeg驼峰参数兼容由于类装饰了handle_camel_case_argsgs_quant/base.py构造时同样可以传入profitStrike、fixingDate、notionalAmount等驼峰形式与后端 API 的 JSON 命名保持一致缺省即解析所有字段默认None未显式给出的条款会保留为待解析状态调用tarf.resolve()时由定价服务按市场数据补全resolve的实现见 gs_quant/instrument/core.py。五、定价与风险计量构造完成的FXTarf是Instrument的子类继承链为FXTarf → Instrument → (PriceableImpl, InstrumentBase)其中Instrument定义于 gs_quant/instrument/core.py可直接调用基类Priceable提供的定价接口gs_quant/base.pyfrom gs_quant.risk import FXDelta, FXGamma, FXOptionVega with PricingContext(): delta tarf.calc(FXDelta) # 返回 PricingFuture退出上下文后取 .result() gamma tarf.calc(FXGamma) vega tarf.calc(FXOptionVega) print(delta.result())要点calc支持单度量与度量列表传入单个RiskMeasure返回单个结果传入可迭代对象则返回MultipleRiskMeasureFuture可在一次定价上下文中批量计算多个希腊字母见 gs_quant/instrument/core.py异步批量在PricingContext内发起的所有calc调用会合并为一次后端请求适合对同一 TARF 的多个腿、多个场景做批量估值解析与缓存首次resolve()会生成resolution_key后续相同参数的定价请求可命中缓存避免重复计算。六、常见问题与边界说明ScheduleLeg 能否脱离 FXTarf 独立定价从源码结构看FXTarfScheduleLeg虽然自身继承Instrument但它是FXTarf.schedules的组成单元仓库中不存在单独定价腿的独立场景实际使用应始终以顶层FXTarf作为定价入口。strike 传字符串安全吗安全。profit_strike/loss_strike/european_knock_in均声明为Union[float, str]仓库注册了decode_float_or_str解码器gs_quant/base.py字符串形式的相对价格如ATMF会被原样传递并由后端解析。字段命名用驼峰还是下划线两者均可。handle_camel_case_args会自动把驼峰参数归一为下划线字段名若同时传入两种写法会抛出ValueError见 gs_quant/base.py。metadata与name有什么区别name用于结构标识序列化时总是保留metadata用于携带任意自定义业务信息二者都是可选项不影响定价结果。哪些字段属于只读/由后端回填asset_class、type_由类定义固定initFalseinstrument_quantity、quantity_由基类管理resolution_key、unresolved在 resolve 过程中由框架回填不建议手动赋值。七、进一步阅读类文档入口gs_quant.instrument.FXTarfScheduleLeg.rst 与父类文档 gs_quant.instrument.FXTarf.rst其方法继承自 gs_quant.base.Priceable.rst源码实现gs_quant/target/instrument.pyLeg 定义、gs_quant/target/instrument.pyTarf 定义基类机制gs_quant/instrument/core.pyInstrument 与 calc/resolve/scale 工作流、gs_quant/base.pyPriceable 定价接口枚举定义gs_quant/target/common.pyAssetType.Tarf/AssetType.TarfScheduleLeg全部外汇产品文档索引docs/classes含 FXForward、FXOption、FXTarf、FXWorstOf 等同类结构化外汇工具的类文档。通过FXTarf与FXTarfScheduleLeg的组合gs-quant 将目标累积 逐期排期 欧式敲入 杠杆加速这类复杂外汇结构条款拆解为可序列化、可解析、可批量定价的数据模型使交易台和量化研究团队能够用同一套 Python API 完成从结构搭建到风险计量的全流程。【免费下载链接】gs-quantPython toolkit for quantitative finance项目地址: https://gitcode.com/GitHub_Trending/gs/gs-quant创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考