Class EPEC

Inheritance Relationships

Base Type

Class Documentation

class EPEC : public Game::EPEC

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.