gs-quant EqSynthetic 股票合成工具详解：字段体系、双腿结构与定价实战

gs-quant EqSynthetic 股票合成工具详解：字段体系、双腿结构与定价实战

【免费下载链接】gs-quantPython toolkit for quantitative finance项目地址: https://gitcode.com/GitHub_Trending/gs/gs-quant

gs-quant 的EqSynthetic是面向股票合成类工具（Synthetic/Total Return Swap、CFD 及 OET 变体）的一站式建模入口，本文以其官方 API 文档（docs/classes/gs_quant.instrument.EqSynthetic.rst）为骨架，结合源码中该类的完整字段定义与配套子结构，逐项讲解每个属性的语义、类型与默认值，并给出从构造、序列化到解析定价的完整用法，帮助你直接复用这套工具建模股票合成头寸。

一、EqSynthetic 是什么：一条腿建模股票合成工具

EqSynthetic定义在 gs_quant/target/instrument.py，继承自Instrument（位于 gs_quant/instrument/core.py），其asset_class固定为AssetClass.Equity，type_固定为AssetType.Synthetic，也就是说：无论具体选哪种合成结构，它在资产分类上都归属“股票、合成工具”。

它的swap_type字段默认取值为SwapType.Eq_Synthetic_OET（即字符串'Eq Synthetic OET'）。从SwapType枚举（gs_quant/target/common.py）可以看到该类可覆盖的合成结构全谱：

需要说明的是，官方文档页面 gs_quant.instrument.EqSynthetic.rst 采用 Sphinxautoclass自动生成，其“Properties”一节完整列举了该类对外暴露的全部属性（约 35 项），并注明其余方法继承自 gs_quant.base.Priceable。下文即按这份属性清单逐项展开。

二、交易方向与规模：buy_sell、quantity_ 与佣金

这一类字段描述“谁、以多大头寸、花多少成本”参与这笔合成工具：

• buy_sell：交易方向，取值BuySell.Buy/BuySell.Sell（枚举定义于 gs_quant/target/common.py），序列化为'Buy'/'Sell'。
• quantity_：InstrumentBase提供的内部规模字段（见 gs_quant/base.py），默认值为1，通过同名构造参数初始化；对外由只读属性instrument_quantity暴露（gs_quant/base.py）。
• num_of_underlyers：标的下方对应的“underlyer 数量”，类型为float，适用于一篮子多标的情形。
• commission / commission_type / commission_units：交易佣金及其类型、单位，三者配套使用，类型分别为float/str/str，默认均未设置（None）。

三、标的信息：underlier、underlier_type 与双币种

• underlier：标的价格或标识符，类型为Union[float, str]——既可以传数值（固定价格），也可以传字符串标识（如代码、指数名）。
• underlier_type：标的标识符类型，取自UnderlierType枚举（gs_quant/target/common.py），支持BBID、BID、CUSIP、ISIN、SEDOL、RIC、Ticker共七种。
• currency：工具计价货币，取Currency枚举（gs_quant/target/common.py）。
• settlement_currency：结算货币，可不同于计价货币，用于跨币种结算场景。
• fx_data_source：汇率数据源，str类型，用于涉及货币折算时的 FX 曲线选择。
• strike：行权/参考价，float类型，对于含敲出或行权结构的合成工具定义执行水平。
• dividend_pay_ratio：股利支付比率，float类型，控制股票腿中股利收益的传递比例。

四、日期体系：从生效日到交割延迟

合成工具的现金流依赖一整套日期字段，EqSynthetic对这些日期做了显式建模：

• effective_date：生效日，datetime.date类型。
• expiry：到期日，Union[datetime.date, str]——既可直接给日期，也可给相对期限字符串（如'3m'）。
• trade_date：交易日，str。
• initial_valuation_date：初始估值日，str。
• designated_maturity：指定期限（如'1y'、'10y'这类期限标签），str类型，用于描述工具的原始期限而非具体日历日。
• rate_tenor：利率期限，str，用于确定 funding 腿的基准利率期限结构。
• settlement_delay / reset_delay / payment_delay：结算、重置、支付三个环节的延迟天数，均为str。
• valuation_bdc / payment_bdc：估值与支付的营业日惯例（Business Day Convention），float类型，控制遇到节假日时日期如何顺延。
• schedule_type：日程类型，str，用于驱动内部日程生成规则。

五、经济条款与 OET 条款：rate_option、oet_terms

• rate_option：利率基准选项，str，例如常见的浮动利率索引标识，用于 funding 腿计息。
• oet_terms：OET（One Equity Trade / OET 交易条款）参数集合，类型为tuple[EqSyntheticOETTerms, ...]。EqSyntheticOETTerms定义于 gs_quant/target/instrument.py，内含：
  • client_fee/client_notice/client_terms（str）与client_fee_at（float）：客户侧的费用、通知期、条款文本与费用触发点；
  • firm_fee/firm_notice/firm_terms（str）与firm_fee_at（float）：机构（firm）侧对应字段；
  • oet_type（str）：OET 结构类型。
• forwardstartingfixednotional / forwardstartingnotionalprecision / forwardstartingtype：远期起始名义金额、名义精度与起始类型，属于远期起始（forward-starting）结构的专属参数。

六、双腿结构：eq_leg 与 funding_leg

EqSynthetic采用“股票腿 + 融资腿”的双腿结构，分别由两个EqSyntheticLeg元组承载：

• eq_leg：股票腿，tuple[EqSyntheticLeg, ...]。
• funding_leg：融资腿，tuple[EqSyntheticLeg, ...]，通常挂钩rate_option与rate_tenor描述的浮动基准。

EqSyntheticLeg定义于 gs_quant/target/instrument.py，其字段为：

而每条日程EqSyntheticSchedule（gs_quant/target/instrument.py）包含period（周期）、delay（延迟）、date_rule（日期规则）与dates（tuple[EqSyntheticDateInfo, ...]）四个字段；EqSyntheticDateInfo（gs_quant/target/instrument.py）仅含一个date字段，用于穷举法指定具体日期。

七、元数据与框架属性：name、metadata、type_、unresolved 等

• name：工具名称，str，使用name_metadata序列化。
• metadata：任意元数据字典，由InstrumentBase管理（gs_quant/base.py），clone时会被一并复制。
• type_：固定为AssetType.Synthetic，序列化字段名为type，None时不输出（exclude=exclude_none）。
• provider：数据/定价提供方，抽象属性（见 gs_quant/base.py）。
• unresolved / resolution_key：解析前的原始快照与解析密钥，resolve()之后由InstrumentBase.resolved()写入（gs_quant/base.py）。
• dataclass_json_config：dataclass-json 框架注入的序列化配置。

八、序列化与反序列化：camelCase 与构造容错

EqSynthetic类的三个装饰器（源码 gs_quant/target/instrument.py 上方）共同决定了其序列化行为：

• @handle_camel_case_args：构造时自动兼容 camelCase 参数名，例如可直接写underlierType、swapType，与 Python 侧underlier_type、swap_type等价；
• @dataclass_json(letter_case=LetterCase.CAMEL)：to_json()/from_json()时字段统一转为 camelCase，与 Marquee 平台契约保持一致；
• @dataclass(unsafe_hash=True, repr=False)：可哈希、自定义repr。

典型用法：

from gs_quant.instrument import EqSynthetic # 构造：股票腿 + 融资腿的合成互换 sw = EqSynthetic( underlier='.SPX', underlier_type='Ticker', swap_type='Eq Synthetic OET', buy_sell='Buy', currency='USD', expiry='3m', ) # camelCase 参数同样被接受 sw2 = EqSynthetic(underlier='AAPL UW', underlierType='Ticker', buySell='Sell') # 序列化与回读 payload = sw.to_json() restored = EqSynthetic.from_json(payload)

九、解析、定价与风险：Priceable 能力集

官方文档注明该类的其余方法继承自Priceable（docs/classes/gs_quant.base.Priceable.rst），核心能力定义于 gs_quant/base.py：

• resolve(in_place=True)：补齐未提供的属性。合成工具的固定利率、缺口日期等可在解析后自动算出。
• price()/dollar_price()：返回本币现值 / 美元现值；在PricingContext异步上下文中调用则返回 future，可批量并行定价。
• calc(risk_measure, fn=None)：计算任意风险度量（如股票 Delta、Vega），结果可为标量或 DataFrame。
• **clone(kwargs)：复制工具并覆盖指定字段，InstrumentBase.clone会保留unresolved、metadata与resolution_key（gs_quant/base.py）。

在PricingContext中批量并行计算的完整模式（参照 gs_quant/base.py 的示例范式）：

from gs_quant.markets import PricingContext from gs_quant.risk import EqDelta, EqVega with PricingContext(): price_f = sw.price() # 返回 future delta_f = sw.calc(EqDelta) # 返回 future price = price_f.result() # float：本币现值 delta = delta_f.result() # 风险度量结果

十、小结

EqSynthetic用一套统一、显式的字段体系覆盖了股票合成工具的完整生命周期：从方向（buy_sell）、规模（quantity_/num_of_underlyers）、标的（underlier/underlier_type）、日期（effective_date/expiry/ 各类delay与bdc），到双腿结构（eq_leg/funding_leg）与 OET 条款（oet_terms），再经由 camelCase 序列化与Priceable的解析、定价、风险计算能力完成全链路使用。深入阅读 gs_quant/target/instrument.py 中EqSynthetic、EqSyntheticLeg、EqSyntheticSchedule、EqSyntheticOETTerms的定义，以及 gs_quant/target/common.py 中的SwapType、UnderlierType、BuySell枚举，即可在自身项目中精确复现这套建模语义。

【免费下载链接】gs-quantPython toolkit for quantitative finance项目地址: https://gitcode.com/GitHub_Trending/gs/gs-quant