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
$ python m pip install correlatedpy
To install Correlatepy on Fedora, use:
$ dnf install python3correlatepy
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 alphaequilibrium
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.
This game has two pure Nash equilibria and one mixed Nash equilibrium.
D  C  

D  0,0  7,2 
C  2,7  6,6 
We show the evolution of the probabilities of play of each profile.
This game has a unique mixed Nash equilibrium point.
R  P  S  

R  0,0  1,1  1,1 
P  1,1  0,0  1,1 
S  1,1  1,1  0,0 
The simulation results show the probability of play of each profile.
A 3×2 game
This game has two mixed Nash equilibria.
X  Y  

A  2,29  16,7 
B  4,7  6,13 
C  4,4  6,6 
We show the empirical distribution of play of each profile.
threeplayer game
X  Y  



Usage
Payoff matrices
For an nplayer game with action spaces of size , creating the payoff matrice for player i is performed in the following manner:
>>> 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])
“>
>>> 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/