feat(trlib): plot API + TOML config runner (reference)

[k-yoshimi]

Summary

Reference implementation of the declarative plot(varname) API and TOML-driven runner described in project_visualization_followup.md and project_toml_sample_runner.md. trlib is the most mature Python wrapper (L-0..L-7 merged) so it lands first; ti / wr / wrx / fp / eq will copy this pattern after their L-7 + MCP work.

What's new

Plot API — python/trlib/plot.py (new)

• plot(varname, *, output, format, path, title, overlay, state) — 1D / species-stacked 2D radial profiles via matplotlib
• plot_sweep(param, y, *, range) — ad-hoc parameter scan
• plot_available() + VARIABLE_INFO registry so callers (humans, MCP, LLMs) can probe support before requesting a figure
• Output modes: window (interactive), file (returns Path), return (returns Figure); _in_notebook() heuristic flips plt.show to non-blocking inside Jupyter
• matplotlib stays an optional dependency — importing trlib.plot raises a clear ImportError when matplotlib is absent; trlib itself remains importable

Trlib instance methods

• Trlib.plot(varname, **kwargs) — captures state internally and forwards to trlib.plot.plot
• Trlib.plot_available() — staticmethod so callers can probe without instantiating (no libtrapi.so load required)

TOML config loader — python/trlib/loader.py (new)

• load_config(path_or_stream) returns {module, scalars, arrays, strings, plots, raw}; accepts pathlib.Path, str, bytes, or any file-like
• apply_config(tr, cfg) replays strings -> scalars -> arrays in the order the existing tests/fixtures/*.py::apply helpers use
• run_plots(tr, cfg) executes every [plot] / [[plots]] spec; supports kind = "sweep" entries
• Uses stdlib tomllib (3.11+) with tomli fallback

CLI entry — python/trlib/__main__.py (new)

python -m trlib python/trlib/samples/iter01.toml          # full run + plots
python -m trlib python/trlib/samples/iter01.toml --dry-run  # parse only
python -m trlib python/trlib/samples/tst2.toml --ntmax 5    # NTMAX override
python -m trlib python/trlib/samples/iter01.toml --no-plots # skip matplotlib

Exit codes: 0 success, 1 library/calc error, 2 config error.

TOML samples — python/trlib/samples/

• iter01.toml — mirror of test_run/inputs/tr_iter01.in (4 species, NTMAX=100)
• tst2.toml — mirror of test_run/inputs/tr_tst2.in (uses sparse PA = { 2 = 1.0 } form)

Tests

• test_plot.py (10 tests, skip if matplotlib absent) — VARIABLE_INFO schema, plot_available ordering, all 3 output modes round-trip with hand-built TrState
• test_loader.py (10 tests, no .so needed) — inline string / bytes / Path / BytesIO inputs, singular [plot] table, [module].ntmax alias, error paths
• test_main.py (8 tests) — --help / --dry-run / --ntmax / --no-plots smoke; library-dependent test gated on libtrapi.so

Run: python3 -m unittest discover python/trlib/tests -> 56 tests, 14 skipped (lib-dependent), 0 failures.

Docs

README gains TOML schema + plot section in です・ます調 with sample invocations.

Reference pattern for other modules

When ti / wr / wrx / fp / eq follow:

1. Copy plot.py → adjust VARIABLE_INFO for that module's state schema
2. Copy loader.py verbatim (schema is module-agnostic) and tweak the apply_config ordering if needed
3. Copy __main__.py, swap the Trlib import
4. Add samples/*.toml mirroring test_run/inputs/*.in
5. Mirror the three test files

Hard constraints honoured

• No Fortran / Makefile / other Python lib changes
• No core trlib.py field changes beyond .plot() / .plot_available()
• matplotlib remains optional; --no-plots works without it
• No --admin / no self-merge

Test plan

• CI: python3 -m unittest discover python/trlib/tests — all pass / skip cleanly
• python -m trlib --help prints usage
• python -m trlib python/trlib/samples/iter01.toml --dry-run exits 0
• When libtrapi.so present: full run produces plots under ./plots/

---

Note

Medium Risk
Adds a new CLI entrypoint and optional matplotlib plotting layer, plus configuration parsing that can affect how simulations are parameterized and executed. Risk is moderated by --dry-run/library gating and unit tests, but it touches execution flow and introduces new user-facing I/O paths.

Overview
Adds a TOML-driven python -m trlib runner that loads a config, applies scalars/arrays/strings, runs the simulation, and optionally generates plots, with --dry-run, --ntmax overrides, --no-plots, and defined exit codes.

Introduces a matplotlib-backed plotting module (trlib.plot) with a VARIABLE_INFO registry, plot() output modes (window/file/return), and plot_sweep() for parameter scans, and wires it into Trlib via new Trlib.plot() and Trlib.plot_available() helpers.

Ships sample configs (iter01.toml, tst2.toml), expands README with TOML/plot documentation, and adds unit tests covering TOML parsing/application, CLI smoke paths, and plotting (skipped when matplotlib or libtrapi.so are unavailable).

^{Reviewed by Cursor Bugbot for commit 6a9de89. Bugbot is set up for automated code reviews on this repo. Configure here.}

[k-yoshimi]

@cursor review

[k-yoshimi]

@cursor review

[k-yoshimi]

@cursor review

[k-yoshimi]

@cursor review

[k-yoshimi]

@cursor review

[k-yoshimi]

@cursor review

[k-yoshimi]

@cursor review

[k-yoshimi]

@cursor review

[k-yoshimi]

@cursor review

[k-yoshimi]

@cursor review

[k-yoshimi]

@cursor review

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit d5442fd. Configure here.}

[cursor]

Heuristic misclassifies long file paths as inline TOML

Low Severity

The _looks_like_toml heuristic treats any string containing = and longer than 40 characters as inline TOML content rather than a file path. A legitimate file path like /home/user/configs/long_project_name_config/param=default.toml would match the condition "=" in text and len(text) > 40, causing _loads() to attempt TOML parsing of the path string itself. This produces a confusing TOMLDecodeError instead of loading the intended file. The os.PathLike branch is unaffected (only str/bytes inputs hit this heuristic).

 

^{Reviewed by Cursor Bugbot for commit d5442fd. Configure here.}

[cursor]

Unnecessary state copy when all plots are sweeps

Low Severity

run_plots unconditionally calls tr.get_state() before iterating over plot specs, even when every spec has kind == "sweep" and will be skipped. The state copy involves marshalling Fortran arrays through ctypes. Moving the tr.get_state() call to just before the first non-sweep spec is actually used would avoid the unnecessary work in sweep-only configurations.

 

^{Reviewed by Cursor Bugbot for commit d5442fd. Configure here.}