Models

namespace Models
namespace EPEC

Typedefs

typedef struct FollPar FollPar

This namespace contains modeling tools for international energy markets with climate-conscious countries.

The parameters for each follower

typedef struct DemPar DemPar

The parameters for each leader demand curve.

typedef struct LeadPar LeadPar

The parameters for each leader.

typedef struct LeadAllPar LeadAllPar

The parameters for each leader.

using LeadLocs = std::map<LeaderVars, unsigned int>

Enums

enum class TaxType

Values:

enumerator StandardTax

Each producer can have a different tax level per unit-energy.

enumerator SingleTax

Each producer has the same tax level per unit-energy.

enumerator CarbonTax

The tax to each follower is proportional to the CO2.

enum class LeaderVars

Values:

enumerator FollowerStart

Start of followers variables.

enumerator NetImport

Net Import variable.

enumerator NetExport

Net Export variable.

enumerator CountryImport

Net import variables from each other leader.

enumerator Caps

Caps variables.

enumerator Tax

Tax variables.

enumerator TaxQuad

Quadratic (carbon) tax variables.

enumerator DualVar

Dual variables.

enumerator ConvHullDummy

Extra convex-hull variables.

enumerator End

End of variables.

enum class prn

Values:

enumerator label
enumerator val

Functions

std::ostream &operator<<(std::ostream &ost, const FollPar &P)

Print the FollPar.

Parameters

  • ost – Output Stream

  • P – The object to print

Returns

An ostream

std::ostream &operator<<(std::ostream &ost, const DemPar P)

Print the DemPar.

Parameters

  • ost – Output Stream

  • P – The object to print

Returns

An ostream

std::ostream &operator<<(std::ostream &ost, const LeadPar P)

Print the LeadPar.

Parameters

  • ost – Output Stream

  • P – The object to print

Returns

An ostream

std::ostream &operator<<(std::ostream &ost, const LeadAllPar &P)

Print the LeadAllPar.

Parameters

  • ost – Output Stream

  • P – The object to print

Returns

An ostream

std::ostream &operator<<(std::ostream &ost, const LeaderVars l)

Print the LeaderVars.

Parameters

  • ost – Output Stream

  • l – The object to print

Returns

An ostream

std::ostream &operator<<(std::ostream &ost, const EPECInstance &I)

Print the EPECInstance.

Parameters

  • ost – Output Stream

  • I – The object to print

Returns

An ostream

void increaseVal(LeadLocs &L, const LeaderVars start, const unsigned int val, const bool startnext = true)

This method increases the size of the leader locations.

Note

Should be called ONLY after initializing L by calling Models::EPEC::init

Parameters

  • L – The LeadLocs to increase

  • start – The start Leading Vars

  • val – The size of the increase

  • startnext – Should the append after start?

void decreaseVal(LeadLocs &L, const LeaderVars start, const unsigned int val, const bool startnext = true)

This method decreases the size of the leader locations.

Note

Should be called ONLY after initializing L by calling Models::EPEC::init

Parameters

  • L – The LeadLocs to decrease

  • start – The start Leading Vars

  • val – The size of the decrease

  • startnext – Should the append after start?

void init(LeadLocs &L)

Initializes the LeadLocs.

Parameters

L – The input LeadLocs leader locations.

LeaderVars operator+(Models::EPEC::LeaderVars a, int b)

Perform an addition of the number of leadervars plus a term b.

Parameters

  • a – The LeaderVars

  • b – The int b

Returns

The size of the two input, summed.

std::ostream &operator<<(std::ostream &ost, Models::EPEC::prn l)

Helper class to print label and their values.

Parameters

  • ost – Output stream

  • l – The prn to print

Returns

An std::oststream

struct FollPar
#include <epec_models.h>

Stores the parameters of the follower in a country model.

Public Functions

inline FollPar(std::vector<double> costs_quad_ = {}, std::vector<double> costs_lin_ = {}, std::vector<double> capacities_ = {}, std::vector<double> emission_costs_ = {}, std::vector<double> tax_caps_ = {}, std::vector<std::string> names_ = {})

Public Members

std::vector<double> costs_quad = {}

Quadratic coefficient of i-th follower’s cost. Size of this std::vector should be equal to n_followers.

std::vector<double> costs_lin = {}

Linear coefficient of i-th follower’s cost. Size of this std::vector should be equal to n_followers.

std::vector<double> capacities = {}

Production capacity of each follower. Size of this std::vector should be equal to n_followers.

std::vector<double> emission_costs = {}

Emission costs for unit quantity of the fuel. Emission costs feature only on the leader’s problem.

std::vector<double> tax_caps = {}

Individual tax caps for each follower.

std::vector<std::string> names = {}

Optional Names for the Followers.

struct DemPar
#include <epec_models.h>

Public Functions

inline DemPar(double alpha = 100, double beta = 2)

Public Members

double alpha = 100

Intercept of the demand curve. Written as: Price = alpha - beta*(Total quantity in domestic market)

double beta = 2

Slope of the demand curve. Written as: Price = alpha - beta*(Total quantity in domestic market)

struct LeadPar
#include <epec_models.h>

Public Functions

inline LeadPar(double imp_lim = -1, double exp_lim = -1, double price_limit = -1, bool tax_revenue = false, unsigned int tax_type_ = 0, bool tradeBool = true)

Standard constructor for LeadPar.

s

Parameters

  • imp_lim – Import cap

  • exp_lim – Export cap

  • price_limit – Price cap

  • tax_revenue – Leader tax revenue

  • tax_type_ – Taxation type

  • tradeBool – Is trade allowed?

Public Members

double import_limit = -1

Maximum net import in the country. If no limit, set the value as -1;.

double export_limit = -1

Maximum net export in the country. If no limit, set the value as -1;.

double price_limit = -1

Government does not want the price to exceed this limit.

bool tradeAllowed = true

False if the country cannot trade with other countries.

Models::EPEC::TaxType tax_type = Models::EPEC::TaxType::StandardTax

The taxation type.

bool tax_revenue = false
struct LeadAllPar
#include <epec_models.h>

Stores the parameters of a country model.

Public Functions

inline LeadAllPar(unsigned int n_foll, std::string name, Models::EPEC::FollPar FP = {}, Models::EPEC::DemPar DP = {}, Models::EPEC::LeadPar LP = {})

Public Members

unsigned int n_followers

Number of followers in the country.

std::string name

Country Name.

Models::EPEC::FollPar FollowerParam = {}

A struct to hold Follower Parameters.

Models::EPEC::DemPar DemandParam = {}

A struct to hold Demand Parameters.

Models::EPEC::LeadPar LeaderParam = {}

A struct to hold Leader Parameters.

struct EPECInstance
#include <epec_models.h>

Stores a single Instance.

Public Functions

inline explicit EPECInstance(std::string filename)

Constructor from instance file.

inline EPECInstance(std::vector<Models::EPEC::LeadAllPar> Countries_, arma::sp_mat Transp_)

Constructor from instance objects.

void load(const std::string &filename)

Reads the EPECInstance from a file.

Reads an instance file and return a vector of LeadAllPar that can be fed to the EPEC class filename dictates the name of the JSON instance file.

void save(const std::string &filename)

Writes the EPECInstance from a file.

Writes the current EPEC instance to the standard JSON instance file filename dictates the name of the JSON instance file.

Public Members

std::vector<Models::EPEC::LeadAllPar> Countries = {}

LeadAllPar vector.

arma::sp_mat TransportationCosts = {}

Transportation costs matrix.

class EPEC : public Game::EPEC
#include <epec_models.h>

Public Functions

EPEC() = delete
inline EPEC(GRBEnv *env, arma::sp_mat TranspCosts = {})
EPEC &addCountry(LeadAllPar Params, const unsigned int addnlLeadVars = 0)

Models a Standard Nash-Cournot game within a country

A Nash cournot game is played among the followers, for the leader-decided values of import export, caps and taxations on all players. The total quantity used in the demand equation is the sum of quantity produced by all followers + any import - any export.

Use \(l_i\) to denote the \(i\)-th element in costs_lin and \(q_i\) for the \(i\)-th element in costs_quad. Then to produce quantity \(x_i\), the \(i\)-th producer’s cost will be

\[ l_ix_i + \frac{1}{2}q_ix_i^2 \]
In addition to this, the leader may impose “tax”, which could increase \(l_i\) for each player.

Total quantity in the market is given by sum of quantities produced by all producers adjusted by imports and exports

\[{Total\quad Quantity} = \sum_i x_i + x_{imp} - x_{exp} \]
The demand curve in the market is given by
\[{Price} = a-b({Total\quad Quantity})\]

Each follower is also constrained by a maximum production capacity her infrastructure allows. And each follower is constrained by a cap on their production, that is imposed by the leader.

Each follower decides \(x_i\) noncooperatively maximizing profits.

The leader decides quantity imported \(q_{imp}\), quantity exported \(q_{exp}\), cap on each player, \(\tilde{x_i}\), and the tax for each player \(t_i\).

The leader is also constrained to not export or import anything more than the limits set by export_limit and import_limit. A negative value to these input variables imply that there is no such limit.

Similarly the leader cannot also impose tax on any player greater than what is dictated by the input variable max_tax.

Parameters

  • Params – The Parameter structure for the leader

  • addnlLeadVars – Create columns with 0s in it. To handle additional dummy leader variables.

Returns

Pointer to LCP object dynamically created using new.

EPEC &addTranspCosts(const arma::sp_mat &costs)

Adds intercountry transportation costs matrix.

Adds the transportation cost matrix. Entry in row i and column j of this matrix corresponds to the unit transportation costs for sending fuel from country i to country j.

Parameters

costs – The transportation cost matrix

unsigned int getPosition(const unsigned int countryCount, const LeaderVars var = LeaderVars::FollowerStart) const

Gets position of a variable in a country.

unsigned int getPosition(const std::string &countryCount, const LeaderVars var = LeaderVars::FollowerStart) const

Gets position of a variable in a country given the country name and the variable.

EPEC &unlock()

Unlocks an EPEC model.

A Finalized model cannot be edited unless it is unlocked first.

std::unique_ptr<GRBModel> Respond(const std::string &name, const arma::vec &x) const
Game::NashGame *get_LowerLevelNash(const unsigned int i) const

Returns a non-owning pointer to the i -th country’s lower level NashGame.

void writeLeadParams(const std::string &filename, const unsigned int i, bool append = true) const

Write to a fine the parameters of leader i.

Parameters

  • filename – The filename

  • i – The index of the leader

  • append – Append to the file?

void readSolutionJSON(const std::string &filename)
void writeSolutionJSON(const std::string &filename, const arma::vec &x, const arma::vec &z) const

Writes the solution to a JSON file.

Parameters

  • filename – The filename

  • x – The x vector for the solution

  • z – The z vector for the solution

void writeSolution(const int writeLevel, const std::string &filename) const
inline const EPECInstance getInstance() const

Get the current EPECInstance loaded.

Public Members

bool quadraticTax = {false}

If set to true, a term for the quadratic tax is added to each leader objective.

Private Functions

virtual void makeObjectivePlayer(const unsigned int i, MathOpt::QP_Objective &QP_obj) final

Makes the objective function of each country.

Parameters

  • i – The location of the country whose objective is to be made

  • QP_obj – The object where the objective parameters are to be stored.

virtual void updateLocations() override

This function is called after makePlayerQP()

virtual void preFinalize() override

Empty function - optionally re-implementable in derived class.

This function can be optionally implemented by the derived class. Code in this class will be run before calling Game::EPEC::finalize().

inline virtual void postFinalize() override

Empty function - optionally re-implementable in derived class.

This function can be optionally implemented by the derived class. Code in this class will be run after calling Game::EPEC::finalize().

bool dataCheck(bool chkAllLeadPars = true, bool chkcountriesLL = true, bool chkMC_QP = true, bool chkLeadConses = true, bool chkLeadRHSes = true, bool chknImportMarkets = true, bool chkLocations = true, bool chkLeaderLocations = true, bool chkLeadObjec = true) const

Checks the data in Models::EPEC::EPEC object, based on checking flags, n is the number of countries in the Models::EPEC::EPEC object.

Parameters
bool ParamValid(const LeadAllPar &Param) const

Checks that the parameter given to add a country is valid. Does not have obvious errors.

Checks the Validity of Models::EPEC::LeadAllPar object.

Checks the following:

  • Size of FollowerParam.costs_lin, FollowerParam.costs_quad, FollowerParam.capacities, FollowerParam.emission_costs are all equal to Params.n_followers - DemandParam.alpha and DemandParam.beta are greater than zero - name is not empty - name does not match with the name of any other existing countries in the EPEC object.

Parameters

Param – Object whose validity is to be tested

void make_LL_QP(const LeadAllPar &Params, const unsigned int follower, MathOpt::QP_Param *Foll, const LeadLocs &Loc) noexcept

Makes the lower level quadratic program object for each follower.

Makes Lower Level Quadratic Programs.

Sets the constraints and objective for the lower level problem (i.e., the follower)

Parameters

  • Params – The Parameters object

  • follower – Which follower’s QP has to be made?

  • Foll – Non-owning pointer to the Follower QP_Param object

  • Loc – LeadLocs object for accessing different leader locations.

void make_LL_LeadCons(arma::sp_mat &LeadCons, arma::vec &LeadRHS, const LeadAllPar &Param, const Models::EPEC::LeadLocs &Loc = {}, const unsigned int import_lim_cons = 1, const unsigned int export_lim_cons = 1, const unsigned int price_lim_cons = 1, const unsigned int activeTaxCaps = 0, const unsigned int disableTrade = 0) const noexcept

Makes the leader constraint matrix and RHS.

Makes the leader level constraints for a country. The constraints added are as follows:

\[\begin{split}\begin{eqnarray} t_i^{I} &\leq& \bar{t_i^{I}}\\ q^{import} - q^{export} &\leq& \bar{q^{import}}\\ q^{export} - q^{import} &\leq& \bar{q^{export}}\\ \alpha - \beta\left(q^{import} - q^{export} + \sum_i q_i \right) &\leq& *\bar{\pi}\\ q^{export} &\leq& \sum_i q_i +q^{import} \end{eqnarray}\end{split}\]
Here \(\bar{q^{import}}\) and \(\bar{q^{export}}\) denote the net import limit and export limit respectively. \(\bar\pi\) is the maximum local price that the government desires to have.

The first two constraints above limit net imports and exports respectively. The third constraint limits local price. These constraints are added only if the RHS parameters are given as non-negative value. A default value of -1 to any of these parameters (given in Models::EPEC::LeadAllPar Params object) ensures that these constraints are not added. The last constraint is always added. It ensures that the country does not export more than what it has produced + imported!

Parameters

  • LeadCons – The LHS matrix of leader constraints (for output)

  • LeadRHS – RHS vector for leader constraints (for output)

  • Param – All country specific parameters

  • Loc – Location of variables

  • import_lim_cons – Does a constraint on import limit exist or no limit?

  • export_lim_cons – Does a constraint on export limit exist or no limit?

  • price_lim_cons – Does a constraint on price limit exist or no limit?

  • activeTaxCaps – Number of active Tax Caps constraints. If strictly positive, tax cap constraint(s) will be enforced

  • disableTrade – If greater than zero, the quantity of exported goods will be forced to zero

void add_Leaders_tradebalance_constraints(const unsigned int i)

Adds leaders’ trade balance constraints for import-exports.

Does the following job:

  • Counts the number of import markets for the country i to store in Models::EPEC::EPEC::nImportMarkets - Adds the trade balance constraint. Total quantity imported by country i = Sum of Total quantity exported by each country to country i. - Updates the LeadLocs in Models::EPEC::EPEC::Locations.at(i)

void make_MC_leader(const unsigned int i)

Makes the market clearing constraint for country i.

Writes the market clearing constraint as a MathOpt::QP_Param and stores it in Models::EPEC::EPEC::MC_QP

virtual void makeMCConstraints(arma::sp_mat &MCLHS, arma::vec &MCRHS) const override

Returns leader’s Market clearing constraints in matrix form.

void WriteCountrySolution(const unsigned int i, const std::string &filename, const arma::vec &x, const bool append = true) const

Write the country solution data to a file.

Parameters

  • i – The country (leader) index

  • filename – The filename

  • x – The solution vector

  • append – Append to file?

void WriteFollower(const unsigned int i, const unsigned int j, const std::string &filename, const arma::vec &x, bool append) const

Writes the follower’s solution to a file.

Parameters

  • i – The leader’s index

  • j – The follower’s index

  • filename – The filename

  • x – The solution vector

  • append – Should it append to a file?

Private Members

std::vector<LeadAllPar> AllLeadPars = {}

The parameters of each leader in the EPEC game.

std::vector<std::shared_ptr<MathOpt::QP_Param>> MC_QP = {}

The QP corresponding to the market clearing condition of each player.

arma::sp_mat TranspCosts = {}

Transportation costs between pairs of countries.

std::vector<unsigned int> nImportMarkets = {}

Number of countries from which the i-th country imports.

std::vector<LeadLocs> Locations = {}

Location of variables for each country.

std::map<std::string, unsigned int> name2nos = {}
unsigned int taxVars = {0}
std::vector<arma::sp_mat> LeadConses = {}

Stores each leader’s constraint LHS.

std::vector<arma::vec> LeadRHSes = {}

Stores each leader’s constraint RHS.

namespace IPG

Functions

std::ostream &operator<<(std::ostream &ost, IPGInstance I)
struct IPGInstance
#include <ipg_models.h>

Public Functions

void load(std::string filename)

Reads the IPGInstance from a file.

void save(std::string filename)

Writes the IPGInstance from a file.

void addIPParam(const MathOpt::IP_Param &ip, const std::string filename)

Protected Attributes

std::vector<std::string> IPFiles = {}
unsigned int NumVariables = {0}
std::vector<unsigned int> PlayerVariables = {}

Friends

friend class Models::IPG::IPG
class IPG : public Game::IPG
#include <ipg_models.h>

Public Functions

IPG(GRBEnv *env, const std::string instanceFileName)
IPG(GRBEnv *env, IPGInstance instance)
std::shared_ptr<const MathOpt::IP_Param> getIPParam(unsigned int player)
void writeSolution(std::string filename) const
inline const IPGInstance getInstance() const

Get the current EPECInstance loaded.

Private Functions

inline virtual void preFinalize() override

Virtual (empty) method. Can be implemented by a derived class.

inline virtual void postFinalize() override

Virtual (empty) method. Can be implemented by a derived class.

Private Members

IPGInstance Instance