pycontrol-gui 3.0.0a1

Qt desktop frontend for pycontrol-core.

pycontrol-gui

pycontrol-gui is the Qt desktop frontend for pycontrol-core.

It provides the main pyControl operator workflows:

• Run one task on one setup.
• Edit and run multi-subject experiments.
• Manage setup names, ports, auto-detected MCU cache, and setup variables.
• View live logs and plots.
• Use workspace task extensions, experiment extensions, task plotters, task controls, and extension settings.

Install From PyPI Alpha

For the 3.0.0a1 alpha, pin the prerelease:

uv add "pycontrol-gui==3.0.0a1"
# or
pip install --pre "pycontrol-gui==3.0.0a1"

To accept the newest available alpha with uv, use:

uv add pycontrol-gui --prerelease allow

Install For Development

Install the sibling core package first:

cd ../pycontrol-core
pip install -e ".[test,lint]"

cd ../pycontrol-gui
pip install -e ".[test]"

With uv, pycontrol-gui/pyproject.toml points pycontrol-core at the sibling ../pycontrol-core path.

Run the app:

pycontrol-gui
pycontrol-gui /path/to/workspace
# or
python -m pycontrol_gui
python -m pycontrol_gui /path/to/workspace

Run tests with Python's module form so stale local script shebangs do not get in the way:

uv run python -m pytest

Workspaces

Open a workspace with Workspace -> Open Workspace..., create one with Workspace -> New Workspace..., or pass a workspace path on the command line. If no path is supplied, the GUI uses the last-opened workspace from application preferences, then falls back to discovering a workspace from the current working directory. Use Workspace -> Reload workspace to refresh selectors after external file changes.

The GUI uses the standard pycontrol-core workspace layout:

Path	GUI use
tasks/	Task selector in Run task and Experiments.
hardware_definitions/	Hardware-definition selector and setup validation.
devices/	Workspace-local device drivers for task sharing and setup maintenance.
plugins/task_extensions/	Host-side task automation.
plugins/experiment_extensions/	Whole-experiment automation.
plugins/task_plotters/	Custom live plot widgets.
plugins/task_controls/	Declarative or Python task-control panels.
experiments/*.json	Experiment editor and run view.
settings.json / setups.json	Workspace settings and setup registry.

Workspace settings.json includes the default data directory plus GUI settings such as startup tab, plot update frequency, font sizes, and whether task controls are mounted by default. Relative data paths are resolved against the workspace root, and users can still override the data directory for an individual run. GUI application preferences (QSettings) store process-local state such as the selected workspace root, splitter layouts, and update-check timestamps.

Run Task

The Run task tab connects to one setup, uploads an optional hardware definition, loads a task, starts/stops a session, writes data through core loggers, and routes board events into logs, controls, and plots.

The live log view supports filtering and autoscroll, and task extensions can publish status snapshots with TaskExtension.update_status(...) for the Run task and experiment status panels.

Task files can select optional GUI helpers:

v.task_extension = "sequence"
v.task_plotter = "SequencePlotter"
v.task_controls = "reward_panel"

If a helper is missing or fails to load, the task can still run with the default plotter and no custom controls.

Experiments

The Experiments tab edits experiment JSON files and creates one subject panel per active subject/setup assignment. Each subject panel owns its own SessionRuntime, SessionController, QThread, QtBusAdapter, logger, controls, and plot widget so one rig's failure does not directly own another rig's state.

Experiments can also select an optional hardware-test task. When enabled, the run view uploads and runs that task for each subject before preparing the main experiment task.

Active Run task sessions lock the Experiments and Setups tabs; active experiment runs lock Run task and Setups so one workflow owns the shared application runtime at a time.

The Qt experiment editor exposes hardware definitions as first-class fields. For tasks that import hardware_definition, the editor shows a hardware-definition selector (saved to the experiment's hardware_definition field) and the subjects table previews the effective hwdef per subject. The effective hwdef is the experiment override, else the setup's hardware_definition default. Run task offers the same selector, and Setups store a default hwdef per setup.

Plugins And Trusted Code

Workspace plugins are trusted Python and execute in the GUI process.

• Task plotters live in plugins/task_plotters/ and subclass pycontrol_gui.plotting.TaskPlotter.
• Task controls live in plugins/task_controls/ and can be declarative JSON or custom Python widgets exporting build_controls(parent, context). The GUI renders JSON specs with TaskControlsPanel and embeds Python widgets directly.
• Task and experiment extensions are loaded through pycontrol-core.
• SETTINGS declarations for task extensions, experiment extensions, and task plotters are edited in the GUI Settings dialog and saved under settings.extensions.*. Task controls are configured through task variables or declarative control defaults instead.
• The Settings dialog shows a configurable-file page for built-in plotting defaults and each plugin file with valid SETTINGS. Each page has a Use defaults button that resets only that file's settings before saving.

Secret settings are masked in the GUI but still saved in settings.json.

Plotting Diagnostics

The workspace GUI.plot_update_frequency_hz setting controls live plot redraws; new workspaces default to 35 Hz. Plot data ingestion still happens through the session event stream, so lowering the redraw rate reduces GUI paint work without dropping incoming events.

For hardware performance checks, launch with plot profiling enabled:

PYCONTROL_PLOT_PROFILE=1 pycontrol-gui /path/to/workspace

Set PYCONTROL_PLOT_PROFILE_INTERVAL_S to change the reporting interval. The GUI logs [plot-profile] lines with call counts plus average and maximum latency for process_batch() and update_plot() spans.

Import Stability

The supported import surfaces are:

• pycontrol_gui.plotting
• pycontrol_gui.error_logging
• pycontrol_gui.resources

Widgets, controllers, and workspace models are application internals. Tests may import them, but downstream code should not treat them as stable.

Error Logging

pycontrol-gui writes host-side diagnostics to a rotating ErrorLog.txt file:

1. <workspace root>/ErrorLog.txt
2. ~/.pycontrol-gui/logs/ErrorLog.txt
3. ./ErrorLog.txt

Open View -> Error log (Ctrl+E) to inspect or clear the current log. Run/session .tsv files are separate and remain in the experiment data directory.

Documentation

New to the project? Start with the repo-level guides:

• Documentation index - map of everything, with a reading order.
• Architecture tour - learn core and GUI end to end.
• Why the rewrite - what changed versus pyControl v2 and why.

GUI guides:

• Architecture, threading, and data flow
• Task sharing and sandboxes
• Task plotter plugins
• Task controls
• Extensions in the GUI
• Current code review backlog
• Shared contributor workflow