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.

Base Components

Bond.h

class Bond
#include <Bond.h>

The Bond class represents a financial instrument that allows the issuer to borrow money from investors. Created by bernardo on 4/12/18.

Subclassed by BalloonPaymentBond, FloatingInterestBalloonPaymentBond, LevelDebtServiceBond, VariableDebtServiceBond

Public Functions

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

Constructs a Bond object with specified attributes. This function initializes a bond and validates its cost of capital.

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.

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

  • type – The type of bond.

  • begin_repayment_at_issuance – Boolean indicating whether repayment starts immediately upon issuance.

Throws:

std::invalid_argument – If cost_of_capital is NaN or negative.

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

Constructs a Bond object with specified attributes. This function initializes a bond with a coupon rate and validates its cost of capital.

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.

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

  • coupon_rate – The fixed interest rate paid to bondholders each year associated with the bond.

  • type – The type identifier for the bond.

  • begin_repayment_at_issuance – Boolean indicating whether repayment starts immediately upon issuance.

Throws:

std::invalid_argument – If cost_of_capital is NaN or negative.

Bond()

Constructs a default Bond object with uninitialized values. This function initializes a Bond object with placeholder values.

virtual ~Bond()

Destroys the Bond object. This function cleans up resources used by the Bond object.

Bond(const Bond&) = default
virtual double getDebtService(int week) = 0

Gets the debt service for the bond. This function is intended to be overridden in derived classes and is not meant to be called directly on the base Bond class.

Parameters:

week – The week for which to calculate total remaining value of the debt service (accounting for inflation).

Returns:

double The debt service for the bond.

virtual double getPresentValueDebtService(int week, double discount_rate) = 0

Get the Present Value Debt Service object. This function is intended to be overridden in derived classes and is not meant to be called directly on the base Bond class.

Parameters:

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

  • discount_rate – The discount rate to use in the calculation.

Returns:

double The present value of the debt service.

virtual void setDebtService(double updated_allocated_fraction_of_annual_debt_service)

Sets the debt service for the bond. This function is intended to be overridden in derived classes and is not meant to be called directly on the base Bond class.

Parameters:

updated_allocated_fraction_of_annual_debt_service – The updated fraction of the annual debt service allocation.

Throws:

std::logic_error – Always throws an exception when called on the base Bond class.

Returns:

None

virtual int getWaterSourceID()

Returns the bond’s unique identifier. This function retrieves the id of the bond, which serves as its water source ID.

Parameters:

None –

Returns:

int The unique identifier (id) of the bond.

virtual double getNetPresentValueAtIssuance(double discount_rate, int week) const = 0
virtual void issueBond(int week, int construction_time, double bond_term_multiplier, double bond_interest_rate_multiplier)

Issues a bond and adjusts its parameters based on given multipliers. This function sets the repayment start date and modifies bond parameters upon issuance.

See also

Bond::setIssued

Parameters:

  • week – The week when the bond is issued.

  • construction_time – The duration of construction in weeks, used to calculate the repayment start date.

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

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

Returns:

None

virtual void setRealizationWaterSource(unsigned long r, vector<double> &rdm_factors)

Adjusts the bond’s cost of capital based on a realization factor. This function modifies the bond’s cost of capital using a random factor.

See also

Bond::issueBond

Parameters:

  • r – An unsigned long integer representing the realization identifier (not used in the function logic).

  • rdm_factors – A vector of random factors used to adjust the bond’s cost of capital. The first element is used.

Throws:

std::out_of_range – If rdm_factors is empty or does not contain at least one element.

Returns:

None

bool isIssued() const

Checks if the bond has been issued. This function returns whether the bond has been marked as issued.

Parameters:

None –

Returns:

bool true if the bond has been issued; false otherwise.

void setIssued()

Marks the bond as issued. This function sets the issued status of the bond to true.

Parameters:

None –

Returns:

None

double getCostOfCapital()

Returns the cost of capital required to issue the bond. This function retrieves the cost_of_capital of the bond.

Parameters:

None –

Returns:

double The cost of capital (cost_of_capital) of the bond.

void adjustCostOfCapital(double reduction)

Adjusts the bond’s cost of capital by a specified reduction. This function decreases the bond’s cost_of_capital by the given reduction value.

Parameters:

reduction – The amount by which to reduce the bond’s cost_of_capital.

Throws:

std::logic_error – If the adjusted cost_of_capital becomes negative.

Returns:

None

Public Members

const int type

The type of bond.

const vector<int> pay_on_weeks

A vector specifying the weeks when payments are due.

const int id

The unique identifier of the bond.

Protected Attributes

int week_issued

The week the bond was issued.

double cost_of_capital

The cost of capital for the bond.

double coupon_rate

The fixed interest rate paid to bondholders each year, as a percentage of the bond’s face value.

int n_payments

The number of payments to be made on the bond.

int begin_repayment_after_n_years = NON_INITIALIZED

The number of years after issuance that the bond will start being repaid.

Private Members

bool issued = false

A boolean indicating whether the bond has been issued.