Skip to content

Interface to Gamut#930

Merged
edwardchalstrey1 merged 22 commits into
masterfrom
catalog/910
Jun 24, 2026
Merged

Interface to Gamut#930
edwardchalstrey1 merged 22 commits into
masterfrom
catalog/910

Conversation

@edwardchalstrey1

@edwardchalstrey1 edwardchalstrey1 commented Jun 5, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Issues closed by this PR

Description of the changes in this PR

This PR adds:

  • The ability to generate games with Gamut via the pygambit.catalog module, with a new function called generate_gamut (as oppose to load_gamut which would make it more similar to the OpenSpiel one, but I thought this made sense)
    • The params argument maps directly to GAMUT command-line flags. Boolean flags such as
      -normalize and -int_payoffs are passed as True; list values for -actions
      expand to space-separated tokens.
  • Documentation explaining how to install Gamut (and Java) and use via PyGambit - see the bottom of the catalog page
  • A tutorial notebook demonstrating using Gamut's functionality via PyGambit, covering some of the key features of Gamut as per the documentation PDF downloaded from here.
    • Some metadata has been added to prevent docs builds from attempting to run this nb, since it requires Java/Gamut, so instead the outputs are saved.

Example usage:

pygambit.catalog.generate_gamut(
    "RandomGame", params={"players": 2, "actions": 3}, gamut_jar="/path/to/gamut.jar"
)
pygambit.catalog.generate_gamut(
    "CovariantGame",
    params={"players": 2, "actions": [3, 3]},
    gamut_jar="/path/to/gamut.jar",
)
pygambit.catalog.generate_gamut(
    "RandomGame",
    params={
        "players": 3,
        "actions": 4,
        "normalize": True,
        "min_payoff": 0,
        "max_payoff": 100,
    },
    gamut_jar="/path/to/gamut.jar",
)

Todo:

  • Review and edit the tutorial, ensuring it makes sense and covers what a user might find helpful
  • Update tutorial or docs to cover all the available GAMUT classes

How to review this PR

@tturocy @rahulsavani I've taken an approach to this that mirrors that of OpenSpiel loading since #910 is listed as a catalog issue, however re-reading I notice Ted said "and we call as an external process, similar to the model established for PHCpack and lrslib" - so perhaps that approach makes more sense than what I've done here. Since Gamut involves Game generation rather than just loading pre-made games as in OpenSpiel (though I suppose you can pass in params there too)... my thought is perhaps Gamut generation should live elsewhere from the Catalog module? Again this brings up the issue of the Catalog being currently a PyGambit-only feature which Ted has raised. What are your thoughts?

@review-notebook-app

review-notebook-app Bot commented Jun 5, 2026

Copy link
Copy Markdown

Check out this pull request on  ReviewNB

See visual diffs & provide feedback on Jupyter Notebooks.

Powered by ReviewNB

edwardchalstrey1
edwardchalstrey1 commented Jun 15, 2026
View reviewed changes
Comment thread doc/tutorials/interoperability_tutorials/gamut.ipynb
@@ -0,0 +1,534 @@
{

@edwardchalstrey1 edwardchalstrey1 Jun 15, 2026 •
edited
Loading

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this accurate for the definition of the one MSP above?


Reply via ReviewNB

@edwardchalstrey1
edwardchalstrey1 marked this pull request as ready for review June 15, 2026 10:49
@tturocy

tturocy commented Jun 16, 2026

Copy link
Copy Markdown
Member

This looks quite good to me already out of the box.

I still have a feeling that the verb differentiation between OpenSpiel and GAMUT here isn't meaningful - I could just as easily justify "generate" for OpenSpiel, or "load" for both. In both cases the external tools are doing a generation step, even if we are using .efg/.nfg as the communication format those files are being created on demand by the library we're calling.

@edwardchalstrey1

edwardchalstrey1 commented Jun 17, 2026

Copy link
Copy Markdown
Member Author

This looks quite good to me already out of the box.

I still have a feeling that the verb differentiation between OpenSpiel and GAMUT here isn't meaningful - I could just as easily justify "generate" for OpenSpiel, or "load" for both. In both cases the external tools are doing a generation step, even if we are using .efg/.nfg as the communication format those files are being created on demand by the library we're calling.

Shall we stick with "load" for both to be consistent with the regular catalog load function?

@tturocy

tturocy commented Jun 17, 2026

Copy link
Copy Markdown
Member

I can see it both ways.

A reason I might lean to generate is the distinction that those methods may do work to realise the game beyond simply reading an already-serialised format. It can be useful to have different verbs or syntax in the API to hint at the underlying complexity or process. Compare for example the principle with Python @property that it's not good style to hide something that's computationally non-trivial in a property, just because then the API is communicating information that calling code should be aware of.

So load would mean "read an existing serialisation" while generate would mean "execute some code that constructs the representation"

@edwardchalstrey1

edwardchalstrey1 commented Jun 17, 2026

Copy link
Copy Markdown
Member Author

Thanks @tturocy load_openspiel has now been renamed to generate_openspiel as per your comment above

@tturocy tturocy added this to the gambit-16.7.0 milestone Jun 18, 2026
@edwardchalstrey1

edwardchalstrey1 commented Jun 18, 2026

Copy link
Copy Markdown
Member Author

Hi @wyz2368 I was just discussing with @rahulsavani - it would be helpful to have your review on this pull request. If you could check out the branch and read and run the tutorial I added locally (noting you will need to download Gamut as it should explain) and let me know if anything doesn't work, and also if the tutorial makes sense or should be re-written at all.

@wyz2368

wyz2368 commented Jun 18, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

@edwardchalstrey1 I tested all the examples in the notebook and everything works. Thank you.

@edwardchalstrey1

edwardchalstrey1 commented Jun 19, 2026

Copy link
Copy Markdown
Member Author

Thanks @wyz2368 !

rahulsavani
rahulsavani reviewed Jun 23, 2026
View reviewed changes
Comment thread doc/tutorials/interoperability_tutorials/gamut.ipynb
@@ -0,0 +1,809 @@
{

@rahulsavani rahulsavani Jun 23, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Unfortunately, this is not a standard version of Battle of the Sexes (not your fault, Gamut's). The standard version would have by symmetric, but only by swapping players AND actions. However this game in Gamut is unusually actually "symmetric" in the standard game-theoretic sense with payoffs (3,3) for (Opera, Opera) and likewise for (Football, Football). A standard (non-symmetric) version, e.g. , a la Wiki:

https://en.wikipedia.org/wiki/Battle_of_the_sexes_(game_theory)

has the man preferring (Football, Football) to (Opera, Opera) and vice versa for the woman, e.g. with payoffs (3, 2) and (2, 3). We should avoid confusing people.

@tturocy Do you agree?

If so, a simple fix would be to swap out BoS for Chicken, which is symmetric in Gamut and symmetric as standard too.


Reply via ReviewNB

rahulsavani
rahulsavani requested changes Jun 23, 2026
View reviewed changes

@rahulsavani rahulsavani left a comment •
edited
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good apart from the fact Gamut (and thereby we) have used a non-standard version of Battle of the Sexes. We should probably swap it out for, e.g. Chicken. Let's see if @tturocy agrees.

@tturocy

tturocy commented Jun 24, 2026

Copy link
Copy Markdown
Member

Yes, I would agree with using Chicken instead, doesn't require substantial changes to the exposition of the example but users familiar with game theory won't be surprised by the game's payoffs.

rahulsavani
rahulsavani approved these changes Jun 24, 2026
View reviewed changes

@rahulsavani rahulsavani left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good to me.

@edwardchalstrey1
edwardchalstrey1 merged commit aaf5753 into master Jun 24, 2026
26 checks passed
@edwardchalstrey1
edwardchalstrey1 deleted the catalog/910 branch June 24, 2026 14:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@rahulsavani rahulsavani rahulsavani approved these changes
@tturocy tturocy Awaiting requested review from tturocy

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

gambit-16.7.0

Development

Successfully merging this pull request may close these issues.

[Catalog]: Add convenience Python interface for GAMUT [Catalog] 3rd party game libraries inclusion

4 participants

@edwardchalstrey1 @tturocy @wyz2368 @rahulsavani