diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index 092d9f75d..e83059645 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -19,6 +19,26 @@ body: - Other validations: required: true + - type: dropdown + id: os + attributes: + label: What operating system are you using? + multiple: true + options: + - Windows + - macOS + - Linux + validations: + required: true + - type: textarea + id: version + attributes: + label: What version of Gambit are you using? + description: Please provide the version number. + placeholder: e.g., 16.3.0 + value: "16.3.0" + validations: + required: true - type: textarea id: what-happened attributes: diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index 05feae890..365148a74 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -2,7 +2,15 @@ name: Linters and coding standards checks on: push: + paths-ignore: + - 'doc/**' + - '.github/ISSUE_TEMPLATE/**' + - 'README.md' pull_request: + paths-ignore: + - 'doc/**' + - '.github/ISSUE_TEMPLATE/**' + - 'README.md' jobs: clang-format: diff --git a/.github/workflows/osxbinary.yml b/.github/workflows/osxbinary.yml index 2152b294c..428a75a7e 100644 --- a/.github/workflows/osxbinary.yml +++ b/.github/workflows/osxbinary.yml @@ -2,6 +2,10 @@ name: MacOS static GUI binary on: push: + paths-ignore: + - 'doc/**' + - '.github/ISSUE_TEMPLATE/**' + - 'README.md' tags: - 'v*' schedule: diff --git a/.github/workflows/python.yml b/.github/workflows/python.yml index 9aa1d0303..e6611c86c 100644 --- a/.github/workflows/python.yml +++ b/.github/workflows/python.yml @@ -2,7 +2,15 @@ name: pygambit Python extension on: push: + paths-ignore: + - 'doc/**' + - '.github/ISSUE_TEMPLATE/**' + - 'README.md' pull_request: + paths-ignore: + - 'doc/**' + - '.github/ISSUE_TEMPLATE/**' + - 'README.md' jobs: linux: diff --git a/.github/workflows/tools.yml b/.github/workflows/tools.yml index db6875dad..673145e82 100644 --- a/.github/workflows/tools.yml +++ b/.github/workflows/tools.yml @@ -2,7 +2,15 @@ name: Build executables on: push: + paths-ignore: + - 'doc/**' + - '.github/ISSUE_TEMPLATE/**' + - 'README.md' pull_request: + paths-ignore: + - 'doc/**' + - '.github/ISSUE_TEMPLATE/**' + - 'README.md' jobs: linux: diff --git a/.github/workflows/wheels.yml b/.github/workflows/wheels.yml index 72119a389..2624184ec 100644 --- a/.github/workflows/wheels.yml +++ b/.github/workflows/wheels.yml @@ -1,7 +1,12 @@ + name: pygambit wheels on: push: + paths-ignore: + - 'doc/**' + - '.github/ISSUE_TEMPLATE/**' + - 'README.md' tags: - 'v*' schedule: diff --git a/.readthedocs.yml b/.readthedocs.yml index d91034ca8..1dd08d262 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -8,7 +8,7 @@ formats: all build: os: ubuntu-22.04 tools: - python: "3.9" + python: "3.13" apt_packages: - libgmp-dev diff --git a/README.md b/README.md index 0f84442cb..c4f4793cd 100644 --- a/README.md +++ b/README.md @@ -13,6 +13,9 @@ **Gambit** is the package for doing computation in (non-cooperative) game theory. +- See our [documentation](https://gambitproject.readthedocs.io/) +- Check our [project website](https://www.gambit-project.org/) + Gambit provides: - Structures to represent games in extensive and strategic form diff --git a/doc/Makefile b/doc/Makefile index 22f7f23ff..26efc85c2 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -11,11 +11,12 @@ PAPEROPT_a4 = -D latex_paper_size=a4 PAPEROPT_letter = -D latex_paper_size=letter ALLSPHINXOPTS = -d _build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . -.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest +.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest livehtml help: @echo "Please use \`make ' where is one of" @echo " html to make standalone HTML files" + @echo " livehtml to make HTML files with auto-rebuild and live server" @echo " dirhtml to make HTML files named index.html in directories" @echo " pickle to make pickle files" @echo " json to make JSON files" @@ -34,6 +35,11 @@ html: @echo @echo "Build finished. The HTML pages are in _build/html." +livehtml: + sphinx-autobuild -b html $(ALLSPHINXOPTS) _build/html --host 0.0.0.0 --port 8000 + @echo + @echo "Live server started at http://localhost:8000" + dirhtml: $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) _build/dirhtml @echo diff --git a/doc/_templates/layout.html b/doc/_templates/layout.html index c44167417..3130e3530 100644 --- a/doc/_templates/layout.html +++ b/doc/_templates/layout.html @@ -12,10 +12,11 @@ {% block relbar1 %} -
-Chadwick -Gambit: Software Tools for Game Theory +
+ Chadwick + +

Software tools for game theory.

{{ super() }} {% endblock %} diff --git a/doc/conf.py b/doc/conf.py index 532628e7b..60292ade6 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -28,6 +28,10 @@ "sphinx_design", ] +# IPython directive configuration +ipython_execlines = ['import pygambit as gbt', 'import os', 'import sys'] +ipython_savefig_dir = 'savefig' + # Add any paths that contain templates here, relative to this directory. templates_path = ["_templates"] @@ -100,7 +104,35 @@ # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. -# html_theme_options = {} +html_theme_options = { + "external_links": [ + { + "name": "GitHub", + "url": "https://github.com/gambitproject/gambit" + }, + { + "name": "Releases", + "url": "https://github.com/gambitproject/gambit/releases" + }, + { + "name": "Older releases", + "url": "https://sourceforge.net/projects/gambit/files/" + }, + { + "name": "Cite Gambit", + "url": "https://www.gambit-project.org/cite/" + } + ], + "navbar_end": ["theme-switcher", "navbar-icon-links"], + "icon_links": [ + { + "name": "GitHub", + "url": "https://github.com/gambitproject/gambit", + "icon": "fab fa-github-square", + "type": "fontawesome", + } + ], +} # Add any paths that contain custom themes here, relative to this directory. # html_theme_path = [] diff --git a/doc/contents.rst b/doc/contents.rst index df74f8dd5..4b49795cc 100644 --- a/doc/contents.rst +++ b/doc/contents.rst @@ -7,11 +7,11 @@ Detailed table of contents :maxdepth: 3 intro - tools pygambit + tools gui samples - build + developer formats biblio diff --git a/doc/build.rst b/doc/developer.build.rst similarity index 77% rename from doc/build.rst rename to doc/developer.build.rst index 67fa403ec..62a8f4706 100644 --- a/doc/build.rst +++ b/doc/developer.build.rst @@ -1,5 +1,5 @@ -For developers: Building Gambit from source -=========================================== +Building Gambit from source +=========================== This section covers instructions for building Gambit from source. This is for those who are interested in developing Gambit, or who @@ -144,34 +144,3 @@ using `nose2`. Once installed, simply ``import pygambit`` in your Python shell or script to get started. - -Editing this documentation --------------------------- - -1. 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: :: - - python -m venv docenv - source docenv/bin/activate - -3. Install the requirements and make the docs: :: - - pip install . - cd doc - pip install -r requirements.txt - make html - -4. 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. Follow the usual GitHub workflow 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. - -.. TODO: Add instructions for the GitHub workflow during contributor docs refactoring. - See https://github.com/gambitproject/gambit/issues/541 \ No newline at end of file diff --git a/doc/developer.contributing.rst b/doc/developer.contributing.rst new file mode 100644 index 000000000..daf27fcac --- /dev/null +++ b/doc/developer.contributing.rst @@ -0,0 +1,87 @@ +Contributing to the Gambit Project +================================== + +This section provides guidelines for contributing to the Gambit project, including how to report bugs, suggest features, and contribute code. +It includes information relevant to both core developers and external contributors. + +GitHub issues +---------------- + +In the first instance, bug reports, feature requests and improvements to the Gambit documentation should be +posted to the Gambit issue tracker, located at +``_. +Use the issue templates to help you provide the necessary information. + +When reporting a bug, please be sure to include the following: + +* The version(s) of Gambit you are using. (If possible, it is helpful + to know whether a bug exists in both the current stable/teaching and + the current development/research versions.) +* The operating system(s) on which you encountered the bug. +* A detailed list of steps to reproduce the bug. Be sure to include a + sample game file or files if appropriate; it is often helpful to + simplify the game if possible. + +Contributing code +---------------- + +Gambit is an open-source project, and contributions are welcome from anyone. +The project is hosted on GitHub, and contributions can be made via pull requests following the standard GitHub workflow. + +1. To get started contributing code in the `Gambit GitHub repo `__, do one of the following: + +- Core developers: request contributor access from one of the `team `__ +- External contributors: fork the repository on GitHub. + +2. Clone the repository to your local machine :: + + git clone https://github.com/gambitproject/gambit.git # or your fork URL + cd gambit + +3. Create a new branch for your changes :: + + git checkout -b feature/your-feature-name + +4. Make your changes. Commit each change with a clear commit message :: + + git add . + git commit -m "Add feature X or fix bug Y" + +5. Push your changes to your fork or branch :: + + git push origin feature/your-feature-name + +6. Open a pull request on GitHub to the master branch of the upstream repository, describing your changes and linking to any relevant issues. +7. Core developers will review your changes, provide feedback, and merge them into the master branch if they meet the project's standards. + +Editing this documentation +-------------------------- + +1. 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: :: + + python -m venv docenv + source docenv/bin/activate + +3. 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. Make any changes you want to the `.rst` files in the ``doc`` directory and rebuld the documentation to check your changes. + +6. Follow the usual GitHub workflow 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. + +.. TODO: Add instructions for the GitHub workflow during contributor docs refactoring. + See https://github.com/gambitproject/gambit/issues/541 + diff --git a/doc/developer.rst b/doc/developer.rst new file mode 100644 index 000000000..ba1605914 --- /dev/null +++ b/doc/developer.rst @@ -0,0 +1,13 @@ +.. _developer: + + +Developer docs +============== + +This section contains information for developers who want to contribute to the Gambit project, including how to build Gambit from source, how to contribute code, and how to report bugs. + +.. toctree:: + :maxdepth: 2 + + developer.build + developer.contributing \ No newline at end of file diff --git a/doc/gui.rst b/doc/gui.rst index 4ca0cee37..361681c40 100644 --- a/doc/gui.rst +++ b/doc/gui.rst @@ -1,8 +1,8 @@ .. _section-gui: -*********************** -The graphical interface -*********************** +*** +GUI +*** Gambit's graphical user interface provides an "integrated development environment" to help visually construct diff --git a/doc/index.rst b/doc/index.rst index 5788ba252..2fcb284f3 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,44 +1,9 @@ -################# -Welcome to Gambit -################# - - +########################## +Gambit: User documentation +########################## **Gambit** is a library of game theory software and tools for the construction and analysis of finite extensive and strategic games. -Gambit is fully-cross platform, and is supported on Linux, Mac OS X, -and Microsoft Windows. - -Key features of Gambit include: - -* A :ref:`graphical user interface `, which uses - `wxWidgets `_ to provide a common - interface with native look-and-feel across platforms. -* All equilibrium-computing algorithms are available as - :ref:`command-line tools `, callable from scripts and - other programs. -* A :ref:`Python API ` for developing scripting applications. - - -Gambit is Free/Open Source software, released under the terms of the -`GNU General Public License `_, -Version 2. - -We hope you will find Gambit useful for both teaching and research -applications. If you do use Gambit in a class, or in a paper, we would -like to hear about it. We are especially interested in finding out -what you like about Gambit, and where you think improvements could be -made. - -If you are citing Gambit in a paper, we suggest a citation of the form: - - Savani, Rahul and Turocy, Theodore L. (2025) - Gambit: The package for computation in game theory, Version 16.3.1. - https://www.gambit-project.org. - -Replace the version number and year as appropriate if you use a -different release. - .. grid:: @@ -93,17 +58,16 @@ different release. :expand: - .. toctree:: :hidden: :maxdepth: 1 intro - tools pygambit + tools gui samples - build + developer formats biblio diff --git a/doc/intro.rst b/doc/intro.rst index 68c8d7caa..493829225 100644 --- a/doc/intro.rst +++ b/doc/intro.rst @@ -1,9 +1,6 @@ -********************* -An overview of Gambit -********************* - +*************** What is Gambit? -=============== +*************** Gambit is a set of software tools for doing computation on finite, noncooperative games. These comprise a graphical interface for @@ -11,51 +8,8 @@ interactively building and analyzing general games in extensive or strategy form; a number of command-line tools for computing Nash equilibria and other solution concepts in games; and, a set of file formats for storing and communicating games to external tools. - -A brief history of Gambit -========================= - -The Gambit Project was founded in the mid-1980s by Richard McKelvey at -the California Institute of Technology. The original implementation -was written in BASIC, with a simple graphical interface. This code was -ported to C around 1990 with the help of Bruce Bell, and was -distributed publicly as version 0.13 in 1991 and 1992. - -A major step in the evolution of Gambit took place with the awarding -of the NSF grants in 1994, with McKelvey and Andrew McLennan as -principal investigators, and `Theodore Turocy `__ as the head programmer. -The grants sponsored a complete rewrite of Gambit in C++. The -graphical interface was made portable across platforms through the use -of the wxWidgets library (`http://www.wxwidgets.org -`__). Version 0.94 of Gambit was released in -the late summer of 1994, version 0.96 followed in 1999, and version -0.97 in 2002. During this time, many students at Caltech and Minnesota -contributed to the effort by programming, testing, and/or documenting. -These include, alphabetically, Bruce Bell, Anand Chelian, Matthew -Derer, Nelson Escobar, Ben Freeman, Eugene Grayver, Todd Kaplan, Geoff -Matters, Brian Trotter, Michael Vanier, Roberto Weber, and Gary Wu. - -Over the same period, Bernhard von Stengel, of the London School of -Economics, made significant contributions in the implementation of the -sequence form methods for two-player extensive games, and for -contributing his "clique" code for identification of equilibrium -components in two-player strategic games, as well as other advice -regarding Gambit's implementation and architecture. - -Development since the mid-2000s has focused on two objectives. First, -the graphical interface was reimplemented and modernized, with the -goal of following good interaction design principles, especially in -regards to easing the learning curve for users new to Gambit and new -to game theory. Second, the internal architecture of Gambit was -refactored to increase interoperability between the tools provided by -Gambit and those written independently. - -Gambit is proud to have participated in the Google Summer of Code -program in the summers of 2011 and 2012 as a mentoring organization. -The Python API, which became part of Gambit from Gambit 13, was -developed during these summers, thanks in particular to the work -of Stephen Kunath and Alessandro Andrioni. - +Gambit is fully-cross platform, and is supported on Linux, Mac OS X, +and Microsoft Windows. Key features of Gambit ====================== @@ -135,10 +89,15 @@ that Gambit will both contribute to these two areas of research, as well as make the resulting methods available to both students and practitioners. -Developers -========== +Who built Gambit? +================= + +Check out the `team page `__ on the Gambit website for up-to-date information on the current Gambit development team. + +History +------- -The principal developers of Gambit are: +The principal developers of Gambit have been: * `Theodore Turocy `__, University of East Anglia: director. @@ -177,32 +136,44 @@ include: of British Columbia, the NSERC Canada Graduate Scholarship, and a Google Research Award to Leyton-Brown. -.. _section-downloading: - -Downloading Gambit -================== - -Gambit source code and built binaries can be downloaded from the project -`GitHub repository releases section `_. - -Older versions of Gambit can be downloaded from -`http://sourceforge.net/projects/gambit/files -`_. +The Gambit Project was founded in the mid-1980s by Richard McKelvey at +the California Institute of Technology. The original implementation +was written in BASIC, with a simple graphical interface. This code was +ported to C around 1990 with the help of Bruce Bell, and was +distributed publicly as version 0.13 in 1991 and 1992. -Bug reports -=========== +A major step in the evolution of Gambit took place with the awarding +of the NSF grants in 1994, with McKelvey and Andrew McLennan as +principal investigators, and `Theodore Turocy `__ as the head programmer. +The grants sponsored a complete rewrite of Gambit in C++. The +graphical interface was made portable across platforms through the use +of the wxWidgets library (`http://www.wxwidgets.org +`__). Version 0.94 of Gambit was released in +the late summer of 1994, version 0.96 followed in 1999, and version +0.97 in 2002. During this time, many students at Caltech and Minnesota +contributed to the effort by programming, testing, and/or documenting. +These include, alphabetically, Bruce Bell, Anand Chelian, Matthew +Derer, Nelson Escobar, Ben Freeman, Eugene Grayver, Todd Kaplan, Geoff +Matters, Brian Trotter, Michael Vanier, Roberto Weber, and Gary Wu. -In the first instance, bug reports or feature requests should be -posted to the Gambit issue tracker, located at -``_. +Over the same period, Bernhard von Stengel, of the London School of +Economics, made significant contributions in the implementation of the +sequence form methods for two-player extensive games, and for +contributing his "clique" code for identification of equilibrium +components in two-player strategic games, as well as other advice +regarding Gambit's implementation and architecture. -When reporting a bug, please be sure to include the following: +Development since the mid-2000s has focused on two objectives. First, +the graphical interface was reimplemented and modernized, with the +goal of following good interaction design principles, especially in +regards to easing the learning curve for users new to Gambit and new +to game theory. Second, the internal architecture of Gambit was +refactored to increase interoperability between the tools provided by +Gambit and those written independently. -* The version(s) of Gambit you are using. (If possible, it is helpful - to know whether a bug exists in both the current stable/teaching and - the current development/research versions.) -* The operating system(s) on which you encountered the bug. -* A detailed list of steps to reproduce the bug. Be sure to include a - sample game file or files if appropriate; it is often helpful to - simplify the game if possible. +Gambit is proud to have participated in the Google Summer of Code +program in the summers of 2011 and 2012 as a mentoring organization. +The Python API, which became part of Gambit from Gambit 13, was +developed during these summers, thanks in particular to the work +of Stephen Kunath and Alessandro Andrioni. diff --git a/doc/pygambit.rst b/doc/pygambit.rst index c38cad446..556a80afb 100644 --- a/doc/pygambit.rst +++ b/doc/pygambit.rst @@ -1,12 +1,18 @@ .. _pygambit: -``pygambit`` Python package -=========================== +PyGambit +======== -Gambit provides a Python package, ``pygambit``, which provides access to -Gambit's features. ``pygambit`` is available on PyPI -(https://pypi.org/project/pygambit/), and can be installed via ``pip``. +Gambit provides a Python package, ``pygambit``, which is available on `PyPI +`_. + +Installation +------------ + +To install the package, use the following command:: + + pip install pygambit .. toctree:: :maxdepth: 2 diff --git a/doc/requirements.txt b/doc/requirements.txt index d86c98f3d..5909d77ee 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -1,7 +1,10 @@ -Cython -numpy -scipy -pydata-sphinx-theme -sphinx_design -ipython -pickleshare +Cython==3.1.2 +numpy==2.3.2 +scipy==1.16.1 +pydata-sphinx-theme==0.16.1 +sphinx_design==0.6.1 +sphinx-autobuild==2024.10.3 +ipython==9.4.0 +matplotlib==3.10.5 +pickleshare==0.7.5 +jupyter==1.1.1 \ No newline at end of file diff --git a/doc/tools.rst b/doc/tools.rst index d08acbebc..542c5bf4e 100644 --- a/doc/tools.rst +++ b/doc/tools.rst @@ -1,8 +1,8 @@ .. _command-line: -****************** -Command-line tools -****************** +*** +CLI +*** Gambit provides command-line interfaces for each method for computing Nash equilibria. These are suitable for scripting or calling from