Correlatedpy: a python library for distributed learning of correlated equilibrium in multiplayer strategic games.

View Demo · Report Bug · Request Feature

The library implements a distributed learning algorithm allowing players to converge towards a correlated equilibrium point.

Installation

Correlatedpy has a small set of Python dependencies. It is straightforward to install on all operating systems as it only requires the following python packages

• matplotlib
• numpy
• qe

$ python -m pip install correlatedpy

To install Correlatepy on Fedora, use:

$ dnf install python3-correlatepy

The Environment

Parameters

The game has three global parameters that are shared accross all instances of all classes of the game. They can be initialized as follows

history = [(0,0)] # history of action profiles played by players
epsilon = 0.02 # exploration rate
alpha = 0.01 # targetted approximate correlated equilibrium

Players

the Player class has the attributes we list below:

• number: object instance unique identifier
• payoff: player's payoff matrix
• state: player's state ('syn' or 'asyn')
• history: game history
• epsilon: exploration rate
• alpha: approximate correlated alpha-equilibrium

We can now create the players by setting a value for each one of the parameters.

P1 = Player(number = 1, payoff = np.array([[0, 0], [1, -1]]), state = 'asyn', history = [(0, 0)], epsilon = 0.02, alpha = 0.01)
P2 = Player(number = 2, payoff = np.array([[0, 0], [-1, 1]]), state = 'asyn', history = [(0, 0)], epsilon = 0.02, alpha = 0.01)

Game

After creating players, we can now instanciate a game, define how many rounds to play, and add the players to it.

G = Game(iterations = 100000, history = [(0, 0)], epsilon = 0.02, alpha=0.01)

G.add_player(P1)
G.add_player(P2)

Learning

The game is played repeatedly by calling the instance method run().

G.run()

Simulation Results

G.results()

Diagram

Examples of Games

See the documentation for some examples and notebooks.

Chicken Game

This game has two pure Nash equilibria and one mixed Nash equilibrium.

We show the evolution of the probabilities of play of each profile.

Rock-Paper-Scissors

This game has a unique mixed Nash equilibrium point.

The simulation results show the probability of play of each profile.

A 3x2 game

This game has two mixed Nash equilibria.

We show the empirical distribution of play of each profile.

three-player game

Usage

Payoff matrices

For an n-player game with action spaces of size , creating the payoff matrice for player i is performed in the following manner:

>>> import correlatedpy as correlated
>>> A = [[1, 2], [3, 0]]
>>> B = [[0, 2], [3, 1]]
>>> game = correlated.Game(A, B)
>>> for eq in game.support_enumeration():
...     print(eq)
(array([1., 0.]), array([0., 1.]))
(array([0., 1.]), array([1., 0.]))
(array([0.5, 0.5]), array([0.5, 0.5]))
>>> game[[0, 1], [1, 0]]
array([3, 3])

Documentation

Full documentation is available here: http://correlatedpy.readthedocs.io/

Citing

If you use the project in your work, please consider citing it with:

@misc{correlatedpy,
  author = {Boufous, Omar},
  title = {Correlatedpy: a python library for distributed learning of correlated equilibrium in multiplayer strategic games.},
  year = {2021},
  publisher = {GitHub},
  journal = {GitHub repository},
  howpublished = {\url{https://github.com/oboufous/correlatedpy}},
}

Other game theoretic software

• Nashpy is a python library for the computation of equilibria of 2 player strategic games.
• Gambit is a library with a python api and support for more algorithms and more than 2 player games.
• Game theory explorer is a web interface to gambit useful for teaching.
• Axelrod is a research library aimed at the study of the Iterated Prisoners dilemma.

Development

Clone the repository and create a virtual environment:

$ git clone https://github.com/oboufous/correlatedpy.git
$ cd correlatedpy
$ python -m venv env

Activate the virtual environment and install tox:

$ source env/bin/activate
$ python -m pip install tox

Make modifications.

To run the tests:

$ python -m tox

To build the documentation. First install the software which also installs the documentation build requirements.

$ python -m pip install flit
$ python -m flit install --symlink

Then:

$ cd docs
$ make html

Full contribution documentation is available at https://correlatedpy.readthedocs.io/en/latest/contributing/index.html

Pull requests are welcome.

Code of conduct

In the interest of fostering an open and welcoming environment, all contributors, maintainers and users are expected to abide by the Python code of conduct: https://www.python.org/psf/codeofconduct/