diff --git a/doc/figures/beerquiche.png b/doc/figures/beerquiche.png deleted file mode 100644 index ad22ca61b0..0000000000 Binary files a/doc/figures/beerquiche.png and /dev/null differ diff --git a/doc/gui.dominance.rst b/doc/gui.dominance.rst index 9b6b818786..d4846c89ca 100644 --- a/doc/gui.dominance.rst +++ b/doc/gui.dominance.rst @@ -6,19 +6,18 @@ Investigating dominated strategies Selecting :menuselection:`Tools --> Dominance` toggles the appearance of a toolbar which can be used to investigate the structure of dominated strategies. -Strategies can be eliminated iteratively -based on whether they are strictly or weakly dominated. - -.. image:: screens/pddom1.* - :width: 33% - :alt: the prisoner's dilemma example, with dominated - strategies indicated - :align: right - :target: _images/pddom1.png +A :guilabel:`Hide strategies which are` dropdown at the left of this +toolbar selects whether strategies are considered dominated when they +are :guilabel:`strictly` dominated, or when they are +:guilabel:`strictly or weakly` dominated; this defaults to +:guilabel:`strictly`. Strategies can then be eliminated iteratively +based on whichever of these two notions is selected. When the dominance toolbar is shown, the strategic game table contains -indicators of strategies that are dominated. -In the prisoner's dilemma, the Cooperate strategy is strictly +indicators of strategies that are dominated according to the selected +notion. +In the prisoner's dilemma, with the dropdown set to +:guilabel:`strictly`, the Cooperate strategy is strictly dominated for both players. This strict dominance is indicated by the solid "X" drawn across the corresponding strategy labels for both players. In addition, the payoffs corresponding to the dominated @@ -27,22 +26,20 @@ contingency in the table containing at least one "X" is a contingency that can only be reached by at least one player playing a strategy that is dominated. - -Strategies that are weakly dominated are similarly indicated, except -the "X" shape is drawn using a thinner, dashed line instead of the -thick, solid line. - -.. image:: screens/pddom2.* - :width: 33% - :alt: the prisoner's dilemma example, with dominated - strategies removed - :align: right - :target: _images/pddom2.png - -Clicking the next level icon removes the strictly dominated strategies -from the display. - -The elimination of multiple levels can be automated using the fast -forward icon, which iteratively eliminates dominated actions until no -further actions can be eliminated. The rewind icon restores the -display to the full game. +Setting the dropdown to :guilabel:`strictly or weakly` additionally +indicates weakly dominated strategies, using the same "X" shape drawn +with a thinner, dashed line instead of the thick, solid line used for +strict dominance. + +To the right of the dropdown, a status readout (for example, +:guilabel:`All strategies shown` or :guilabel:`Eliminated 1 level`) +shows how many rounds of elimination are currently applied, and four +buttons step through rounds of elimination one at a time or all at +once. Clicking :guilabel:`Next round of elimination` removes the +currently-indicated dominated strategies from the display, advancing +one round; :guilabel:`Previous round of elimination` undoes the most +recent round, restoring the strategies it removed. The elimination of +multiple rounds can be automated using :guilabel:`Eliminate +iteratively`, which repeats elimination until no further strategies of +the selected notion can be eliminated. :guilabel:`Show all strategies` +restores the display to the full game. diff --git a/doc/gui.efg.rst b/doc/gui.efg.building.rst similarity index 60% rename from doc/gui.efg.rst rename to doc/gui.efg.building.rst index 4a97a3e8d7..8d2c1d0982 100644 --- a/doc/gui.efg.rst +++ b/doc/gui.efg.building.rst @@ -1,5 +1,5 @@ -Extensive games -=============== +Building an extensive-form game +================================ The graphical interface provides a flexible set of operations for constructing and editing general extensive games. These are outlined @@ -12,7 +12,7 @@ Creating a new extensive game To create a new extensive game, select :menuselection:`File --> New --> Extensive game`, or -click on the new extensive game icon . The extensive game created is a +click on the new extensive game icon. The extensive game created is a trivial game with two players, named by default :guilabel:`Player 1` and :guilabel:`Player 2`, with one node, which is both the root and terminal node of the game. @@ -45,12 +45,6 @@ submenu, and the more flexible :guilabel:`Insert move` dialog. changed between the chance player and a personal player this way -- nor can it be, at present, using any other method in the interface. -.. image:: screens/insertmove.* - :width: 33% - :alt: insert move dialog - :align: right - :target: _images/insertmove.png - 2. Right-click any terminal node in the tree, and choose :guilabel:`Insert move` to display the :guilabel:`insert move` dialog. @@ -209,16 +203,15 @@ node onto another and choosing :guilabel:`Put node in same information set` (or, when dropping on a terminal node, :guilabel:`Insert move using same information set`) from the popup menu. -.. image:: screens/editnode.* - :width: 33% - :alt: node properties dialog - :align: right - :target: _images/editnode.png - The information set to which a node belongs can also be set by right-clicking the node and choosing :guilabel:`Node properties` (or by double-clicking the node). This displays the -:guilabel:`node properties` dialog. +:guilabel:`node properties` dialog, which besides the information set +has a text field for the node's label and, at the bottom, a dropdown +for the node's outcome, offering the same choices and editing behavior +described in :ref:`Outcomes and payoffs ` below. +If the node is the root of the tree, or the root of a proper subgame, +the dialog states this beneath the information set dropdown. The :guilabel:`Information set` dropdown defaults to the current information set to which the node belongs, and contains a list of all other information sets in the game which are compatible @@ -252,6 +245,8 @@ are adjusted based on the action selected at this node. based on this information during subsequent editing of the game. +.. _outcomes-and-payoffs: + Outcomes and payoffs -------------------- @@ -278,207 +273,3 @@ so that editing the payoffs at either node updates both. To remove an outcome from a node, right-click the node, and choose :guilabel:`Remove outcome`. - - - -Formatting and labeling the tree --------------------------------- - -Gambit offers some options for customizing the display of game trees. - - -Labels on nodes and branches -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The information displayed at the nodes and on the branches of the tree -can be configured by selecting :menuselection:`Format --> Labels`, -which displays the :guilabel:`tree labels` dialog. - -.. image:: screens/labels.* - :width: 33% - :alt: tree labels dialog - :align: right - :target: _images/labels.png - -Above and below each node, the following information can be displayed: - - -:guilabel:`No label` - The space is left blank. - -:guilabel:`The node's label` - The text label assigned to the node. (This is the - default labeling above each node.) - -:guilabel:`The player's name` - The name of the player making the move at the node. - -:guilabel:`The information set's label` - The name of the information set to - which the node belongs. - -:guilabel:`The information set's number` - A unique identifier of the information - set, in the form player number:information set number. (This is the - default labeling below each node.) - -:guilabel:`The realization probability` - The probability the node is reached. - (Only displayed when a behavior strategy is selected to be displayed - on the tree.) - -:guilabel:`The belief probability` - The probability a player assigns to being at - the node, conditional on reaching the information set. (Only displayed - when a behavior strategy is selected to be displayed on the tree.) - -:guilabel:`The payoff of reaching the node` - The expected payoff to the player - making the choice at the node, conditional on reaching the node. (Only - displayed when a behavior strategy is selected to be displayed on the - tree.) - - -Above and below each branch, the following information can be -displayed: - - -:guilabel:`No label` - The space is left blank. - -:guilabel:`The name of the action` - The name of the action taken on the branch. - (This it the default labeling above the branch.) - -:guilabel:`The probability the action is played` - For chance actions, the - probability the branch is taken; this is always displayed. For player - actions, the probability the action is taken in the selected profile - (only displayed when a behavior strategy is selected to be displayed - on the tree). In some cases, behavior strategies do not fully specify - behavior sufficiently far off the equilibrium path; in such cases, an - asterisk is shown for such action probabilities. (This is the default - labeling below each branch.) - -:guilabel:`The value of the action` - The expected payoff to the player of taking - the action, conditional on reaching the information set. (Only - displayed when a behavior strategy is selected to be displayed on the - tree.) - - - -.. _gui-tree-layout: - -Controlling the layout of the tree -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Gambit implements an automatic system for layout out game trees, which -provides generally good results for most games. These can be adjusted -by selecting :menuselection:`Format --> Layout`. -The layout parameters are organized on three tabs. - -.. image:: screens/layoutnodes.* - :width: 33% - :alt: layout options dialog, nodes tab - :align: right - :target: _images/layoutnodes.png - -The first tab, -labeled :guilabel:`Nodes`, controls the size, location, and -rendering of nodes in the tree. -Nodes can be indicated using one -of five tokens: a horizontal line (the "traditional" Gambit style from -previous versions), a box, a diamond, an unfilled circle, and a filled -circle). These can be set independently to distinguish chance and -terminal nodes from player nodes. - -The sizing of nodes can be configured for best results. Gambit styling -from previous versions used the horizontal line tokens with relatively -long lines; when using the other tokens, smaller node sizes often look -better. - -.. image:: screens/layoutbranches.* - :width: 33% - :alt: layout options dialog, branches tab - :align: right - :target: _images/layoutbranches.png - -The layout algorithm is based upon identifying the location of -terminal nodes. The vertical spacing between these nodes can be set; -making this value larger will tend to give the tree a larger vertical -extent. - -The second tab, -labeled :guilabel:`Branches`, controls the display of the branches -of the tree. -The traditional Gambit way of drawing branches is a "fork-tine" -approach, in which there is a flat part at the end of each branch at -which labels are displayed. Alternatively, branches can be drawn -directly between nodes by setting :guilabel:`Draw branches` -to using straight -lines between nodes. With this setting, labels are now displayed at -points along the (usually) diagonal branches. Labels are usually shown -horizontally; however, they can be drawn rotated parallel to the -branches by setting :guilabel:`Draw labels` to rotated. - -The rotated label drawing is experimental, and does not always look -good on screen. - -.. image:: screens/layoutinfosets.* - :width: 33% - :alt: layout options dialog, information sets tab - :align: right - :target: _images/layoutinfosets.png - -The length used for branches and their tines, if drawn, can be -configured. Longer branch and tine lengths give more space for longer -labels to be drawn, at the cost of giving the tree a larger horizontal -extent. - -Finally, display of the information sets in the game is configured -under the tab labeled :guilabel:`Information sets`. -Members of information sets are -by default connected using a "bubble" similar to that drawn in -textbook diagrams of games. The can be modified to use a single line -to connect nodes in the same information set. In conjunction with -using lines for nodes, this can sometimes lead to a more compact -representation of a tree where there are many information sets at the -same horizontal location. - -The layout of the tree may be such that members of the same -information set appear at different horizontal locations in the tree. -In such a case, by default, Gambit draws a horizontal arrow pointing -rightward or leftward to indicate the continuation of the information -set, as illustrated in the diagram nearby. - -.. image:: screens/connectinfoset.* - :width: 33% - :alt: information sets spanning multiple levels - :align: right - :target: _images/connectinfoset.png - -These connections can be disabled by setting -:guilabel:`Connect members of information -sets` to :guilabel:`only when on the same level`. -In addition, drawing information -set indicators can be disabled entirely by setting this to invisibly -(don't draw indicators). - - -Selecting fonts and colors -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -To select the font used to draw the labels in the tree, select -:menuselection:`Format --> Font`. -The standard font selection dialog for the operating -system is displayed, showing the fonts available on the system. Since -available fonts vary across systems, when opening a workspace on a -system different from the system on which it was saved, Gambit tries -to match the font style as closely as possible when the original font -is not available. - -The color-coding for each player (and for chance) can be changed on the -:guilabel:`Players` page of the :guilabel:`Game properties` dialog -(:menuselection:`Edit --> Game`), by clicking the color swatch next to the -player's name. diff --git a/doc/gui.efg.viewing.rst b/doc/gui.efg.viewing.rst new file mode 100644 index 0000000000..0c2477838b --- /dev/null +++ b/doc/gui.efg.viewing.rst @@ -0,0 +1,171 @@ +Formatting and labeling the tree +================================= + +Gambit offers some options for customizing the display of game trees. + + +Labels on nodes and branches +----------------------------- + +The information displayed at the nodes and on the branches of the tree +can be configured by selecting :menuselection:`Format --> Labels`, +which displays the :guilabel:`tree labels` dialog. + +Above and below each node, the following information can be displayed: + + +:guilabel:`No label` + The space is left blank. + +:guilabel:`The node's label` + The text label assigned to the node. (This is the + default labeling above each node.) + +:guilabel:`The player's name` + The name of the player making the move at the node. + +:guilabel:`The information set's label` + The name of the information set to + which the node belongs. + +:guilabel:`The information set's number` + A unique identifier of the information + set, in the form player number:information set number. (This is the + default labeling below each node.) + +:guilabel:`The realization probability` + The probability the node is reached. + (Only displayed when a behavior strategy is selected to be displayed + on the tree.) + +:guilabel:`The belief probability` + The probability a player assigns to being at + the node, conditional on reaching the information set. (Only displayed + when a behavior strategy is selected to be displayed on the tree.) + +:guilabel:`The payoff of reaching the node` + The expected payoff to the player + making the choice at the node, conditional on reaching the node. (Only + displayed when a behavior strategy is selected to be displayed on the + tree.) + + +Above and below each branch, the following information can be +displayed: + + +:guilabel:`No label` + The space is left blank. + +:guilabel:`The name of the action` + The name of the action taken on the branch. + (This it the default labeling above the branch.) + +:guilabel:`The probability the action is played` + For chance actions, the + probability the branch is taken; this is always displayed. For player + actions, the probability the action is taken in the selected profile + (only displayed when a behavior strategy is selected to be displayed + on the tree). In some cases, behavior strategies do not fully specify + behavior sufficiently far off the equilibrium path; in such cases, an + asterisk is shown for such action probabilities. (This is the default + labeling below each branch.) + +:guilabel:`The value of the action` + The expected payoff to the player of taking + the action, conditional on reaching the information set. (Only + displayed when a behavior strategy is selected to be displayed on the + tree.) + + + +.. _gui-tree-layout: + +Controlling the layout of the tree +----------------------------------- + +Gambit implements an automatic system for layout out game trees, which +provides generally good results for most games. These can be adjusted +by selecting :menuselection:`Format --> Layout`. +The layout parameters are organized on three tabs. + +The first tab, +labeled :guilabel:`Nodes`, controls the size, location, and +rendering of nodes in the tree. +Nodes can be indicated using one +of five tokens: a horizontal line (the "traditional" Gambit style from +previous versions), a box, a diamond, an unfilled circle, and a filled +circle). These can be set independently to distinguish chance and +terminal nodes from player nodes. + +The sizing of nodes can be configured for best results. Gambit styling +from previous versions used the horizontal line tokens with relatively +long lines; when using the other tokens, smaller node sizes often look +better. + +The layout algorithm is based upon identifying the location of +terminal nodes. The vertical spacing between these nodes can be set; +making this value larger will tend to give the tree a larger vertical +extent. + +The second tab, +labeled :guilabel:`Branches`, controls the display of the branches +of the tree. +The traditional Gambit way of drawing branches is a "fork-tine" +approach, in which there is a flat part at the end of each branch at +which labels are displayed. Alternatively, branches can be drawn +directly between nodes by setting :guilabel:`Draw branches` +to using straight +lines between nodes. With this setting, labels are now displayed at +points along the (usually) diagonal branches. Labels are usually shown +horizontally; however, they can be drawn rotated parallel to the +branches by setting :guilabel:`Draw labels` to rotated. + +The rotated label drawing is experimental, and does not always look +good on screen. + +The length used for branches and their tines, if drawn, can be +configured. Longer branch and tine lengths give more space for longer +labels to be drawn, at the cost of giving the tree a larger horizontal +extent. + +Finally, display of the information sets in the game is configured +under the tab labeled :guilabel:`Information sets`. +Members of information sets are +by default connected using a "bubble" similar to that drawn in +textbook diagrams of games. The can be modified to use a single line +to connect nodes in the same information set. In conjunction with +using lines for nodes, this can sometimes lead to a more compact +representation of a tree where there are many information sets at the +same horizontal location. + +The layout of the tree may be such that members of the same +information set appear at different horizontal locations in the tree. +In such a case, by default, Gambit draws a horizontal arrow pointing +rightward or leftward to indicate the continuation of the information +set. + +These connections can be disabled by setting +:guilabel:`Connect members of information +sets` to :guilabel:`only when on the same level`. +In addition, drawing information +set indicators can be disabled entirely by setting this to invisibly +(don't draw indicators). + + +Selecting fonts and colors +---------------------------- + +To select the font used to draw the labels in the tree, select +:menuselection:`Format --> Font`. +The standard font selection dialog for the operating +system is displayed, showing the fonts available on the system. Since +available fonts vary across systems, when opening a workspace on a +system different from the system on which it was saved, Gambit tries +to match the font style as closely as possible when the original font +is not available. + +The color-coding for each player (and for chance) can be changed on the +:guilabel:`Players` page of the :guilabel:`Game properties` dialog +(:menuselection:`Edit --> Game`), by clicking the color swatch next to the +player's name. diff --git a/doc/gui.nash.rst b/doc/gui.nash.rst index 2fee7672af..ce6906c421 100644 --- a/doc/gui.nash.rst +++ b/doc/gui.nash.rst @@ -27,12 +27,6 @@ done on the extensive or strategic games, and on details of the game, such as whether the game has two players or more, and whether the game is constant-sum. -.. image:: screens/nash.* - :width: 33% - :alt: dialog for computing Nash equilibria - :align: right - :target: _images/nash.png - The first step in finding equilibria is to specify how many equilibria are to be found. Some algorithms for computing equilibria are adapted to finding a single equilibrium, while others attempt to compute the @@ -95,12 +89,6 @@ Method Parameters used by the graphical interface local Newton refinement every 3 steps, with at most 10 iterations. ================ ============================================================================ -.. image:: screens/computing.* - :width: 33% - :alt: dialog for monitoring computation of equilibria - :align: right - :target: _images/computing.png - For extensive games, there is an option of whether to use the extensive or strategic game for computation when the selected method supports both. In general, computation @@ -113,7 +101,7 @@ time-intensive process. Gambit runs all computations in the background, and displays a dialog showing all equilibria computed so far. The computation can be cancelled at any time by clicking on the -cancel icon , which terminates the computation but keeps any +cancel icon, which terminates the computation but keeps any equilibria computed. @@ -127,12 +115,6 @@ toggled by selecting :menuselection:`View --> Profiles`, or clicking on the playing card icon on the toolbar. -.. image:: screens/profiles.* - :width: 33% - :alt: poker game with the unique equilibrium displayed - :align: right - :target: _images/profiles.png - This game has a unique equilibrium in which Fred raises after Red with probability one, and raises with probability one-third after Black. Alice, at her only information set, plays meet with probability two- @@ -143,32 +125,45 @@ more than one equilibrium is found, this panel lists all equilibria found. Equilibria computed are grouped by separate computational runs; computing equilibria using a different method (or different settings) will add a second list of profiles. The list of profiles displayed is -selected using the drop-down at the top left of the profiles panel; in -the screenshot, it is set to +selected using the drop-down at the top left of the profiles panel; +since only one computation has been run in this example, it shows :guilabel:`Profiles 1`. A brief description of the method used to compute the equilibria is listed across the top of the profiles panel. +Some methods for computing equilibria construct good numerical +approximations to equilibrium points rather than exact values; for +these methods, the computed equilibria are stored in floating-point +format. When such a profile is displayed in the profiles panel, a +:guilabel:`Decimals` control appears next to the profile list chooser, +letting you increase or decrease the number of decimal places shown. +This control only appears for profiles computed in floating-point +precision; it is hidden when the displayed profiles are exact +(rational-number) equilibria, since changing the number of decimals +would have no effect on them. Increasing or decreasing the number of +decimals displayed in computed strategy profiles will not have any +effect on the display of outcome payoffs in the game itself, since +those are always stored in arbitrary precision (see +:ref:`payoffs-and-probabilities`). + The currently selected equilibrium is shown in bold in the profiles listing, and information about this equilibrium is displayed in the -extensive game. In the figure, the probabilities of selecting each +extensive game. For this equilibrium, the probabilities of selecting each action are displayed below each branch of the tree. (This is the default Gambit setting; see :ref:`gui-tree-layout` for configuring the labeling of trees.) Each branch of the tree also shows a black line, the length of which is proportional to the probability with which the action is played. -.. image:: screens/beliefs.* - :width: 33% - :alt: poker game with the beliefs at Alice's top node - :align: right - :target: _images/beliefs.png - -Hovering the mouse pointer over any node in the tree briefly displays -additional information about the profile at that node, in a small window -next to the node, including each player's expected payoff from that point -in the game onward, as well as information about Alice's beliefs at the -node. +Hovering the mouse pointer over any node in the tree briefly displays a +popup listing, for each player, that player's expected payoff from that +point in the game onward under the currently-selected profile, color-coded +to match the player. For a node that is not a terminal node, the popup +also names the player who moves there and shows the probability of +reaching the node, the probability of reaching its information set, that +player's belief about being at this particular node conditional on having +reached the information set, and the information set's value to the +player who moves there. The computed profiles can also be viewed in the reduced strategic game. Clicking on the strategic game icon changes the view to the @@ -189,13 +184,6 @@ equilibrium correspondence for extensive games :cite:p:`McKPal98` and strategic games :cite:p:`McKPal95`, using the tracing method of :cite:p:`Tur05`. -.. image:: screens/qre.* - :width: 33% - :alt: quantal response equilibria - :align: right - :target: _images/qre.png - - To compute the correspondence, select :menuselection:`Tools --> Qre`. If viewing an extensive game, the agent quantal response equilibrium correspondence diff --git a/doc/gui.nfg.rst b/doc/gui.nfg.building.rst similarity index 56% rename from doc/gui.nfg.rst rename to doc/gui.nfg.building.rst index ac2c2a0bc6..9739e9a459 100644 --- a/doc/gui.nfg.rst +++ b/doc/gui.nfg.building.rst @@ -1,5 +1,5 @@ -Strategic games -=============== +Building a strategic-form game +================================ Gambit has full support for constructing and manipulating arbitrary N-player strategic (also known as normal form) games. @@ -29,121 +29,12 @@ game, select :menuselection:`File --> New --> Strategic game`, or click the new strategic game icon on the toolbar. -Displaying a strategic game -=========================== - -Gambit displays a strategic game as a table. Each cell represents one -strategy profile: one strategy choice for every player. The cell shows -the payoffs that result when the players choose the strategies named by -that cell's row and column labels. - -For a two-player game, Gambit initially uses the familiar matrix -arrangement. One player's strategies label the rows, and the other -player's strategies label the columns. - -.. image:: screens/pd1.* - :width: 50% - :alt: A two-player strategic game with Alice's strategies on the rows and Bob's strategies on the columns. - :align: center - :target: _images/pd1.png - -Each row-and-column combination identifies one strategy profile. For -example, a cell in the row labelled ``Cooperate`` and the column -labelled ``Defect`` represents the outcome in which the row player -chooses ``Cooperate`` and the column player chooses ``Defect``. - -The payoffs in each cell are colour-coded by player. In the standard -two-player arrangement, Gambit displays the row player's payoff first -and the column player's payoff second. - -Whenever a profile has been computed and selected, hovering the mouse -pointer over any strategy's row or column label also shows that -strategy's probability under the current profile, the payoff its player -would get by playing that strategy alone against the others' current -play, and that player's overall payoff under the current profile. -Comparing this payoff-if-played figure across a player's strategies is -how to check whether the current profile is actually a best response for -that player. - - -Row and column hierarchies --------------------------- - -Games with more than two players require more than one strategy label -to identify each row or column. Gambit handles this by allowing several -players to be assigned to the rows, several players to be assigned to -the columns, or both. - -When several players are assigned to the same side of the table, their -strategy labels form a hierarchy. Each level groups together the -strategy combinations belonging to the players below it. This is -similar to the hierarchical row and column labels used in a pivot table -or a table with a multi-level index. - -For example, suppose Alice and Bob are both assigned to the rows. If -Alice is above Bob in the row hierarchy, Gambit first groups the rows -by Alice's strategy and then lists Bob's strategies within each group. - -.. image:: screens/pd2.* - :width: 50% - :alt: A strategic game with Alice and Bob arranged as two levels of hierarchical row labels. - :align: center - :target: _images/pd2.png - -Reversing their order groups the rows first by Bob's strategy and then -by Alice's. The strategy profiles and payoffs do not change; only their -arrangement in the table changes. - -The same principle applies to the columns. A player placed at a higher -level of the column hierarchy forms the outer grouping, while players -at lower levels form groups within it. - -This arrangement provides a single table view of games that are often -printed as a collection of separate payoff matrices. For example, a -three-player game can be displayed with one player on the rows and two -players in a column hierarchy, rather than as a separate matrix for -each strategy of the third player. - - -Rearranging the table ---------------------- - -To change the table arrangement, right-click any row or column label and -choose a player from the menu that appears. If that side of the table -already has one or more players assigned to it, the menu offers -:guilabel:`Place player before` and :guilabel:`Place player after` -submenus, each listing every player; if not, it offers a single -:guilabel:`Use as row player` (or :guilabel:`Use as column player`) -submenu instead. Gambit updates the display without changing the game -itself. - -The available positions depend on the current arrangement. Choosing a -player from :guilabel:`Place player before` makes that player a higher -level in the hierarchy than the row or column that was right-clicked; -choosing one from :guilabel:`Place player after` makes it a lower level. - -.. image:: screens/pd3.* - :width: 50% - :alt: The same strategic game displayed with a different ordering of its hierarchical strategy labels. - :align: center - :target: _images/pd3.png - -Changing the row and column hierarchies may also change the order in -which payoffs appear within each cell. The colour of each payoff -continues to identify the player to whom it belongs. - -.. note:: - - Rearranging the table changes only the presentation of the game. It - does not change the players, strategies, outcomes, or payoffs. - - Adding players -------------- Players are added, removed, and reordered on the :guilabel:`Players` page of the :guilabel:`Game properties` dialog (:menuselection:`Edit --> Game`); see -:doc:`gui.general`. A newly added player has one strategy, by default +:doc:`gui.orientation`. A newly added player has one strategy, by default labeled with the number :guilabel:`1`. diff --git a/doc/gui.nfg.viewing.rst b/doc/gui.nfg.viewing.rst new file mode 100644 index 0000000000..9e20d72cb3 --- /dev/null +++ b/doc/gui.nfg.viewing.rst @@ -0,0 +1,89 @@ +Displaying a strategic game +============================ + +Gambit displays a strategic game as a table. Each cell represents one +strategy profile: one strategy choice for every player. The cell shows +the payoffs that result when the players choose the strategies named by +that cell's row and column labels. + +For a two-player game, Gambit initially uses the familiar matrix +arrangement. One player's strategies label the rows, and the other +player's strategies label the columns. + +Each row-and-column combination identifies one strategy profile. For +example, a cell in the row labelled ``Cooperate`` and the column +labelled ``Defect`` represents the outcome in which the row player +chooses ``Cooperate`` and the column player chooses ``Defect``. + +The payoffs in each cell are colour-coded by player. In the standard +two-player arrangement, Gambit displays the row player's payoff first +and the column player's payoff second. + +Whenever a profile has been computed and selected, hovering the mouse +pointer over any strategy's row or column label also shows that +strategy's probability under the current profile, the payoff its player +would get by playing that strategy alone against the others' current +play, and that player's overall payoff under the current profile. +Comparing this payoff-if-played figure across a player's strategies is +how to check whether the current profile is actually a best response for +that player. + + +Row and column hierarchies +---------------------------- + +Games with more than two players require more than one strategy label +to identify each row or column. Gambit handles this by allowing several +players to be assigned to the rows, several players to be assigned to +the columns, or both. + +When several players are assigned to the same side of the table, their +strategy labels form a hierarchy. Each level groups together the +strategy combinations belonging to the players below it. This is +similar to the hierarchical row and column labels used in a pivot table +or a table with a multi-level index. + +For example, suppose Alice and Bob are both assigned to the rows. If +Alice is above Bob in the row hierarchy, Gambit first groups the rows +by Alice's strategy and then lists Bob's strategies within each group. + +Reversing their order groups the rows first by Bob's strategy and then +by Alice's. The strategy profiles and payoffs do not change; only their +arrangement in the table changes. + +The same principle applies to the columns. A player placed at a higher +level of the column hierarchy forms the outer grouping, while players +at lower levels form groups within it. + +This arrangement provides a single table view of games that are often +printed as a collection of separate payoff matrices. For example, a +three-player game can be displayed with one player on the rows and two +players in a column hierarchy, rather than as a separate matrix for +each strategy of the third player. + + +Rearranging the table +------------------------ + +To change the table arrangement, right-click any row or column label and +choose a player from the menu that appears. If that side of the table +already has one or more players assigned to it, the menu offers +:guilabel:`Place player before` and :guilabel:`Place player after` +submenus, each listing every player; if not, it offers a single +:guilabel:`Use as row player` (or :guilabel:`Use as column player`) +submenu instead. Gambit updates the display without changing the game +itself. + +The available positions depend on the current arrangement. Choosing a +player from :guilabel:`Place player before` makes that player a higher +level in the hierarchy than the row or column that was right-clicked; +choosing one from :guilabel:`Place player after` makes it a lower level. + +Changing the row and column hierarchies may also change the order in +which payoffs appear within each cell. The colour of each payoff +continues to identify the player to whom it belongs. + +.. note:: + + Rearranging the table changes only the presentation of the game. It + does not change the players, strategies, outcomes, or payoffs. diff --git a/doc/gui.general.rst b/doc/gui.orientation.rst similarity index 68% rename from doc/gui.general.rst rename to doc/gui.orientation.rst index 6a04c9b4c9..7a027998d6 100644 --- a/doc/gui.general.rst +++ b/doc/gui.orientation.rst @@ -4,12 +4,6 @@ General concepts General layout of the main window --------------------------------- -.. image:: screens/overview.* - :width: 33% - :alt: the default extensive game at launch - :align: right - :target: _images/overview.png - The frame presenting a game consists of a single main panel, which displays the game graphically; in this case, showing the game tree of a simple one-card poker game. Note that where applicable, information is color-coded @@ -26,14 +20,6 @@ A player can't be removed if it has decisions in the game, or more than one strategy in the game's strategic representation; its :guilabel:`✕` button is disabled, with a tooltip explaining why. -Hovering the mouse pointer over a node in the tree briefly displays a small -window showing, for each player, that player's expected payoff from that -point in the game onward, under the currently-selected profile. For a node -that is not a terminal node, this window also shows the probability of -reaching that node and its information set, the information set's value to -the player who moves there, and that player's belief about being at this -particular node within the information set. - Two additional panels are available. Selecting :menuselection:`Tools --> Dominance` toggles the display of an additional toolbar across the top of the window. @@ -50,6 +36,8 @@ in :ref:`computing-equilibria`. +.. _payoffs-and-probabilities: + Payoffs and probabilities in Gambit ----------------------------------- @@ -59,24 +47,10 @@ decimal places. In addition, Gambit supports representing payoffs using rational numbers. So, for example, in any place in which a payoff may appear, either an outcome of an extensive game or a payoff entry in a strategic game, the payoff one-tenth may be entered either -as .1 or 1/10. - -The advantage of this format is that, in certain circumstances, Gambit -may be able to compute equilibria exactly. In addition, some methods -for computing equilibria construct good numerical approximations to -equilibrium points. For these methods, the computed equilibria are -stored in floating-point format. When such a profile is displayed in -the profiles panel, a :guilabel:`Decimals` control appears next to the -profile list chooser, letting you increase or decrease the number of -decimal places shown. This control only appears for profiles computed -in floating-point precision; it is hidden when the displayed profiles -are exact (rational-number) equilibria, since changing the number of -decimals would have no effect on them. - -Increasing or decreasing the number of decimals displayed in -computed strategy profiles will not have any effect on the display of -outcome payoffs in the game itself, since those are stored in -arbitrary precision. +as .1 or 1/10. The advantage of this format is that, in certain +circumstances, Gambit may be able to compute equilibria exactly; see +:ref:`computing-equilibria` for how this interacts with the display of +computed profiles. diff --git a/doc/gui.rst b/doc/gui.rst index 83e6e10094..dbbfb8b02d 100644 --- a/doc/gui.rst +++ b/doc/gui.rst @@ -30,9 +30,11 @@ systematically, it is recommended to use .. toctree:: :maxdepth: 2 - gui.general - gui.efg - gui.nfg + gui.orientation + gui.efg.building + gui.nfg.building + gui.efg.viewing + gui.nfg.viewing gui.dominance gui.nash gui.export diff --git a/doc/icons/adddecimal.gif b/doc/icons/adddecimal.gif deleted file mode 100644 index a55852eaa9..0000000000 Binary files a/doc/icons/adddecimal.gif and /dev/null differ diff --git a/doc/icons/calc.gif b/doc/icons/calc.gif deleted file mode 100644 index 6919154019..0000000000 Binary files a/doc/icons/calc.gif and /dev/null differ diff --git a/doc/icons/color.gif b/doc/icons/color.gif deleted file mode 100644 index d1e2550d6c..0000000000 Binary files a/doc/icons/color.gif and /dev/null differ diff --git a/doc/icons/datasrc.gif b/doc/icons/datasrc.gif deleted file mode 100644 index ccd54b3e25..0000000000 Binary files a/doc/icons/datasrc.gif and /dev/null differ diff --git a/doc/icons/deldecimal.gif b/doc/icons/deldecimal.gif deleted file mode 100644 index e125746b9c..0000000000 Binary files a/doc/icons/deldecimal.gif and /dev/null differ diff --git a/doc/icons/dice.gif b/doc/icons/dice.gif deleted file mode 100644 index 77d06f2ddc..0000000000 Binary files a/doc/icons/dice.gif and /dev/null differ diff --git a/doc/icons/move.gif b/doc/icons/move.gif deleted file mode 100644 index d7626f4139..0000000000 Binary files a/doc/icons/move.gif and /dev/null differ diff --git a/doc/icons/newplayer.gif b/doc/icons/newplayer.gif deleted file mode 100644 index fc455e94ff..0000000000 Binary files a/doc/icons/newplayer.gif and /dev/null differ diff --git a/doc/icons/newrow.gif b/doc/icons/newrow.gif deleted file mode 100644 index 2694efd487..0000000000 Binary files a/doc/icons/newrow.gif and /dev/null differ diff --git a/doc/icons/newtable.gif b/doc/icons/newtable.gif deleted file mode 100644 index 5e7843263b..0000000000 Binary files a/doc/icons/newtable.gif and /dev/null differ diff --git a/doc/icons/newtree.gif b/doc/icons/newtree.gif deleted file mode 100644 index 026aae2225..0000000000 Binary files a/doc/icons/newtree.gif and /dev/null differ diff --git a/doc/icons/next.gif b/doc/icons/next.gif deleted file mode 100644 index 8f89c44f2a..0000000000 Binary files a/doc/icons/next.gif and /dev/null differ diff --git a/doc/icons/person.gif b/doc/icons/person.gif deleted file mode 100644 index 83558bc305..0000000000 Binary files a/doc/icons/person.gif and /dev/null differ diff --git a/doc/icons/prev.gif b/doc/icons/prev.gif deleted file mode 100644 index 563fc8adf2..0000000000 Binary files a/doc/icons/prev.gif and /dev/null differ diff --git a/doc/icons/print.gif b/doc/icons/print.gif deleted file mode 100644 index c54ea3bfa9..0000000000 Binary files a/doc/icons/print.gif and /dev/null differ diff --git a/doc/icons/profiles.gif b/doc/icons/profiles.gif deleted file mode 100644 index 15c1687d30..0000000000 Binary files a/doc/icons/profiles.gif and /dev/null differ diff --git a/doc/icons/savedata.gif b/doc/icons/savedata.gif deleted file mode 100644 index 0772ee8692..0000000000 Binary files a/doc/icons/savedata.gif and /dev/null differ diff --git a/doc/icons/stop.gif b/doc/icons/stop.gif deleted file mode 100644 index 53c09b182e..0000000000 Binary files a/doc/icons/stop.gif and /dev/null differ diff --git a/doc/icons/tobegin.gif b/doc/icons/tobegin.gif deleted file mode 100644 index 61a2d8151a..0000000000 Binary files a/doc/icons/tobegin.gif and /dev/null differ diff --git a/doc/icons/toend.gif b/doc/icons/toend.gif deleted file mode 100644 index 397a1f3dcb..0000000000 Binary files a/doc/icons/toend.gif and /dev/null differ diff --git a/doc/icons/zoomfit.gif b/doc/icons/zoomfit.gif deleted file mode 100644 index 4c92706c8e..0000000000 Binary files a/doc/icons/zoomfit.gif and /dev/null differ diff --git a/doc/images/caution.gif b/doc/images/caution.gif deleted file mode 100755 index 9cc2e15574..0000000000 Binary files a/doc/images/caution.gif and /dev/null differ diff --git a/doc/images/home.gif b/doc/images/home.gif deleted file mode 100755 index 55e1d5993f..0000000000 Binary files a/doc/images/home.gif and /dev/null differ diff --git a/doc/images/important.gif b/doc/images/important.gif deleted file mode 100755 index 25e40c76b5..0000000000 Binary files a/doc/images/important.gif and /dev/null differ diff --git a/doc/images/next.gif b/doc/images/next.gif deleted file mode 100755 index 8c502e740a..0000000000 Binary files a/doc/images/next.gif and /dev/null differ diff --git a/doc/images/note.gif b/doc/images/note.gif deleted file mode 100755 index 7322e8e40b..0000000000 Binary files a/doc/images/note.gif and /dev/null differ diff --git a/doc/images/prev.gif b/doc/images/prev.gif deleted file mode 100755 index 0894d9ecb2..0000000000 Binary files a/doc/images/prev.gif and /dev/null differ diff --git a/doc/images/tip.gif b/doc/images/tip.gif deleted file mode 100755 index f062955fa7..0000000000 Binary files a/doc/images/tip.gif and /dev/null differ diff --git a/doc/images/toc-blank.gif b/doc/images/toc-blank.gif deleted file mode 100755 index 6c65e3a194..0000000000 Binary files a/doc/images/toc-blank.gif and /dev/null differ diff --git a/doc/images/toc-minus.gif b/doc/images/toc-minus.gif deleted file mode 100755 index 40ebe61e46..0000000000 Binary files a/doc/images/toc-minus.gif and /dev/null differ diff --git a/doc/images/toc-plus.gif b/doc/images/toc-plus.gif deleted file mode 100755 index 3e9e7d55a3..0000000000 Binary files a/doc/images/toc-plus.gif and /dev/null differ diff --git a/doc/images/up.gif b/doc/images/up.gif deleted file mode 100755 index e899a272d0..0000000000 Binary files a/doc/images/up.gif and /dev/null differ diff --git a/doc/images/warning.gif b/doc/images/warning.gif deleted file mode 100755 index a5870799fb..0000000000 Binary files a/doc/images/warning.gif and /dev/null differ diff --git a/doc/screens/beliefs.png b/doc/screens/beliefs.png deleted file mode 100644 index bd3ebaf5b4..0000000000 Binary files a/doc/screens/beliefs.png and /dev/null differ diff --git a/doc/screens/computing.png b/doc/screens/computing.png deleted file mode 100644 index 57d2c4fa89..0000000000 Binary files a/doc/screens/computing.png and /dev/null differ diff --git a/doc/screens/connectinfoset.png b/doc/screens/connectinfoset.png deleted file mode 100644 index d5f46c72f0..0000000000 Binary files a/doc/screens/connectinfoset.png and /dev/null differ diff --git a/doc/screens/editnode.png b/doc/screens/editnode.png deleted file mode 100644 index 892be1f6bb..0000000000 Binary files a/doc/screens/editnode.png and /dev/null differ diff --git a/doc/screens/insertmove.png b/doc/screens/insertmove.png deleted file mode 100644 index ae7f44f41e..0000000000 Binary files a/doc/screens/insertmove.png and /dev/null differ diff --git a/doc/screens/labels.png b/doc/screens/labels.png deleted file mode 100644 index 7d09495791..0000000000 Binary files a/doc/screens/labels.png and /dev/null differ diff --git a/doc/screens/layoutbranches.png b/doc/screens/layoutbranches.png deleted file mode 100644 index 9617a8f158..0000000000 Binary files a/doc/screens/layoutbranches.png and /dev/null differ diff --git a/doc/screens/layoutinfosets.png b/doc/screens/layoutinfosets.png deleted file mode 100644 index 5ba8f9a31e..0000000000 Binary files a/doc/screens/layoutinfosets.png and /dev/null differ diff --git a/doc/screens/layoutnodes.png b/doc/screens/layoutnodes.png deleted file mode 100644 index 3a4a35f413..0000000000 Binary files a/doc/screens/layoutnodes.png and /dev/null differ diff --git a/doc/screens/logit.png b/doc/screens/logit.png deleted file mode 100644 index 162dcb81a6..0000000000 Binary files a/doc/screens/logit.png and /dev/null differ diff --git a/doc/screens/nash.png b/doc/screens/nash.png deleted file mode 100644 index e418bade2f..0000000000 Binary files a/doc/screens/nash.png and /dev/null differ diff --git a/doc/screens/overview.png b/doc/screens/overview.png deleted file mode 100644 index 683491eb74..0000000000 Binary files a/doc/screens/overview.png and /dev/null differ diff --git a/doc/screens/pd1.png b/doc/screens/pd1.png deleted file mode 100644 index ff6fdaf898..0000000000 Binary files a/doc/screens/pd1.png and /dev/null differ diff --git a/doc/screens/pd2.png b/doc/screens/pd2.png deleted file mode 100644 index 425d5312a7..0000000000 Binary files a/doc/screens/pd2.png and /dev/null differ diff --git a/doc/screens/pd3.png b/doc/screens/pd3.png deleted file mode 100644 index 08c51299c6..0000000000 Binary files a/doc/screens/pd3.png and /dev/null differ diff --git a/doc/screens/pddom1.png b/doc/screens/pddom1.png deleted file mode 100644 index 379aaa9d02..0000000000 Binary files a/doc/screens/pddom1.png and /dev/null differ diff --git a/doc/screens/pddom2.png b/doc/screens/pddom2.png deleted file mode 100644 index d95cebb804..0000000000 Binary files a/doc/screens/pddom2.png and /dev/null differ diff --git a/doc/screens/profiles.png b/doc/screens/profiles.png deleted file mode 100644 index 95fbd9e805..0000000000 Binary files a/doc/screens/profiles.png and /dev/null differ diff --git a/doc/screens/qre.png b/doc/screens/qre.png deleted file mode 100644 index 94e9a875af..0000000000 Binary files a/doc/screens/qre.png and /dev/null differ