Introduction
BCESolve is a library of routines for representing, solving, and analyzing Bayes correlated equilibria (BCE), a solution concept that generalized correlated equilibrium to games of incomplete information. BCE, like correlated equilibria, are joint distributions that satisfy a series of linear constraints. The library utilizes Gurobi's linear programming package to solve for BCE that maximize a given linear objective, such as expected payoffs of the players.
The package consists of two main components. The first piece is a library of C++ classes for representing and solving games of incomplete information, and the second is a graphical user interface (BCEViewer) for using and interacting with the solver library. The purpose of this guide is to give advanced users an overview of how the library and graphical interface are structured.
BCESolve makes use of external software packages: the Boost libraries are used for serialalization of data relating to games and solutions, which are represented with the BCEGame and BCESolution classes and are saved as .bgm and .bce files, respectively. The graphical interface uses the Qt framework and the Qt plotting library QCustomPlot.
Installation
The source code is also available through the author's github page. The code has been most recently compiled on Mac OS 12.1 using Boost 1.76 and Gurobi 9.0.3. BCEViewer was compiled using Qt 6.2. To compile the source and example code yourself, you need to change the relevant variables in localsettings.mk and locasettings2.mk to direct the compiler to Boost and Gurobi. Importantly, just directing the compiler to Gurobi is not sufficient; your Gurobi installation must be associated with a valid license. A free academic license may be obtained here: Gurobi University License. You can then build the desired examples by calling "make examplename" (the .cpp or .hpp ending is not included) in the example dirctory. After you build the source, you can build the BCEViewer program from the viewer directory by first calling "qmake" and then running "make".
Overview of the solver library
The BCESolve library contains a series of classes for representing, solving, and analyzing BCE. The BCEAbstractGame class is a base class for representing games of incomplete information. One must derive from this class, and reimplement its BCEGame::objective and BCEGame::prior methods to reflect the payoff functions and the distribution of the state and types for the particular game of interest.
The BCESolver class uses Gurobi to solve a game represented by an object derived from the BCEAbstractGame class, by maximizing a particular linear objective over all BCE for that game. The output from the BCESolver class is stored in a BCESolution object. BCESolution objects can be serialized and de-serialized, and the class also contains routines for analyzing the BCE contained within.
For a more detailed description of the solver library and its usage, see The BCESolve library.
Overview of the graphical interface
BCESolve includes a graphical interface for interacting with the library called BCEViewer. The interface contains three tabs: a game tab, a solution tab, and a log tab. The game tab facilitates both creation of custom games and editing of games that were generated outside the interface. The solution tab has various visualizations for understanding equilibria. The log tab outputs progress and numerical solutions for any games games solved within the interface.
For more details about the object model underlying BCEViewer, see the The BCEViewer graphical interface.
Examples
We have included several examples of how to use the BCESolve package. The files allpayauction.hpp and allpayauction.cpp are an example of a standard, common-values allpay auction in which bidders pay their bids, irrespective of whether or not they win the good. The header file allpayauction.hpp shows how to construct a simple BCEGame by specifying the objectives and prior over the states (uniform, in this example). The example commonvalueauction.hpp specifies a prior over values distributed according to the CDF 
, where 
denotes the value in [0,1].
The header fpaknown.hpp formulates a private-values first-price auction. The header file shows to how implement private values within the library's framework. The file fpaknown.cpp solves the model using the mapBoundary method, which traces out the equilibria that maximize the weighted sum of a given pair of objectives for all possible weights. This payoffs themselves are saved in a data file, "fpaknown.dat," so that it can also be analyzed elsewhere. The model in fpaunknown.cpp is of a first-price auction in which bidders do not know their own values.
Final thoughts
The package has many more features that the user will no doubt discover. Within the src folder is a src/MATLAB subfolder, that contains tools for interfacing between MATLAB and BCESolve. In particular, bcemex.cpp is a mex program that can be used to create games and load solution files from within MATLAB. There is also a matlab m-file bcemexbuild.m that was most recently used to build bcemex on Linux and with MATLAB R2014a. (Note that building bcemex is a bit tricky since the mex file needs to be linked to position independent code, and the default Boost libraries obtained through most package managers were compiled without the -fPIC compiler flag. You may need to build the Boost serialization library from the source code.)
This program would not have been possible without the support of numerous groups and the contributions of others, and it is entirely fitting and appropriate that their contributions should be acknowledged. In particular, this program was developed with and incorporates elements of a number of other open source projects, including the Qt application framework (www.qt.io), Emmanuel Eichhammer's QCustomPlot (www.qcustomplot.com), the Boost libraries (www.boost.org), and the GNU project (www.gnu.org). We would also like to gratefully acknowledge support from the Becker Friedman Institute and the University of Chicago. Also, special thanks to Robbie Minton, who made significant contributions to this project in 2016.
Finally, it should go without saying that this program is a work in progress. Feedback, bug reports, and contributions are much appreciated.
Enjoy!
Ben Brooks Chicago, IL ben@b.nosp@m.enja.nosp@m.minbr.nosp@m.ooks.nosp@m..net
