Add easy way to visualise game trees in PyGambit

[edwardchalstrey1]

This feature request is for...

PyGambit

Requested enahancement or feature

When working on #542 I noticed there doesn't seem to be a way to display the Game trees for extensive form games with Python.

For normal form games, after you have set up a game with Game.new_table and then added payoffs, there is a nice feature in a Jupyter notebook where running a cell with the pygambit.gambit.Game object displays the payout matrix pandas-style:

It would be very useful for the tutorials and in general to be able to quickly view the shape of your extensive form Game object set up with Game.new_tree with a display function, which could similarly get triggered when just running a cell with the game object. You could see the tree grow as you add nodes.

Relatedly, in the current user guide, calling g.root.children doesn't show anything different when you append a move see user guide where code output doesn't change. But if doing so called the display function, it would be clearer what has changed.

Implementation

It might make sense to use an existing library, perhaps we could convert a Gambit game to NetworkX to make use of that plotting functionality.

Drawbacks

I guess this may end up being quite a big task as it could entail re-implementing a lot of the visualisation features already present in the GUI. That being said, I can imagine this would be very handy especially for viewing large extensive form games with modern Python plotting libraries.

@tturocy @rahulsavani @d-kad Is this something you have already discussed, or did I miss a way to do this that already exists? For me, when learning the PyGambit API in a notebook context exploring setting up a game, it feels difficult not being able to see the tree I'm building as I go

[edwardchalstrey1]

Implementation

Bernhard Von-Stengel's code (drawTree)

Edit: now available at: https://github.com/gambitproject/draw_tree

drawTree draws a tree as a TikZ file from an .ef file. Steps needed to integrate this code (drawtree.py) as a Gambit extensive form game visualisation, with the game layout code steps above as pre-requisite:

draw_tree

• Add as a new repo under gambitproject
• Package the code in a way that can be imported by Gambit
  • Add tests, documentation etc
  • Tests should cover a variety of games
  • Ensure "macros-drawtree.tex" relative path does not need to be passed in, when using Jupyter
• Ensure draw_tree func can output all of the following:
  • .png
  • Document .png specific requirments
  • .pdf (but use the function in the main code)
  • tikz_code for use in Latex/Jupyter
  • Document all of these
  • Can you copy tikz into any latex doc? At the moment it lacks the q.tex formatting so need to refactor to include this
• Document how to use the Python functions as well as CLI
• Add GH actions

On a Gambit branch

Open a branch on Gambit that installs draw_tree and uses it to draw a Gambit object, then can make it a requirement and use the Game object show() Update: attempted this and kernel kept crashing, might be better to just keep draw_tree separate and import it in tutorial notebooks - related draw_tree issues:

• Check for LaTeX installation draw_tree#13
• Add to PyPI draw_tree#15
• Update tutorials to use draw_tree
• Ensure that .readthedocs.yml build includes installing draw_tree (already installs doc/requirements.txt)
• Ensure that .readthedocs.yml build includes installing LaTeX
  • Will try with texlive-full, however if this proves too much, investigate the min requirements for Ubuntu and update here: https://github.com/gambitproject/draw_tree?tab=readme-ov-file#installing-latex

Game Layout code

draw_tree has a default layout, but can also adapt the following:

• GTE Layout code: https://github.com/Martin-Antonov/GTE-ng/blob/master/src/app/gte-core/gte/src/View/TreeView.ts
• Gambit (GUI) Layout code
  • Create a function that creates a Layout from a Gambit game object structure
    • This might involve somehow extracting the layout code defined in src/gui/dlefglayout.cc to Python - see here
    • Ted still doing a bit more on this to expose the layout structure to Python

Issues to open:

• pyproject.toml does not pin versions for numpy and scipy dependecies, whereas in doc/requirements.txt these are pinned