In the section on numeric types in QuantLib, the Rate type was introduced which was intended to hold any kind of rates, including interest rates. The Rate type is essentially a double or a float number, depending on the configuration at the build time of QuantLib. For calculations with interest rates we need to know more than just the floating point number of the rate. We need to know how the interest rate should be compounded and what the frequency of compounding should be. This is handled by the InterestRate class which stores an interest rate and all the relevant information needed to calculate discount factors and compound factors. The class defines two constructors.
InterestRate(); InterestRate(Rate r, const DayCounter& dc, Compounding comp, Frequency freq);
The first constructor is the default constructor that doesn’t take any arguments and creates a null InterestRate object. Note that InterestRate is immutable. This means that after calling the default constructor there is no way to change the interest rate or any other information within the object. For this reason you will almost always want to call the second constructor which takes the rate, a day counter, a compounding method and a frequency. The rate is the annual interest rate. The day counting convention is needed to convert dates to fractions of a year when calculating discount rates. Compounding is an enum which can take the following values
Simple Compounded Continuous SimpleThenCompounded
The compounding parameter has an influence on how the compounding factor is calculated. The fourth parameter specifies the compounding frequency using the Frequency enum. This enum is further described in the section Periods, Time Units and Frequencies.
A number of self explanatory inspection methods give allow reading of the internal variables.
Rate rate() const; const DayCounter& dayCounter() const; Compounding compounding() const; Frequency frequency() const;
An InterestRate object can also be cast directly into the floating point type Rate which is the equivalent of calling the rate() method.
operator Rate() const;
The method that contains the actual calculations are is compoundFactor(). This method calculates the compound factor for a specific time interval
Real compoundFactor(Time t) const; Real compoundFactor(const Date& d1, const Date& d2, const Date& refStart = Date(), const Date& refEnd = Date());
The first version of compoundFactor() takes the time interval measured in years, or fractions thereof. The time interval should be calculated using the same day counting conventions as the InterestRate. The second method is a convenience method. It takes two dates and, if necessary, two reference dates. It uses the day counter’s yearFraction() method to calculate the time interval and then call the first version of compoundFactor() with the resulting time interval. See the discussion of the day counter for the meaning of the date and reference date arguments.
Depending on the compounding method, the compound factor c is calculated in the following way. Here r is the rate, t is the time and f is the frequency.
c = 1 + rt
c = (1+r/f)^(tf)
c = e^(rt)
for t<=1/f: c = 1 + rt
for t > 1/f: c = (1+r/f)^(tf)
The discount factor can be calculated using the discountFactor() methods.
DiscountFactor discountFactor(Time t) const; DiscountFactor discountFactor(const Date& d1, const Date& d2, const Date& refStart = Date(), const Date& refEnd = Date());
Again, the first version of discountFactor() takes a time interval in units of years. The second version takes two dates and, if necessary, two reference dates. The discount factor d is simply the reciprocal of the compound factor, d = 1/c. It is, in fact, calculated using the compoundFactor() method.
It is possible to convert an InterestRate object to another one with a different frequency, compounding rule and/or day counter. This is done by calculating the interest rate in such a way that the converted InterestRate object gives the same compound rate. The result is not unique and depends on the time interval for which the compound rates are chosen. Such a conversion can be made using the equivalentRate() method.
InterestRate equivalentRate(Compounding comp, Frequency freq, Time t) const; InterestRate equivalentRate(const DayCounter& resultDC, Compounding comp, Frequency freq, Date d1, Date d2, const Date& refStart = Date(), const Date& refEnd = Date());
The first version uses a specific time interval and returns an equivalent InterestRate with a different compounding rule and a different frequency. Note that this version does not allow to change the day counting convention. The second version takes a new day counter as well as compounding rule and a frequency. The equivalence is evaluated for a date interval using the respective day counters to convert the dates into time intervals. In both cases the equivalent rate will result in the identical compounding factor or discount factor when evaluated for the specific time interval. For any other time interval the compounding factors will, most likely, be different.
In many cases, such as the above conversion, one has a compound rate and is looking for an interest rate with a specific day counter, compounding rule and frequency that will produce the known compound rate. This is taken care of by the static method impliedRate() provided by the InterestRate class.
static InterestRate impliedRate(Real compound, const DayCounter& resultDC, Compounding comp, Frequency freq, Time t); static InterestRate impliedRate(Real compound, const DayCounter& resultDC, Compounding comp, Frequency freq, const Date& d1, const Date& d2, const Date& refStart = Date(), const Date& refEnd = Date());
As with the other methods, there are two versions. The first taking a time interval and the second taking a number of dates. The two static methods will return an object of type InterestRate, with a given day counting convention, frequency and compounding rule. The ineterst rate will reproduce the value compound when the compoundRate() method is called with the same time or date arguments for which the object was created.