QuantLib: Coupons

Coupons are special cash flows which accrue interest over a fixed period. There are many different types of coupons but they all share a number of properties. For this reason, the Coupon class defines a number of properties and operations, but it also defines a number of abstract methods which have to be implemented by a specific coupon type.

Coupons are initialised by passing the appropriate values to the constructor

Coupon(const Date& paymentDate,
       Real nominal,
       const Date& accrualStartDate,
       const Date& accrualEndDate,
       const Date& refPeriodStart = Date(),
       const Date& refPeriodEnd = Date());

The parameters are pretty self explanatory, paymentDate is the payment date of the coupon and nominal is the nominal value of the coupon. The start and end of the accrual period are passed in the variables accrualStartDate and accrualEndDate. The ISMA variant of the Actual/Actual day counter will take into account a reference period to calculate the fraction of a year, which is needed to evaluate the accrued amount. This reference period is specified by refPeriodStart and refPeriodEnd. These do not have to be specified if not needed and their default values are empty Date objects.

Since Coupon indirectly inherits from the Event class it has to implement the date() method, which returns the payment date. A list of all methods allowing to read the properties are given here.

Date date() const;
Real nominal() const;
const Date& accrualStartDate() const;
const Date& accrualEndDate() const;
const Date& referencePeriodStart() const;
const Date& referencePeriodEnd() const;

The nominal() method returns the nominal value of the coupon. The two methods accrualStartDate() and accrualEndDate() return the start date and the end date of the accrual period respectively. The reference period start date and end date are returned by the two methods refPeriodStart() and refPeriodEnd(). The CouponĀ also defines three abstract virtual methods.

virtual Real rate() const = 0;
virtual DayCounter dayCounter() const = 0;
virtual Rate accruedAmount(const Date&) const = 0;

The rate() method is intended to return the rate of the coupon and should be implemented by any concrete coupon type. The day counting convention associated with the coupon should be returned by the dayCounter() method. Finally, the amount accrued up to a given date should be returned by the accruedAmount() method.

The remainder of the methods are convenience methods that use the above methods to perform some calculations which are common to all coupons.

Time accrualPeriod() const;
BigInteger accrualDays() const;
Time accruedPeriod(const Date&) const;
BigInteger accruedDays(const Date&) const;

All four methods use the day counter to calculate either a fraction of a year or the number of days between certain dates. The accrualPeriod() method gives the fraction of the year of one accrual period, i.e. between the accrual start date and the accrual end date. Similarly, the accrualDays() method returns the number of days in the accrual period. The accruedPeriod() and the accruedDays() methods return the fraction of a year and the number of days, respectively, between the accrual start date and the date passed as argument. If the date passed to either function does not lie within the accrual period, the functions will return zero.