Utility Module

The Utility module contains classes and functions related defining the utilities of the water system. It is a submodule of the SystemComponents module.

API Reference

Below is the API reference for the Utility submodule.

Base Components

InfrastructureManager.h

class InfrastructureManager

#include <InfrastructureManager.h>

The InfrastructureManager class manages the construction, sequencing, and financial aspects of infrastructure projects.

Created by Bernardo on 4/4/2018.

Public Functions

InfrastructureManager(int id, const vector<double> &infra_construction_triggers, const vector<vector<int>> &infra_if_built_remove, double infra_discount_rate, double bond_term, double bond_interest_rate, vector<int> rof_infra_construction_order, vector<int> demand_infra_construction_order)

Constructs an InfrastructureManager object.

This constructor initializes an instance of the InfrastructureManager class, setting up various vectors and financial parameters required for managing infrastructure construction, sequencing, and financial adjustments.

See also

InfrastructureManager::rearrangeInfraRofVector() for rearranging the construction triggers to match construction order.

Parameters:

id – The unique identifier for the infrastructure manager.
infra_construction_triggers – A vector of thresholds that trigger infrastructure construction, ordered by both ROF and demand-based projects.
infra_if_built_remove – A 2D vector that determines which infrastructure should be removed from the queue once other infrastructure projects are built.
infra_discount_rate – The discount rate applied to the infrastructure’s financial calculations.
bond_term – The term of the bond used for financing infrastructure projects.
bond_interest_rate – The interest rate applied to the bond financing the infrastructure projects.
rof_infra_construction_order – A vector representing the order of infrastructure projects based on ROF.
demand_infra_construction_order – A vector representing the order of infrastructure projects based on demand.

InfrastructureManager(): Basic constructor a new Infrastructure Manager object.

InfrastructureManager &operator=(const InfrastructureManager &infrastructure_manager)

An assignment operator that copies the values of the infrastructure manager object to another infrastructure manager object.

Parameters:: infrastructure_manager – The InfrastructureManager object to be copied
Returns:: InfrastructureManager& A reference to the new InfrastructureManager object

InfrastructureManager(InfrastructureManager &infrastructure_manager)

Constructs a new Infrastructure Manager object from an existing Infrastructure Manager object.

Parameters:: infrastructure_manager – A reference to the InfrastructureManager object to be copied

vector<double> rearrangeInfraRofVector(const vector<double> &infra_construction_triggers, const vector<int> &rof_infra_construction_order, const vector<int> &demand_infra_construction_order)

Rearranges the infrastructure construction trigger vector to match the specified order of construction based on ROF and demand.

This function takes the infrastructure construction triggers and reorders them according to the specified order of infrastructure construction for both ROF (Reliability of Supply) and demand-based projects. It ensures that the construction triggers are applied correctly to each infrastructure, respecting the prioritization of ROF-based projects followed by demand-based projects.

FIXME: THIS DOESN’T WORK IF A UTILITY HAS BOTH ROF AND DEMAND TRIGGERED INFRASTRUCTURE FIXME: AND THERE ARE NOT AN EQUAL NUMBER OF EACH

See also

InfrastructureManager::rearrangeInfraRofVector() for details on how triggers are adjusted and applied in the construction process.

Parameters:

infra_construction_triggers – A vector of construction triggers (thresholds) for infrastructure.
rof_infra_construction_order – A vector representing the order of infrastructure projects based on ROF.
demand_infra_construction_order – A vector representing the order of infrastructure projects based on demand.

Throws:

invalid_argument – if a source is triggered by both ROF and demand.

Returns:

A reordered vector of construction triggers that matches the infrastructure construction order for both ROF and demand projects.

void setWaterSourceOnline(unsigned int source_id, int week, double &total_storage_capacity, double &total_treatment_capacity, double &total_available_volume, double &total_stored_volume)

Identifies the type of water source and sets a water source online and updates related capacities and volumes.

This function activates a specified water source and categorizes it as either priority or non-priority. It also handles special cases such as new water treatment plants, reservoir expansions, and source relocations. The function updates total storage capacity, treatment capacity, available volume, and stored volume for all active water sources.

See also

waterTreatmentPlantConstructionHandler

See also

reservoirExpansionConstructionHandler

See also

sourceRelocationConstructionHandler

See also

intakeExpansionConstructionHandler

Parameters:

source_id – The unique identifier of the water source to be set online.
week – The current week, used to track the activation time of the water source.
total_storage_capacity – A reference to the total storage capacity of all active sources, updated after the function execution.
total_treatment_capacity – A reference to the total treatment capacity of all active sources, updated after the function execution.
total_available_volume – A reference to the total available volume of all active sources, updated after the function execution.
total_stored_volume – A reference to the total stored volume of all active sources, updated after the function execution.

void waterTreatmentPlantConstructionHandler(unsigned int source_id, double &total_storage_capacity)

Handles the construction of a water treatment plant and updates the associated water source’s capacity and priority lists.

This function manages the expansion of a water treatment plant by adding treatment capacity to the associated water source. It also ensures the source is appropriately categorized as either a priority or non-priority source and updates the priority and non-priority lists accordingly.

See also

SequentialJointTreatmentExpansion

Parameters:

source_id – The unique identifier of the water source for which the treatment plant is being expanded.
total_storage_capacity – A reference to the total storage capacity, which is updated if the source is added to the priority list.

Throws:

std::runtime_error – If the treatment capacity cannot be added to the parent reservoir.

void reservoirExpansionConstructionHandler(unsigned int source_id)

Handles the construction of a reservoir expansion by adding capacity to its parent reservoir.

This function manages the logic for integrating a reservoir expansion into the system. It dynamically casts the specified water source to a ReservoirExpansion type, adds its allocated capacity to the associated parent reservoir, and marks the reservoir expansion as online.

See also

ReservoirExpansion

See also

WaterSource::addCapacity

See also

WaterSource::setOnline

Parameters:: source_id – The unique identifier of the reservoir expansion source.
Throws:: std::bad_cast – If the specified source_id does not correspond to a ReservoirExpansion type.

void sourceRelocationConstructionHandler(unsigned int source_id)

Handles the relocation of a water source by updating its allocation fractions and activating it.

This function manages the process of relocating a water source by adjusting the allocation fractions for its parent reservoir and marking the relocation source as online.

See also

Relocation

See also

WaterSource::resetAllocations

See also

WaterSource::setOnline

Parameters:: source_id – The unique identifier of the relocation source to be processed.
Throws:: std::bad_cast – If the specified source_id does not correspond to a Relocation type.

void removeRelatedSourcesFromQueue(int next_construction)

Checks if piece of infrastructure to be built next prevents another one from being build. If yes, remove the latter from the queue.

This function ensures that dependent or redundant infrastructure projects are removed from the construction queues (rof_infra_construction_order and demand_infra_construction_order) when a specific project (next_construction) is scheduled.

See also

Utils::removeIntFromVector

Parameters:: next_construction – The identifier of the infrastructure project that is scheduled for construction.

int infrastructureConstructionHandler(double long_term_rof, int week, double past_year_average_demand, double &total_storage_capacity, double &total_treatment_capacity, double &total_available_volume, double &total_stored_volume)

Handles the initiation, progression, and completion of infrastructure construction based on demand and reliability triggers. Also handles the accounting and financing of the infrastructure.

This function manages the construction of infrastructure projects based on demand and long-term reliability of failure (ROF) metrics. It ensures infrastructure is built when thresholds are exceeded, and sets completed projects online while updating the relevant system capacities.

Parameters:

long_term_rof – The long-term reliability of failure metric used to trigger construction of infrastructure.
week – The current simulation week.
past_year_average_demand – The average demand observed in the past year, used to trigger demand-based projects.
total_storage_capacity – [out] Updates the total storage capacity of all active water sources.
total_treatment_capacity – [out] Updates the total treatment capacity of all active water sources.
total_available_volume – [out] Updates the total available volume of all active water sources.
total_stored_volume – [out] Updates the total stored volume of all active water sources.

Throws:

<tt>logic_error</tt> – if a completed project is not found in either construction queue.

Returns:

The ID of the infrastructure project triggered for construction, or NON_INITIALIZED if none were triggered.

void forceInfrastructureConstruction(int week, vector<int> new_infra_triggered)

Forces the construction of specified infrastructure options for all other utilities if they are in the queue.

This function checks if the specified infrastructure options are present in the queue of infrastructure to be built (rof_infra_construction_order). If so, it forces their construction by calling beginConstruction.

This function also handles infrastructure triggered by other utilities if the options exist in this utility’s construction queue.

FIXME: The function currently includes a placeholder for triggering related infrastructure in sequence (marked as FIXME).

See also

beginConstruction

Parameters:

week – The current simulation week.
new_infra_triggered – A vector containing the IDs of the infrastructure options that need to be forced into construction.

void beginConstruction(int week, int infra_id)

Initiates the construction of the specified infrastructure and records the start and end dates.

This function starts the construction process for a given infrastructure by marking it as “under construction” and calculating its construction end date. Additionally, it ensures that any conflicting infrastructure options are removed from the construction queue if necessary.

See also

removeRelatedSourcesFromQueue

Parameters:

week – The current simulation week.
infra_id – The ID of the infrastructure that is to be constructed.

Throws:

out_of_range – If the infrastructure ID is not valid or not found in the infrastructure manager.

void addWaterSourceToOnlineLists(int source_id, double &total_storage_capacity, double &total_treatment_capacity, double &total_available_volume, double &total_stored_volume)

Adds a water source to the utility’s online lists and updates the relevant capacity and volume totals.

This function adds the specified water source to either the priority or non-priority list of online sources, depending on the source type. It also updates the total storage capacity, treatment capacity, available volume, and stored volume for the utility.

Parameters:

source_id – The ID of the water source to be added to the online lists.
total_storage_capacity – The total storage capacity of the utility, updated by this function.
total_treatment_capacity – The total treatment capacity of the utility, updated by this function.
total_available_volume – The total available volume of water in the utility, updated by this function.
total_stored_volume – The total stored volume of water in the utility, updated by this function.

void addWaterSource(WaterSource *water_source)

Adds a water source to the construction management system.

This function checks if the ID of the water source exceeds the current size of the under_construction list. If so, it resizes the under_construction and construction_end_date vectors to accommodate the new water source.

Parameters:: water_source – A pointer to the WaterSource object to be added to the system.

void connectWaterSourcesVectorsToUtilitys(vector<WaterSource*> &water_sources, vector<int> &priority_draw_water_source, vector<int> &non_priority_draw_water_source)

Connects the provided water source vectors to the utility.

This function establishes references to the provided vectors of water sources, priority draw water sources, and non-priority draw water sources. These references are stored in the utility class for later use.

Parameters:

water_sources – A reference to the vector of WaterSource objects.
priority_draw_water_source – A reference to the vector containing the IDs of priority water sources.
non_priority_draw_water_source – A reference to the vector containing the IDs of non-priority water sources.

const vector<bool> &getUnder_construction() const

Retrieves the list of infrastructure construction statuses.

This function returns a constant reference to the under_construction vector, which contains the status (true or false) for each infrastructure item, indicating whether it is currently under construction.

Returns:: A constant reference to the vector containing the construction status of each infrastructure item.

void intakeExpansionConstructionHandler(unsigned int source_id)

Handles the construction of an intake expansion.

This function processes the construction of an intake expansion. It updates the parent intake’s capacity and treatment capacity based on the values from the intake expansion and sets the intake expansion as online.

FIXME: [July 2019]:There may be an issue here if this were to be used for an allocated source where it mattered what utility ID was associated with the increase in treatment capacity but this addTreatmentCapacity function is not overrode within the Intake or IntakeExpansion class so it should be fine

Parameters:: source_id – The ID of the intake expansion water source.

void waterTreatmentPlantJointConstructionHandler(unsigned int source_id, double &total_storage_capacity)

Handles the construction of a joint water treatment plant (WTP) with either fixed or variable treatment allocations.

This function handles the construction process of a joint water treatment plant (WTP), including updating the treatment capacity of the associated parent reservoir. It sets the water treatment plant and the associated parent reservoir online. The function accounts for both fixed and variable allocation types for joint WTPs.

See also

InfrastructureManager::addWaterSourceToOnlineLists() for related water source handling and online status setting.

Parameters:

source_id – The ID of the joint water treatment plant being constructed.
total_storage_capacity – The total storage capacity to be updated during the process.

Throws:

runtime_error – If there is an issue adding treatment capacity to the reservoir.
logic_error – If the water treatment plant type is not recognized.

void allocatedIntakeExpansionConstructionHandler(unsigned int source_id)

Handles the construction of an allocated intake expansion and updates related capacities.

This function manages the construction process of an allocated intake expansion. It updates the parent intake with the new allocated capacity and treatment capacity, then sets the intake expansion source online.

See also

InfrastructureManager::addWaterSourceToOnlineLists() for related handling of water sources and setting online status.

Parameters:: source_id – The ID of the allocated intake expansion being constructed.
Throws:: runtime_error – If there is an issue adding capacity or treatment capacity to the parent intake.

void checkForSequenceProjects(int original_build_id)

Checks if a water source is part of a sequence of projects and adjusts capital costs based on the sequence.

This function checks if the given water source is part of a sequence of infrastructure projects. If so, it ensures that the previous parts of the sequence have been built or are under construction. If the prior projects are already completed, the current project’s capital costs are adjusted accordingly.

See also

InfrastructureManager::waterTreatmentPlantJointConstructionHandler() for related project construction handling.

Parameters:: original_build_id – The ID of the water source to check and adjust costs for.
Throws:: logic_error – If a project in the sequence is found but its construction status is undetermined.

const vector<int> &getRof_infra_construction_order() const

Retrieves the list of water sources in the ROF infrastructure construction order.

This function returns a constant reference to the rof_infra_construction_order vector, which contains the list of water sources in the order they are to be constructed based on the ROF (Reliability of Flow) criteria.

Returns:: A constant reference to the vector containing the order of infrastructure construction based on ROF.

const vector<int> &getDemand_infra_construction_order() const

Retrieves the list of water sources in the demand infrastructure construction order.

This function returns a constant reference to the demand_infra_construction_order vector, which contains the list of water sources in the order they are to be constructed based on demand criteria.

Returns:: A constant reference to the vector containing the order of infrastructure construction based on demand.

const vector<int> &getInfra_built_last_week() const

Retrieves the list of infrastructure built in the last week.

This function returns a constant reference to the infra_built_last_week vector, which contains the information about the infrastructure that was completed in the previous week, including the utility ID, the week of completion, and the infrastructure ID.

Returns:: A constant reference to the vector containing information about the infrastructure built in the last week.

Private Members

int id: An integer representing the ID of the infrastructure option.

vector<double> infra_construction_triggers: A vector of doubles storing the ROF trigger values for infrastructure construction.

vector<int> *priority_draw_water_source: A pointer to the vector of integers storing the ID sequence of water sources to be utilized for fulfilling water demand.

vector<int> *non_priority_draw_water_source: A pointer to the vector of integers storing the IDs for water sources that are not prioritized for water demand fulfillment. Allocation of demand is executed proportionally to the available capacity of these sources.

vector<vector<int>> infra_if_built_remove: A 2D vector of integers storing the IDs of infrastructure options to be removed if a given infrastructure option is built.

vector<WaterSource*> *water_sources: A pointer to the vector of WaterSource pointers storing all water sources that supply water to a specific supply infrastructure.

double infra_discount_rate: A double representing the discount rate for infrastructure construction.

double bond_term: A double representing the term of the bond for infrastructure construction.

double bond_interest_rate: A double representing the interest rate for the bond for infrastructure construction.

vector<int> rof_infra_construction_order: A vector representing the order of infrastructure projects based on long-term ROFs.

vector<int> demand_infra_construction_order: A vector representing the order of infrastructure projects based on demand.

vector<int> infra_built_last_week: A vector of integers recording the ID, week of completion, and new water supply source (WSS) for an infrastructure option (utility_id, week, new source id)

vector<int> construction_end_date: A vector of integers corresponding to the vector of infrastructure options indicating the week in which each infrastructure option’s construction was completed. Indexed using the infrastructure ID number.

vector<bool> under_construction: A vector of booleans storing whether each infrastructure option is currently under construction. Indexed using the infrastructure ID number.

double infra_net_present_cost = NONE: A double representing the net present cost of the infrastructure option.

Utility.h

class Utility

#include <Utility.h>

The Utility class manages the water supply, demand, financial, and ROF aspects of a utility. It also handles all its connected water sources.

Created by Bernardo on 1/13/17.

Public Functions

Utility(const char *name, int id, vector<vector<double>> &demands_all_realizations, vector<double> &annual_demand_projections, int number_of_week_demands, const double percent_contingency_fund_contribution, const double contingency_fund_cap, const vector<vector<double>> &typesMonthlyDemandFraction, const vector<vector<double>> &typesMonthlyWaterPrice, WwtpDischargeRule wwtp_discharge_rule, double demand_buffer, int demand_projection_forecast_length, int demand_projection_historical_period_to_use, int demand_projection_reprojection_frequency)

Main constructor (14-parameter) for a Utility object with specified attributes and initializes its parameters.

This constructor sets up the Utility instance with various properties related to water demand, pricing, contingency funds, and infrastructure financing. It also computes the weekly average water prices based on monthly demand fractions and water price types.

See also

Utility::calculateWeeklyAverageWaterPrices for details on the computation of weekly average water prices.

Parameters:

name – The name of the utility.
id – The unique identifier for the utility.
demands_all_realizations – A reference to a vector of weekly demand data for all realizations.
annual_demand_projections – A reference to a vector of annual demand projections.
number_of_week_demands – The number of weekly demand entries.
percent_contingency_fund_contribution – Percentage contribution to the contingency fund.
contingency_fund_cap – The maximum allowed value of the contingency fund.
typesMonthlyDemandFraction – A reference to a vector of vectors containing monthly demand fractions by water type. Table of size 12 (months in year) by number of consumer tiers with the fraction of the total demand consumed by each tier in each month of the year. The last column must be the fraction of the demand treated as sewage. The summation of all number in a row but the last one, therefore, must sum to 1.
typesMonthlyWaterPrice – A reference to a vector of vectors containing monthly water prices by tier type. The last column is the price charged for waste water treatment.
wwtp_discharge_rule – The rule governing wastewater treatment plant discharges. A 53-week-long time series according to which fractions of sewage is discharged in different water sources (normally one for each WWTP).
demand_buffer – A buffer for smoothing demand projections.
demand_projection_forecast_length – Length of the forecast period for demand projections (in weeks).
demand_projection_historical_period_to_use – Historical period (in weeks) used for demand projection.
demand_projection_reprojection_frequency – Frequency (in weeks) for updating demand projections.

Utility(const char *name, int id, vector<vector<double>> &demands_all_realizations, vector<double> &annual_demand_projections, int number_of_week_demands, const double percent_contingency_fund_contribution, const vector<vector<double>> &typesMonthlyDemandFraction, const vector<vector<double>> &typesMonthlyWaterPrice, WwtpDischargeRule wwtp_discharge_rule, double demand_buffer, const vector<int> &rof_infra_construction_order, const vector<int> &demand_infra_construction_order, const vector<double> &infra_construction_triggers, double infra_discount_rate, double bond_term, double bond_interest_rate)

The constructor (16-parameter) for a Utility object for when there is infrastructure to be built.

This constructor sets up a Utility with specified attributes and initializes its parameters and infrastructure manager. Sets up the Utility instance, initializes water demand, pricing, and financial properties, and integrates infrastructure construction management functionality. It also computes weekly average water prices and ensures the provided parameters are valid.

See also

Utility::calculateWeeklyAverageWaterPrices for details on the computation of weekly average water prices.

See also

InfrastructureManager for details on infrastructure construction management.

Parameters:

name – The name of the utility.
id – The unique identifier for the utility.
demands_all_realizations – A vector of weekly demand data for all realizations.
annual_demand_projections – A vector of annual demand projections.
number_of_week_demands – The number of weekly demand entries.
percent_contingency_fund_contribution – Percentage contribution to the contingency fund.
typesMonthlyDemandFraction – A reference to a vector of vectors containing monthly demand fractions by water type. Table of size 12 (months in year) by number of consumer tiers with the fraction of the total demand consumed by each tier in each month of the year. The last column must be the fraction of the demand treated as sewage. The summation of all number in a row but the last one, therefore, must sum to 1.
typesMonthlyWaterPrice – A reference to a vector of vectors containing monthly water prices by tier type. The last column is the price charged for waste water treatment.
wwtp_discharge_rule – The rule governing wastewater treatment plant discharges. A 53-week-long time series according to which fractions of sewage is discharged in different water sources (normally one for each WWTP).
demand_buffer – A buffer for smoothing demand projections.
rof_infra_construction_order – A vector defining the ROF-based construction order for infrastructure.
demand_infra_construction_order – A vector defining the demand-based construction order for infrastructure.
infra_construction_triggers – A vector of construction triggers for infrastructure projects.
infra_discount_rate – The discount rate applied to infrastructure construction costs.
bond_term – The term of infrastructure bonds.
bond_interest_rate – The interest rate for infrastructure bonds.

Throws:

std::invalid_argument – If both construction order vectors are empty.
std::invalid_argument – If the infrastructure discount rate is less than or equal to zero.

Utility(const char *name, int id, vector<vector<double>> &demands_all_realizations, vector<double> &annual_demand_projections, int number_of_week_demands, const double percent_contingency_fund_contribution, const double contingency_fund_cap, const vector<vector<double>> &typesMonthlyDemandFraction, const vector<vector<double>> &typesMonthlyWaterPrice, WwtpDischargeRule wwtp_discharge_rule, double demand_buffer, const vector<int> &rof_infra_construction_order, const vector<int> &demand_infra_construction_order, const vector<double> &infra_construction_triggers, double infra_discount_rate, const vector<vector<int>> &infra_if_built_remove, double bond_term, double bond_interest_rate, int demand_projection_forecast_length, int demand_projection_historical_period_to_use, int demand_projection_reprojection_frequency)

The constructor (21-parameter) for a Utility object for when there is infrastructure to be built.

This constructor sets up a Utility with specified attributes and initializes its parameters and infrastructure manager. Sets up the Utility instance, initializes water demand, pricing, and financial properties, and integrates infrastructure construction management functionality. It also computes weekly average water prices and ensures the provided parameters are valid.

See also

Utility::calculateWeeklyAverageWaterPrices for details on the computation of weekly average water prices.

See also

InfrastructureManager for details on infrastructure construction management.

Parameters:

name – The name of the utility.
id – The unique identifier for the utility.
demands_all_realizations – A vector of weekly demand data for all realizations.
annual_demand_projections – A vector of annual demand projections.
number_of_week_demands – The number of weekly demand entries.
percent_contingency_fund_contribution – Percentage contribution to the contingency fund.
contingency_fund_cap – The maximum allowed value of the contingency fund.
typesMonthlyDemandFraction – A reference to a vector of vectors containing monthly demand fractions by water type. Table of size 12 (months in year) by number of consumer tiers with the fraction of the total demand consumed by each tier in each month of the year. The last column must be the fraction of the demand treated as sewage. The summation of all number in a row but the last one, therefore, must sum to 1.
typesMonthlyWaterPrice – A reference to a vector of vectors containing monthly water prices by tier type. The last column is the price charged for waste water treatment.
wwtp_discharge_rule – The rule governing wastewater treatment plant discharges. A 53-week-long time series according to which fractions of sewage is discharged in different water sources (normally one for each WWTP).
demand_buffer – A buffer for smoothing demand projections.
rof_infra_construction_order – A vector defining the ROF-based construction order for infrastructure.
demand_infra_construction_order – A vector defining the demand-based construction order for infrastructure.
infra_construction_triggers – A vector of construction triggers for infrastructure projects.
infra_discount_rate – The discount rate applied to infrastructure construction costs.
infra_if_built_remove – A vector defining dependencies for infrastructure projects. if infra option in position 0 of a row is built, remove infra options of IDs in remaining positions of the same row.
bond_term – The term of infrastructure bonds.
bond_interest_rate – The interest rate for infrastructure bonds.
demand_projection_forecast_length – Length of the forecast period for demand projections (in weeks).
demand_projection_historical_period_to_use – Historical period (in weeks) used for demand projection.
demand_projection_reprojection_frequency – Frequency (in weeks) for updating demand projections.

Throws:

std::invalid_argument – If both construction order vectors are empty.
std::invalid_argument – If the infrastructure discount rate is less than or equal to zero.

Utility(const char *name, int id, vector<vector<double>> &demands_all_realizations, vector<double> &annual_demand_projections, int number_of_week_demands, const double percent_contingency_fund_contribution, const double contingency_fund_cap, const vector<vector<double>> &typesMonthlyDemandFraction, const vector<vector<double>> &typesMonthlyWaterPrice, WwtpDischargeRule wwtp_discharge_rule, double demand_buffer, const vector<int> &rof_infra_construction_order, const vector<int> &demand_infra_construction_order, const vector<double> &infra_construction_triggers, double infra_discount_rate, double bond_term, double bond_interest_rate, int demand_projection_forecast_length, int demand_projection_historical_period_to_use, int demand_projection_reprojection_frequency)

Constructor (20-parameter) for a Utility object for when there is infrastructure to be built (uses a different InfrastructureManager constructor). Also includes a check for empty demand vectors that the prior constructor does not have.

This constructor sets up a Utility with specified attributes and initializes its parameters and infrastructure manager. Sets up the Utility instance, initializes water demand, pricing, and financial properties, and integrates infrastructure construction management functionality. It also computes weekly average water prices and ensures the provided parameters are valid.

FIXME: Unclear where this constructor is used, and how it differs from the other constructor.

See also

Utility::calculateWeeklyAverageWaterPrices for details on the computation of weekly average water prices.

See also

InfrastructureManager for details on infrastructure construction management.

Parameters:

name – The name of the utility.
id – The unique identifier for the utility.
demands_all_realizations – A vector of weekly demand data for all realizations.
annual_demand_projections – A vector of annual demand projections.
number_of_week_demands – The number of weekly demand entries.
percent_contingency_fund_contribution – Percentage contribution to the contingency fund.
contingency_fund_cap – The maximum allowed value of the contingency fund.
typesMonthlyDemandFraction – A reference to a vector of vectors containing monthly demand fractions by water type. Table of size 12 (months in year) by number of consumer tiers with the fraction of the total demand consumed by each tier in each month of the year. The last column must be the fraction of the demand treated as sewage. The summation of all number in a row but the last one, therefore, must sum to 1.
typesMonthlyWaterPrice – A reference to a vector of vectors containing monthly water prices by tier type. The last column is the price charged for waste water treatment.
wwtp_discharge_rule – The rule governing wastewater treatment plant discharges. A 53-week-long time series according to which fractions of sewage is discharged in different water sources (normally one for each WWTP).
demand_buffer – A buffer for smoothing demand projections.
rof_infra_construction_order – A vector defining the ROF-based construction order for infrastructure.
demand_infra_construction_order – A vector defining the demand-based construction order for infrastructure.
infra_construction_triggers – A vector of construction triggers for infrastructure projects.
infra_discount_rate – The discount rate applied to infrastructure construction costs.
bond_term – The term of infrastructure bonds.
bond_interest_rate – The interest rate for infrastructure bonds.
demand_projection_forecast_length – Length of the forecast period for demand projections (in weeks).
demand_projection_historical_period_to_use – Historical period (in weeks) used for demand projection.
demand_projection_reprojection_frequency – Frequency (in weeks) for updating demand projections.

Throws:

std::invalid_argument – If both construction order vectors are empty.
std::invalid_argument – If the infrastructure discount rate is less than or equal to zero.

Utility(Utility &utility)

Copy constructor for the Utility class.

This constructor creates a new Utility object by copying the attributes and state from an existing Utility instance. It ensures that the infrastructure construction manager is properly reconnected to the new object’s water source vectors. The water_sources vector is cleared after the copy to avoid duplicate or conflicting resources.

Parameters:: utility – The Utility object to copy.

~Utility()

Destructor for the Utility class.

Cleans up resources associated with the Utility instance. Specifically, clears the water_sources vector to release any dynamically allocated water source objects or references.

Utility &operator=(const Utility &utility)

Copy assignment operator for the Utility class.

Assigns the state of an existing Utility object to the current instance. This operator ensures a deep copy of the relevant data, including reinitializing and clearing resources before copying.

Parameters:: utility – The Utility object to copy data from.
Returns:: A reference to the current instance (*this) after copying.

bool operator<(const Utility *other)

Less-than operator for comparing Utility objects based on their IDs.

This operator compares the current Utility instance with another Utility object to determine if the ID of the current instance is less than that of the other.

Parameters:: other – A pointer to the other Utility object to compare against.
Returns:: true if the id of the current Utility is less than the id of the other Utility. Otherwise, returns false.

bool operator>(const Utility *other)

Compares the current Utility object with another Utility object using their IDs.

Parameters:: other – A pointer to another Utility object to compare with.
Returns:: true if the current Utility object’s ID is greater than the other Utility object’s ID, false otherwise.

void setRisk_of_failure(double risk_of_failure)

Sets the actual short-term risk of failure.

Parameters:: risk_of_failure – The actual risk of failure for storage components (max of storage/treatment ROF).

void setRisk_of_failures(double storage_risk_of_failure, double treatment_risk_of_failure)

Sets the short-term risk of failure for both storage and treatment components.

Parameters:

storage_risk_of_failure – The risk of failure for storage components.
treatment_risk_of_failure – The risk of failure for treatment components.

void updateTotalAvailableVolume()

Update the total available volume and net stream inflow based on current water sources.

This function recalculates the total available volume, total stored volume, and net stream inflow by iterating over both priority and non-priority draw water sources and updating these values accordingly.

See also

getAvailableAllocatedVolume()

See also

getAllocatedInflow()

See also

getPrioritySourcePotentialVolume()

void calculateWastewater_releases(int week, double *discharges)

Calculate wastewater releases for a given week and update discharge values.

This function calculates wastewater discharges based on the current week’s demand and updates the discharge values for each source in the wwtp_discharge_rule. The demand_offset is accounted for when calculating the discharges.

It iterates over the wastewater treatment plant (WWTP) discharge rules, applying the relevant dependent variables to calculate the discharge for each source and updating the total wastewater discharge.

Parameters:

week – The week for which the calculation is being performed.
discharges – A pointer to an array where the discharge values for each source will be updated.

double calculateCurrentToNextYearDemandDelta(int current_year)

Calculate the demand difference between the current year and the next year.

This function calculates the delta (difference) in demand between the current year and the next year by subtracting the recorded demand for the current year from the projected demand for the next year. This value is used to update water treatment plant (WTP) allocations for the upcoming year.

This function uses annual_demand_projections to retrieve the projected demand for the next year and compares it with the current_year_recorded_demand to compute the change in demand.

See also

annual_demand_projections, current_year_recorded_demand

Parameters:: current_year – The index representing the current year.
Returns:: double The delta in demand between the next year’s projection and the current year’s recorded demand.

void addWaterSource(WaterSource *water_source)

Connect a water source to the utility.

This function adds a new water source to the utility’s water sources list and updates the infrastructure construction manager accordingly. It also makes the water source online if certain conditions are met, such as having allocated treatment capacity or being an intake.

This function performs checks to ensure that the water source is correctly added to the utility’s system, resizing the water_sources vector if necessary to accommodate the new source. It then updates the water source’s status in the infrastructure construction manager and adjusts the utility’s total capacity metrics.

See also

checkErrorsAddWaterSourceOnline

See also

infrastructure_construction_manager

See also

WaterSource

Parameters:: water_source – Pointer to the WaterSource object to be added.

void splitDemands(int week, vector<vector<double>> &demands, bool apply_demand_buffer = false, bool apply_demand_projection = false)

Splits demands across available water sources.

This function allocates the utility’s water demand across various water sources based on their available capacity and treatment capabilities, and updates the contingency fund if necessary. It accounts for projections and buffers applied to demand and rebalances demand among sources in case of overallocation.

Demand is allocated so that river intakes and reuse are first used to their capacity before requesting water from allocations in reservoirs.

Parameters:

week – The current week number for which the demands are being split.
demands – A 2D vector that stores the demands allocated to each water source for the utility.
apply_demand_buffer – Flag to indicate whether a demand buffer should be applied.
apply_demand_projection – Flag to indicate whether future demand projections should be used.

Returns:

void

void checkErrorsAddWaterSourceOnline(WaterSource *water_source)

Checks for errors when adding a water source to the utility.

This function verifies if a water source with the same ID already exists in the utility’s water source list. If a duplicate is found, it throws an invalid_argument exception. It helps ensure that each water source added to the utility has a unique ID.

Parameters:: water_source – A pointer to the water source being added to the utility.
Throws:: std::invalid_argument – If the water source has a duplicate ID in the utility.
Returns:: void

void resetDroughtMitigationVariables()

Resets the drought mitigation variables in the utility.

This function resets key variables related to drought mitigation, which include the restricted price, offset rate per volume, and the demand offset. These variables are typically used during drought conditions to manage water allocation and pricing.

Returns:: void

void issueBond(int new_infra_triggered, int week)

Issues a bond for the new infrastructure triggered in the utility.

This function issues a bond for a newly triggered infrastructure and adds it to the list of issued bonds if it hasn’t been issued already. It calculates the net present value (NPV) of the bond at the time of issuance and updates the infrastructure net present cost.

Parameters:

new_infra_triggered – (int) The ID of the newly triggered infrastructure. If the value is NON_INITIALIZED, no bond is issued.
week – (int) The current week of the simulation, used for bond issuance.

Returns:

void

void calculateWeeklyAverageWaterPrices(const vector<vector<double>> &typesMonthlyDemandFraction, const vector<vector<double>> &typesMonthlyWaterPrice)

Calculates average water price from consumer types and respective prices.

This function calculates the weekly average water prices based on monthly water prices and the demand fraction for each consumer type. It computes the average monthly water price for each tier of consumers and then converts it into weekly prices by evenly distributing the monthly price across the weeks of the month.

See also

priceCalculationErrorChecking

Parameters:

typesMonthlyDemandFraction – (const vector<vector<double>>&) A 2D vector containing the demand fraction for each consumer type across the months.
typesMonthlyWaterPrice – (const vector<vector<double>>&) A 2D vector containing the water prices for each consumer type across the months.

Throws:

std::invalid_argument – if there is a mismatch in the dimensions of the input data or other validation errors from priceCalculationErrorChecking.

Returns:

void

double waterPrice(int week)

Returns the water price for a specific week.

This function retrieves the weekly average volumetric water price for the given week from the weekly_average_volumetric_price vector.

FIXME: Can change name to better reflect the function’s purpose as a getter

See also

weekly_average_volumetric_price

Parameters:: week – The week number (from 0 to WEEKS_IN_YEAR) for which the water price is requested.
Throws:: std::out_of_range – if the week parameter is out of bounds (less than 0 or greater than WEEKS_IN_YEAR).
Returns:: double The water price for the specified week.

void forceInfrastructureConstruction(int week, vector<int> new_infra_triggered)

Forces the construction of triggered infrastructure and issues the corresponding bonds.

This function initiates the construction of infrastructure that has been triggered for the specified week. It also ensures that bonds are issued for each triggered infrastructure project. If the project is part of a sequence, capital costs will be adjusted accordingly before bond issuance.

NOTE: This function is useful when there is a need to immediately force the construction of infrastructure regardless of other conditions or timelines.

See also

infrastructure_construction_manager

See also

issueBond

Parameters:

week – The week during which infrastructure construction is forced to begin.
new_infra_triggered – A vector containing the IDs of the newly triggered infrastructure projects.

Throws:

std::out_of_range – if any of the elements in new_infra_triggered are invalid or do not correspond to existing infrastructure projects.

Returns:

void

int infrastructureConstructionHandler(double long_term_rof, int week)

Handles infrastructure construction based on long-term risk of failure and other parameters.

This function calculates whether new infrastructure should be triggered based on the long-term risk of failure, the current demand series, and the available infrastructure capacity. If new infrastructure is triggered, it initiates the necessary steps to issue bonds and update the infrastructure Net Present Value (NPV).

This function is typically used to manage the infrastructure expansion process when the utility faces increased risk or demand that necessitates additional capacity.

See also

infrastructure_construction_manager

See also

issueBond

Parameters:

long_term_rof – The long-term risk of failure, influencing infrastructure construction decisions.
week – The current week number in the simulation or process.

Throws:

std::invalid_argument – if long_term_rof or week are outside expected ranges or invalid.

Returns:

int The ID of the newly triggered infrastructure project. Returns NON_INITIALIZED if no new infrastructure was triggered.

void priceCalculationErrorChecking(const vector<vector<double>> &typesMonthlyDemandFraction, const vector<vector<double>> &typesMonthlyWaterPrice)

Checks for errors in the monthly demand fraction and water price data.

This function verifies that the given monthly demand fractions and water prices meet the expected format and size. It checks that there are exactly 12 months’ worth of data and that the number of tiers (e.g., consumer types) matches across the demand fractions and water prices. If any of the checks fail, it throws an invalid_argument exception with a descriptive message.

This function is used before performing price calculations to ensure the integrity and correctness of the data.

Parameters:

typesMonthlyDemandFraction – A 2D vector where each row represents a month, and each column represents the demand fraction for a different consumer tier.
typesMonthlyWaterPrice – A 2D vector where each row represents a month, and each column represents the water price for a different consumer tier.

Throws:

std::invalid_argument – if the number of months is not equal to 12 or if the dimensions of the demand fractions and water prices do not match.

Returns:

void

void updateContingencyFundAndDebtService(double unrestricted_demand, double demand_multiplier, double demand_offset, double unfulfilled_demand, int week)

Updates the utility’s contingency fund and debt service based on the current demand and water prices.

This function calculates and updates the contingency fund, gross revenue, revenue losses due to restrictions, and the debt service for the utility. It takes into account factors such as unrestricted and restricted demand, the current water price, and any unfulfilled demand. It also updates variables related to drought mitigation costs and fund contributions.

This function works for both sources and receivers of transfers, and the transfer water prices are different than regular prices for both sources and receivers. It also stores the cost of drought mitigation.

See also

Utility::updateDebtPayment

See also

Utility::calculateRevenueLosses

Parameters:

unrestricted_demand – The total demand for water without any restrictions applied.
demand_multiplier – The multiplier applied to demand to reflect adjustments such as restrictions.
demand_offset – The offset to be applied to demand, typically due to transfer agreements or other adjustments.
unfulfilled_demand – The amount of demand that could not be fulfilled due to limitations on supply.
week – The current week of the year for which the update is being performed.

Throws:

logic_error – If the restricted price is lower than the unrestricted price, which is invalid.

Returns:

void

double getTotal_storage_capacity() const

Retrieves the total storage capacity of the utility.

This function returns the total storage capacity available to the utility. It is used to get the total volume of water that the utility can store.

See also

Utility::setTotalStorageCapacity

Returns:: double The total storage capacity of the utility.

double getRisk_of_failure() const

Retrieves the short-term risk of failure for the utility.

This function returns the short-term risk of failure value for the utility. It provides an indicator of the risk level for the utility’s operations in the near future, helping in decision-making and planning for infrastructure improvements or other mitigative actions.

See also

Utility::setRisk_of_failure

Returns:: double The short-term risk of failure of the utility.

double getStorageToCapacityRatio() const

Retrieves the ratio of stored volume to total storage capacity.

This function calculates and returns the ratio of the total stored volume to the total storage capacity of the utility. It provides a measure of how efficiently the utility is utilizing its storage capacity, indicating whether the storage is under-utilized or nearing full capacity.

Returns:: double The ratio of stored volume to total storage capacity.

double getGrossRevenue() const

Retrieves the gross revenue of the utility.

This function returns the current gross revenue of the utility. Gross revenue refers to the total revenue generated before any expenses or deductions, such as operational costs or taxes, are subtracted.

See also

Utility::setGrossRevenue

See also

Utility::calculateGrossRevenue

Returns:: double The current gross revenue of the utility.

void setDemand_multiplier(double demand_multiplier)

Sets the demand multiplier for the utility.

This function sets the multiplier for the utility’s demand calculations. The demand multiplier is used to adjust the demand for the utility based on various factors, such as changes in demand patterns, growth projections, or other external factors that may affect water consumption.

See also

Utility::getDemand_multiplier

See also

Utility::calculateDemandWithMultiplier

Parameters:: demand_multiplier – The value to set as the demand multiplier. It should be a positive value that adjusts the demand calculations for the utility.
Returns:: void

void setDemand_offset(double demand_offset, double offset_rate_per_volume)

Sets the demand offset and the offset rate per volume for the utility.

This function updates the demand offset by adding the specified value to the current demand offset, allowing for multiple transfer agreements to accumulate. Additionally, it sets the offset rate per volume, which is used to adjust the demand calculations based on the volume of water allocated or transferred.

See also

Utility::getDemand_offset

See also

Utility::calculateAdjustedDemand

Parameters:

demand_offset – The amount by which to adjust the utility’s demand offset. This value will be added to the current demand offset.
offset_rate_per_volume – The rate at which the demand offset adjusts based on the volume of water.

Returns:

void

double getTotal_treatment_capacity() const

Returns the total treatment capacity of the utility.

This function provides the total treatment capacity available to the utility, which is the capacity to treat water for distribution or other uses. The total treatment capacity is crucial for calculating the utility’s ability to process incoming water and meet demand, especially in cases of varying or increasing water demand.

See also

Utility::getTotal_storage_capacity

See also

Utility::calculateWaterTreatmentNeeds

Returns:: double The total treatment capacity of the utility.

void setWaterSourceOnline(unsigned int source_id, int week)

Sets a specified water source as online for the utility.

This function triggers the transition of a water source from offline to online status, updating the utility’s infrastructure to reflect the new capacity and availability of the water source. The change is reflected in the utility’s storage and treatment capacities, as well as the available and stored volumes.

See also

InfrastructureConstructionManager::setWaterSourceOnline

Parameters:

source_id – The unique identifier of the water source to be set online.
week – The current week of the year, used to manage construction timelines and updates.

Returns:

void

double updateCurrent_debt_payment(int week)

Updates the current debt payment for the utility for a specific week, if that’s the first week of the year.

This function calculates the current debt payment that the utility owes based on the bonds it has issued. It checks if any bonds are variable debt service bonds (associated with variable joint water treatment projects), and adjusts the debt service accordingly. It also sums up the debt service for all issued bonds and returns the total debt payment for the given week.

See also

Bond::setDebtService

See also

Bond::getDebtService

Parameters:: week – The current week of the year, used to calculate the applicable debt service for that week.
Throws:: none –
Returns:: double The total current debt payment for the utility for the specified week.

double getContingency_fund() const

Retrieves the current contingency fund balance.

This function returns the current balance of the utility’s contingency fund, which is used to cover unexpected costs such as water shortages, transfer costs, or other financial needs related to utility operations.

Returns:: double The current contingency fund balance.

double getUnrestrictedDemand() const

Retrieves the unrestricted demand for the utility.

This function returns the unrestricted demand, which is the total water demand without any restrictions or adjustments applied. This value represents the demand that the utility would expect if there were no supply limitations.

Returns:: double The current unrestricted demand value.

double getRestrictedDemand() const

Retrieves the restricted demand for the utility.

This function returns the restricted demand, which is the total water demand after restrictions or adjustments, such as limitations in water supply or surcharges, have been applied. This value represents the demand that the utility expects under restricted conditions.

Returns:: double The current restricted demand value.

void setRestricted_price(double restricted_price)

Sets the restricted price for the utility.

This function sets the restricted price, which is the water price applied when restrictions are enacted (e.g., during a drought or water usage limitations). This price may differ from the unrestricted price and is used when the utility enforces supply constraints.

Parameters:: restricted_price – The new restricted price value to be set for the utility.
Returns:: void

double getDemand_multiplier() const

Gets the demand multiplier for the utility.

This function returns the current demand multiplier, which is a factor that adjusts the demand calculations for the utility. It may be used to simulate changes in water consumption patterns, such as demand increases or decreases due to pricing, conservation efforts, or other factors.

Returns:: double The current demand multiplier.

double getUnrestrictedDemand(int week) const

Gets the unrestricted demand for the utility at a specific week.

This function returns the unrestricted demand for the utility in a given week. Unrestricted demand is the total demand for water without any restrictions or adjustments such as demand offset or restriction due to droughts or other operational limitations.

Parameters:: week – The week for which the unrestricted demand is being queried.
Throws:: std::out_of_range – If the provided week is outside the valid range of the demand series.
Returns:: double The unrestricted demand value for the specified week.

double getInfrastructure_net_present_cost() const

Gets the net present cost of infrastructure for the utility.

This function returns the current net present value (NPV) of the infrastructure for the utility. The net present cost represents the total cost of the infrastructure investments, accounting for both construction and operational costs, discounted over time.

Returns:: double The net present cost of the utility’s infrastructure.

double getCurrent_debt_payment() const

Gets the current debt payment for the utility.

This function returns the current debt payment that the utility must make for its outstanding bonds. The debt payment is calculated based on the terms of the issued bonds and is used to manage the utility’s financial obligations.

Returns:: double The current debt payment for the utility.

double getCurrent_contingency_fund_contribution() const

Gets the current contribution to the contingency fund.

This function returns the current contribution made to the utility’s contingency fund. The fund contribution is calculated based on various factors such as revenue losses, transfer costs, and other operational variables that affect the financial health of the utility.

Returns:: double The current contribution to the contingency fund.

double getDrought_mitigation_cost() const

Gets the current cost for drought mitigation.

This function returns the current cost for drought mitigation efforts, which are calculated based on factors like revenue losses, transfer costs, insurance payouts, and other variables affecting the utility’s drought response.

Returns:: double The current drought mitigation cost.

void addInsurancePayout(double payout_value)

Adds an insurance payout to the contingency fund.

This function increases the contingency fund by the specified payout value and records the insurance payout. The payout value is added directly to the fund and also stored for future reference.

Parameters:: payout_value – The amount of the insurance payout to be added to the contingency fund.
Returns:: void

void clearWaterSources()

Clears all water sources associated with the utility.

This function removes all entries from the water_sources container, effectively disassociating all water sources from the utility. This operation will clear any stored references to water sources and reset the state of the utility with regard to water source management.

Returns:: void

void purchaseInsurance(double insurance_price)

Purchases insurance by deducting from the contingency fund.

This function reduces the contingency_fund by the specified insurance_price and records the insurance purchase amount. It is used to simulate the purchase of insurance, typically for risk mitigation or disaster recovery purposes.

Parameters:: insurance_price – The cost of the insurance to be purchased.
Returns:: void

double getInsurance_payout() const

Retrieves the insurance payout value.

This function returns the amount of insurance payout that has been recorded. It can be used to check how much insurance the utility has received, typically as a result of an event triggering an insurance claim.

Returns:: double The amount of the insurance payout.

double getInsurance_purchase() const

Retrieves the insurance purchase value.

This function returns the amount of insurance purchased by the utility. It can be used to check the total cost of insurance purchased by the utility, typically used for mitigating financial risk due to adverse events.

Returns:: double The amount of insurance purchased.

const vector<int> &getRof_infrastructure_construction_order() const

Retrieves the order of infrastructure construction based on risk of failure (ROF).

This function returns a reference to a vector containing the order in which infrastructure should be constructed based on the risk of failure. The infrastructure construction order is determined by evaluating the ROF of different infrastructure elements, which informs the prioritization for construction.

See also

infrastructure_construction_manager

Returns:: A constant vector<int> reference to a vector of integers representing the infrastructure construction order.

void setRealization(unsigned long r, vector<double> &rdm_factors)

Sets the realization factors for the utility and adjusts demand series. Eliminates reference to comprehensive demand data set.

This function adjusts the utility’s demand series based on the provided realization factors, which are applied to the demands for the current realization. It also adjusts bond-related parameters, infrastructure discount rates, and other factors that influence the utility’s operations.

See also

calculateWeeklyPeakingFactor

See also

calculateAnnualAverageWeeklyDemand

See also

demands_all_realizations

Parameters:

r – The index of the realization (from the set of all realizations).
rdm_factors – A vector containing realization factors:
- rdm_factors[0] is the demand factor applied to the demand series.
- rdm_factors[1] is the multiplier for the bond term.
- rdm_factors[2] is the multiplier for the bond interest rate.
- rdm_factors[3] is the multiplier for the infrastructure discount rate.

Returns:

void

const vector<int> getInfrastructure_built() const

Retrieves the infrastructure that was built in the last week.

This function returns a list of the infrastructure items that were completed during the most recent week, as tracked by the infrastructure construction manager.

See also

infrastructure_construction_manager.getInfra_built_last_week

Returns:: A constant reference to a vector of integers representing the IDs of the infrastructure items that were completed in the last week.

void setNoFinaicalCalculations()

Disables financial calculations for the utility.

This function sets the used_for_realization flag to false, indicating that financial calculations should not be performed for the utility in the current context or iteration.

FIXME: Fix name to setNoFinancialCalculations

Returns:: void

double getLong_term_risk_of_failure() const

Gets the actual long-term risk of failure (max of storage/treatment ROF).

Parameters:: risk_of_failure – The max risk of failure between storage/treatment ROFs.
Returns:: double The long-term risk of failure.

const vector<int> &getDemand_infra_construction_order() const

Retrieves the demand-based infrastructure construction order.

This function returns the order in which infrastructure should be constructed, based on the demand requirements for the utility. It helps in prioritizing construction efforts according to demand.

Returns:: const vector<int>& A constant reference to the vector representing the infrastructure construction order based on demand.

vector<double> calculateWeeklyPeakingFactor(vector<double> *demands)

Calculates the weekly peaking factor for demand.

This function calculates the peaking factor for each week over multiple years based on the demand data. The factor is determined by comparing each week’s demand to the average demand of the corresponding year, and then averaging over all years.

Parameters:: demands – A pointer to a vector containing demand values over multiple years.
Returns:: vector<double> A vector of weekly peaking factors.

const vector<WaterSource*> &getWater_sources() const

Returns the list of water sources associated with the utility.

This function provides access to the collection of water sources that are currently associated with the utility. The list is returned as a constant reference to ensure that the original list is not modified.

Returns:: const vector<WaterSource *> & A constant reference to a vector containing the water sources.

double getWaste_water_discharge() const

Returns the amount of waste water discharge for the utility.

This function retrieves the current waste water discharge value associated with the utility. The value represents the amount of waste water being discharged by the utility, typically measured in a specified unit such as cubic meters or gallons.

Returns:: double The amount of waste water discharge.

double getTotal_available_volume() const

Returns the total available volume of the utility.

This function retrieves the total available volume of water that the utility has access to. The value represents the quantity of water available for distribution, typically measured in cubic meters or gallons.

Returns:: double The total available volume of water.

void resetTotal_storage_capacity()

Resets the total storage capacity of the utility.

This function sets the total storage capacity of the utility to 0, essentially clearing the current storage capacity value. This may be used in cases where the storage capacity needs to be recalculated or reset due to changes in infrastructure or other conditions.

Returns:: void

double getUnfulfilled_demand() const

Returns the unfulfilled demand of the utility.

This function calculates and returns the amount of demand that cannot be fulfilled by the available resources, based on the restricted demand and the total available volume or treatment capacity. The unfulfilled demand is the excess demand that exceeds the utility’s resources, if any.

Returns:: double The unfulfilled demand value.

double getNet_stream_inflow() const

Returns the net stream inflow of the utility.

This function retrieves the net stream inflow value, representing the amount of water entering the utility’s system from stream sources. The net stream inflow accounts for the total inflow minus any outflow, providing a measure of the system’s incoming water volume.

Returns:: double The net stream inflow value.

double getTotal_stored_volume() const

Returns the total stored volume of water in the utility’s system.

This function retrieves the total volume of water that has been stored within the utility’s storage facilities. The stored volume is an important measure for understanding the utility’s capacity to manage and supply water, especially in relation to demand and available volume.

Returns:: double The total stored volume of water.

const InfrastructureManager &getInfrastructure_construction_manager() const

Returns the infrastructure construction manager for the utility.

This function provides access to the infrastructure construction manager, which handles the planning and management of infrastructure construction within the utility. This manager is responsible for managing the development of new infrastructure projects, including water sources, storage, and treatment facilities.

See also

setInfrastructure_construction_manager

Returns:: const InfrastructureManager& The infrastructure construction manager.

double getDemand_offset() const

Returns the current demand offset for the utility.

This function retrieves the value of the demand offset, which represents any adjustments made to the utility’s demand due to factors such as policy or agreements. It is used in calculating the utility’s total demand and pricing strategies.

Returns:: double The current demand offset.

double getAvailableVolumeToCapacityRatio() const

Returns the ratio of available volume to total storage capacity.

This function calculates the ratio of the current available volume (the volume of water that can still be utilized or stored) to the total storage capacity of the utility. This ratio provides an indication of how much capacity is currently available compared to the total storage potential.

Returns:: double The ratio of available volume to total storage capacity.

double getUnrestrictedDemandToTreatmentCapacityRatio() const

Returns the ratio of unrestricted demand to total treatment capacity.

This function calculates the ratio of the current unrestricted demand to the total treatment capacity of the utility. The ratio helps to assess whether the current demand can be handled by the available treatment capacity.

Returns:: double The ratio of unrestricted demand to total treatment capacity.

void setLongTermRisk_of_failures(double storage_risk_of_failure, double treatment_risk_of_failure)

Sets the long-term risk of failure for storage and treatment.

This function sets the long-term risk of failure for both the storage and treatment components of the utility. It allows the user to define the risk of failure for each aspect, which is used in subsequent calculations related to infrastructure planning and management.

Parameters:

storage_risk_of_failure – The long-term risk of failure for storage, as a percentage.
treatment_risk_of_failure – The long-term risk of failure for treatment, as a percentage.

Returns:

void

double getLong_term_storage_risk_of_failure() const

Retrieves the long-term storage risk of failure.

This function returns the long-term risk of failure for the storage component of the utility, which is set using the setLongTermRisk_of_failures function. This value is used in risk management and infrastructure planning calculations.

Returns:: double The long-term storage risk of failure as a percentage.

double getLong_term_treatment_risk_of_failure() const

Retrieves the long-term treatment risk of failure.

This function returns the long-term risk of failure for the treatment component of the utility, which is set using the setLongTermRisk_of_failures function. This value is used in risk management and infrastructure planning calculations.

Returns:: double The long-term treatment risk of failure as a percentage.

void calculateDemandEstimateFromProjection(int year, bool reproject_demand)

Calculates the estimated future demand based on projections and historical data.

This function is used in ltROF calculations to estimate the demand for 5 years ahead on the utility’s historical demand data and the projected demand. The demand is reprojected by calculating the average annual growth rate over the last few years if at least 5 years or prior data is available. To be used along with demand buffer.

The demand projection is updated if the re-projection conditions are met.

See also

annual_demand_projections, demand_projection_forecast_length, setDemand_projection_parameters

Parameters:

week – The current week in the simulation.
reproject_demand – A flag indicating whether the demand should be reprojected.

Throws:

logic_error – if the forecast length exceeds the available projection data.

Returns:

void

double getCurrent_year_demand_record() const

Gets the recorded demand for the current year.

This function returns the actual demand recorded for the current year, which is used for demand projections and calculations. The value is updated at the end of each year.

Returns:: The recorded demand for the current year.

double getFuture_demand_estimate() const

Gets the estimated future demand.

This function returns the projected demand for a future year, calculated based on historical demand growth rates or pre-defined projections. It is used for long-term risk of failure (LTROF) calculations and planning.

Returns:: The estimated demand for a future year.

void setFuture_demand_estimate(double demand_estimate)

Sets the estimated future demand.

This function sets the projected demand for a future year. The demand estimate is typically used in long-term planning and risk calculations.

Parameters:: demand_estimate – The projected demand for a future year.
Returns:: void

void setCurrent_year_demand_record(double current_demand)

Sets the recorded demand for the current year.

This function records the actual demand for the current year, which is used in various projections and calculations, such as estimating future demand and calculating growth rates.

Parameters:: current_demand – The actual demand recorded for the current year.
Returns:: void

vector<double> calculateAnnualAverageWeeklyDemand(vector<double> *demands)

Calculates the annual average weekly demand for each year.

This function computes the average weekly demand for each year based on the input demand series. It assumes the demand data is provided for each week of the year, and calculates the annual average by dividing the total demand for each year by the number of weeks in the year.

Parameters:: demands – A pointer to a vector of weekly demand values. The size of this vector should be a multiple of the number of weeks in a year (WEEKS_IN_YEAR).
Returns:: vector<double> A vector containing the average weekly demand for each year.

void updateTreatmentCapacity(double capacity_adjustment)

This function calculates the annual average weekly demand for a given set of demand data.

Parameters:: demands – A pointer to a vector containing weekly demand values.
Throws:: No – exceptions are thrown in this function.
Returns:: A vector containing the annual average weekly demand for each year.

void setTreatmentCapacity(double total_capacity)

This function sets the total treatment capacity for the utility.

Parameters:: total_capacity – The total treatment capacity to be set.
Returns:: void

double updateCurrent_present_value_debt_payment(int week)

Updates the present value of the debt payment for the current week.

This function calculates the total present value of the debt payments to be made in a week for each bond issued by the utility (if that’s the first week of the year), considering any changes in debt service allocation over the course of the repayment. It sums the present value of debt payments for all bonds and returns the total amount.

See also

Bond::getPresentValueDebtService()

Parameters:: week – The current week for which the present value of debt service is calculated.
Throws:: None –
Returns:: double The total present value of the debt payment for the given week.

double getCurrent_debt_payment_present_valued() const

Retrieves the current present-valued debt payment.

This function returns the present-valued debt payment for the current week as calculated by the updateCurrent_present_value_debt_payment function.

Returns:: double The current present-valued debt payment.

double getStorageRisk_of_failure() const

Retrieves the short-term storage risk of failure.

This function returns the short-term storage risk of failure, which is a value that indicates the likelihood of failure in the storage capacity over a short period.

Returns:: double The short-term storage risk of failure.

double getTreatmentRisk_of_failure() const

Retrieves the short-term treatment risk of failure.

This function returns the short-term treatment risk of failure, which is a value that indicates the likelihood of failure in the treatment capacity over a short period.

Returns:: double The short-term treatment risk of failure.

double getSinusoidalFactor(int week, double A, double T, double p)

Calculates the sinusoidal factor based on the given parameters.

This function computes a sinusoidal factor for a given week, where the output is influenced by amplitude (A), period (T), and phase (p). It is typically used in scenarios where a periodic fluctuation is modeled.

Parameters:

week – The current week for which the sinusoidal factor is calculated.
A – The amplitude of the sinusoidal fluctuation.
T – The period of the fluctuation (in weeks).
p – The phase shift of the sinusoidal function.

Returns:

double The computed sinusoidal factor.

Public Members

const int id: The unique identifier for the utility.

const int number_of_week_demands: The number of weeks where demand data is available.

const char *name: A pointer to the name of the utility.

const double percent_contingency_fund_contribution: The percentage contribution of its gross revenue to the contingency fund.

const double demand_buffer: The demand buffer for smoothing demand projections.

Public Static Functions

static bool compById(Utility *a, Utility *b)

Compares two Utility objects based on their IDs.

Parameters:

a – A pointer to the first Utility object.
b – A pointer to the second Utility object.

Returns:

true if the id of the first Utility object is less than the id of the second Utility object, false otherwise.

Private Members

vector<double> weekly_average_volumetric_price: A vector of weekly average volumetric prices of a utility’s water supply.

vector<int> priority_draw_water_source: A vector containing the IDs of the prioritized water sources that the utility can draw from.

vector<int> non_priority_draw_water_source: A vector containing the IDs of the non-prioritized water sources that the utility can draw from.

vector<double> weekly_peaking_factor

A vector of demand weekly peaking factors.

See also

splitDemands, setRealization

double short_term_risk_of_failure = 0

The actual risk of failure for the utility’s storage and treatment components.

See also

getRisk_of_failure, setRisk_of_failure

double short_term_storage_risk_of_failure = 0

The risk of failure for the utility’s storage components.

double short_term_treatment_risk_of_failure = 0

The risk of failure for the utility’s treatment components.

double long_term_actual_risk_of_failure = 0

The max long-term risk of failure between the utility’s storage and treatment components.

double long_term_treatment_risk_of_failure = 0

The long-term risk of failure for the utility’s treatment components.

double long_term_storage_risk_of_failure = 0

The long-term risk of failure for the utility’s storage components.

double total_storage_capacity = 0

The total storage capacity of the utility.

double total_available_volume = 0

The total available volume for the utility.

double total_stored_volume = 0

The total stored volume for the utility.

double total_treatment_capacity = 0

The total treatment capacity of the utility.

double waste_water_discharge = 0

The total wastewater discharged by the utility after treatment.

double gross_revenue = 0

The total gross revenue generated by the utility.

double unfulfilled_demand = 0

The total unrestricted demand for the utility.

double net_stream_inflow = 0

The net stream inflow for the utility accounting allocations across all sources.

bool used_for_realization = true

A boolean flag indicating if a utility uses a speific source in a given realization.

See also

splitDemands, setNoFinaicalCalculations

vector<WaterSource*> water_sources: A vector of water sources available to the utility.

WwtpDischargeRule wwtp_discharge_rule: The waste water treatment discharge rule for the utility/.

vector<vector<double>> &demands_all_realizations: The 2D vector storing the full timeseries of demands for the utility across all realizations.

vector<double> &annual_demand_projections

The vector of average annual demand projections for the utility.

vector<double> demand_series_realization

The number of weekly unrestricted demand entries for the utility for one realization.

double *rdm_factors_realization: The vector of realization factors for the utility. FIXME: Unused in the code.

InfrastructureManager infrastructure_construction_manager

The infrastructure construction manager for the utility.

double fund_contribution = 0

Drought mitigation.

The contribution to the contingency fund.

double contingency_fund_cap = 1: The maximum allowed value of the contingency fund.

double demand_multiplier = 1: The DU factor multiplier that increases or increases demand.

double demand_offset = 0

The demand offset for the utility.

double restricted_price = NON_INITIALIZED

The price of water under water use restrictions for the utility.

double offset_rate_per_volume = 0

The rate of change of the demand offset per unit volume.

double contingency_fund = 0

The total current value of the utility’s contingency fund.

double drought_mitigation_cost = 0

The total cost of drought mitigation measures.

See also

getDrought_mitigation_cost

double insurance_payout = 0

The total insurance payout for the utility.

double insurance_purchase = 0

The total insurance purchase cost for the utility.

double restricted_demand = 0

The total demand for the utility under restrictions.

double unrestricted_demand = 0

The total unrestricted demand for the utility.

int n_sources = 0

The total number of water sources that are online and supplying water to the utility.

See also

addWaterSource

double infra_discount_rate: The infrastructure discount rate for the utility.

double bond_term_multiplier: The bond term multiplier used to adjust the term of infrastructure bonds.

double bond_interest_rate_multiplier: The bond interest rate multiplier used to adjust the interest rate for infrastructure bonds.

double max_capacity = 0

The maximum capacity of the utility’s water sources.

See also

addWaterSource

double current_debt_payment = 0

Infrastructure cost.

The current (weekly) debt payment of the utility.

double current_present_valued_debt_payment = 0: The present value of the current debt payment.

vector<vector<double>> debt_payment_streams: The net present cost of infrastructure for the utility. FIXME: Unused in the code.

double infra_net_present_cost = 0: The net present cost of infrastructure for the utility.

vector<Bond*> issued_bonds: A vector of bonds that have been issued by the utility.

double future_demand_estimate = 0

Demand projection for ROF.

The future demand estimate for the utility calculated by adjusting current demand with the average demand growth rate and length of projected demand.

double current_year_recorded_demand = 0

The current year’s recorded demand for the utility.

vector<double> annual_average_weekly_demand

The average annual weekly demand across all simulation years.

int demand_projection_forecast_length = LOOK_AHEAD_YEARS_FOR_DEMAND_PROJECTION

The length (in years) of the forecast period for demand projections.

int demand_projection_historical_period_to_use = LOOK_BACK_YEARS_FOR_DEMAND_REPROJECTION

The historical period (in years) used for demand projection. Caps the number of years before reprojection is done.

int demand_projection_reprojection_frequency = FREQUENCY_OF_DEMAND_REPROJECTION_YEARS

The frequency (in years) for updating demand projections.