Interface to Gamut

[edwardchalstrey1]

Issues closed by this PR

• Closes [Catalog]: Add convenience Python interface for GAMUT #910
• Closes [Catalog] 3rd party game libraries inclusion #760 (SageMath to be handled later)

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]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[edwardchalstrey1]

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

Reply via ReviewNB

[tturocy]

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]

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]

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]

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

[edwardchalstrey1]

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]

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

[edwardchalstrey1]

Thanks @wyz2368 !