Bonds Module

The Bonds submodule contains classes and functions related defining the different financing mechanisms of the water system. It is a submodule of the SystemComponents module.

API Reference

Below is the API reference for the Bonds submodule. Documentation is automatically extracted from the header files.

Submodule Components

BalloonPaymentBond.h

class BalloonPaymentBond : public Bond
#include <BalloonPaymentBond.h>

The BalloonPaymentBond class is a subclass of the main Bond class. This class that represents a balloon bond that pays interest for a number of years and then pays the face value of the bond plus the last interest payment.

Created by bernardo on 4/17/18.

Public Functions

BalloonPaymentBond(const int id, const double cost_of_capital, const int n_payments, const double coupon_rate, vector<int> pay_on_weeks)

Constructs a BalloonPaymentBond object with specified attributes. This function initializes a balloon payment bond with the provided parameters.

Parameters:

  • id – The unique identifier for the bond.

  • cost_of_capital – The cost of capital associated with the bond. Must be non-negative.

  • n_payments – The total number of payments for the bond.

  • coupon_rate – The fixed coupon rate for the bond.

  • pay_on_weeks – A vector specifying the weeks when payments are due.

Returns:

None

BalloonPaymentBond(const int id, const double cost_of_capital, const int n_payments, const double coupon_rate, vector<int> pay_on_weeks, const int begin_repayment_after_n_years)

Constructs a BalloonPaymentBond object with specified attributes, including the repayment start time. This function initializes a balloon payment bond with the provided parameters, including the number of payments and repayment start time.

Parameters:

  • id – The unique identifier for the bond.

  • cost_of_capital – The cost of capital associated with the bond. Must be non-negative.

  • n_payments – The total number of payments for the bond.

  • coupon_rate – The fixed coupon rate for the bond.

  • pay_on_weeks – A vector specifying the weeks when payments are due.

  • begin_repayment_after_n_years – The number of years after which repayment should begin. A value of NONE indicates no specific start time.

Returns:

None

virtual double getDebtService(int week) override

Calculates the debt service for a balloon payment bond at a specific week. This function determines whether a payment is due based on the current week and the bond’s payment schedule. It returns the debt service, which includes interest payments for the period and the principal payment for the final period.

Parameters:

week – The current week for which to calculate the debt service.

Returns:

double The debt service for the given week, including interest payments and principal payment if due.

virtual double getPresentValueDebtService(int week, double discount_rate) override

Calculates the present value of the balloon payment bond’s debt service for a specific week. This function computes the present value of the bond’s debt service based on the interest payments, the principal payment (if due), and the discount rate.

Parameters:

  • week – The current week to calculate the present value of the debt service for.

  • discount_rate – The discount rate used to calculate the present value of the future payments.

Returns:

double The present value of the debt service for the given week.

virtual double getNetPresentValueAtIssuance(double yearly_discount_rate, int week) const override

Calculates the net present value (NPV) of the balloon payment bond at issuance. This function computes the NPV of the bond based on the interest payments and the discount rate. The NPV is calculated using the bond’s payment schedule, adjusting for the time until repayment begins.

Parameters:

  • yearly_discount_rate – The annual discount rate used to calculate the present value of future payments.

  • week – The week of the year to calculate the NPV for, typically the week the bond is issued.

Returns:

double The net present value at issuance of the balloon payment bond.

virtual void issueBond(int week, int construction_time, double bond_term_multiplier, double bond_interest_rate_multiplier) override

Issues the balloon payment bond, initializing the bond parameters and setting the interest payments. This function sets up the bond’s issuance details, including adjusting the interest payments based on the bond’s parameters.

Parameters:

  • week – The week in which the bond is being issued.

  • construction_time – The time it takes to complete the construction associated with the bond, in weeks.

  • bond_term_multiplier – A multiplier for adjusting the term length of the bond.

  • bond_interest_rate_multiplier – A multiplier for adjusting the bond’s interest rate.

Returns:

None

Private Members

double interest_payments

Interest payments for each period.

const int begin_repayment_after_n_years

Number of years after which payments to the bond begins.

int n_payments_made = 0

Number of payments made so far.

FloatingInterestBalloonPaymentBond.h

class FloatingInterestBalloonPaymentBond : public Bond
#include <FloatingInterestBalloonPaymentBond.h>

The FloatingInterestBalloonPaymentBond class is a subclass of the main Bond class. This class that represents a floating interest balloon payment bond that pays interest at a variable, market-benchmarked rate for a number of years and then pays the face value of the bond plus the last interest payment.

Created by bernardo on 4/17/18.

Public Functions

FloatingInterestBalloonPaymentBond(const int id, const double cost_of_capital, const double n_payments, const vector<double> interest_rate_series, vector<int> pay_on_weeks)

Constructs a FloatingInterestBalloonPaymentBond object with specified attributes. This function initializes a floating interest balloon payment bond with the provided parameters.

Parameters:

  • id – The unique identifier for the bond.

  • cost_of_capital – The cost of capital associated with the bond. Must be non-negative.

  • n_payments – The total number of payments for the bond.

  • interest_rate_series – A vector representing the series of interest rates for the bond.

  • pay_on_weeks – A vector specifying the weeks when payments are due.

Returns:

None

FloatingInterestBalloonPaymentBond(const int id, const double cost_of_capital, double n_payments, const vector<double> interest_rate_series, vector<int> pay_on_weeks, const int starts_paying_after_n_years)

Constructs a FloatingInterestBalloonPaymentBond object with specified attributes. This function initializes a floating interest balloon payment bond with the provided parameters and sets the start of repayment after a specified number of years.

Parameters:

  • id – The unique identifier for the bond.

  • cost_of_capital – The cost of capital associated with the bond. Must be non-negative.

  • n_payments – The total number of payments for the bond.

  • interest_rate_series – A vector representing the series of interest rates for the bond.

  • pay_on_weeks – A vector specifying the weeks when payments are due.

  • starts_paying_after_n_years – The number of years after which repayment begins.

Returns:

None

virtual double getDebtService(int week) override

Calculates the debt service for the bond at a specified week. This function computes the bond’s debt service payment based on the floating interest rate at a specific week.

Parameters:

week – The current week for which to calculate the debt service.

Throws:

std::out_of_range – If the interest rate series is shorter than the number of payments made.

Returns:

double The debt service amount for the given week, or 0.0 if no payment is due.

virtual double getPresentValueDebtService(int week, double discount_rate) override

Calculates the present value of the debt service for the bond at a specific week. This function computes the present value of the debt service based on the bond’s floating interest rate and a discount rate for the given week.

FIXME: Check calculation for this class. Clarify what a floating interest bond is.

Parameters:

  • week – The current week for which to calculate the present value of the debt service.

  • discount_rate – The discount rate used to calculate the present value of future payments.

Throws:

std::out_of_range – If the interest rate series is shorter than the number of payments made.

Returns:

double The present value of the debt service for the given week, or 0.0 if no payment is due.

virtual double getNetPresentValueAtIssuance(double yearly_discount_rate, int week) const override

Calculates the net present value (NPV) of the bond at the time of issuance. This function computes the NPV of the bond based on its cost of capital, the interest rate for the given week, and a yearly discount rate.

Parameters:

  • yearly_discount_rate – The yearly discount rate used to calculate the present value.

  • week – The week for which to calculate the NPV.

Returns:

double The net present value of the bond at the time of issuance.

virtual void issueBond(int week, int construction_time, double bond_term_multiplier, double bond_interest_rate_multiplier) override

Issues a floating interest balloon payment bond and adjusts its interest rate series. This function issues the bond and multiplies the entire interest rate series by the provided bond interest rate multiplier.

Parameters:

  • week – The week when the bond is issued.

  • construction_time – The duration of construction in weeks FIXME: not used in this function.

  • bond_term_multiplier – A multiplier to adjust the total number of payments (n_payments).

  • bond_interest_rate_multiplier – A multiplier to adjust the bond’s interest rate series.

Returns:

None

Private Members

vector<double> interest_rate_series

The interest rate time series beginning from week 0 of simulation.

const int begin_repayment_after_n_years

The time after which bond repayment begins.

int n_payments_made = 0

Number of payments made so far.

LevelDebtServiceBond.h

class LevelDebtServiceBond : public Bond
#include <LevelDebtServiceBond.h>

The LevelDebtServiceBond class is a subclass of the main Bond class. This class represents a bond where the total amount of interest paid each year remains relatively constant.

Created by bernardo on 4/12/18.

Public Functions

LevelDebtServiceBond(const int id, const double cost_of_capital, const int n_payments, const double coupon_rate, vector<int> pay_on_weeks, bool begin_repayment_at_issuance = false)

Constructs a LevelDebtServiceBond object with specified attributes. This function initializes a level debt service bond with the provided parameters.

Parameters:

  • id – The unique identifier for the bond.

  • cost_of_capital – The cost of capital associated with the bond. Must be non-negative.

  • n_payments – The total number of payments for the bond.

  • coupon_rate – The fixed coupon rate for the bond.

  • pay_on_weeks – A vector specifying the weeks when payments are due.

  • begin_repayment_at_issuance – Flag indicating whether repayment should begin at issuance.

Returns:

None

~LevelDebtServiceBond() override

Destructor for the LevelDebtServiceBond class. This destructor cleans up the resources associated with the LevelDebtServiceBond object.

Parameters:

None –

Returns:

None

virtual double getDebtService(int week) override

Calculates the debt service for the bond at a specific week. This function computes the bond’s debt service payment based on a level debt service structure, where payments are the same amount for each period.

Parameters:

week – The current week for which to calculate the debt service.

Returns:

double The debt service amount for the given week, or 0.0 if no payment is due.

virtual double getPresentValueDebtService(int week, double discount_rate) override

Calculates the present value of the debt service for the bond at a specific week. This function computes the present value of the debt service payment based on the level debt service structure and a discount rate for the given week.

Parameters:

  • week – The current week for which to calculate the present value of the debt service.

  • discount_rate – The discount rate used to calculate the present value of future payments.

Throws:

None –

Returns:

double The present value of the debt service for the given week, or 0.0 if no payment is due.

virtual double getNetPresentValueAtIssuance(double yearly_discount_rate, int week) const override

Calculates the net present value (NPV) of the bond at the time of issuance. This function computes the NPV of the bond based on its level debt service payments, discount rate, and the number of payments.

Parameters:

  • yearly_discount_rate – The yearly discount rate used to calculate the present value.

  • week – The week for which to calculate the NPV. This is used to adjust for the time of the first payment.

Throws:

None –

Returns:

double The net present value of the bond at the time of issuance.

virtual void issueBond(int week, int construction_time, double bond_term_multiplier, double bond_interest_rate_multiplier) override

Issues a level debt service bond and calculates the level debt service payment. This function issues the bond and calculates the fixed level debt service payment based on the cost of capital, coupon rate, and number of payments.

Parameters:

  • week – The week when the bond is issued.

  • construction_time – The duration of construction in weeks, used to determine when repayment begins.

  • bond_term_multiplier – A multiplier to adjust the total number of payments (n_payments).

  • bond_interest_rate_multiplier – A multiplier to adjust the bond’s coupon rate.

Returns:

None

Private Members

double level_debt_service_payment

The level debt service payment. This amount remains constant over the life of the bond.

int n_payments_made = 0

Number of payments made so far.

VariableDebtServiceBond.h

class VariableDebtServiceBond : public Bond
#include <VariableDebtServiceBond.h>

The VariableDebtServiceBond class is a subclass of the main Bond class. This class represents a bond (typically a municipal bond) where the floating coupon payments are adjusted at specified intervals. This bond is associated with a specific water source.

Public Functions

VariableDebtServiceBond(const int id, const int water_source_id, const double total_unallocated_cost_of_capital, const double initial_fraction_of_allocated_debt, const int n_payments, const double coupon_rate, vector<int> pay_on_weeks, bool begin_repayment_at_issuance = false)

Constructs a variable debt service bond with specified parameters. This constructor initializes the bond with a set of parameters specific to variable debt service bonds, including the bond’s debt allocation and associated water source ID.

Parameters:

  • id – The unique identifier for the bond.

  • water_source_id – The identifier for the water source associated with the bond.

  • total_unallocated_cost_of_capital – The total cost of capital for the bond that has not been allocated yet.

  • initial_fraction_of_allocated_debt – The initial fraction of the allocated debt for the bond.

  • n_payments – The number of payments to be made on the bond.

  • coupon_rate – The interest rate to be applied to the bond’s payments.

  • pay_on_weeks – A vector of weeks in each calendar year when payments are due.

  • begin_repayment_at_issuance – A boolean indicating whether repayment begins at the issuance date.

Returns:

None

~VariableDebtServiceBond() override

Destroys the variable debt service bond object. This destructor cleans up resources associated with the variable debt service bond. It is automatically called when an object of the VariableDebtServiceBond class goes out of scope or is deleted.

Returns:

None

virtual double getDebtService(int week) override

Calculates and returns the debt service payment for a given week. This function calculates the debt service for the bond, checking if repayments are due and handling any corrections if the calculated debt service value is NaN.

Parameters:

week – The week number for which the debt service is to be calculated.

Returns:

double The calculated debt service for the specified week. If no payment is due for the week, returns 0.

virtual double getPresentValueDebtService(int week, double discount_rate) override

Calculates the present value of the debt service for a given week.

This function calculates the present value of the debt service payment for a specific week, taking into account the discount rate. It checks if the bond is in its repayment phase, and if the current week is a designated payment week.

Parameters:

  • week – The current week for which the debt service present value is calculated.

  • discount_rate – The annual discount rate used for present value calculations.

Returns:

double The present value of the debt service for the given week.

virtual double getNetPresentValueAtIssuance(double yearly_discount_rate, int week) const override

Calculates the net present value (NPV) at issuance for the variable debt service bond. This calculation is generally not applicable for a variable rate bond and might require an additional calculation at the end of realization. This method is intended as a placeholder.

Parameters:

  • yearly_discount_rate – The annual discount rate used for the NPV calculation.

  • week – The week number at which the NPV is to be calculated.

Returns:

double The calculated NPV at issuance.

virtual void issueBond(int week, int construction_time, double bond_term_multiplier, double bond_interest_rate_multiplier) override

Issues the bond, initializes bond details, and calculates the variable debt service payment. This method calculates the initial variable debt service payment for the bond based on the bond’s cost of capital, debt fraction, coupon rate, and the number of payments.

Parameters:

  • week – The week when the bond is issued.

  • construction_time – The time (in weeks) it takes to complete construction.

  • bond_term_multiplier – A multiplier that adjusts the term of the bond.

  • bond_interest_rate_multiplier – A multiplier that adjusts the interest rate of the bond.

Returns:

void

virtual void setDebtService(double updated_allocated_fraction_of_annual_debt_service) override

Calculates and updates the variable debt service payment based on the provided allocated fraction of annual debt service. Overrides the virtual base class method.

Parameters:

updated_allocated_fraction_of_annual_debt_service – The new fraction of the annual debt service to be allocated to the bond.

Returns:

void

virtual int getWaterSourceID() override

Retrieves the water source ID associated with the bond. Overrides the virtual base class method.

This function returns the water source ID that is associated with the bond. The ID can be used to track or link the bond to a specific water source.

Returns:

int The water source ID associated with the bond.

Private Members

double variable_debt_service_payment

The value of variable debt service for this bond.

double initial_debt_fraction

The initial fraction of allocated debt.

int water_source_id

The ID of the water source associated with this bond.

int n_payments_made = 0

The number of payments made.