cfd-solver-gui — Developer Onboarding

cfd-solver-gui is a PySide6 desktop frontend for the companion Fortran solver in ../cfd-solver. The GUI does not link against solver code directly: it writes a Fortran namelist, launches the solver as an external process, and reads back snapshot.dat / result.dat style outputs.

Keep these boundaries in mind from day one:

• src/cfd_gui/namelist_io.py is the GUI-side source of truth for solver parameters.
• The solver CLI contract is fixed: the GUI launches the solver with one positional argument, the path to a .nml file.
• Output files are a shared contract with the solver repo, not GUI-private implementation details.

If you touch namelist keys, scheme names, solver CLI behavior, or output-file formats, inspect the matching code in ../cfd-solver before you finalize the change.

Install the GUI in editable mode with the contributor toolchain:

pip install -e '.[dev]'
pre-commit install

Run the app:

cfd-gui
# or
python -m cfd_gui

Run the main validation commands:

pytest
pytest -m "not qt"
ruff check src/
mypy src/
mkdocs build --strict

The docs build expects emacs to be available on your PATH so the Org files can be exported during the MkDocs build.

If the solver binary is not already on your PATH, build it from ../cfd-solver and then point the GUI at the resulting euler_1d executable through Solver → Set Solver Binary….

For live docs preview during writing, use:

mkdocs serve

There are three ideas worth memorizing early:

1. Schema-driven UI. The parameter editor is generated from SCHEMA in src/cfd_gui/namelist_io.py. Most parameter work starts there, not in widget code.
2. The solver is a subprocess. The GUI launches it through Qt process plumbing and reacts to structured events instead of embedding solver logic directly.
3. Files are the contract. input.nml, snapshot.dat, result.dat, run_manifest.json, and events.jsonl form the durable boundary between the GUI and the compute run.

When a bug feels “UI-ish,” first ask which layer actually owns the behavior: schema, process control, file parsing, plotting, or the solver itself.

• src/cfd_gui/namelist_io.py — parameter schema, namelist parsing/writing
• src/cfd_gui/config_editor.py — schema-driven widget generation
• src/cfd_gui/main_window.py — main window actions, run flow, status/log UI
• src/cfd_gui/run_manager.py — durable run directory and worker orchestration
• src/cfd_gui/run_worker.py — worker-side solver launch and event stream
• src/cfd_gui/snapshot_monitor.py — snapshot parsing and live-update logic
• src/cfd_gui/settings.py — solver binary discovery and persistent settings
• tests/ — behavior contracts and regression coverage

For the GUI-heavy modules, start with the developer guide's architecture sections before reading class-by-class code.

• README.md — lean first-contact page: quick orientation, minimal install/run commands, and links to the real manuals
• doc/onboarding.org — this contributor starting point
• doc/developer-guide.org — authoritative maintainer manual: architecture, module responsibilities, and change recipes
• doc/user-guide.org — authoritative end-user manual: install, run, and UI behavior
• AGENT_GUIDE.md — canonical contributor and agent workflow rules, documentation-maintenance policy, and validation commands

Treat the Org files in doc/ as the canonical narrative docs. Keep README.md short and update it only when the first-contact quickstart needs to change. The generated MkDocs site is derived output for browsing and API reference, not a second place to maintain the same prose by hand.

• Schema coupling: adding or renaming a solver parameter means updating both the GUI schema and the matching solver-side contract.
• CLI assumptions: do not change how the GUI launches the solver without coordinating the GUI and ../cfd-solver together.
• Output-format drift: parser changes for snapshot.dat / result.dat must stay aligned with the solver's actual file format.
• Qt test split: pure-Python tests and @pytest.mark.qt tests serve different purposes; use both tiers appropriately.
• Narrative docs vs. summaries: update the Org sources first, then trim or relink README.md if the change affects first-contact guidance. Do not hand-edit derived site output.

When in doubt, read AGENT_GUIDE.md first, then confirm the current behavior in tests before changing the implementation.