QuantLib Python聊聊(三) : 關於物件IborCoupon

更新於 2025/05/04發佈於 2025/05/04閱讀時間約 17 分鐘

前言

在利率交換（IRS）或債券產品中，浮動利率利息（Floating Rate Interest）往往是根據某種銀行間拆款(Interbank Bank Offering Rate, IBOR) 指標利率（如過往的USD LIBOR、TAIBOR、HIBOR）來決定。QuantLib 提供的 IborCoupon 就是這類浮動利率利息的核心實作類別。

本篇文章將深入介紹 IborCoupon 在 QuantLib Python 中的使用方式、內部邏輯與注意事項。

基本結構與建構方式

IborCoupon 是 FloatingRateCoupon 的子類別，專門處理根據IBOR指標利率（如TAIBOR、HIBOR等）的浮動利息計算。

Python 建構語法：

ql.IborCoupon(
    paymentDate,              # 利息支付日
    nominal,                  # 本金
    startDate,                # 計息起日
    endDate,                  # 計息終日
    fixingDays,               # fixing提前天數
    iborIndex,                # ql.IborIndex類別
    gearing=1.0,              # 利率槓桿倍數
    spread=0.0,               # 利率加碼
    refPeriodStart=ql.Date(), # 計息區間參考起日
    refPeriodEnd=ql.Date(),   # 計息區間參考終日
    dayCounter=ql.Actual360(),# 計息方式
    isInArrears=False         # 期末利率比價 
)

手動設定Pricer `.setPricer()`

IborCoupon 必須明確設定 Pricer 才能正確計算利息金額 :

coupon.setPricer(ql.BlackIborCouponPricer())

這是由於在QuantLib的設計中，都會物件將進行解構拆開，利於程式的維護與功能的延伸。像此處的例子，便是將利息(現金流)物件(IborCoupon)與計算方式(BlackIborCouponPricer)分開設計，目的就是假如未來有發展出新的利息計算方式，程式這邊僅需去延伸實作出新的Pricer即可，不用去更動到原始已經存在的利息物件，架構上也沒有任何需要異動之處。這邊的利息計算，並沒有利率上/下限(Cap/Floor)的特徵，因此無須用到波動率(Volatility)的市場資料，所以在計算一般利息時給定pricerBlackIborCouponPricer即可。利息的計算公式為如下常見的方式:

QuantLib Python 程式範例

我們以TWD TAIBOR利率指標為範例來進行說明。首先定義TAIBOR Index 類別(當然也可以直接使用QuantLib Python中的IborIndex類別):

import QuantLib as ql

class TAIBOR(ql.IborIndex):
    def __init__(self, tenor=ql.Period("3M"), 
                 yield_curve=ql.RelinkableYieldTermStructureHandle()):
        family_name = "TAIBOR"
        fixing_days = 2
        currency = ql.TWDCurrency()
        calendar = ql.Taiwan()
        convention = ql.ModifiedFollowing
        end_of_month = False
        day_counter = ql.Actual365Fixed()

        super().__init__(
            family_name,
            tenor,
            fixing_days,
            currency,
            calendar,
            convention,
            end_of_month,
            day_counter,
            yield_curve
        )

利用QuantLib Python已經建立好的類別IborCoupon來直接進行利息的計算:

# set rate fixing Date
fixing_Date = ql.Date(7, 4, 2025)
# create TAIBOR instance
taibor3m = TAIBOR()
# get value date based on USDLibor object
value_date = taibor3m.valueDate(fixing_Date)
# get maturity date based on USDLibor object
maturity_date = taibor3m.maturityDate(value_date)
# add fixing (or reset) rate to current coupon period.
taibor3m.addFixing(fixing_Date, 0.05)
# create IborCoupon object
float_coupon = ql.IborCoupon(
    maturity_date, 
    1000000.0, 
    value_date, 
    maturity_date, 
    taibor3m.fixingDays(), 
    taibor3m)
# set Coupon Pricer for the coupon
float_coupon.setPricer(ql.BlackIborCouponPricer())
coupon = float_coupon.amount()

print(f'start date: {value_date.ISO()}')
print(f'maturity date: {maturity_date.ISO()}')
print(f"coupon interest: TWD {coupon:,.2f}")

start date: 2025-04-09
maturity date: 2025-07-09
coupon interest: TWD 12,465.75

上面的範例說明，假設在2025/4/7這天決價日，我們已知當期TAIBOR的利率水準，因此透過IborCoupon物件，可以很快地計算出這期間(2025/4/9~2025/7/9)的利息金額為12,465.75。

遠期利息的計算

上面的例子是我們已經知道當期的利率水準，若想要知道未來的利息數字為何時，則我們需要藉助利率指標所連結的利率曲線(Yield Term Structure)來計算。在這邊為了簡化說明，我們先假定利率指標連結的是一條平坦的利率曲線(Flat Forward curve)，然後直接透過QuantLib Python中已經定義好取得遠期利率(forward rate)的邏輯公式來計算利息，範例程式如下:

# setup curve reference date
reference_date = ql.Date(7, 4, 2025)
# assume a flat interest rate curve
flat_curve = ql.FlatForward(reference_date, 0.05, ql.Actual365Fixed())
flat_ts = ql.YieldTermStructureHandle(flat_curve)
# initialize TABIOR index with flat curve for simplicity
taibor_3m = TAIBOR(ql.Period('3M'), flat_ts)
# future coupon start date and end date
cpn_start = ql.Date(9, 5, 2025)
cpn_end = ql.Date(9, 8, 2025)
# create IborCoupon object
float_coupon = ql.IborCoupon(
    cpn_end, 
    1000000.0, 
    cpn_start, 
    cpn_end, 
    2, 
    taibor_3m)
# set Coupon Pricer for the coupon
float_coupon.setPricer(ql.BlackIborCouponPricer())
coupon = float_coupon.amount()
print(f'start date: {cpn_start.ISO()}')
print(f'maturity date: {cpn_end.ISO()}')
print(f'forward interest rate: {float_coupon.rate()}')
print(f"coupon interest: TWD {coupon:,.2f}")

start date: 2025-05-09
maturity date: 2025-08-09
forward interest rate: 0.050323304015461014
coupon interest: TWD 12,684.23

上面的範例說明，在遠期時點2025/5/9日至2025/8/9這期間，TAIBOR的預估利率為約5.0323%以及利息金額為12,684.23。

其他參數說明

再生成IborCoupon物件時，有額外兩個參考日期參數-refPeriodStart與refPeriodEnd，這兩參數主要是搭配當Daycounter選擇的是Act/Act(ISMA)時使用，如此才會計算正確的利息計息區間與利息數字。

(詳細可以參考這篇ISDA說明 )

www.isda.org

start = ql.Date(15, 1, 2025) # short stub period-start
end = ql.Date(1, 3, 2025)    # short stub period-end
ref_start = ql.Date(1, 1, 2025) # regular reference period-start
ref_end = ql.Date(1, 4, 2025)   # regular reference period-end

taibor3m.addFixing(ql.Date(13, 1, 2025), 0.045)

float_coupon = ql.IborCoupon(
    paymentDate=end,
    nominal=1_000_000,
    startDate=start,
    endDate=end,
    fixingDays=2,
    index=taibor3m,
    refPeriodStart=ref_start,
    refPeriodEnd=ref_end,
    dayCounter=ql.ActualActual(ql.ActualActual.ISMA)
)

float_coupon.setPricer(ql.BlackIborCouponPricer())
coupon = float_coupon.amount()
print(f"start date: {start.ISO()}")
print(f'end date: {end.ISO()}')
print(f"coupon interest: TWD {coupon:,.2f}")

start date: 2025-01-15
end date: 2025-03-01
coupon interest: TWD 5,625.00

所以計息區間是stub時，且要使用Daycounter為Act/Act(ISMA)時，記得在IborCoupon中給定相應的計息參考區間，否則會得到未預期的利息數字(如下範例)!

# when daycounter with Act/Act(ISMA) method, but didn't give regular reference period
# the coupon interest would be unexpected.
float_coupon_2 = ql.IborCoupon(
    paymentDate=end,
    nominal=1_000_000,
    startDate=start,
    endDate=end,
    fixingDays=2,
    index=taibor3m,
    dayCounter=ql.ActualActual(ql.ActualActual.ISMA)
)

float_coupon_2.setPricer(ql.BlackIborCouponPricer())
coupon = float_coupon_2.amount()
print(f"Accrued interest: TWD {coupon:,.2f}")

Accrued interest: TWD 3,750.00

最後isInArrears 是 IborCoupon 中一個重要且與產品設計密切相關的參數，它控制的是利率重設「fixing」的時機點，預設值為False:

isInArrears = False：代表利率在期間開始日就已知（即 fixing in advance）
isInArrears = True：代表利率在期間結束日才知道（即 fixing in arrears ）

當金融商品利率指標為IBOR，且是fixing in arrear的情況下，遠期利率(forward rate)的計算不再是簡單的公式，需借助模型來進一步調整，這部份涉及到背後一些財務數學理論，之後再寫一篇文章來介紹這內容。

結語

IborCoupon 是 QuantLib中建構浮動利率產品（如利率交換、浮動債券）最核心的元素之一。在這篇文章中我們快速地介紹說明該如何生成使用這物件，同時也提到影響利息計算內容的參數，例如refPeriodStart / refPeriodEnd 的設定邏輯與isInArrears 對利率比價時機的影響，以及提醒搭配setPricer()的方法。下一篇文章我們將介紹另一個重要的Floating Rate Coupon的物件 - OvernightIndexCoupon。

參考資料

Ballabio, Luigi. Implementing QuantLib. Online resource
Goutham Balaraman, Luigi Ballabio. QuantLib Python Cookbook. Leanpub, 2020. https://leanpub.com/quantlibpythoncookbook

QuantivorQuantLib Python聊聊基本概念與使用

留言

留言分享你的想法！

Quantivor

1會員

10內容數

在金融市場中，從外匯、利率交換、選擇權，到複雜結構型商品，每一種商品背後，都仰賴嚴謹的模型運算與穩定的計算工具。QuantLib 作為一套專為金融商品設計的開源程式庫，提供了從定價模型、利率與波動率曲線到風險分析的完整能力，讓理論走向實務。透過這裡跟大家分享如何使用QuantLib-Python這強大的工具。

你可能也想看