Class NashGame

Class Documentation

class Game::NashGame

Class to model Nash-cournot games with each player playing a QP.

Stores a vector of QPs with each player’s optimization problem. Potentially common (leader) constraints can be stored too.

Helpful in rewriting the Nash-Cournot game as an LCP Helpful in rewriting leader constraints after incorporating dual variables etc

Warning

This has public fields which if accessed and changed can cause undefined behavior!

Public Functions

inline explicit NashGame(GRBEnv *e) noexcept

To be used only when NashGame is being loaded from a file.

explicit NashGame(GRBEnv *e, const std::vector<std::shared_ptr<MathOpt::MP_Param>> &players, arma::sp_mat MC, arma::vec MCRHS, unsigned int nLeadVar = 0, arma::sp_mat leadA = {}, arma::vec leadRHS = {})

Constructing a NashGame from a set of MathOpt::MP_Param, Market clearing constraints.

Construct a NashGame by giving a std::vector of pointers to MP_Param, defining each player’s game A set of Market clearing constraints and its RHS And if there are leader variables, the number of leader vars.

Have a std::vector of pointers to MathOpt::MP_Param ready such that the variables are separated in \(x^{i}\) and \(x^{-i}\) format.

In the correct ordering of variables, have the Market clearing equations ready.

Now call this constructor. It will allocate appropriate space for the dual variables for each player.

Parameters
  • e – A pointer to the Gurobi Environment

  • players – The MathOpt::MP_Param associated to the players

  • MC – Market clearing LHS matrix

  • MCRHS – Market clearing RHS vector

  • nLeadVar – Number of leaders’ variables

  • leadA – Leaders’ constraints

  • leadRHS – Leaders’ RHSs

NashGame(const NashGame &N)

Default copy constructor.

Parameters

N – The original copy object

~NashGame() = default

Default destructor.

const NashGame &formulateLCP(arma::sp_mat &M, arma::vec &q, perps &Compl, VariableBounds &Bounds, bool writeToFile = false, const std::string &M_name = "dat/LCP.txt", const std::string &q_name = "dat/q.txt") const

Formulates the LCP corresponding to the Nash game. Computes the KKT conditions for each Player, calling MP_Param::KKT. Arranges them systematically to return M, q as an LCP \(0\leq q \perp Mx+q \geq 0 \). The way the variables of the players get distributed is shown in the image below.

../_images/FormulateLCP.png

Warning

Does not return the leader constraints. Use NashGame::rewriteLeadCons() to handle them

Parameters
  • M – The output matrix M

  • q – The output vector q

  • Compl – The output complementarities pairings

  • OutBounds – The output Bounds on variables

  • writeToFile – If true, writes M and q to file.k

  • M_name – Filename for M

  • q_name – Filename for Q

Returns

arma::sp_mat rewriteLeadCons() const

Rewrites leader constraint adjusting for dual variables. Rewrites leader constraints given earlier with added empty columns and spaces corresponding to Market clearing duals and other equation duals. This becomes important if the Lower level complementarity problem is passed to LCP with upper level constraints.

Returns

The matrix with the leader constraints

inline arma::vec getLeadRHS() const

Gets the RHS of the Leader Constraints.

Returns

THe LeaderConstraintsRHS object

inline arma::vec getMCLeadRHS() const

Gets the RHS of the Market Clearing Constraints plus the leader ones.

Returns

THe queried object

std::unique_ptr<GRBModel> respond(unsigned int player, const arma::vec &x, bool fullvec = true) const

Given the decision of other players, find the optimal response for player in position player. Given the strategy of each player, returns a Gurobi Model that has the optimal strategy of the player at position player.

Parameters
  • player – The player id

  • x – A std::vector of pure strategies (either for all players or all other players)

  • fullvec – True if x contains the strategy for all players

Returns

double respondSol(arma::vec &sol, unsigned int player, const arma::vec &x, bool fullvec = true) const

Returns the optimal objective value that is obtainable for the player player given the decision x of all other players. Calls Game::NashGame::respond and obtains the std::unique_ptr to GRBModel of best response by player player. Then solves the model and returns the appropriate objective value.

Parameters
  • sol – Output optimal response

  • player – The input player’s id

  • x – A std::vector of pure strategies (either for all players or all other players)

  • fullvec – True if x contains the strategy for all players

Returns

The optimal objective value for the player player.

arma::vec computeQPObjectiveValues(const arma::vec &x, bool checkFeas = false) const

Computes players’ objective. Computes the objective value of each player in the Game::NashGame object.

Returns

An arma::vec with the objective values.

bool isSolved(const arma::vec &sol, unsigned int &violPlayer, arma::vec &violSol, double tol = 1e-4) const

Checks if the Nash game is solved.

Checks if the Nash game is solved, if not provides a proof of deviation

Parameters
  • sol – The std::vector of pure strategies for the Nash Game

  • violPlayer – Output index of the player with profitable deviation

  • violSol – The output pure strategy for that player - which gives a profitable deviation

  • tol – The deviation tolerance

NashGame &addDummy(unsigned int par = 0, int position = -1)

Add dummy variables (parameters) in a NashGame object. These are just zero columns that don’t feature in the problem anywhere. They are of importance only where the NashGame gets converted into an LCP and gets parametrized. Typically, they appear in the upper level objective in such a case.

Parameters
  • par – Number of parameters

  • position – Position of the parameters

Returns

NashGame &addLeadCons(const arma::vec &a, double b)

Adds Leader constraint to a NashGame object. In case common constraint to all followers is to be added (like a leader constraint in an MPEC), this function can be used. It adds a single constraint \( a^Tx \leq b\).

Parameters
  • a – The constraint LHS

  • b – The constraint RHS

Returns

A pointer to this

void write(const std::string &filename, bool append = true, bool KKT = false) const

Writes the Nash Game sum up to a file.

Parameters
  • filename – The filename

  • append – Should the method append to the file?

  • KKT – True if the KKT needs to be included

void save(const std::string &filename, bool erase = true) const

Saves the Game::NashGame object in a loadable file.

long int load(const std::string &filename, long int pos = 0)

Loads the Game::NashGame object stored in a file.

Loads the NashGame object stored in a file. Before calling this function, use the constructor NashGame::NashGame(GRBEnv *Env) to initialize. Loads the NashGame object stored in a file. Before calling this function, use the constructor NashGame::NashGame(GRBEnv *Env) to initialize.

Example usage:

int main()
{
        GRBEnv Env;
        Game::NashGame N(&Env);
        N.load("./dat/Ndata.dat");
        std::cout<<N<<'\n';
        return 0;
}

Parameters
  • filename – The filename

  • pos – The start writing position

Returns

The end position

Private Functions

void setPositions()

Stores the position of each players’ primal and dual variables. Also allocates Leader’s position appropriately. The ordering is according to the columns of the following image.

../_images/FormulateLCP.png

Private Members

GRBEnv *Env = nullptr

A pointer to the Gurobi Environment.

arma::sp_mat LeaderConstraints

Upper level leader constraints LHS.

arma::vec LeaderConstraintsRHS

Upper level leader constraints RHS.

unsigned int NumPlayers

Number of players in the Nash Game.

VariableBounds Bounds

BoundsX on primal variables.

std::vector<std::shared_ptr<MathOpt::MP_Param>> Players

The QP that each player solves.

arma::sp_mat MarketClearing

Market clearing constraints.

arma::vec MCRHS

RHS to the Market Clearing constraints.

std::vector<unsigned int> PrimalPosition

In the vector of variables of all players, which position does the variable corresponding to this player starts.

std::vector<unsigned int> DualPosition

In the vector of variables of all players, which position do the DUAL variable corresponding to this player starts.

unsigned int MC_DualPosition = {}

Manages the position of Market clearing constraints’ duals.

unsigned int LeaderPosition = {}

Manages the position of where the leader’s variables start.

unsigned int numLeaderVar

Manages the position of where the leader’s variables start. These many variables will not have a matching complementary equations.

Friends

inline friend std::ostream &operator<<(std::ostream &os, const NashGame &N)