Add Gambit/OpenSpiel interoperability tutorial

.gitignore

@@ -20,6 +20,7 @@ _build
 build
 *.egg-info
 *.pyc
+*.so
 
 config.guess
 config.sub
@@ -37,3 +38,5 @@ gambit
 .python-version
 dist
 .venv
+*.dmg
+Gambit.app/*

.readthedocs.yml

@@ -11,6 +11,7 @@ build:
     python: "3.13"
   apt_packages:
     - libgmp-dev
+    - pandoc
 
 python:
   install:

doc/conf.py

@@ -26,6 +26,7 @@
     "IPython.sphinxext.ipython_console_highlighting",
     "IPython.sphinxext.ipython_directive",
     "sphinx_design",
+    "nbsphinx",
 ]
 
 # IPython directive configuration

doc/developer.contributing.rst

@@ -22,6 +22,8 @@ When reporting a bug, please be sure to include the following:
   sample game file or files if appropriate; it is often helpful to
   simplify the game if possible.
 
+.. _contributing-code:
+
 Contributing code
 ----------------
 
@@ -57,31 +59,31 @@ The project is hosted on GitHub, and contributions can be made via pull requests
 Editing this documentation
 --------------------------
 
-1. If you haven't already, clone the Gambit repository from GitHub: ::
+1. `Install Pandoc <https://pandoc.org/installing.html>`_ for your OS
+
+2. If you haven't already, clone the Gambit repository from GitHub: ::
 
     git clone https://github.com/gambitproject/gambit.git
     cd gambit
 
-2. Either install the docs requirements into your existing PyGambit development environment, or create a new virtual environment and install both the requirements and PyGambit there. For example, you can use `venv` to create a new environment: ::
+3. Either install the docs requirements into your existing PyGambit development environment, or create a new virtual environment and install both the requirements and PyGambit there. For example, you can use `venv` to create a new environment: ::
 
     python -m venv docenv
     source docenv/bin/activate
 
-3. Install the requirements and make the docs: ::
+4. Install the requirements and make the docs: ::
 
     pip install .
     cd doc
     pip install -r requirements.txt
     make html  # or make livehtml for live server with auto-rebuild
 
-4. Open ``doc/_build/html/index.html`` in your browser to view the documentation.
+5. Open ``doc/_build/html/index.html`` in your browser to view the documentation.
 
-5. Make any changes you want to the `.rst` files in the ``doc`` directory and rebuld the documentation to check your changes.
+6. Make any changes you want to the `.rst` files in the ``doc`` directory and rebuild the documentation to check your changes.
 
-6. Follow the usual GitHub workflow to commit your changes and push them to the repository.
+7. Follow the usual GitHub workflow (see :ref:`contributing-code` above) to commit your changes and push them to the repository.
 
-7. Core developers will review your changes and merge to the master branch, which automatically deploys the documentation via the ReadTheDocs service.
+8. Core developers will review your changes and merge to the master branch, which automatically deploys the documentation via the ReadTheDocs service.
 
-.. TODO: Add instructions for the GitHub workflow during contributor docs refactoring.
-   See https://github.com/gambitproject/gambit/issues/541
 

doc/gui.rst

@@ -25,6 +25,68 @@ To build larger games or to explore parameter spaces of a game
 systematically, it is recommended to use
 :ref:`the Python package <pygambit>`.
 
+Installation
+------------
+
+To install the Gambit GUI, visit the `Gambit releases page on GitHub <https://github.com/gambitproject/gambit/releases>`_ and download the appropriate installer or package for your operating system.
+Each release includes pre-built binaries for Windows, macOS, and Linux distributions, accessible under the "Assets" section of each release.
+
+.. dropdown:: Manual macOS Build Instructions
+   :class-container: sd-border-0
+
+   To build and install the Gambit GUI from source on macOS, follow these steps:
+
+   1. **Install build dependencies:**
+
+      .. code-block:: bash
+
+         brew install automake autoconf libtool
+
+      .. note::
+         If you encounter interpreter errors with autom4te, you may need to ensure
+         your Perl installation is correct or reinstall the autotools:
+
+         .. code-block:: bash
+
+            brew reinstall automake autoconf libtool
+
+   2. **Download and build wxWidgets:**
+
+      .. code-block:: bash
+
+         curl -L -O https://github.com/wxWidgets/wxWidgets/releases/download/v3.2.8/wxWidgets-3.2.8.tar.bz2
+         tar xjf wxWidgets-3.2.8.tar.bz2
+         cd wxWidgets-3.2.8
+         mkdir build-release
+         cd build-release
+         ../configure --disable-shared --disable-sys-libs
+         make -j4
+         sudo make install
+
+   3. **Build and install Gambit:**
+
+      Navigate back to the Gambit source directory and run:
+
+      .. code-block:: bash
+
+         aclocal
+         automake --add-missing
+         autoconf
+         ./configure
+         make
+         sudo make install
+
+   4. **Create macOS application bundle:**
+
+      To create a distributable DMG file:
+
+      .. code-block:: bash
+
+         make osx-dmg
+
+   5. **Install the application:**
+
+      After creating the DMG file, open it and drag the Gambit application to your Applications folder.
 
 .. toctree::
    :maxdepth: 2

doc/index.rst

@@ -7,13 +7,13 @@ construction and analysis of finite extensive and strategic games.
 
 .. grid::
 
-   .. grid-item-card:: Python user guide
+   .. grid-item-card:: Python tutorials and user guide
       :columns: 6
 
       An introduction to using the ``pygambit`` package
       in Python.
 
-      .. button-ref:: pygambit-user
+      .. button-ref:: pygambit
          :ref-type: ref
          :click-parent:
          :color: secondary

doc/pygambit.external_programs.rst

@@ -0,0 +1,31 @@
+Using external programs to compute Nash equilibria
+==================================================
+
+Because the problem of finding Nash equilibria can be expressed in various
+mathematical formulations (see [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
+
+.. [McKMcL96] McKelvey, Richard D. and McLennan, Andrew M.  (1996) Computation of equilibria
+              in finite games.  In Handbook of Computational Economics, Volume 1,
+              pages 87-142.

doc/pygambit.rst

@@ -4,18 +4,70 @@
 PyGambit
 ========
 
-Gambit provides a Python package, ``pygambit``, which is available on `PyPI
-<https://pypi.org/project/pygambit/>`_.
+The Gambit Python package, ``pygambit``, is available on `PyPI <https://pypi.org/project/pygambit/>`_ and can be installed with pip::
 
-Installation
-------------
+   pip install pygambit
 
-To install the package, use the following command::
 
-   pip install pygambit
+For newcomers to Gambit, we recommend reading through the PyGambit tutorials, which demonstrate the API's key capabilities for analyzing and solving Game Theory games.
+These tutorials are available to be run interactively as Jupyter notebooks, see :ref:`local_tutorials`.
+All of the tutorials assume a basic knowledge of programming in Python.
+
+Tutorials **1-3** assume no prior knowledge of Game Theory or the PyGambit API and provide detailed explanations of the concepts and code.
+
+.. toctree::
+   :maxdepth: 2
+
+   tutorials/01_quickstart
+   tutorials/02_extensive_form
+   tutorials/03_poker
+
+Tutorials **4-5** assume some familiarity with the PyGambit API and Game Theory terminology and concepts including:
+
+- Nash equilibria
+- Pure and mixed strategies
+- Simplex representations of available strategies
+- Logit quantal response equilibrium (LQRE) correspondence
+
+.. toctree::
+   :maxdepth: 2
+
+   tutorials/04_starting_points
+   tutorials/05_quantal_response
+   tutorials/06_gambit_with_openspiel
+
+You may also wish to read:
+
+.. toctree::
+   :maxdepth: 2
+
+   tutorials/running_locally
+   pygambit.external_programs
+
+Algorithms for computing Nash equilibria
+----------------------------------------
+
+Interfaces to algorithms for computing Nash equilibria are provided in :py:mod:`pygambit.nash`.
+The table below summarizes the available PyGambit functions and the corresponding Gambit CLI commands.
+
+==========================================    ========================================
+CLI command                                   PyGambit function
+==========================================    ========================================
+:ref:`gambit-enumpure <gambit-enumpure>`      :py:func:`pygambit.nash.enumpure_solve`
+:ref:`gambit-enummixed <gambit-enummixed>`    :py:func:`pygambit.nash.enummixed_solve`
+:ref:`gambit-lp <gambit-lp>`                  :py:func:`pygambit.nash.lp_solve`
+:ref:`gambit-lcp <gambit-lcp>`                :py:func:`pygambit.nash.lcp_solve`
+:ref:`gambit-liap <gambit-liap>`              :py:func:`pygambit.nash.liap_solve`
+:ref:`gambit-logit <gambit-logit>`            :py:func:`pygambit.nash.logit_solve`
+:ref:`gambit-simpdiv <gambit-simpdiv>`        :py:func:`pygambit.nash.simpdiv_solve`
+:ref:`gambit-ipa <gambit-ipa>`                :py:func:`pygambit.nash.ipa_solve`
+:ref:`gambit-gnm <gambit-gnm>`                :py:func:`pygambit.nash.gnm_solve`
+==========================================    ========================================
+
+API documentation
+----------------
 
 .. toctree::
    :maxdepth: 2
 
-   pygambit.user
-   pygambit.api
+   pygambit.api