Draft overview of architecture

[tturocy]

This adds a section to the docs giving a brief overview of the conceptual architecture of Gambit.

This is written with an eye to it being accurate for Gambit 17. Therefore, it ignores the various remaining "third-party" bits of code we are removing and for which issues are already open (see e.g. #897 , #896 ). It also anticipates the plan to have command-line tools be written in Python rather than C++ (see #894 ).

In drafting this, an observation comes to mind that without the command-line tools, make in practice now is entirely about the graphical interface (and so if wxWidgets is not installed/available then make does nothing). The disclaimer that the C++ does not constitute a "library" seems awkward - and perhaps this indicates we should build the core as a C++ library (even if it comes with a disclaimer that as yet the API is not promised to be as stable as pygambit at least for 17.x?)

[edwardchalstrey1]

Looks good to me, I made one suggestion but feel free to reject

[tturocy]

@rahulsavani I've incorporated changes based on the discussions over the last few days - pending only your final once-over before we merge.

[rahulsavani]

Looks good. Just one question/comment:

"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 catalog"

Is that true? I thought that we had decided that the catalog would only contain games of general interest (e.g. from textbooks and papers) and that games specifically constructed for testing edge cases would continue to live in tests/test_games or similar.

Approving, assuming this is confirmed or a corresponding minor edit is made.

[tturocy]

Looks good. Just one question/comment:

"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 catalog"

Is that true? I thought that we had decided that the catalog would only contain games of general interest (e.g. from textbooks and papers) and that games specifically constructed for testing edge cases would continue to live in tests/test_games or similar.

Approving, assuming this is confirmed or a corresponding minor edit is made.

It's a good question.

I had been influenced in drafting this by also working on merging the new features for subgames. There, for example, we now have an example where we need an additional check in the edge case of an absent-minded information set with a single action. On the one hand that's not going to appear in any paper, but on the other it is a useful test case that also does serve as an example of an edge case. So that feels more catalog-y.

Are there going to be examples where we want to have test games that we load from game files but are constructed entirely for reasons of testing some code path in Gambit? Entirely willing to believe the answer is "yes" to this. I've scanned the current list of test games and part of the problem is we don't really know systematically why the games that are there, are there. :)

A good practice would be that if we have a test game, we should have a reason in the game's extended description of what it is good for. At which point, thinking about these test games as being "circumstances that can arise in game representations that are unlikely to be covered by standard examples of game-theoretic interest but which would be useful for testing libraries which represent games" - might make them "something that ought to be in the catalog"

[rahulsavani]

Looks good. Just one question/comment:
"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 catalog"
Is that true? I thought that we had decided that the catalog would only contain games of general interest (e.g. from textbooks and papers) and that games specifically constructed for testing edge cases would continue to live in tests/test_games or similar.
Approving, assuming this is confirmed or a corresponding minor edit is made.

It's a good question.

I had been influenced in drafting this by also working on merging the new features for subgames. There, for example, we now have an example where we need an additional check in the edge case of an absent-minded information set with a single action. On the one hand that's not going to appear in any paper, but on the other it is a useful test case that also does serve as an example of an edge case. So that feels more catalog-y.

Are there going to be examples where we want to have test games that we load from game files but are constructed entirely for reasons of testing some code path in Gambit? Entirely willing to believe the answer is "yes" to this. I've scanned the current list of test games and part of the problem is we don't really know systematically why the games that are there, are there. :)

A good practice would be that if we have a test game, we should have a reason in the game's extended description of what it is good for. At which point, thinking about these test games as being "circumstances that can arise in game representations that are unlikely to be covered by standard examples of game-theoretic interest but which would be useful for testing libraries which represent games" - might make them "something that ought to be in the catalog"

I don't know but I could well imagine the answer is "yes", like you. On reflection, I think we can just commit to having them in the catalog -- we can always have a suitably named (sub)directory or two for these games, and it is cleaner. No such game will be totally uninteresting for the catalog, so why not?

[tturocy]

We can close this off by proposing the following principle: If a game is interesting enough as a test case to be an actual game file, then it should be in the catalog - even if it's a part of the catalog which is a "rogue's gallery of edge cases".

There may be other games which we find useful in the test suite, but those we might just construct directly via the API rather than having them be saved, named games.

[rahulsavani]

We can close this off by proposing the following principle: If a game is interesting enough as a test case to be an actual game file, then it should be in the catalog - even if it's a part of the catalog which is a "rogue's gallery of edge cases".

There may be other games which we find useful in the test suite, but those we might just construct directly via the API rather than having them be saved, named games.

Agreed.