bondInstrumentCalculator

bondInstrumentCalculator(bond, settlement, price, priceType, [calcRisk=false], [benchmark='Qeubee'], [isExercised])

Performs conversion among yield to maturity, clean price, and dirty price, and calculates risk measures such as duration and convexity.

Supports floating-rate bonds. The calculator uses lastFixing + spread as the coupon rate and applies the fixed-rate bond calculation rules for price, yield, and risk measures.

bond is an INSTRUMENT scalar/vector representing the bond instrument(s). If the instrumentId field of the bond instrument has the .SH or .SZ suffix, the bond is treated as an exchange-traded bond and one day is added when calculating accrued interest.

settlement is a DATE scalar/vector indicating the bond settlement date.

price is a numeric scalar/vector. Its meaning depends on priceType:

• When priceType is "YTM", price indicates the yield to maturity.
• When priceType is "CleanPrice", price indicates the clean price.
• When priceType is "DirtyPrice", price indicates the dirty price.
• When priceType is "YTE", price indicates the yield to exercise.

priceType is a STRING scalar/vector specifying the bond price type. It can take the following values:

• "YTM": Yield to maturity.
• "CleanPrice": Clean price.
• "DirtyPrice": Dirty price.
• "YTE": Yield to exercise. It is available only when bond is an OptionBond.

calcRisk (optional) is a BOOL value. The default value is false, indicating that only dirty price, clean price, accrued interest, and yield are returned. If it is set to true, Macaulay duration, modified duration, convexity, and PVBP are also calculated.

benchmark (optional) is a STRING scalar indicating the benchmark algorithm. It can take the following values:

• "Qeubee" (default): Uses the terminal algorithm.
• "CSI": Uses the China Securities Index algorithm.

isExercised (optional) is a BOOL scalar indicating whether the option is exercised:

• If unspecified, the function automatically determines whether it is exercised.
• If set to true, the calculation assumes exercise.
• If set to false, the calculation assumes no exercise.

taxRate is a DOUBLE scalar or vector that specifies the tax rate applied to coupon payments. Principal is not taxed. The default value is 0, and the valid range is [0, 1). This parameter applies only to fixed-rate bonds. An error is returned if taxRate > 0 is specified for any other type of bond.

taxStartDate is a DATE scalar or vector that specifies the date on which taxation begins. A bond is subject to tax if its interest accrual date is on or after taxStartDate. Bonds issued earlier are not subject to tax. The default value is 2025.08.08.

A dictionary that contains the following key-value pairs:

Example 1. Calculate the price, yield to maturity (YTM), accrued interest, and risk indicators for fixed-rate bonds.

fixedRateBondDict = {
    "productType": "Cash",
    "assetType": "Bond",
    "bondType": "FixedRateBond",
    "start": 2022.07.15,
    "maturity": 2072.07.15,
    "issuePrice": 100.0,
    "coupon": 0.034,
    "dayCountConvention": "ActualActualISMA",
    "calendar": "CFET",
    "frequency": "Semiannual"
}
fixedRateBond = parseInstrument(fixedRateBondDict);
bondInstrumentCalculator(fixedRateBond, settlement=2025.04.10, price=0.02, priceType="YTM", calcRisk=true);

/* Output:
dirtyPrice->143.4689
cleanPrice->142.6705
ytm->0.02
accruedInterest->0.7983
macaulayDuration->27.4761
modifiedDuration->27.2041
convexity->1025.4003
pvbp->0.3902
*/


bondInstrumentCalculator(fixedRateBond, settlement=2072.04.18, price=100.2143, priceType="CleanPrice", calcRisk=false);

/* Output:
dirtyPrice: 101.0923
cleanPrice: 100.2143
ytm: 0.0250
accruedInterest: 0.8780
*/

Example 2. Calculate the price, yield to maturity (YTM), accrued interest, and risk indicators for zero-coupon bonds.

zeroCouponBondDict = {
    "productType": "Cash",
    "assetType": "Bond",
    "bondType": "ZeroCouponBond",
    "coupon": 0.0119,
    "start": 2025.01.09,
    "maturity": 2026.02.05,
    "issuePrice": 100.0,
    "dayCountConvention": "ActualActualISMA",
    "calendar": "CFET"
}
zeroCouponBond = parseInstrument(zeroCouponBondDict);
bondInstrumentCalculator(zeroCouponBond, settlement=2025.04.10, price=0.025, priceType="YTM", calcRisk=true);

/* Output:
dirtyPrice->99.2322
cleanPrice->98.9355
ytm->0.025
accruedInterest->0.2966
macaulayDuration->0.8246
modifiedDuration->0.8079
convexity->1.3057
pvbp->0.0080
*/

Example 3. Calculate the price, yield to maturity (YTM), accrued interest, and risk indicators for discounted bonds.

discountBondDict = {
    "productType": "Cash",
    "assetType": "Bond",
    "bondType": "Discount",
    "start": 2025.02.13,
    "maturity": 2025.05.15,
    "issuePrice": 99.663,
    "dayCountConvention": "ActualActualISMA",
    "calendar": "CFET"
}
discountBond = parseInstrument(discountBondDict);
bondInstrumentCalculator(discountBond, settlement=2025.04.10, price=0.02, priceType="YTM", calcRisk=true);

/* Output:
dirtyPrice->99.8085
cleanPrice->99.6012
ytm->0.02
accruedInterest->0.2073
macaulayDuration->0.0958
modifiedDuration->0.0957
convexity->0.0183
pvbp->0.0009
*/discountBondDict = {
    "productType": "Cash",
    "assetType": "Bond",
    "bondType": "Discount",
    "start": 2025.02.13,
    "maturity": 2025.05.15,
    "issuePrice": 99.663,
    "dayCountConvention": "ActualActualISMA",
    "calendar": "CFET"
}
discountBond = parseInstrument(discountBondDict);
bondInstrumentCalculator(discountBond, settlement=2025.04.10, price=0.02, priceType="YTM", calcRisk=true);

/* Output:
dirtyPrice->99.8085
cleanPrice->99.6012
ytm->0.02
accruedInterest->0.2073
macaulayDuration->0.0958
modifiedDuration->0.0957
convexity->0.0183
pvbp->0.0009
*/

Example 4. Simultaneously calculate the price, yield to maturity (YTM), accrued interest, and risk indicators for multiple types of bonds.

result = bondInstrumentCalculator([discountBond, zeroCouponBond, fixedRateBond], settlement=[2025.04.10, 2025.04.10, 2072.04.18], price=[0.02, 0.025, 100.2143], priceType=["YTM", "YTM", "CleanPrice"], calcRisk=true);

print result

/* Output:
dirtyPrice->[99.8086,99.2322,101.09234]
cleanPrice->[99.6012,98.9356,100.2143]
accruedInterest->[0.2074,0.2969,0.8780]
ytm->[0.02,0.025,0.025]
macaulayDuration->[0.0959,0.8247,0.2404]
modifiedDuration->[0.0957,0.808,0.2397]
convexity->[0.0183,1.3057,0.1142]
pvbp->[0.0009,0.008,0.0024]
*/

Example 5. Calculate the price, yield to maturity (YTM), accrued interest, and risk indicators for callable/putable bonds (bonds with embedded options).

optionBond = {
    "productType": "Cash",
    "assetType": "Bond",
    "bondType": "OptionBond",
    "version": 0,
    "instrumentId": "242659.SH",
    "nominal": 100.0,
    "start": 2025.03.26,
    "maturity": 2030.03.26,
    "coupon": 0.0207,
    "frequency": "Annual",
    "exerciseDates": [2028.03.26],
    "hasCallOption": true,
    "hasPutOption": true,
    "hasCouponAdjust": true,
    "dayCountConvention": "ActualActualISMA"
}
ins = parseInstrument(optionBond)

bondInstrumentCalculator(ins, settlement=2025.12.19, price=0.0195216, priceType="YTM", calcRisk=true, benchmark="CSI");

/* Output:
dirtyPrice: 101.9939
cleanPrice: 100.4683
accruedInterest: 1.5256
ytm: 0.0195
yte: 0.0185
macaulayDuration: 2.2056
modifiedDuration: 2.1654
convexity: 6.9085
pvbp: 0.0221
*/

Example 6. Calculate the pre-tax and after-tax prices, yield to maturity, and accrued interest for a fixed-rate bond.

fixedRateBondDict = {
    "productType": "Cash",
    "assetType": "Bond",
    "bondType": "FixedRateBond",
    "start": 2026.04.25,
    "maturity": 2027.04.25,
    "issuePrice": 100.0,
    "coupon": 0.0106,
    "dayCountConvention": "ActualActualISMA",
    "frequency": "Semiannual"
}
fixedRateBond = parseInstrument(fixedRateBondDict);


res = bondInstrumentCalculator(
    fixedRateBond,
    settlement=2026.06.25,
    price=0.0102996,
    priceType="YTM",
    calcRisk=false,
    taxRate=0.0634,
    taxStartDate=2025.08.08
);

res
/*
dirtyPrice: 100.20122678523695
cleanPrice: 100.02456011857029
accruedInterest: 0.17666666666666667
afterTaxDirty: 100.26806073041192
afterTaxClean: 100.09139406374526
afterTaxYtm: 0.009492960236371169
ytm: 0.0102996
*/

Related functions: bondPricer