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 in the main process: it writes a Fortran namelist, starts a local Python worker, and has that worker drive the solver through the shared library/session ABI while keeping durable run artifacts on disk.

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 shared-library contract is fixed: the worker loads the solver library, points it at input.nml, and emits structured run events back to the GUI.
• Output files are a shared contract with the solver repo, not GUI-private implementation details.

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

Create or update the project-local contributor environment:

uv python install
uv sync
uv run pre-commit install

uv manages a repo-local .venv/ next to pyproject.toml. If you prefer an activated shell for repeated commands, run:

source .venv/bin/activate

Run the app:

uv run cfd-gui
# or
uv run python -m cfd_gui

Run the main validation commands:

uv run pytest
uv run pytest -m "not qt"
uv run ruff check src/
uv run mypy src/
uv run 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 Qt-marked tests crash in a local headless session, retry with QT_QPA_PLATFORM=offscreen uv run pytest. We observed that macOS can require the explicit Qt platform override even though Linux CI does not.

If the solver shared library is not already discoverable, build it from ../cfd-solver (typically via make shared-lib, which writes the default release bundle) and then point the GUI at the resulting libcfd_solver.dylib / libcfd_solver.so / cfd_solver.dll through Solver → Set Solver Library….

For live docs preview during writing, use:

uv run 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 lives behind a worker boundary. The GUI talks to a local worker process through Qt, and that worker drives the shared library.
3. Files plus structured events are the contract. input.nml, result.dat, checkpoints, run_manifest.json, and events.jsonl remain durable artifacts; live plot frames arrive as transient worker events.

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 ABI polling loop and event stream
• src/cfd_gui/snapshot_monitor.py — compatibility parser for manual snapshot.dat / result.dat loading
• src/cfd_gui/settings.py — solver library 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.
• ABI assumptions: do not change how the worker loads or drives the solver library 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.