bondZSpreadCalculator

bondZSpreadCalculator(instrument, calcDate, dirtyPrice, discountCurve, [spreadCurve], [forwardCurve])

根据债券的市场全价和贴现曲线，计算债券的零波动利差（Z-Spread）。Z-Spread 是加在各期贴现利率上的常数利差，使未来现金流的现值之和等于市场全价。

若指定 spreadCurve，则在贴现曲线和信用利差曲线的基础上求解额外的常数利差。若未指定，则信用利差按 0 处理。

贴现曲线的 compounding 字段指定计息方式，可取 "Simple"（单利）、"Compounded"（离散复利）或 "Continuous"（连续复利）。

注意： 所有输入向量必须等长。输入标量会自动扩展到与向量相同的长度；长度为 1 的向量仍按向量处理，不会作为标量扩展。

instrument INSTRUMENT 类型标量或向量，表示债券产品，可通过 parseInstrument 创建。固定利率债的 bondType 设置为 "FixedRateBond"；产品字段详见 bondPricer 的债券产品字段说明。

calcDate DATE 类型标量或向量，表示计算日。必须与对应贴现曲线的 referenceDate 一致。

dirtyPrice 整型或浮点型标量或向量，表示债券的市场全价，包含应计利息。值必须大于 0 且不为 NULL。输入金额应与债券 nominal 字段指定的名义金额口径一致；例如 nominal 为 100 时，输入每 100 面值对应的全价。

discountCurve MKTDATA 类型标量或向量，表示贴现曲线，curveType 必须为 "IrYieldCurve"。可通过 parseMktData 将曲线字典解析为 MKTDATA 对象。曲线字段详见该函数的利率收益率曲线说明。

spreadCurve 可选参数，MKTDATA 类型标量或向量，表示已有信用利差曲线，curveType 必须为 "IrYieldCurve"。未指定或设为 NULL 时，信用利差按 0 处理。指定该参数后，返回值表示在已有信用利差基础上求得的额外利差。

forwardCurve 可选参数，MKTDATA 类型标量或向量，表示用于计算浮动利率债券现金流的远期曲线，curveType 必须为 "IrYieldCurve"。当 instrument 的 bondType 为 "FloatingRateBond" 时，该参数必须指定且不能为 NULL；其他债券类型不使用该参数。曲线的 referenceDate 必须与 calcDate 一致。

所有输入均为标量时，返回 DOUBLE 类型标量；存在向量输入时，返回与输入向量等长的 DOUBLE 向量。

结果以小数形式表示，例如 0.01 表示 1%，即 100 bp。

例1. 计算单只固定利率债的 Z-Spread。债券面值为 100，年票面利率为 3%，每年付息一次，期限为 5 年。计算日为起息日，市场全价为 100，贴现曲线为 2% 的平坦曲线，采用按年离散复利。

valuationDate = 2025.01.01
couponBondSpec = {
    "productType": "Cash",
    "assetType": "Bond",
    "bondType": "FixedRateBond",
    "nominal": 100.0,
    "start": 2025.01.01,
    "maturity": 2030.01.01,
    "issuePrice": 100.0,
    "coupon": 0.03,
    "frequency": "Annual",
    "dayCountConvention": "ActualActualISDA"
}
couponBond = parseInstrument(obj=couponBondSpec)

discountSpec = {
    "mktDataType": "Curve",
    "curveType": "IrYieldCurve",
    "referenceDate": valuationDate,
    "currency": "CNY",
    "dayCountConvention": "ActualActualISDA",
    "compounding": "Compounded",
    "frequency": "Annual",
    "interpMethod": "Linear",
    "extrapMethod": "Flat",
    "dates": [2026.01.01, 2030.01.01],
    "values": [0.02, 0.02]
}
discountCurve = parseMktData(dict=discountSpec)

bondSpread = bondZSpreadCalculator(
    instrument=couponBond,
    calcDate=valuationDate,
    dirtyPrice=100.0,
    discountCurve=discountCurve
)
round(bondSpread, 8)
// output: 0.01

计算得到的 Z-Spread 为 0.01，即 100 bp。

例2. 沿用例1的债券、计算日和贴现曲线，另外指定 0.5% 的平坦信用利差曲线。

creditSpec = {
    "mktDataType": "Curve",
    "curveType": "IrYieldCurve",
    "referenceDate": valuationDate,
    "currency": "CNY",
    "dayCountConvention": "ActualActualISDA",
    "compounding": "Compounded",
    "frequency": "Annual",
    "interpMethod": "Linear",
    "extrapMethod": "Flat",
    "dates": [2026.01.01, 2030.01.01],
    "values": [0.005, 0.005]
}
creditCurve = parseMktData(dict=creditSpec)

additionalSpread = bondZSpreadCalculator(
    instrument=couponBond,
    calcDate=valuationDate,
    dirtyPrice=100.0,
    discountCurve=discountCurve,
    spreadCurve=creditCurve
)
round(additionalSpread, 8)
// output: 0.005

返回的额外利差为 0.005，即 50 bp。

例3. 沿用例1的债券、计算日和贴现曲线，批量计算全价分别为 98、100 和 102 时的 Z-Spread。instrument、calcDate 和 discountCurve 均为标量，会扩展以匹配 dirtyPrice 向量。

marketPrices = [98.0, 100.0, 102.0]
spreadValues = bondZSpreadCalculator(
    instrument=couponBond,
    calcDate=valuationDate,
    dirtyPrice=marketPrices,
    discountCurve=discountCurve
)
round(spreadValues, 8)
// output: [0.01442238,0.01,0.00568655]

例4. 计算一只三年期、每半年付息一次的浮动利率债券的 Z-Spread。债券面值为 100，市场全价为 108。通过 forwardCurve 提供用于计算浮动票息的远期曲线，并使用 discountCurve 对现金流贴现。

valuationDate = 2017.09.11
floatingBondSpec = {
    "productType": "Cash",
    "assetType": "Bond",
    "bondType": "FloatingRateBond",
    "nominal": 100.0,
    "start": 2017.09.11,
    "maturity": 2020.09.11,
    "frequency": "Semiannual",
    "dayCountConvention": "Actual365",
    "iborIndex": "LPR_1Y",
    "spread": 0.01,
    "lastFixing": 0.045
}
floatingBond = parseInstrument(obj=floatingBondSpec)

discountCurve = parseMktData(dict={
    "mktDataType": "Curve",
    "curveType": "IrYieldCurve",
    "referenceDate": valuationDate,
    "currency": "CNY",
    "dayCountConvention": "Actual365",
    "compounding": "Continuous",
    "frequency": "Semiannual",
    "interpMethod": "Linear",
    "extrapMethod": "Flat",
    "dates": [2018.03.11, 2018.09.11, 2019.03.11, 2019.09.11, 2020.03.11, 2020.09.11],
    "values": [0.025, 0.026, 0.023, 0.024, 0.029, 0.027]
})

forwardCurve = parseMktData(dict={
    "mktDataType": "Curve",
    "curveType": "IrYieldCurve",
    "referenceDate": valuationDate,
    "currency": "CNY",
    "dayCountConvention": "Actual365",
    "compounding": "Continuous",
    "frequency": "Semiannual",
    "interpMethod": "Linear",
    "extrapMethod": "Flat",
    "dates": [2018.03.11, 2018.09.11, 2019.03.11, 2019.09.11, 2020.03.11, 2020.09.11],
    "values": [0.046, 0.05, 0.048, 0.0515, 0.051, 0.049]
})

floatingSpread = bondZSpreadCalculator(
    instrument=floatingBond,
    calcDate=valuationDate,
    dirtyPrice=108.0,
    discountCurve=discountCurve,
    forwardCurve=forwardCurve
)
floatingSpread
// output: 0.004129343258666133

计算得到的 Z-Spread 约为 41.2934 bp。

相关函数： bondPricer、parseInstrument、parseMktData