Metadata-Version: 2.4
Name: pycontrol-gui
Version: 3.0.0a1
Summary: Qt desktop frontend for pycontrol-core.
Author: Karpova Lab contributors
License: GPL-3.0-or-later
Requires-Python: >=3.11
Requires-Dist: pycontrol-core<3.1,>=3.0.0a1
Requires-Dist: pyqtgraph>=0.13.7
Requires-Dist: pyside6>=6.8
Provides-Extra: test
Requires-Dist: pytest-qt>=4.4; extra == 'test'
Requires-Dist: pytest>=8; extra == 'test'
Description-Content-Type: text/markdown

# 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:

```bash
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:

```bash
uv add pycontrol-gui --prerelease allow
```

## Install For Development

Install the sibling core package first:

```bash
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:

```bash
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:

```bash
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:

```python
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:

```bash
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](../rewrite-docs/README.md) - map of everything, with a reading order.
- [Architecture tour](../rewrite-docs/md-viewer.html?doc=ARCHITECTURE-TOUR.md) - learn core and GUI end to end.
- [Why the rewrite](../rewrite-docs/md-viewer.html?doc=WHY-REWRITE.md) - what changed versus pyControl v2 and why.

GUI guides:

- [Architecture, threading, and data flow](docs/architecture.md)
- [Task sharing and sandboxes](docs/task-sharing.md)
- [Task plotter plugins](docs/plot-plugins.md)
- [Task controls](docs/task-controls.md)
- [Extensions in the GUI](docs/extensions.md)
- [Current code review backlog](docs/code-review.md)
- [Shared contributor workflow](../CONTRIBUTING.md)
