ENH: Implement NFGReader and NFGWriter

[oyamad]

• This PR adds a reader and a writer for the Gambit .nfg file format, based on its public documentation.
• The original code was written long time ago when I was reading Peter Norvig, "(How to Write a (Lisp) Interpreter (in Python))" and wanted to try my understanding with a concrete example, which was an .nfg interpreter. This one is a revised version generated by Claude Code Fable 5.1.

Detailed description by Claude Code follows:

---

Summary

Adds from_nfg, from_nfg_string, from_nfg_url, and to_nfg, which read and write normal form games in the Gambit .nfg format, alongside the existing .gam functions. The reader handles both versions of the format, the payoff version (a flat list of payoffs, player 1 varying fastest) and the outcome version (a table of named outcomes followed by one outcome index per action profile, with index 0 meaning zero payoffs). The title, the names of the players, actions, and outcomes, and the comment are read and ignored. The writer emits the payoff version with an empty title and players named "1", ..., "N".

Changes, by commit

• PayoffVector replaces GAMPayoffVector as the intermediate representation between a NormalFormGame and a flat list of payoffs. It carries a layout argument, 'player-major' (the .gam order: all payoffs to player 0, then player 1, ...) or 'profile-major' (the .nfg order: the N payoffs at the first action profile, then the second, ...), with from_normal_form_game, to_normal_form_game, and to_layout to convert between them. GAMPayoffVector was never exported, so this is not a breaking change.
• Reader and writer entry points factored out into _Reader (from_file, from_url, from_string) and _Writer (to_file, to_string) base classes; each format implements only _parse and _dump. The .gam classes now use them.
• NFGReader. A regular-expression tokenizer (quoted strings with \" escapes, braces, bare tokens; commas are separators), then a recursive-descent reader that turns the token stream into nested lists by the braces alone, in the manner of a Lisp reader, and finally interpretation of the nested lists by position. The version is detected from the first token after the prologue. Numbers are parsed as int when written as integers and as float otherwise; a rational such as 1/3 is converted to the nearest float through fractions.Fraction.
• NFGWriter and the module-level to_nfg(g, file_path=None), which writes to a file or returns the text. Floats are written with numpy.format_float_positional, so no digits are lost.
• Fix: a file in the outcome version with an empty outcome list, where every profile has the null outcome, is read correctly.
• Tests: the overflow test of PayoffVector now fails if the overflow check regresses; the fixture comment names the null-outcome profile in a way that is correct in both 0-based and 1-based conventions.
• Docs: the module docstring lists the eight public functions. The API page is generated by qe_apidoc.py without :inherited-members:, so the reader and writer class pages show their docstrings only; the inherited from_file/from_url/from_string/to_file/to_string methods are not rendered.

Validation policy

Validation is minimal by design: these files are almost always written by programs, so the reader checks what it needs to build the game and does not try to catch every malformed input. Payoff and index counts that do not match the declared numbers of actions raise an error; names and comments are not validated.

Implementation approach

The reader is organized in the textbook way: a lexer, a parser, and an interpreter. What characterizes it is the parser, which is the classic S-expression reader, the read of every Lisp, applied to a bracket language with braces in place of parentheses.

• Lexer. One regular expression, _NFG_TOKEN, cuts the text into quoted strings (with \" escapes), braces, and bare tokens; whitespace and commas are separators and are dropped.

• Parser. _read_from_tokens(tokens, pos) is a recursive-descent parser for the one-rule grammar of nested brackets,

  item := token | "{" item* "}"
  

  It returns the item starting at pos, either the token itself or a nested list built by calling itself up to the matching }, together with the position after it. The grammar has a single self-referential rule, so recursive descent collapses to this one function, which knows nothing of .nfg beyond the two braces and turns the whole file into a generic tree of nested lists. It is Norvig's read_from_tokens, with an index in place of pop(0), so that parsing is linear rather than quadratic in the file size, and with an outer pair of braces so that the file reads as one list.

• Interpreter. NFGReader._parse gives the generic tree its meaning by position: the prologue items, the players, the action counts, an optional comment, then the body, whose first item, a { or a number, distinguishes the outcome version from the payoff version. Numbers go through _str2num, outcome indices through the outcome table, and the result is a profile-major PayoffVector.

This is Lisp's read/eval split: the parser parses only the brackets, and all knowledge of the format sits in the interpreter. A parser written for .nfg directly would have one rule per part of the file and would catch structural errors as it met them; the Lisp-reader approach has a ten-line, format-agnostic parser and catches those errors late or, under the minimal-validation policy above, not at all. Since the parts of an .nfg file are recognized by position, the shorter approach suffices.

Tests

33 tests in test_game_converters.py: PayoffVector in both layouts, round trips through the layouts, the .gam tests, and for .nfg the payoff and outcome versions, the null-only outcome file, string and file round trips, cross-format round trips with .gam, invalid inputs, and the shared fixtures.

🤖 Generated with Claude Code (Claude Fable 5.1)

[coveralls]

coverage: 94.076% (+0.08%) from 94.0% — payoff-vector into main

[Copilot]

Copilot review overview

🟡 Changes recommended

Negative outcome indices are silently misinterpreted, and inherited converter methods would disappear from generated API documentation.

Review effort: Balanced
Findings: 1 · 1

Open (2)

• Reject negative outcome IDs before NumPy table indexing · New
• Enable inherited members in game converter API documentation · New

What changed in this PR

Adds Gambit .nfg import/export support alongside existing .gam conversion.

Changes:

• Introduces layout-aware PayoffVector and shared reader/writer bases.
• Adds and exports NFG readers, writers, and convenience functions.
• Adds fixtures and comprehensive conversion tests.

File	Description
quantecon/​game_theory/​game_converters.py	Implements shared conversion infrastructure and NFG support.
quantecon/​game_theory/​__init__.py	Exports the new NFG APIs.
quantecon/​game_theory/​tests/​test_game_converters.py	Tests layouts, parsing, writing, and round trips.
quantecon/​game_theory/​tests/​game_files/​3x2_payoff.nfg	Adds a payoff-format fixture.
quantecon/​game_theory/​tests/​game_files/​3x2_outcome.nfg	Adds an outcome-format fixture.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[mmcky]

Approved. CI is green, the branch merges cleanly onto main (also with #979 stacked on top), and the .nfg reader and writer check out against the Gambit format documentation. The internal GAMPayoffVector rename is safe, since nothing outside its own tests referenced it. Merging.