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 in any n-player normal form game.

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
• tqdm

Stable release

To install the latest stable version:

bash $ python -m pip install correlatedpy

To install Correlatepy on Fedora, use:

sh $ dnf install python3-correlatepy

The Environment

Parameters

The game has two global parameters that are shared accross all instances of all classes of the game. They can be initialized as follows for a two-player game

```python

history = [(0,0)] # history contaning the initial action profile played by the two players epsilon = 0.02 # targetted approximate correlated equilibrium ```

Players

the Player class has the attributes we list below:

• number: object instance unique identifier
• payoff: player's payoff matrix
• history: game history
• epsilon: targetted approximate correlated expislon-equilibrium

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

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

```

Game

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

```python G = Game(history = [(0, 0)], epsilon = 0.02)

G.addplayer(P1) G.addplayer(P2)

```

Learning

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

python G.runGame() G.getResults()

Simulation results are shown. In particular, the correlated equilibrium distribution reached is displyed as well as the evolution of the probabilities of action profiles as depicted in the examples below. Note that all game attributes can be used for further analysis (e.g., regret computation).

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.

A three-player game

Usage

Payoff matrices

For an n-player game with action spaces of size , a payoff matrix of size needs to be created for each player.

Creating the payoff matrice for player i can be performed in the following manner:

```python

import correlatedpy game = Game(history = [(0, 0)], epsilon = 0.02) u1 = [[1, 2], [3, 0]] u2 = [[0, 2], [3, 1]] P1 = Player(number = 1 payoff = u1, history = [(0, 0)], epsilon = 0.02) P2 = Player(number = 2 payoff = u2, history = [(0, 0)], epsilon = 0.02) game.addplayer(P1) game.addplayer(P2) game.runGame() game.getResults() ```

Documentation

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

Citing

If you use the project in your work, please consider citing it with: bibtex @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:

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

```

Activate the virtual environment and install tox:

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

```

Make modifications.

To run the tests:

```bash $ python -m tox

```

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

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

Then:

bash $ 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/