MFGLib: A Library for Mean-Field Games

Overview

MFGLib is an open-source Python library dedicated to solving Nash equilibria (NEs) for generic mean-field games (MFGs) with a user-friendly and customizable interface, aiming at promoting both applications and research of MFGs. On one hand, it facilitates the creation and analysis of arbitrary user-defined MFG environments with minimal prior knowledge on MFGs. On the other hand, it serves as a modular and extensible code base for the community to easily prototype and implement new algorithms and environments of MFGs as well as their variants and generalizations.

The official documentation for MFGLib is available at https://mfglib.readthedocs.io/en/latest/. A companion introductory paper can be found at https://arxiv.org/abs/2304.08630.

Installation

MFGLib supports all major platforms and can be installed with pip:

$ pip install mfglib

Developers who would like to contribute to the library should refer to the Contributing section on the project's documentation site.

Usage

Here is an example that shows how to use MFGLib to define an environment called rock paper scissors, and solve it using MF-OMO with default hyperparameters and tolerances, and plot the exploitability scores over iterations.

from mfglib.env import Environment
from mfglib.alg import MFOMO
from mfglib.scoring import exploitability_score
import matplotlib.pyplot as plt

# Environment
rock_paper_scissors_instance = Environment.rock_paper_scissors()

# Run the MF-OMO algorithm with default hyperparameters and default tolerances and plot exploitability scores
solns, expls, runtimes = MFOMO().solve(rock_paper_scissors_instance, max_iter=300, verbose=True)

plt.semilogy(runtimes, exploitability_score(rock_paper_scissors_instance, solns)) 
plt.grid(True)
plt.xlabel("Runtime (seconds)")
plt.ylabel("Exploitability")
plt.title("Rock Paper Scissors Environment - MFOMO Algorithm")
plt.show()

Please refer to the documentation for more info on how to use the library.

Citing

If you wish to cite MFGLib, please use the following:

@article{mfglib,
    author  = {Guo, X. and Hu, A. and Santamaria, M. and Tajrobehkar, M. and Zhang, J.},
    title   = {{MFGLib}: A Library for Mean Field Games},
    journal = {arXiv preprint arXiv:2304.08630},
    year    = {2023}
}

If you find MFGLib to be helpful and would like to send virtual kudos, please consider leaving a star on the GitHub repository.