pycontrol-gui 3.0.0a9

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

pyControl is installed once per machine as a global app. For a first install plus a new workspace, prefer the uvx bootstrapper:

uvx --prerelease allow pycontrol-init my-workspace --launch

Or install the app directly (allowing prereleases for the current alpha):

uv tool install --prerelease allow --with-executables-from pycontrol-core pycontrol-gui
# or, in an existing Python environment
pip install --pre pycontrol-gui

Upgrade with uv tool upgrade pycontrol-gui (or re-run uvx --prerelease allow pycontrol-init --update-gui while alphas need prerelease resolution).

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 the compatibility entry point
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

See maintainability.md for the standard-GUI adoption target and the current GUI simplification hotspots.

Workspaces

Workspaces are plain data folders; the app is installed once and switches between them. Open a workspace with Workspace -> Open Workspace..., create one with Workspace -> New Workspace..., or pass a workspace path on the command line. An explicit command-line path takes precedence, then a workspace discovered from the current working directory, then the last-used workspace from application preferences. On first run, with no remembered workspace, a welcome dialog offers to open or create one. pycontrol-gui --set-workspace PATH records the workspace to open on next launch without starting the GUI. 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.

An active Run task run (RUNNING) locks the Experiments and Setups tabs. An open experiment run view locks Run task and Setups so one workflow owns the shared application state 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.

Task Sharing And Sandboxes

The Run task tab can export a selected task and its workspace-local dependencies as a protocol bundle ZIP. Workspace -> Enter sandbox... opens a sandbox manager that can create an isolated workspace from a shared ZIP, run it against local setups, and return to the parent workspace with a visible sandbox banner. See task-sharing.md.

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.
• Data-flow walkthrough - one packet's journey through the pipeline.

GUI guides:

• Architecture, threading, and data flow
• Task sharing and sandboxes
• Task plotter plugins
• Task controls
• Extensions in the GUI
• Maintainability notes
• Shared contributor workflow