Parameter Manager: Types, Locks and a new GUI

[marcosfrenkel]

Adds Types and Locks to the Parameter Manager and rebuilds its GUI around them. Everything works from a Python client and from the Qt GUI, and open GUIs update live when another client changes something.

Why

• Multi-qubit devices repeat the same structure per qubit. Today each copy is edited by hand and drifts apart. Types make the structure explicit and keep the copies complete.
• Shared settings (an LO frequency, a readout bandwidth) are duplicated across qubits. Locks make one parameter authoritative without copying values around.
• Measurement code needs these as well as the GUI, so they are instrument methods first and widgets second.

What's new

Types

A Type is a named shape: relative parameter paths with a default and a unit, plus Nested Types at named submodules (qubit requires a readout at readout). Any submodule carrying that shape with the right units is an Instance. Membership is structural and recomputed on demand, never stored (ADR 0001).

• add_type, remove_type, add_type_parameter, remove_type_parameter, add_nested_type, remove_nested_type, instances_of, types_of, add_instance.
• Adding an entry to a Type writes it into every Instance. add_instance builds a new Instance from the Type's defaults and refuses up front on a unit conflict.

Locks

A Lock makes one parameter (the Follower) read another (its Target). While locked, the Follower answers get with the Target's value and refuses set. Unlocked, it acts as a plain parameter but remembers its Target.

• lock, unlock, relock, toggle_lock, remove_lock, get_lock, list_locks.
• Values are pulled on get; nothing is ever pushed into a Follower (ADR 0002). This lives in a ManagedParameter subclass, so the Server's call path and the instrument mutex are unchanged. Snapshots of a locked Follower report the Target's value, so measurement metadata isn't stale.
• Locks can chain but never cycle. Targets must be in the same Parameter Manager.
• Deleting a Target removes the Locks pointing at it; their Followers become plain parameters.

Type Locks and _globals

lock_type_parameter / unlock_type_parameter declare a Lock on a Type entry, so every Instance follows one Target. By default that Target is a parameter under _globals. _globals is never matched as an Instance.

Broadcasts: the Broadcaster contract

Until now the Server only broadcast what it could see itself: parameter sets, and calls literally named add_parameter / remove_parameter. A new opt-in mixin, Broadcaster (base.py), lets an instrument emit its own Broadcasts. The Server registers itself as a sink when such an instrument joins the Station (ADR 0003). Instruments without the mixin are untouched.

The Parameter Manager is the first Broadcaster. It emits:

• pm-lock-update (payload PMLockBluePrint, or None when a Lock is removed)
• pm-type-update (payload PMTypeBluePrint, or None when a Type is removed)
• parameter-creation for parameters it creates as side effects (Type edits, add_instance, Type Lock declarations)

Wire format, socket and topic are the same as before, so existing subscribers parse these unchanged. Broadcast action names are now constants in blueprints.py.

Profile files: version 2

toFile writes a versioned document (version: 2): a parameters section (each entry holds its own value, its unit and, if it has one, its lock) and a types section. fromFile reads both version 2 and the old unversioned files. Before changing anything it validates the whole document: if Lock or Type Lock Targets are missing, it raises one ValueError listing all of them and leaves the state untouched. Switching profiles now clears Types and Locks too.

GUI

The Parameter Manager GUI moved out of gui/instruments.py into the new gui/parameter_manager/ package (logic.py is Qt-light state and helpers, widget.py and panels.py hold the widgets).

• Parameters tab: rows tinted by their claiming Type, with gutter bands that show Instance boundaries. A "locked to" column with a lock toggle, a context menu, and an arm strip for picking a Target by clicking a row.
• Locks panel (Ctrl+Shift+L): every Lock in one table, with resizable columns.
• Types tab: a list of Types with Instance counts, the selected Type's entries, and its Instances.
• Deleting a parameter that is a Target asks for confirmation first.
• Tints follow the application theme, with a palette for dark themes too.

The generic parameter GUI (gui/parameters.py) gained column and editor hooks, which the Parameter Manager uses.

Smaller fixes along the way

• _newOrDeleteParameterDetection no longer fails on add_parameter calls that omit initial_value or unit.
• The instrumentserver-param-manager launcher passes the broadcast port into the GUI, so its live updates work.
• QLogHandler is a plain logging.Handler now, so closing the app no longer prints "wrapped C/C++ object of type QLogHandler has been deleted". A dead handler also no longer makes the logger skip the handler after it.
• Tests pick free ports per run instead of fixed ones, so parallel runs don't collide.

Docs

• User Guide: docs/user_guide/parameter_manager.md rewritten (Types, Locks, Type Locks and Globals, profiles and files, the GUI, use from measurement code).
• Technical Guide: docs/technical_guide/broadcasts.md covers what triggers a Broadcast, the wire format, the Broadcaster contract, and the Parameter Manager's actions.
• Both pages are verified by scripts under test/docs_verification/ that run every example against a live Server.
• Design records: CONTEXT.md (glossary) and docs/adr/0001–0003.

Compatibility

• Old unversioned profile files still load. Files this branch writes are version 2, which older instrumentserver releases can't read.
• Instruments that don't use Broadcaster behave exactly as before.

Testing

About 10,000 lines of new tests: test_pm_locks.py, test_pm_types.py, test_pm_persistence.py, test_pm_gui.py, test_broadcaster.py, test_log_widget.py.

With QT_QPA_PLATFORM=offscreen and the venv on PATH, the full suite passes (556 tests). Run with the native macOS style, two layout tests in test_pm_gui.py fail because they expect offscreen Qt's layout spacing (the tree-height one and the Locks panel column-resize one). That's a test issue, not a GUI bug.

Reading this PR

It's large (~26k lines added, most of them tests and docs). The history is meant to be read commit by commit: each implementation commit starts with its plan task number (0.1, 1.2, …), and review fixes are separate commits. PLAN_parameter_manager_redesign.md explains each task and records the design decisions; start with the ADRs and CONTEXT.md.

🤖 Generated with Claude Code