WaterSources Module

The WaterSources module contains classes and functions related defining the components of the water system that supply water. This module is a submodule of the SystemComponents module.

API Reference

Base Components

WaterSource.h

class WaterSource
#include <WaterSource.h>

This class defines the main WaterSource object that provides basic representation of a general water source for a utility.

Created by bernardo on 1/22/17.

Subclassed by AllocatedIntake, AllocatedIntakeExpansion, Intake, IntakeExpansion, JointWTP, Relocation, Reservoir, ReservoirExpansion, SequentialJointTreatmentExpansion, WaterReuse

Public Functions

WaterSource(const char *name, const int id, const vector<Catchment*> &catchments, const double capacity, vector<int> connected_sources, double treatment_capacity, const int source_type)

This constructor initializes a basic WaterSource object with the given parameters. Used when the water source is built and operational.

Parameters:

  • name – The name of the water source.

  • id – The unique identifier for the water source.

  • catchments – A vector of pointers to Catchment objects supplying this water source.

  • capacity – The total storage capacity of the water source.

  • connected_sources – A vector of IDs representing sources connected to this water source.

  • treatment_capacity – The total treatment capacity of the water source.

  • source_type – The type of water source (e.g., reservoir, river, etc.).

Returns:

A new WaterSource object.

WaterSource(const char *name, const int id, const vector<Catchment*> &catchments, const double capacity, double treatment_capacity, vector<int> connected_sources, const int source_type, vector<double> *allocated_treatment_fractions, vector<double> *allocated_fractions, vector<int> *utilities_with_allocations)

This constructor initializes a WaterSource object with pre-set allocation fractions and connected source details. Used when a water source is built and operational.

Parameters:

  • name – The name of the water source.

  • id – The unique identifier for the water source.

  • catchments – A vector of pointers to Catchment objects associated with this water source.

  • capacity – The total storage capacity of the water source (in cubic meters).

  • treatment_capacity – The total treatment capacity of the water source (in cubic meters per week).

  • connected_sources – A vector of IDs representing sources connected to this water source.

  • source_type – The type of water source (e.g., reservoir, river, etc.).

  • allocated_treatment_fractions – A pointer to a vector of pre-set fractions of the total treatment capacity allocated to utilities.

  • allocated_fractions – A pointer to a vector of pre-set fractions of the total storage capacity allocated to utilities.

  • utilities_with_allocations – A pointer to a vector of IDs for utilities allocated to this water source.

Throws:

std::runtime_error – if any issues arise in setting allocations (handled by setAllocations).

Returns:

A new WaterSource object.

WaterSource(const char *name, const int id, const vector<Catchment*> &catchments, const double capacity, double treatment_capacity, vector<int> connected_sources, const int source_type, const vector<double> construction_time_range, double permitting_period, Bond &bond)

This constructor initializes a WaterSource object with the provided parameters, including construction and permitting details. Used when the water source does not exist in the beginning of the simulation for water sources financed by only one bond.

Parameters:

  • name – The name of the water source.

  • id – The unique identifier for the water source.

  • catchments – A vector of pointers to Catchment objects associated with this water source.

  • capacity – The total storage capacity of the water source.

  • treatment_capacity – The total treatment capacity of the water source.

  • connected_sources – A vector of IDs representing sources connected to this water source.

  • source_type – The type of water source (e.g., reservoir, river, etc.).

  • construction_time_range – A vector containing the minimum and maximum construction time range.

  • permitting_period – The permitting time required for the water source.

  • bond – A reference to a Bond object associated with financing this water source.

Throws:

std::invalid_argument – if permitting or construction time is NaN or negative (checked by checkForInputErrorsConstruction).

Returns:

A new WaterSource object.

WaterSource(const char *name, const int id, const vector<Catchment*> &catchments, const double capacity, double treatment_capacity, vector<int> connected_sources, const int source_type, const vector<double> construction_time_range, double permitting_period, vector<Bond*> bonds)

This constructor initializes a WaterSource object with comprehensive parameters, including multiple bonds, construction, and permitting details. Used when the water source does not exist in the beginning of the simulation for water sources financed by a series of bonds (shared water source).

Parameters:

  • name – The name of the water source.

  • id – The unique identifier for the water source.

  • catchments – A vector of pointers to Catchment objects associated with this water source.

  • capacity – The total storage capacity of the water source.

  • treatment_capacity – The total treatment capacity of the water source.

  • connected_sources – A vector of IDs representing sources connected to this water source.

  • source_type – The type of water source (e.g., reservoir, river, etc.).

  • construction_time_range – A vector containing the minimum and maximum construction time range.

  • permitting_period – The permitting time required for the water source.

  • bonds – A vector of pointers to Bond objects associated with financing this water source.

Throws:

std::invalid_argument – if permitting or construction time is NaN or negative (checked by checkForInputErrorsConstruction).

Returns:

A new WaterSource object.

WaterSource(const char *name, const int id, const vector<Catchment*> &catchments, const double capacity, double treatment_capacity, vector<int> built_in_sequence, const int source_type, vector<double> *allocated_treatment_fractions, vector<double> *allocated_fractions, vector<int> *utilities_with_allocations, const vector<double> construction_time_range, double permitting_period, Bond &bond)

This constructor initializes a WaterSource object with detailed allocation settings, construction time, and bond financing. Used when a non-shared water source with multiple stages does not exist in the beginning of the simulation but has a built-in sequence of stages (i.e. low/high).

Parameters:

  • name – The name of the water source.

  • id – The unique identifier for the water source.

  • catchments – A vector of pointers to Catchment objects associated with this water source.

  • capacity – The total storage capacity of the water source (in cubic meters).

  • treatment_capacity – The total treatment capacity of the water source (in cubic meters per week).

  • built_in_sequence – A vector of IDs representing the construction sequence for this water source.

  • source_type – The type of water source (e.g., reservoir, river, etc.).

  • allocated_treatment_fractions – A pointer to a vector of fractions of total treatment capacity allocated to utilities.

  • allocated_fractions – A pointer to a vector of fractions of total storage capacity allocated to utilities.

  • utilities_with_allocations – A pointer to a vector of IDs for utilities allocated to this water source.

  • construction_time_range – A vector containing the minimum and maximum construction time range (in years).

  • permitting_period – The permitting time required for the water source (in years).

  • bond – A reference to a Bond object representing financing details for this water source.

Throws:

std::invalid_argument – if permitting or construction time is NaN or negative (checked by checkForInputErrorsConstruction).

Returns:

A new WaterSource object.

WaterSource(const char *name, const int id, const vector<Catchment*> &catchments, const double capacity, double treatment_capacity, vector<int> connected_sources, vector<int> *utilities_with_allocations, vector<double> *utility_treatment_allocations, const int source_type, const vector<double> construction_time_range, double permitting_period, vector<Bond*> bonds)

This constructor initializes a WaterSource object with parameters for utility allocations, water quality, and bond financing. Used when a shared water source does not exist in the beginning of the simulation and is of class JointWTP (uses only utility_treatment_allocations).

Parameters:

  • name – The name of the water source.

  • id – The unique identifier for the water source.

  • catchments – A vector of pointers to Catchment objects associated with this water source.

  • capacity – The total storage capacity of the water source.

  • treatment_capacity – The total treatment capacity of the water source.

  • connected_sources – A vector of IDs representing sources connected to this water source.

  • utilities_with_allocations – A pointer to a vector of IDs for utilities allocated to this water source.

  • utility_treatment_allocations – A pointer to a vector of treatment capacities allocated to utilities.

  • source_type – The type of water source (e.g., reservoir, river, etc.).

  • construction_time_range – A vector containing the minimum and maximum construction time range.

  • permitting_period – The permitting time required for the water source.

  • bonds – A vector of pointers to Bond objects associated with financing this water source.

Throws:

std::invalid_argument – if permitting or construction time is NaN or negative (checked by checkForInputErrorsConstruction).

Returns:

A new WaterSource object.

WaterSource(const char *name, const int id, const vector<Catchment*> &catchments, const double capacity, double treatment_capacity, vector<int> connected_sources, vector<int> *utilities_with_allocations, vector<double> *utility_supply_allocations, vector<double> *utility_treatment_allocations, const int source_type, const vector<double> construction_time_range, double permitting_period, vector<Bond*> bonds)

This constructor initializes a WaterSource object with comprehensive parameters, including utility supply and treatment allocations, water quality management, and bond financing. Used when a shared water source does not exist in the beginning of the simulation and is of class AllocatedIntake or Expansion (uses utility_supply_allocations and utility_treatment_allocations).

Parameters:

  • name – The name of the water source.

  • id – The unique identifier for the water source.

  • catchments – A vector of pointers to Catchment objects associated with this water source.

  • capacity – The total storage capacity of the water source.

  • treatment_capacity – The total treatment capacity of the water source.

  • connected_sources – A vector of IDs representing sources connected to this water source.

  • utilities_with_allocations – A pointer to a vector of IDs for utilities allocated to this water source.

  • utility_supply_allocations – A pointer to a vector of supply capacities allocated to utilities.

  • utility_treatment_allocations – A pointer to a vector of treatment capacities allocated to utilities.

  • source_type – The type of water source (e.g., reservoir, river, etc.).

  • construction_time_range – A vector containing the minimum and maximum construction time range.

  • permitting_period – The permitting time required for the water source .

  • bonds – A vector of pointers to Bond objects associated with financing this water source.

Throws:

std::invalid_argument – if permitting or construction time is NaN or negative (checked by checkForInputErrorsConstruction).

Returns:

A new WaterSource object.

WaterSource(const WaterSource &water_source)

Copy constructor.

This constructor creates a copy of an existing WaterSource object.

Parameters:

water_source – The WaterSource object to be copied.

Returns:

A new WaterSource object that is a copy of the provided water_source.

virtual ~WaterSource()

Destructor for the WaterSource class.

This destructor cleans up dynamically allocated memory for the Bond objects associated with the water source.

Parameters:

None –

Returns:

void

WaterSource &operator=(const WaterSource &water_source)

Assignment operator for the WaterSource class.

This operator assigns the values of one WaterSource object to another, making a deep copy of the relevant data.

Parameters:

water_source – The WaterSource object whose data is being assigned.

Returns:

A reference to the current WaterSource object after the assignment.

bool operator<(const WaterSource *other)

Less-than operator for comparing two WaterSource objects by their id.

This operator compares the id of the current WaterSource object with that of another WaterSource object to determine their relative order.

Parameters:

other – A pointer to the WaterSource object to be compared with the current object.

Returns:

true if the id of the current WaterSource object is less than the id of the other object, false otherwise.

bool operator>(const WaterSource *other)

Greater-than operator for comparing two WaterSource objects by their id.

This operator compares the id of the current WaterSource object with that of another WaterSource object to determine their relative order.

Parameters:

other – A pointer to the WaterSource object to be compared with the current object.

Returns:

true if the id of the current WaterSource object is greater than the id of the other object, false otherwise.

bool operator==(const WaterSource *other)

Equality operator for comparing two WaterSource objects by their id.

This operator checks if the id of the current WaterSource object is equal to the id of another WaterSource object.

Parameters:

other – A pointer to the WaterSource object to be compared with the current object.

Returns:

true if the id of the current WaterSource object is equal to the id of the other object, false otherwise.

void continuityWaterSource(int week, double upstream_source_inflow, double wastewater_inflow, vector<double> &demand_outflow)

Manages the continuity of a water source by either applying continuity or bypassing it.

This function checks if the water source is online and, depending on the status, either applies continuity or bypasses the process.

Parameters:

  • week – The current week of the simulation or process.

  • upstream_source_inflow – The inflow of water from the upstream source.

  • wastewater_inflow – The inflow of wastewater to the water source.

  • demand_outflow – A reference to a vector that will store the demand outflow values.

Returns:

void

virtual void addTreatmentCapacity(const double added_treatment_capacity, int utility_id)

Adds treatment capacity to the water source.

This function increases the total treatment capacity of the water source by a specified amount. This is a virtual function that can be overridden by subclasses.

Parameters:

  • added_treatment_capacity – The additional treatment capacity to be added to the water source.

  • utility_id – The ID of the utility requesting the capacity addition (UNUSED).

Returns:

void

virtual void removeWater(int allocation_id, double volume)

Removes water from the water source and updates demand.

This function decreases the available volume of water in the source by the specified volume and increases the total demand and policy-added demand accordingly. This is a virtual function that can be overridden by subclasses.

Parameters:

  • allocation_id – The ID of the allocation from which the water is being removed (UNUSED).

  • volume – The volume of water to be removed from the water source.

Returns:

void

virtual void addCapacity(double capacity, int utility_id)

Adds capacity to the water source.

This function increases the capacity of the water source by a specified amount. This is a virtual function that can be overridden by subclasses.

Parameters:

  • capacity – The additional capacity to be added to the water source.

  • utility_id – The ID of the utility requesting the capacity addition (UNUSED).

Returns:

void

virtual void setOnline()

Sets the water source to be online.

This is a virtual function that can be overridden by subclasses.

This function changes the status of the water source to online, enabling its operations.

Returns:

void

virtual bool skipConstruction(int utility_id) const

Determines whether the construction of the water source should be skipped.

This function always returns false, indicating that the construction of the water source cannot be skipped. This is a virtual function that can be overridden by subclasses.

Parameters:

utility_id – The ID of the utility requesting to skip construction (UNUSED).

Returns:

false, indicating that the construction cannot be skipped.

virtual double getAvailableAllocatedVolume(int utility_id)

Retrieves the available allocated volume for a specific utility.

This function returns the available allocated volume for the given utility ID. In its current implementation, it returns the total available volume, as the functionality to allocate volumes to different utilities has not been implemented. This is a virtual function that can be overridden by subclasses.

Parameters:

utility_id – The ID of the utility for which the available allocated volume is being requested (UNUSED).

Returns:

The available allocated volume for the specified utility. In the current implementation, this is equivalent to the total available volume.

virtual double getAvailableVolume() const

Retrieves the available volume of the water source.

This is a virtual function that can be overridden by subclasses.

This function returns the current available volume of the water source, which represents the amount of water that is currently available for allocation or usage.

Returns:

The available volume of the water source.

virtual void setFull()

Sets the water source to its full capacity.

This is a virtual function that can be overridden by subclasses.

This function sets the available volume of the water source to its full capacity, indicating that the source is completely filled and no further volume can be added until some is used or allocated.

Returns:

void

virtual double getSupplyCapacity()

Retrieves the available supply capacity of the water source.

This is a virtual function that can be overridden by subclasses.

This function calculates and returns the available supply capacity of the water source, taking into account any allocations to the water quality pool (if initialized). If the water quality pool is not initialized, it returns the total capacity of the water source.

Returns:

The available supply capacity of the water source.

double getMin_environmental_outflow() const

Retrieves the minimum environmental outflow for the water source.

This function returns the minimum environmental outflow, which is a threshold value representing the minimum amount of water that must be released from the water source to maintain environmental standards.

Returns:

The minimum environmental outflow of the water source.

void setMin_environmental_outflow(double min_environmental_outflow)

Sets the minimum environmental outflow for the water source.

This function sets the minimum environmental outflow, which represents the minimum amount of water that must be released from the water source to maintain ecological standards.

Parameters:

min_environmental_outflow – The value to set for the minimum environmental outflow.

Returns:

void

const vector<int> &getBuilt_in_sequence() const

Gets the sequence (vector) of water sources to be built consecutively.

This function returns a reference to the vector containing the built-in sequence, which represents the order in which sources or utilities are connected or initialized in the system.

Returns:

A constant reference to the vector containing the built-in sequence.

double getTotal_outflow() const

Retrieves the total outflow from the water source.

This function returns the total outflow from the water source, which represents the sum of all the water leaving the source, including outflows to utilities and environmental requirements.

Returns:

The total outflow from the water source.

bool isOnline() const

Checks if the water source is online.

This function returns a boolean indicating whether the water source is online and operational.

Returns:

true if the water source is online, false otherwise.

void setOutflow_previous_week(double outflow_previous_week)

Sets the total outflow for the previous week.

This function updates the total outflow of the water source to the value provided for the previous week. This is used to track and record outflows from the water source on a weekly basis.

Parameters:

outflow_previous_week – The outflow value for the previous week to set.

Returns:

void

double getUpstream_source_inflow() const

Retrieves the upstream source inflow.

This function returns the current upstream inflow to the water source, which is the volume of water entering the source from upstream sources. This value is crucial for determining the availability of water for further allocation and usage.

Returns:

The upstream source inflow in cubic units (e.g., cubic meters).

double getDemand() const

Retrieves the total demand for the water source.

This function returns the total demand placed on the water source, which is the total volume of water required by various users or systems connected to the source.

Returns:

The total demand from all utilities sharing the water source.

double getUpstreamCatchmentInflow() const

Retrieves the upstream catchment inflow.

This function returns the current inflow to the water source from upstream catchments. It represents the volume of water entering the source from the catchment areas upstream of the water source.

Returns:

The upstream catchment inflow in cubic units (e.g., cubic meters).

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

Sets the timeseries corresponding to the realization of the water source based on random factors.

This function updates the water source’s properties, including catchment inflow, permitting time, and construction cost overruns based on the given realization index (r) and randomization factors (rdm_factors). The function applies the random factors to the catchments, permitting time, and bonds associated with the water source. This function is a virtual function that can be overridden by subclasses.

Parameters:

  • r – The realization index, which is used to apply different realizations of the water source.

  • rdm_factors – A vector of DU factors, where each entry corresponds to a specific property of the water source.

Returns:

void

virtual double getAllocatedCapacity(int utility_id)

Retrieves the allocated capacity of the water source.

This function returns the total capacity of the water source, which can be allocated to a utility. The function does not currently account for any specific allocation per utility, returning the full capacity. This function is a virtual function that can be overridden by subclasses.

Parameters:

utility_id – The ID of the utility requesting the allocated capacity. (Currently not used in the function.)

Returns:

The total capacity of the water source, represented as a double.

virtual double getAllocatedFraction(int utility_id)

Retrieves the allocated fraction of the water source for a specific utility.

This function returns the fraction of the water source’s capacity allocated to a utility. In its current implementation, the function returns a fixed value of 1.0, indicating full allocation to the utility. This function is a virtual function that can be overridden by subclasses.

Parameters:

utility_id – The ID of the utility requesting the allocated fraction. (Currently not used in the function.)

Returns:

The fraction of the total water source capacity allocated to the utility, represented as a double (always 1.0).

double getEvaporated_volume() const

Retrieves the total evaporated volume of the water source.

This function returns the total volume of water that has evaporated from the water source. The value represents the accumulated evaporated volume for the water source over time.

Returns:

The total evaporated volume, represented as a double.

virtual double getAllocatedTreatmentCapacity(int utility_id) const

Retrieves the allocated treatment capacity of the water source.

This function returns the total treatment capacity allocated to the water source. The value represents the total treatment capacity available for use by the water source. This function is a virtual function that can be overridden by subclasses.

Parameters:

utility_id – The utility identifier for which the treatment capacity is requested (UNUSED).

Returns:

The allocated treatment capacity, represented as a double.

double getTotal_treatment_capacity(int utility_id) const

Retrieves the total treatment capacity of the water source.

This function returns the total treatment capacity allocated to the water source. The value represents the overall treatment capacity available for use by the water source.

Parameters:

utility_id – The utility identifier for which the total treatment capacity is requested.

Returns:

The total treatment capacity, represented as a double.

void setAllocations(vector<int> *utilities_with_allocations, vector<double> *allocated_fractions, vector<double> *allocated_treatment_fractions)

Sets the allocations for utilities in the water source.

This function takes in vectors of utilities, allocated fractions, and treatment fractions, and sets the allocation for the water source. It validates that the fractions sum up to 1.0, assigns the appropriate values to the allocation vectors, and checks that no treatment capacity is allocated to the water quality pool.

Initial set up of allocations with full reservoir in the beginning of the simulations. To be used in constructors only.

Parameters:

  • utilities_with_allocations – A pointer to a vector of utility IDs that have allocations to the water source.

  • allocated_fractions – A pointer to a vector of fractions of the water source’s total capacity allocated for each utility.

  • allocated_treatment_fractions – A pointer to a vector of fractions of the water source’s treatment capacity allocated for each utility.

Throws:

invalid_argument – if any of the following conditions are not met:

  • The size of utilities_with_allocations does not match the size of allocated_fractions.

  • The sum of allocated_fractions is less than or greater than 1.0.

  • A treatment capacity is allocated to the water quality pool.

  • The sizes of utilities_with_allocations, allocated_fractions, and allocated_treatment_fractions are inconsistent.

Returns:

void

virtual void resetAllocations(const vector<double> *new_allocated_fractions)

Resets the allocations for utilities in the water source.

This function resets the allocation fractions and recalculates the corresponding capacities and available volumes for each utility. The water quality pool allocation is handled by the wq_pool_id. The updated allocation fractions are applied to the existing allocation data. This is a virtual function that can be overridden by subclasses.

Parameters:

new_allocated_fractions – A pointer to a vector of new allocation fractions for each utility.

Returns:

void

void setAvailableAllocatedVolumes(vector<double> available_allocated_volumes, double available_volume)

Sets the available allocated volumes to each utility and available volume from the water source.

This function updates the available allocated volumes for each utility and the total available volume for the water source. If utilities_with_allocations is not null, the allocated volumes will be updated accordingly.

Parameters:

  • available_allocated_volumes – A vector containing the available allocated volumes for each utility.

  • available_volume – The total available volume of the water source.

Returns:

void

vector<double> getAvailable_allocated_volumes() const

Returns the available allocated volumes for the water source.

This function retrieves the available allocated volumes for each utility that has an allocation in the water source.

Returns:

A vector of available allocated volumes for each utility.

vector<int> *getUtilities_with_allocations() const

Returns the IDs of the utilities with allocations for the water source.

This function retrieves the list of utilities that have allocations in the water source.

Parameters:

None –

Returns:

A pointer to a vector of utility IDs that have allocations in the water source.

double getWastewater_inflow() const

Returns the wastewater inflow to the water source.

This function retrieves the amount of wastewater inflow currently associated with the water source.

Returns:

The wastewater inflow as a double value.

double getPermitting_period() const

Returns the permitting period of the water source.

This function retrieves the permitting period for the water source, which defines the time required for permitting operations to be completed for the water source.

Returns:

The permitting period as a double value.

double getAvailableSupplyVolume() const

Returns the available supply volume of the water source.

This function calculates the available supply volume by subtracting the allocated volumes for the water quality pool from the total available volume, if the water quality pool is initialized. If the water quality pool is not initialized, it simply returns the total available volume.

Returns:

The available supply volume as a double value.

double getAllocatedInflow(int utility_id) const

This function returns the allocated inflow for a given utility.

This function checks if the water quality pool ID is initialized. If it is not, it returns the upstream catchment inflow. If it is initialized, the function returns the fraction of inflow from the upstream catchment and allocates it to the specified utility.

Parameters:

utility_id – The ID of the utility for which the allocated inflow is being calculated.

Returns:

The allocated inflow for the specified utility.

virtual double getSupplyAllocatedFraction(int utility_id)

This function returns the supply allocated fraction for a given utility.

This function currently returns a constant value of 1.0 for any given utility ID, indicating that the entire supply is allocated to the utility. This is a virtual function that can be overridden by subclasses.

Parameters:

utility_id – The ID of the utility for which the supply allocated fraction is being calculated (UNSUED).

Returns:

The supply allocated fraction (always 1.0).

virtual Bond &getBond(int utility_id)

This function returns the bond associated with a given utility ID.

This function checks the size of the bonds collection. If the collection contains only one bond, it returns the first bond. Otherwise, it returns the bond corresponding to the specified utility_id. This is a virtual function that can be overridden by subclasses.

Parameters:

utility_id – The ID of the utility for which the bond is being retrieved.

Returns:

The bond associated with the specified utility ID.

void checkForInputErrorsConstruction()

This function checks for input errors related to the permitting and construction times for a water source.

Throws:

std::invalid_argument – if the permitting time or construction time is invalid (NaN or negative).

Returns:

Void

int randomConstructionTime(double t0, double tf)

This function generates a random construction time between the specified time bounds, converted to weeks.

This function uses a random number generator to produce a random value within the range [t0, tf] (in years). The result is then scaled by the constant WEEKS_IN_YEAR to convert it into weeks. The function also incorporates a seeded random number generator based on either the id and seed or a fresh random device if seed is not properly initialized.

Parameters:

  • t0 – The lower bound of the construction time range (in years).

  • tf – The upper bound of the construction time range (in years).

Returns:

The random construction time (in weeks).

const double getConstruction_time() const

This function returns the construction time of the water source.

This function simply returns the value of the construction_time member, which represents the total time required for construction, typically measured in weeks.

Returns:

The construction time (in weeks).

virtual double getPrioritySourcePotentialVolume(int utility_id) const

This function returns the potential volume of the priority source for a given utility.

This function currently returns a constant value of 0.0, indicating that the priority source has no potential volume. This is a virtual function that can be overridden by subclasses.

Parameters:

utility_id – The ID of the utility for which the priority source potential volume is being retrieved (UNUSED).

Returns:

The potential volume of the priority source (always 0.0).

virtual int getAgreementType() const

This function retrieves the agreement type of the water source.

This function is designed to be called only by the JointWTP class or its child classes. If called from any other context, it throws a logic_error indicating that the agreement type cannot be accessed. The function will return a default error code (9999) after throwing the exception. This is a virtual function that can be overridden by subclasses.

Throws:

std::logic_error – If called outside the JointWTP class or its child classes.

Returns:

The agreement type (always returns 9999 after throwing an error).

virtual int getParentWaterSourceID() const

This function retrieves the parent water source ID.

This function is intended to be called only through an override in the JointWTP class. If called from any other context, it throws a logic_error indicating that the parent water source ID should only be accessed through the JointWTP class or its child classes. The function will return a default error code (-999) after throwing the exception. This is a virtual function that can be overridden by subclasses.

Throws:

std::logic_error – If called outside the JointWTP class or its child classes.

Returns:

The parent water source ID (always returns -999 after throwing an error).

void resetTreatmentAllocations(const vector<double> current_treatment_allocations, const vector<double> new_treatment_allocations)

This function resets the treatment allocations for each utility based on the provided current and new treatment allocations.

This function calculates the change in treatment capacities for each utility and updates the allocated_treatment_capacities accordingly. It also ensures that there are no negative capacities and adjusts for any over-allocation by normalizing the treatment fractions to ensure that the total treatment capacity is not exceeded.

Parameters:

  • current_treatment_allocations – A vector of current treatment allocations for each utility.

  • new_treatment_allocations – A vector of new treatment allocations for each utility.

Returns:

void

vector<double> getAllocatedTreatmentCapacities() const

This function returns the vector of allocated treatment capacities to relevant utilities.

This function provides access to the allocated_treatment_capacities member, which contains the treatment capacities allocated to each utility. The returned vector holds the allocated capacities for all utilities that have allocations.

Returns:

A vector containing the allocated treatment capacities for each utility.

void setTreatmentAllocations(const vector<double> treatment_capacity_allocations)

This function sets the treatment allocations for each utility based on the provided treatment capacity allocations.

This function updates the allocated_treatment_capacities member with the provided treatment capacity allocations for each utility. It then calculates the treatment fractions for each utility based on the updated treatment capacities and the total treatment capacity. Note: Over-allocation checks are not performed in this function, as they are handled elsewhere.

Parameters:

treatment_capacity_allocations – A vector of treatment capacity allocations for each utility.

Returns:

void

virtual double getAllocatedTreatmentFraction(int utility_id) const

This function returns the allocated treatment fraction for a given utility.

This function currently returns a constant value of 1.0, indicating that the treatment fraction for any utility is set to 100%. This is a virtual function that can be overridden by subclasses.

Parameters:

utility_id – The ID of the utility for which the treatment fraction is being retrieved (UNUSED).

Returns:

The allocated treatment fraction (always 1.0).

int getWaterQualityPoolID() const

This function returns the water quality pool ID.

This function provides access to the wq_pool_id member, which represents the identifier of the water quality pool associated with the water source.

Parameters:

void –

Returns:

The water quality pool ID.

vector<double> getAllocatedSupplyCapacities() const

This function returns the vector of allocated supply capacities.

This function provides access to the allocated_capacities member, which contains the supply capacities allocated to each utility. The returned vector holds the allocated supply capacities for all utilities that have allocations.

Returns:

A vector containing the allocated supply capacities for each utility.

Public Members

const int id

The unique identifier of the water source.

const char *name

The name of the water source.

const int source_type

The type of the water source.

const double construction_time

The time required to build the water source.

Public Static Functions

static bool compare(WaterSource *lhs, WaterSource *rhs)

Compares two water sources based on their ID.

This function compares two instances of WaterSource based on their id attribute. It returns true if the ID of the left-hand side water source (lhs) is less than that of the right-hand side (rhs). This can be useful for sorting or organizing water sources by their ID.

Parameters:
Returns:

true if lhs->id is less than rhs->id, otherwise false.

static void setSeed(int seed)

This function sets the seed value for the random number generator.

This function assigns the provided seed value to the seed member of the WaterSource class. This seed is used to initialize the random number generator for operations that require randomness, such as generating random construction times.

Parameters:

seed – The value to set for the random number generator seed.

Returns:

void

static void unsetSeed()

This function unsets the seed value for the random number generator.

This function resets the seed member of the WaterSource class to a non-initialized state, effectively unsetting the seed. This means that any subsequent use of the random number generator will rely on a fresh random device or an unseeded state.

Parameters:

void –

Returns:

void

Protected Functions

virtual void applyContinuity(int week, double upstream_source_inflow, double wastewater_inflow, vector<double> &demand_outflow) = 0

This function handles the continuity calculations for a water source, ensuring proper inflow and outflow.

Parameters:

  • week – The current week of the simulation.

  • upstream_source_inflow – The inflow from upstream water sources.

  • wastewater_inflow – The inflow from wastewater treatment plants.

  • demand_outflow – A reference to a vector representing the water demand outflows to each utility.

Returns:

void

void bypass(int week, double total_upstream_inflow)

This function bypasses continuity calculations, routing all inflows downstream without adjustments. Does not apply continuity to the water source, by instead just treats it as non existing, i.e. outflow = inflow + catchment_flow.

Parameters:

  • week – The current week of the simulation.

  • total_upstream_inflow – The total inflow from upstream sources excluding water for the catchment between both water sources.

Returns:

void

Protected Attributes

double available_volume = 0

Total available volume in the water source.

double total_outflow = 0

Total outflow from the water source.

double upstream_source_inflow = 0

Total upstream inflow to the water source.

double wastewater_inflow = 0

Total inflow from wastewater treatment plants.

double upstream_catchment_inflow = 0

Total inflow from upstream catchments into the water source.

double total_demand = 0

Total demand being drawn from the water source.

double policy_added_demand = 0

The total demand added to the water source by policy. FIXME: Definition is not clear.

double permitting_time = NON_INITIALIZED

Permitting time required to build the water source.

vector<Bond*> bonds

Bonds associated with the water source.

double upstream_min_env_inflow = 0

Minimum upstream environmental inflow required by the water source.

double capacity = NON_INITIALIZED

Total capacity of the water source.

vector<int> built_in_sequence

Sequence of water sources that are connected to this water source. FIXME: Needs to be clarified.

vector<double> available_allocated_volumes

Available allocated volumes of raw water supplying the water source.

vector<double> allocated_capacities

Allocated capacities of the water source to each utility.

vector<double> allocated_treatment_capacities

Allocated treatment capacities of the water source to each utility.

vector<double> allocated_treatment_fractions

Allocated treatment fractions of the water source to each utility.

vector<double> allocated_fractions

Allocated overall fractions of the water source to each utility.

vector<double> supply_allocated_fractions

Utilities with allocations to the water source.

vector<int> *utilities_with_allocations = nullptr

Utilities with allocations to the water source.

int wq_pool_id = NON_INITIALIZED

ID of the water quality pool, which is the water source used to ensure minimum environmental flows downstream.

double total_allocated_fraction = NON_INITIALIZED

Total allocated fraction of the catchments supplying the water source.

bool online

Flag indicating if the water source is online.

vector<Catchment> catchments

A vector of all the catchements that supply the water source.

double min_environmental_outflow = 0

Minimum environmental outflow required by the water source.

double evaporated_volume = 0

Total volume evaporated from the water source.

double total_treatment_capacity = 0

Total treatment capacity of the water source.

int highest_alloc_id = NON_INITIALIZED

The ID of the utility with the highest percent allocation from the water source.

Protected Static Attributes

static int seed

Seed to generate the random construction time. FIXME: Needs to be clarified.