DroughtMitigationInstruments Module

API Reference

Below is the API reference for submodules of the DroughtMitigationInstruments module.

Submodule Components

InsuranceStorageToROF.h

class InsuranceStorageToROF : public DroughtMitigationPolicy, public ContinuityModelROF 

#include <InsuranceStorageToROF.h>

The InsuranceStorageToROF class is a subclass of the DroughtMitigationPolicy and ContinuityModelROF classes that implements drought insurance policies based on storage-to-ROF triggers.

The InsuranceStorageToROF class is a subclass of the DroughtMitigationPolicy class that implements water use restrictions based on risk of failure (ROF) triggers.

Created by bernardoct on 5/1/17.

Created by bernardo on 2/3/17.

Public Functions

InsuranceStorageToROF(const int id, vector<WaterSource*> &water_sources, const Graph &water_sources_graph, const vector<vector<int>> &water_sources_to_utilities, vector<Utility*> &utilities, vector<DroughtMitigationPolicy*> &drought_mitigation_policies, vector<MinEnvFlowControl*> min_env_flow_controls, vector<vector<double>> &utilities_rdm, vector<vector<double>> &water_sources_rdm, vector<vector<double>> &policy_rdm, vector<double> &rof_triggers, const double insurance_premium, const vector<double> &fixed_payouts, unsigned long total_simulation_time)

Constructs an InsuranceStorageToROF object for drought insurance policies based on storage-to-ROF triggers.

Parameters:

id – Insurance policy ID.
water_sources – Vector of water sources used in the model.
water_sources_graph – Graph of connections between water sources.
water_sources_to_utilities – Mapping between water sources and utilities.
utilities – Vector of utilities involved in the policy.
drought_mitigation_policies – Vector of drought mitigation policies.
min_env_flow_controls – Vector of minimum environmental flow controls.
utilities_rdm – Random decision matrix for utilities.
water_sources_rdm – Random decision matrix for water sources.
policy_rdm – Random decision matrix for policies.
rof_triggers – Risk-of-failure triggers for insurance payouts.
insurance_premium – Premium multiplier for insurance pricing.
fixed_payouts – Fixed payouts for each utility in case of an insurance trigger.
total_simulation_time – Total simulation duration in weeks.

InsuranceStorageToROF(InsuranceStorageToROF &insurance)

Creates a copy of an existing InsuranceStorageToROF object.

Parameters:: insurance – The InsuranceStorageToROF object to copy.

~InsuranceStorageToROF() override: Destroys the InsuranceStorageToROF object and releases resources.

void priceInsurance(int week)

Calculates the insurance price based on payout probabilities.

Parameters:: week – The current week number.
Returns:: void

virtual void applyPolicy(int week) override

Applies the insurance policy for a given week.

This function runs an ROF calculation of 50 year long simulations to estimate the likelihood that payouts will occur. The price of the insurance is set as (average sum of payouts across all 50 years * insurance premium).

This function overrides the pure virtual function applyPolicy in DroughtMitigationPolicy.

Parameters:: week – The current week.
Returns:: void

virtual void addSystemComponents(vector<Utility*> utilities, vector<WaterSource*> water_sources, vector<MinEnvFlowControl*> min_env_flow_controls) override

Adds Utility and WaterSource objects to the InsuranceStorageToROF policy.

This function overrides the pure virtual function addSystemComponents in DroughtMitigationPolicy.

Parameters:

utilities – Vector of system utilities.
water_sources – Vector of water sources.
min_env_flow_controls – Vector of minimum environmental flow controls.

Returns:

void

virtual void setRealization(unsigned long realization_id, vector<double> &utilities_rdm, vector<double> &water_sources_rdm, vector<double> &policy_rdm) override

Sets the realization parameters for the InsuranceStorageToROF policy.

Parameters:

realization_id – ID of the realization.
utilities_rdm – DU factor multipliers for utilities’ demand growth rates.
water_sources_rdm – DU factor multipliers for water sources financing, construction, and permitting times.
policy_rdm – DU factor multipliers for utilities’ drought mitigation policies effectiveness.

Returns:

void

vector<double> calculateShortTermROFTable(int week, const vector<Utility*> &utilities, const int &n_utilities)

Runs a short-term ROF calculation for a given week.

FIXME: Needs to be extended from the original function from ContinuityModelROF.cpp.

Parameters:

week – The current week for which ROFs should be calculated.
utilities – Vector of utilities for the ROF calculation.
n_utilities – Number of utilities involved.

Returns:

A vector of calculated ROF values for each utility.

virtual void updateOnlineInfrastructure(int week) override

Updates the online infrastructure for the current week.

This function overrides the pure virtual function updateOnlineInfrastructure in DroughtMitigationPolicy.

Parameters:: week – The current week number.
Returns:: void

Private Members

vector<double> rof_triggers: A vector of triggers for insurance payouts based on storage-to-ROF triggers.

const unsigned long total_simulation_time: Total simulation duration in weeks.

const double insurance_premium: The percentage of revenue that is used to pay for insurance.

vector<double> payout_multiplier: A vector of payout multiplier to adjust for partially paid insurance price due to insufficient contingency fund.

vector<double> insurance_price: A vector of insurance prices for each utility as a function of fixed_payouts,revenue, and insurance premiums.

const vector<double> &fixed_payouts: A vector of fixed payouts for each utility in case of an insurance trigger.

vector<double> utilities_revenue_update: A vector for the updated (current year) revenues for each utility.

vector<double> utilities_revenue_last_year: A vector for the prior year’s revenues for each utility.

vector<DroughtMitigationPolicy*> drought_mitigation_policies: A vector of drought mitigation policies.

Restrictions.h

class Restrictions : public DroughtMitigationPolicy 

#include <Restrictions.h>

Public Functions

Restrictions(const int id, const vector<double> &stage_multipliers, const vector<double> &stage_triggers)

DU factor multipliers that scale the volume of demand successfully restricted using water use restrictions at a variety of stages (tiers).

This initializes the restriction stages and associated triggers.

Parameters:

id – Restriction policy ID.
stage_multipliers – Multipliers for water usage demand based on restriction stages.
stage_triggers – A vector of ROF thresholds after which different water use restriction stages are triggered.

Restrictions(const int id, const vector<double> &stage_multipliers, const vector<double> &stage_triggers, const vector<vector<double>> *typesMonthlyDemandFraction, const vector<vector<double>> *typesMonthlyWaterPrice, const vector<vector<double>> *priceMultipliers)

DU factor multipliers that scale the volume of demand successfully restricted using water use restrictions at a variety of stages (tiers). This constructor has additional parameters for pricing water during water restrictions.

Parameters:

id – Restriction policy ID.
stage_multipliers – Multipliers for water usage demand based on restriction stages.
stage_triggers – A vector of ROF thresholds after which different water use restriction stages are triggered.
typesMonthlyDemandFraction – Monthly water demand fractions by consumer type.
typesMonthlyWaterPrice – Monthly water prices by consumer type.
priceMultipliers – Price multipliers for each restriction stage.

Restrictions(const Restrictions &reservoir)

Creates a copy of an existing Restrictions object.

Parameters:: restrictions – The Restrictions object to be copied.

~Restrictions()

Destroy the Restrictions object.

Returns:: void

virtual void applyPolicy(int week) override

Applies the restriction policy for a given week based on the utility’s risk of failure.

Parameters:: week – The current week number.
Returns:: void

virtual void addSystemComponents(vector<Utility*> systems_utilities, vector<WaterSource*> water_sources, vector<MinEnvFlowControl*> min_env_flow_controls) override

Links utilities to the Restrictions policy based on the policy ID.

Parameters:

systems_utilities – Vector of system Utility objects.
water_sources – Vector of water sources (not used in this implementation).
min_env_flow_controls – Vector of minimum environmental flow controls (not used in this implementation).

Throws:

std::logic_error – if the policy already has an assigned utility.
std::invalid_argument – if no matching utility is found for the policy ID.

double getCurrent_multiplier() const

Retrieves the current demand multiplier based on the active restriction stage.

Returns:: The current demand multiplier.

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

Calculates the average weekly water prices for each restriction stage and consumer type across each month.

Parameters:

typesMonthlyDemandFraction – Monthly water demand fractions by consumer type.
typesMonthlyWaterPrice – Monthly water prices by consumer type.
priceMultipliers – Price multipliers for each restriction stage.

Returns:

void

virtual void setRealization(unsigned long realization_id, vector<double> &utilities_rdm, vector<double> &water_sources_rdm, vector<double> &policy_rdm) override

Updates the restriction multipliers based on the policy random decision matrix.

Parameters:

realization_id – Realization ID for the current simulation.
utilities_rdm – Random decision matrix for utilities (not used in this implementation).
water_sources_rdm – Random decision matrix for water sources (not used in this implementation).
policy_rdm – Random decision matrix for policies.

Private Members

vector<double> stage_multipliers: DU factor multipliers that scale the volume of demand successfully restricted using water use restrictions at a variety of stages (tiers).

const vector<double> stage_triggers: A vector of ROF thresholds after which different water use restriction stages are triggered.

double current_multiplier = 0: Current multiplier to be applied to demand.

vector<vector<double>> restricted_weekly_average_volumetric_price: A 2D vector of weekly average volumetric price of water for each restriction stage.

Transfers.h

class Transfers : public DroughtMitigationPolicy 

#include <Transfers.h>

The Transfers class is a subclass of the DroughtMitigationPolicy class that implements treated water transfers based on risk of failure (ROF) triggers.

Created by bernardo on 2/21/17.

Public Functions

Transfers(const int id, const int source_utility_id, int transfer_water_source_id, const double source_treatment_buffer, const vector<int> &buyers_ids, const vector<double> &pipe_transfer_capacities, const vector<double> &buyers_transfer_triggers, const Graph utilities_graph, vector<double> conveyance_costs, vector<int> pipe_owner)

Constructs a Transfers object to manage water transfer allocations among utilities without seller information. This function initializes all data structures and ensures input validity.

This constructor allocates transfers by trying to minimize the mean square error between the optimal allocations and allocation requests, and between the available amount of water from source and actual conveyed capacity, which is limited by pipe conveyance capacities.

Parameters:

id – Transfer policy ID.
source_utility_id – The ID of the utility selling water to other utilities to fulfil transfer requests.
transfer_water_source_id – The ID of the water source from which the source utility will be transferring water.
source_treatment_buffer – Treatment capacity to be left unused in source utility.
buyers_ids – IDs of the buyer utilities.
pipe_transfer_capacities – Capacities of transfer pipes.
buyers_transfer_triggers – A vector of each buyer’s ROF threshold after which they will request a water transfer.
utilities_graph – A Graph object representing utilities and their connections.
conveyance_costs – Amount charged by pipe owning utility to convey water to another utility.
pipe_owner – IDs of utilities owning each pipe.

Throws:

std::invalid_argument – if the source utility is also listed as a buyer.

Transfers(const int id, const int source_utility_id, int transfer_water_source_id, const double source_treatment_buffer, const vector<int> &buyers_ids, const vector<double> &pipe_transfer_capacities, const vector<double> &buyers_transfer_triggers, const double seller_transfer_trigger, const Graph utilities_graph, vector<double> conveyance_costs, vector<int> pipe_owner)

Constructs a Transfers object to manage water transfer allocations among utilities including seller information. This function initializes all data structures and ensures input validity.

This constructor allocates transfers by trying to minimize the mean square error between the optimal allocations and allocation requests, and between the available amount of water from source and actual conveyed capacity, which is limited by pipe conveyance capacities.

Parameters:

id – Transfer policy ID.
source_utility_id – The ID of the utility selling water to other utilities to fulfil transfer requests.
transfer_water_source_id – The ID of the water source from which the source utility will be transferring water.
source_treatment_buffer – Treatment capacity to be left unused in source utility.
buyers_ids – IDs of the buyer utilities.
pipe_transfer_capacities – Capacities of transfer pipes.
buyers_transfer_triggers – A vector of each buyer’s ROF threshold after which they will request a water transfer.
seller_transfer_trigger – The short-term ROF threshold above which the seller will not fulfil transfer requests.
utilities_graph – A Graph object representing utilities and their connections.
conveyance_costs – Amount charged by pipe owning utility to convey water to another utility.
pipe_owner – IDs of utilities owning each pipe.

Throws:

std::invalid_argument – if the source utility is also listed as a buyer.

Transfers(const Transfers &transfers)

Creates a copy of an existing Transfers object. This function duplicates all properties and settings of the given Transfers object.

Parameters:: transfers – The Transfers object to be copied.

~Transfers(): Destroys the Transfers object, releasing allocated resources.

const vector<double> &getAllocations() const

Retrieves the current water allocations.

Returns:: A constant reference to the vector of allocations.

virtual void applyPolicy(int week) override

Applies the water transfer policy for a given week.

Parameters:: week – The current week to solve.
Returns:: void

virtual void addSystemComponents(vector<Utility*> system_utilities, vector<WaterSource*> water_sources, vector<MinEnvFlowControl*> min_env_flow_controls) override

Adds water sources, as well as buying and purchasing utilities to the Transfers policy for initialization. FIXME: RIGHT NOW TRANSFERS CAN ONLY HAVE ONE SOURCE. THIS NEEDS TO BE EXPANDED.