QuantLib: Dividends

Dividends are a simple form of cash flows in which a predetermined amount of money is paid out at a specified date. There are two types of dividends, the fixed divided and the fractional dividend. The fixed dividend pairs out a fixed amount of money which is specified from the start. The fractional dividend pairs out a fixed percentage of an underlying or a nominal value. QuantLib supplies three classes, the base class Dividend implements the common functionality for the two types of dividend and is derived from the CashFlow class. The class FixedDividend implements fixed dividends and the FractionalDivident implements fractional dividends.

The constructor of the base class Dividend takes only the payment date of the dividend.

Dividend(const Date& date);

The date is stored in the Dividend object and can be inspected by the date() method.

Date date() const;

This method also implements the Event interface which CashFlow inherited from.

virtual Real amount() const = 0;
virtual Real amount(Real underlying) const = 0;

The amount() method is re-declared from the CashFlow class and another amount method is added which takes the value of an underlying entity. Both method are abstract and are implemented by the FixedDividend and the FractionalDividend class.

virtual void accept(AcyclicVisitor&);

The accept() method allows visitation by the acyclic visitor.

FixedDividend

The FixedDividend class implements a dividend with a fixed amount that is paid out at the specified date. The constructor takes the dividend amount and the date.

FixedDividend(Real amount, const Date& date)

Once the FixedDividend object is created, the values cannot be modified. The class implements the two amount() methods.

virtual Real amount() const;
virtual Real amount(Real) const;

Both versions of amount() return the amount passed to the object in the constructor. The value of an underlying is ignored.

A global utility function lets you quickly create an stl:: vector of fixed dividends from a vector of dates and a vector of amounts.

std::vector<boost::shared_ptr<Dividend> >
    DividendVector(const std::vector<Date>& dividendDates,
                   const std::vector<Real>& dividends);

This method will construct FixedDividend objects and store them in a vector of pointers to dividends. Each date is paired with an amount. The two vector containing the dates and values have to contained the same number of elements, otherwise an exception is thrown.

FractionalDividend

The FractionalDividend implements dividend cash flows that amount to a given fraction of the value of an underlying entity. They can be constructed by specifying the rate and the cash flow date, or by additionally specifying a nominal value of the underlying.

FractionalDividend(Real rate, const Date& date);
FractionalDividend(Real rate, Real nominal, const Date& date);

The nominal does not have to be specified if the amount is always calculated using the value of the underlying. Note that, once the object has been created, the object is immutable. In particular, the nominal value cannot be set or changed. The two amount() methods are also implemented.

virtual Real amount() const;
virtual Real amount(Real underlying) const;

The first version uses the nominal value and returns rate * nominal. This version actually implements the CashFlow interface. If the nominal value has not been set in the constructor then an exception is thrown. The second version returns rate * underlying and ignores the nominal value.

Two inspection methods return the values of the rate and the nominal value respectively.

Real rate() const;
Real nominal() const;

An Example

In the following code we construct an array of Dividend cash flows from data contained in a file and then write out the data.

std::ifstream input("dividends.txt");
int day, month, year;
int fixed;
Real value;
Real rate, nominal;
typedef boost::shared_ptr<Dividend> pCashFlow;
std::list<pCashFlow> dividends;
input >> day >> month >> year >> fixed;
while (input) {
  // convert number into a month
  Date d = Date(day,January,year) + (month-1)*Months;
  if (fixed== 1) {
    input >> value;
    pCashFlow dividend(new FixedDividend(value, d));
    dividends.push_back(dividend);
  } else {
    input >> rate >> nominal;
    pCashFlow dividend(new FractionalDividend(rate, nominal, d));
    dividends.push_back(dividend);
  }
  input >> day >> month >> year >> fixed;
}
BOOST_FOREACH(pCashFlow cashFlow, dividends) {
  std::cout << cashFlow->date() << " " << cashFlow->amount() << std::endl;
}

In the example code Dividend objects are read from a data file and inserted into a list of CashFlow objects. The first three columns in the input file specify the payment date of the dividend. The fourth column is a flag that specifies if the dividend is fixed or fractional. For a fixed dividend only one more value is read and stored in the dividend amount. For fractional dividends twovalues are read from the file and passed to the FractionalDividend as rate and nominal value. After reading the data, all the cash flow amounts are written to the console using a loop over the list. Assume that the file dividends.txt contained the following ficticious data

15 1 2013 0 0.09 100.0
15 4 2013 0 0.10 100.0
15 7 2013 0 0.11 100.0
15 10 2013 1 20.0

This produces the output

January 15th, 2013 9
April 15th, 2013 10
July 15th, 2013 11
October 15th, 2013 20