From 2357922853822b3509c1ca889f208f8cb78fa676 Mon Sep 17 00:00:00 2001 From: Theodore Turocy Date: Mon, 1 Jun 2026 11:37:51 +0100 Subject: [PATCH 1/6] Draft overview of architecture --- doc/developer.overview.rst | 43 ++++++++++++++++++++++++++++++++++++++ doc/developer.rst | 1 + 2 files changed, 44 insertions(+) create mode 100644 doc/developer.overview.rst diff --git a/doc/developer.overview.rst b/doc/developer.overview.rst new file mode 100644 index 0000000000..28abef649f --- /dev/null +++ b/doc/developer.overview.rst @@ -0,0 +1,43 @@ +.. _architecture-overview: + +Overview of Gambit architecture +=============================== + +The core of Gambit is a collection of C++ code for the representation and analysis of finite games. +This code is organised into three directories: + +* ``src/core``: Generic functions, structures, and utility code which is not specific to + game theory. +* ``src/games``: Definition of the interface and representation data structures for game objects + and related concepts. +* ``src/solvers``: Implementation of algorithms for computation on games, principally for the + computation of (exact or approximate) Nash equilibria. + +At present this core is referred to as a "collection" rather than a "library" as +this is not (yet) packaged by the build system as a reusable C++ library with a documented, +stable interface. + +Gambit is written to the C++17 standard. Because Gambit is cross-platform, C++ library +dependencies are avoided to facilitate development and packaging. + +The principal way in which code is written to use Gambit is via the Python package +``pygambit``. In particular, testing is done via the Python test suite and ``pytest``, +which therefore (indirectly) tests the C++ data structures and algorithms. +Running ``make check`` has no effect (there are no tests defined in that build system). + +From Gambit 17, ``pygambit`` is also responsible for providing command-line interfaces to +equilibrium computation and other facilities; previously the command-line wrappers were +implemented in C++. + +Gambit's core is also incorporated into a graphical user interface, also written +in C++ using wxWidgets (see ``src/gui``). This is built by default by ``make``. + +This hybrid architecture aims to maintain some flexibility for future development, by + +1. Although in practice we expect ``pygambit`` will be the most common path for writing + code using Gambit, the C++ implementations are kept separate from the Python wrapper + so they can continue to be used directly in C++ +2. Likewise, the graphical interface layer is kept cleanly separate from the core. + The developers anticipate that graphical-based interfaces will evolve rapidly in + the near future, both in terms of UX and implementation details (different + libraries, languages, browser-based interfaces). diff --git a/doc/developer.rst b/doc/developer.rst index b954f08508..ee1bb5fd44 100644 --- a/doc/developer.rst +++ b/doc/developer.rst @@ -9,6 +9,7 @@ This section contains information for developers who want to contribute to the G .. toctree:: :maxdepth: 2 + developer.overview developer.build developer.contributing developer.catalog From 1ed47ba8d3632da8faeae984a9bab3a19bfecd0a Mon Sep 17 00:00:00 2001 From: Ted Turocy Date: Fri, 5 Jun 2026 08:55:28 +0100 Subject: [PATCH 2/6] Update doc/developer.overview.rst Co-authored-by: Ed Chalstrey --- doc/developer.overview.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/developer.overview.rst b/doc/developer.overview.rst index 28abef649f..031a0ecded 100644 --- a/doc/developer.overview.rst +++ b/doc/developer.overview.rst @@ -38,6 +38,6 @@ This hybrid architecture aims to maintain some flexibility for future developmen code using Gambit, the C++ implementations are kept separate from the Python wrapper so they can continue to be used directly in C++ 2. Likewise, the graphical interface layer is kept cleanly separate from the core. - The developers anticipate that graphical-based interfaces will evolve rapidly in + Development of graphical-based interfaces (different libraries, languages, browser-based interfaces) can be carried out without touching the core code. the near future, both in terms of UX and implementation details (different libraries, languages, browser-based interfaces). From 0a6e389dfc2bed68bf95c9f9d8eb117d3157d905 Mon Sep 17 00:00:00 2001 From: Ted Turocy Date: Fri, 5 Jun 2026 08:55:44 +0100 Subject: [PATCH 3/6] Update doc/developer.overview.rst Co-authored-by: Ed Chalstrey --- doc/developer.overview.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/doc/developer.overview.rst b/doc/developer.overview.rst index 031a0ecded..2df32031e6 100644 --- a/doc/developer.overview.rst +++ b/doc/developer.overview.rst @@ -39,5 +39,4 @@ This hybrid architecture aims to maintain some flexibility for future developmen so they can continue to be used directly in C++ 2. Likewise, the graphical interface layer is kept cleanly separate from the core. Development of graphical-based interfaces (different libraries, languages, browser-based interfaces) can be carried out without touching the core code. - the near future, both in terms of UX and implementation details (different libraries, languages, browser-based interfaces). From 95208376843e1030d99d49cad9b20622bb509e95 Mon Sep 17 00:00:00 2001 From: Ted Turocy Date: Fri, 5 Jun 2026 08:55:52 +0100 Subject: [PATCH 4/6] Update doc/developer.overview.rst Co-authored-by: Ed Chalstrey --- doc/developer.overview.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/doc/developer.overview.rst b/doc/developer.overview.rst index 2df32031e6..1ed0ba1241 100644 --- a/doc/developer.overview.rst +++ b/doc/developer.overview.rst @@ -39,4 +39,3 @@ This hybrid architecture aims to maintain some flexibility for future developmen so they can continue to be used directly in C++ 2. Likewise, the graphical interface layer is kept cleanly separate from the core. Development of graphical-based interfaces (different libraries, languages, browser-based interfaces) can be carried out without touching the core code. - libraries, languages, browser-based interfaces). From dcf71adb14292187f60767121734e2c996078e64 Mon Sep 17 00:00:00 2001 From: Theodore Turocy Date: Fri, 5 Jun 2026 09:10:06 +0100 Subject: [PATCH 5/6] Some final tweaks to architecture overview. --- doc/developer.overview.rst | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/doc/developer.overview.rst b/doc/developer.overview.rst index 1ed0ba1241..b83dc215da 100644 --- a/doc/developer.overview.rst +++ b/doc/developer.overview.rst @@ -3,7 +3,7 @@ Overview of Gambit architecture =============================== -The core of Gambit is a collection of C++ code for the representation and analysis of finite games. +The core of Gambit is a library of C++ code for the representation and analysis of finite games. This code is organised into three directories: * ``src/core``: Generic functions, structures, and utility code which is not specific to @@ -13,10 +13,6 @@ This code is organised into three directories: * ``src/solvers``: Implementation of algorithms for computation on games, principally for the computation of (exact or approximate) Nash equilibria. -At present this core is referred to as a "collection" rather than a "library" as -this is not (yet) packaged by the build system as a reusable C++ library with a documented, -stable interface. - Gambit is written to the C++17 standard. Because Gambit is cross-platform, C++ library dependencies are avoided to facilitate development and packaging. @@ -24,13 +20,18 @@ The principal way in which code is written to use Gambit is via the Python packa ``pygambit``. In particular, testing is done via the Python test suite and ``pytest``, which therefore (indirectly) tests the C++ data structures and algorithms. Running ``make check`` has no effect (there are no tests defined in that build system). +The test suite makes use of a variety of games, which are drawn from examples in +the game theory literature and textbooks, as well as examples constructed specifically +to test edge cases. From Gambit 17, these are all curated as part of Gambit's +:ref:`catalog of games `. From Gambit 17, ``pygambit`` is also responsible for providing command-line interfaces to equilibrium computation and other facilities; previously the command-line wrappers were implemented in C++. Gambit's core is also incorporated into a graphical user interface, also written -in C++ using wxWidgets (see ``src/gui``). This is built by default by ``make``. +in C++ using wxWidgets (see ``src/gui``). This is built by ``make`` if an installation +of a suitable version of wxWidgets is detected. This hybrid architecture aims to maintain some flexibility for future development, by @@ -38,4 +39,5 @@ This hybrid architecture aims to maintain some flexibility for future developmen code using Gambit, the C++ implementations are kept separate from the Python wrapper so they can continue to be used directly in C++ 2. Likewise, the graphical interface layer is kept cleanly separate from the core. - Development of graphical-based interfaces (different libraries, languages, browser-based interfaces) can be carried out without touching the core code. + Graphical-based interfaces (different libraries, languages, + browser-based interfaces) can be developed without touching the core code. From 2df341c4571bd9868a089f96246ee3503264928e Mon Sep 17 00:00:00 2001 From: Rahul Savani Date: Fri, 5 Jun 2026 10:47:22 +0100 Subject: [PATCH 6/6] Clarify hybrid architecture description in overview --- doc/developer.overview.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/developer.overview.rst b/doc/developer.overview.rst index b83dc215da..0960dc4ae0 100644 --- a/doc/developer.overview.rst +++ b/doc/developer.overview.rst @@ -33,7 +33,7 @@ Gambit's core is also incorporated into a graphical user interface, also written in C++ using wxWidgets (see ``src/gui``). This is built by ``make`` if an installation of a suitable version of wxWidgets is detected. -This hybrid architecture aims to maintain some flexibility for future development, by +This hybrid architecture aims to maintain some flexibility for future development as follows: 1. Although in practice we expect ``pygambit`` will be the most common path for writing code using Gambit, the C++ implementations are kept separate from the Python wrapper