Add general concepts section to documentation

doc/algorithms.rst

@@ -129,6 +129,36 @@ support is complete, that support may be reported with incomplete equilibria,
 and (in verbose mode) is identified with the label "budget-exceeded" -- see
 :ref:`gambit-enumpoly <gambit-enumpoly>` for details.
 
+Using external programs to compute Nash equilibria
+----------------------------------------------------
+
+.. TODO: this needs to be updated, see issue #561
+
+Because the problem of finding Nash equilibria can be expressed in various
+mathematical formulations (see :cite:p:`McKMcL96`), it is helpful to make use
+of other software packages designed specifically for solving those problems.
+
+There are currently two integrations offered for using external programs to solve
+for equilibria:
+
+- :py:func:`.enummixed_solve` supports enumeration of equilibria in
+  two-player games via `lrslib`.  [#lrslib]_
+- :py:func:`.enumpoly_solve` supports computation of totally-mixed equilibria
+  on supports in strategic games via `PHCpack`.  [#phcpack]_
+
+For both calls, using the external program requires passing the path to the
+executable (via the `lrsnash_path` and `phcpack_path` arguments, respectively).
+
+The user must download and compile or install these programs on their own; these are
+not packaged with Gambit. The solver calls do take care of producing the required
+input files, and reading the output to convert into Gambit objects for further
+processing.
+
+
+.. [#lrslib] http://cgm.cs.mcgill.ca/~avis/C/lrs.html
+
+.. [#phcpack] https://homepages.math.uic.edu/~jan/PHCpack/phcpack.html
+
 .. _lp:
 
 lp

doc/concepts.rst

@@ -0,0 +1,171 @@
+.. _concepts:
+
+Concepts and conventions
+=========================
+
+
+
+.. _concepts-representations:
+
+Game representations
+--------------------
+
+
+.. _concepts-players-actions-strategies:
+
+Players, actions, and strategies
+----------------------------------
+
+
+
+.. _concepts-outcomes:
+
+Outcomes
+---------
+
+
+.. _concepts-numerical-data:
+
+Numerical data conventions
+-----------------------------
+
+Payoffs to players and probabilities of actions at events are specified as numbers.
+Gambit represents the numerical values in a game in exact precision, using either decimal
+or rational representations.
+
+To illustrate, consider a trivial game which just has one move for the chance player:
+
+.. code-block:: python
+
+   small_game = gbt.ExtensiveGame()
+   small_game.append_event(gbt.H.path(), dict.fromkeys(["a", "b", "c"], gbt.Rational(1, 3)))
+   list(small_game.get_action_probs(gbt.H.path()).values())
+
+Here we specified an equal-probability distribution over the three actions, using
+``pygambit``'s :py:class:`.Rational` class, which is derived from Python's
+``fractions.Fraction``, to represent the probabilities exactly.
+
+Numerical data can be set as rational numbers.
+:py:meth:`.ExtensiveGame.make_event` forms a collection of nodes into an event with a given
+distribution; applied to a single node which is already an event, it resets the probabilities.
+We can use it to change the distribution, again with ``Rational`` numbers:
+
+.. code-block:: python
+
+   small_game.make_event(
+       gbt.H.path(),
+       {"a": gbt.Rational(1, 4), "b": gbt.Rational(1, 2), "c": gbt.Rational(1, 4)}
+   )
+   list(small_game.get_action_probs(gbt.H.path()).values())
+
+Numerical data can also be explicitly specified as decimal numbers:
+
+.. code-block:: python
+
+   small_game.make_event(
+       gbt.H.path(),
+       {"a": gbt.Decimal(".25"), "b": gbt.Decimal(".50"), "c": gbt.Decimal(".25")}
+   )
+   list(small_game.get_action_probs(gbt.H.path()).values())
+
+Although the two representations above are mathematically equivalent, ``pygambit``
+remembers the format in which the values were specified.
+
+Expressing rational or decimal numbers as above is verbose and tedious.
+``pygambit`` offers a more concise way to express numerical data in games: when setting
+numerical game data, ``pygambit`` will attempt to convert text strings to their rational or
+decimal representation.  The above can therefore be written more compactly using string
+representations:
+
+.. code-block:: python
+
+   small_game.make_event(gbt.H.path(), {"a": "1/4", "b": "1/2", "c": "1/4"})
+   list(small_game.get_action_probs(gbt.H.path()).values())
+
+   small_game.make_event(gbt.H.path(), {"a": ".25", "b": ".50", "c": ".25"})
+   list(small_game.get_action_probs(gbt.H.path()).values())
+
+As a further convenience, ``pygambit`` will accept Python ``int`` and ``float`` values.
+``int`` values are always interpreted as :py:class:`.Rational` values.
+
+``pygambit`` attempts to render ``float`` values in an appropriate :py:class:`.Decimal`
+equivalent.  In the majority of cases, this creates no problems.  For example:
+
+.. code-block:: python
+
+   small_game.make_event(gbt.H.path(), {"a": .25, "b": .50, "c": .25})
+   list(small_game.get_action_probs(gbt.H.path()).values())
+
+However, rounding can cause difficulties when attempting to use ``float`` values to
+represent values which do not have an exact decimal representation:
+
+.. code-block:: python
+
+   small_game.make_event(gbt.H.path(), {"a": 1/3, "b": 1/3, "c": 1/3})
+   # ValueError: ...
+
+This behavior can be slightly surprising, especially in light of the fact that in Python,
+
+.. code-block:: python
+
+   1/3 + 1/3 + 1/3
+   # 1.0
+
+In checking whether these probabilities sum to one, ``pygambit`` first converts each of the
+probabilities to a :py:class:`.Decimal` representation, via the following method:
+
+.. code-block:: python
+
+   gbt.Decimal(str(1/3))
+
+and the sum-to-one check then fails because:
+
+.. code-block:: python
+
+   gbt.Decimal(str(1/3)) + gbt.Decimal(str(1/3)) + gbt.Decimal(str(1/3))
+   # Decimal('0.9999999999999999166...')
+
+Setting payoffs for players also follows the same rules.  Representing probabilities and
+payoffs exactly is essential, because ``pygambit`` offers (in particular for two-player
+games) the possibility of computation of equilibria exactly, because the Nash equilibria of
+any two-player game with rational payoffs and chance probabilities can be expressed exactly
+in terms of rational numbers.
+
+It is therefore advisable always to specify the numerical data of games either in terms of
+:py:class:`.Decimal` or :py:class:`.Rational` values, or their string equivalents.  It is
+safe to use ``int`` values, but ``float`` values should be used with some care to ensure the
+values are recorded as intended.
+
+
+
+.. _concepts-information-sets:
+
+Information sets and imperfect information
+---------------------------------------------
+
+
+.. _concepts-strategy-types:
+
+Mixed strategy profiles and mixed behavior profiles
+-----------------------------------------------------
+
+A probability distribution over a player's strategies is a ``MixedStrategy``.
+An assignment of a ``MixedStrategy`` to each player forms a ``MixedStrategyProfile``, where following the
+standard convention in game theory it is assumed players randomize independently.
+
+In an extensive game,
+a probability distribution over a player's actions at an information set is a ``MixedAction``.
+An assignment of a ``MixedAction`` to each information set of a player is a ``MixedBehavior``.
+An assignment of a ``MixedBehavior`` to each player forms a ``MixedBehaviorProfile``.
+Following the standard convention in game theory, it is assumed the randomization of each
+``MixedAction`` in a profile is realized independently.
+
+``MixedStrategyProfile`` and ``MixedBehaviorProfile`` objects express their probabilities either
+as floating-point or rational numbers.  Each profile is one type or the other; the precision of
+all probabilities is the same in any profile.
+
+``MixedStrategy`` and ``MixedAction`` objects enforce that the probability assigned to each strategy
+or action is nonnegative.  By convention, these values are not enforced to sum to one; if they
+do not sum to one, they are interpreted as weights.  It is not valid to set all the probabilities/weights
+of a ``MixedStrategy`` or ``MixedAction`` to zero.  ``MixedStrategy`` and ``MixedAction`` objects can be
+normalized to sum to one via an explicit operation.

doc/contents.rst

@@ -7,6 +7,7 @@ Detailed table of contents
    :maxdepth: 3
 
    intro
+   concepts
    pygambit
    tools
    gui

doc/index.rst

@@ -106,6 +106,7 @@ construction and analysis of finite extensive and strategic games.
    :maxdepth: 1
 
    install
+   concepts
    algorithms
    pygambit
    tools

doc/pygambit.rst

@@ -14,6 +14,10 @@ You can run the tutorials interactively as Jupyter notebooks, see :ref:`local_tu
 Installing PyGambit also installs Gambit's :ref:`command-line tools <command-line>`
 for computing Nash equilibria from the shell or from scripts.
 
+Before working through the tutorials, it may help to read :doc:`concepts`, which sets
+out the terminology and modeling conventions used throughout this documentation and the
+PyGambit API.
+
 New user tutorials
 ------------------
 
@@ -46,7 +50,6 @@ Advanced tutorials:
    tutorials/advanced_tutorials/starting_points
    tutorials/advanced_tutorials/quantal_response
    tutorials/advanced_tutorials/agent_versus_non_agent_regret
-   .. pygambit.external_programs
 
 Interoperability tutorials
 --------------------------