An detailed description of the BCEViewer graphical interface.

Introduction

The BCEViewer module is a graphical interface for specifying, solving, and exploring the solutions of games with incomplete information. The interface is written using Qt 5.5 and the QCustomPlot library (www.qcustomplot.com). This section of the describes the object model underlying the program. For a brief description of how to use the graphical interface, please see Overview of the graphical interface.

The graphical interface is initialized by the BCEWindow class. This class constructs the rest of the interface and handles some high level functions such as loading and saving games and solutions, solving games, and keyboard commands.

The layout has three tabs: these are the "solution tab", the "game tab", and the "log tab". The solution tab is for exploring the solution of games, and the game tab is for specifying and viewing games. The log tab's function is primarily for displaying the progress of the algorithm during computation. Each of the game and solution tabs has a separate class associated with handling the functionality of that tab.

The game tab

The game tab is managed by an object of the BCEGameHandler class. The game handler contains a copy of a game, and handles the interface between various tables and controls for editing payoffs, the prior, the conditional distribution of types, and weights on objectives for optimization. The game tab displays the payoffs and conditional distribution of types for one state at a time. Different states are selected using controls at the top of the tab.

The editing of payoffs and probabilities is implemented using Qt's model-view framework. The tables are BCETableView objects, derived from QTableView. Each table has a model associated with it which is derived from BCETableModel, which is in turn derived from QAbstractTableModel. BCETableModel adds private members: a pointer to an associated BCEGame object and an int "state" member, which is the state that is currently being edited. For payoff tables, the model is BCEPayoffTableModel, which adds methods for generating header data to indicate action profiles and also defines setData/getData methods for interfacing with the BCEGame object. The table displaying the conditional distribution of types, a BCEConditionalTableModel, replicates the functionality of the payoff table model. It handles modifying data related to the distribution of types in the BCEGame object. Correspondingly, the table displaying the prior over the states, a BCEPriorTableModel, handles modifying the prior data in the BCEGame object. The final table, BCEObjWeightsTableModel, manages its data internally, since the BCEGame object contains no data pertaining to which objectives will be maximized or minimized when the solve routine is run. Instead, when the solve routine is run, BCEGameHandler retrieves the objective weights from the BCEObjWeightsTableModel object.

Since some table models are state dependent, when the current state is changed by the user, BCEGameHandler simply updates the state parameters of all of the table models and sends out signals to update the displayed data. Data displayed in the payoff table model and the conditional table model will reflect the new state. The prior table model and objective weights table model exist independently of the state and will not change.

The game tab also has controls for changing the numbers of actions, states, and types. When these options are selected, BCEGameHandler simply invokves the corresponding method in the BCEGame class and signals that the models need to update their layouts.

Finally, the game tab has a "Solve" push button which triggers the solve routine, and a "Cancel" push button for interrupting the computation. More on this in the next subsection.

Solving a game

When the user presses the "Solve" button on the game tab, the signal is handled by the BCEWindow class which begins a computation using the algorithm. This computation is handled via an intermediary class called BCESolverWorker. To start the algorithm, the main window constructs a BCESolverWorker and moves it to a new thread so as not to freeze the program while the computation progresses. The worker constructs a BCESolver object for the given game. The main window and the worker communicate back and forth to manage the progress of the algorithm and output via a BCEGurobiCallback object. The callback object checks periodically to determine if the user has triggered the cancel flag, either by hitting the cancel button in the game tab or by clicking "Cancel Solve" in the tools menu of the menu bar at the top of the graphical interface. At each of these periodic checks, the callback object uses std::cout to emit information about the progress of the alorithm solving the linear program. The main window and the worker communicate back and forth in this manner until the computation terminates, at which point the BCESolution object generated by the computation is copied to BCEPlotHandler and the worker is destroyed.

Interacting with the solution

When a solution is loaded through BCEWindow or when one is produced by solving a game, it is passed to BCEPlotHandler, which is the class that controls the solution tab. This tab contains various plots for visualizing the computations performed by the algorithm and the final solution of the game. BCEPlotHandler also passes the solution to BCEDataState, which contains methods for manipulating the BCESolution into vectors and matrices easily amenable to plotting.

The solution tab presents a series of BCEValueSetPlot objects, which are derived from QCustomPlot. These serve to add tooltip functionality such as displaying coordinates when hovering the mouse over the plot. A right-click on the plots opens a menu with options to save a single plot as a .png or .pdf. A click on points in the plot in the top left of the GUI will select new equilibria, if more than one equilibrium is contained within the solution object.

The primary function of the BCEPlotHandler is to handle the plotting of the data from its BCEDataState member. Which part of the solution is plotted depends on a number of parameters that are controlled by the user through various widgets. These widgets control the plots indirectly through the BCEDataState object. This object aggregates all of the settings in the widgets into one set of parameters and manipulates relevant data for plotting. In particular, when one of the controls is changed, the corresponding signal is connected to a slot in BCEDataState that updates the parameter value, manipulates relevant data for plotting, and then signals to BCEPlotHandler to replot.