# The Experiments tab

The tab in front when the console opens. One row per **run** — one
measurement, in a folder of its own — and below it the selected run: its
buttons and four panes. How to take an experiment from installed to measured
is [Run an experiment](../usage/experiment.md).

```{figure} ../imgs/gui/window-experiments.png
:width: 100%
:alt: The Experiments tab: the Runs card with three runs of pol-pl — running, completed and created — and the completed run's card below it.

The **Experiments** tab, with a completed run selected.
```

## The Runs card

![The Runs card](../imgs/gui/runs-card.png){width="100%"}

| Column | Shows |
|---|---|
| **Run** | The run's name — also the name of its folder. |
| **Experiment** | The experiment it belongs to. |
| **Source** | The module version it runs. |
| **State** | `never run`, `created` (named, not started), `running`, `paused`, `completed`, `stopped` or `aborted`. A run whose job died before it could write its end — killed from the task manager, a crash — reads `aborted`, and the devices it started are stopped, so it can be resumed or deleted. |
| **Progress** | Steps done of the plan's total — `5/12 steps` — and what the step in flight last reported. |
| **Started**, **Ended** | When, as `YY-MM-DD,HH:MM:SS` in local time. |
| **Operator** | Who measures it, as entered in *Create run*. |
| **Note** | The first line of the run's latest note — see *Experiment ▸ [Add note…](menus.md#add-note)*. |

An experiment with no run yet has a row of its own. Double-click a row to
[configure](#configure) it.

| Button | Icon | Does |
|---|---|---|
| **Create** | ![Create](../imgs/gui/btn-exp-create.png){width=39px} | Name a new run and choose its configuration, without starting it — see [below](#create-run). |
| **Duplicate** | ![Duplicate](../imgs/gui/btn-exp-duplicate.png){width=39px} | A new run repeating the selected one, with the settings it used. |
| **Load** | ![Load](../imgs/gui/btn-exp-load.png){width=39px} | Show a run measured elsewhere, from its folder. Nothing is copied. |

### Create run

**Create** ![Create](../imgs/gui/btn-exp-create.png){height=22px} opens **Create run**.
The run is created, not started: **Run** ![Run](../imgs/gui/btn-experiment-run.png){height=22px}
starts it.

```{image} ../imgs/gui/dialog-create-run.png
:width: 640px
:alt: The Create run dialog
```

| Field | Means |
|---|---|
| **Experiment** | A declared experiment, an installed one not yet declared (it is declared for you), or a folder loaded with *Hub ▸ Load from…*, shown as `name (local)`. |
| **Experiment name**, **Repository**, **Ref** | The experiment's declaration. |
| **Config** | The configuration file the run starts from. It is copied into the run's folder, so changing it later changes nothing for this run. |
| **Arguments** | Extra arguments for the experiment module. |
| **Run name** | The run's name, and its folder's. Letters, digits, `.`, `-` and `_`; a name an earlier run had is refused. It can still be changed in [Configure](#configure) until the run starts. |
| **Operator** | Who measures it. Required; proposed from the last run created on this bench. Kept in the run's folder (`created.json`) and shown in the **Operator** column. |
| **Note** | Why: the sample, what is being tried. Optional. It is the first entry of the run's `notes.txt`; *Experiment ▸ Add note…* adds more while the run is open and after it has ended, and the **Note** column shows the latest. |

## The run card

![The card of the selected run](../imgs/gui/run-report.png){width="100%"}

The title names the experiment and the run — and, after *Pause* or *Stop*,
that the request is waiting for the step in flight to finish.

| Button | Icon | Does | Available when |
|---|---|---|---|
| **Run** | ![Run](../imgs/gui/btn-experiment-run.png){width=39px} | Start the run (Ctrl+Shift+R) — see [below](#starting-a-run). On a stopped or aborted run it reads **Resume** and continues, skipping the steps already done. | the run is not going |
| **Pause** | ![Pause](../imgs/gui/btn-experiment-pause.png){width=39px} | Hold before the next step, keeping the instruments connected and where they are. Reads **Continue** while paused. | the run is going |
| **Stop** | ![Stop](../imgs/gui/btn-experiment-stop.png){width=39px} | Let the step in flight finish, then stop. Nothing is lost. | the run is going |
| **Abort** | ![Abort](../imgs/gui/btn-experiment-abort.png){width=39px} | Stop now. The unfinished step runs again on *Resume*. | the run is going |
| **Configure** | ![Configure](../imgs/gui/btn-experiment-configure.png){width=39px} | This run's settings and the experiment's device setup — see [below](#configure). | a run of this bench is selected |
| **Install** | ![Install](../imgs/gui/btn-experiment-install.png){width=39px} | Install the experiment module, as a job. | same |
| **Update** | ![Update](../imgs/gui/btn-experiment-update.png){width=39px} | Pull and reinstall the experiment module, as a job. | same |
| **Open run** | ![Open run](../imgs/gui/btn-experiment-open.png){width=39px} | Open the run's folder in the file manager. | the run has a folder |
| **Delete run** | ![Delete run](../imgs/gui/btn-experiment-remove.png){width=39px} | Delete the run and its data, after a confirmation. For a loaded run it only stops showing it. | the run is not going |

*Pause*, *Stop* and *Abort* all wait for a **step boundary** — a step either
commits whole or not at all — so a request made during a long exposure is
pending, not ignored.

### Starting a run

**Run** ![Run](../imgs/gui/btn-experiment-run.png){height=22px} first opens each
instrument the experiment needs, on its bench — seconds of hardware per
instrument — and a small window names the one being opened. Closing that
window stops nothing: the run starts either way, and the Devices tab shows
what each instrument is doing. What happens in those seconds is
[What Run does](../usage/experiment.md#what-run-does).

### Configure

**Configure** ![Configure](../imgs/gui/btn-experiment-configure.png){height=22px}, *Experiment ▸
Configure…*, or a double-click on a run opens its configuration. Two tabs;
**Save** writes both.

Above the tabs, a run's **Run name**: change it before the run starts and its
folder, its configuration and a duplicate of it follow the new name. A name
an earlier run had is refused, and a name that is refused leaves the run as it
was. A started run keeps its name.

**Experiment Config** — the settings the experiment module declares, as a
form: a box per group, a spin box with its unit for a number, a drop-down for
a choice, rows with **+** and **−** for a list. Grey text in an empty field is
the default. **Config file** switches between the module's configuration
files; **Edit YAML…** opens the file itself.

```{image} ../imgs/gui/dialog-configure.png
:width: 760px
:alt: The Experiment Config tab: a config file picker, a General group and a scan group with angle, points and exposure fields
```

Which file it edits depends on what is selected:

- a **created run** — that run's own copy, and nothing else;
- a run that has **started** — shown read-only: its plan was built from it.
  **Duplicate** ![Duplicate](../imgs/gui/btn-exp-duplicate.png){height=22px} the run to
  measure again with changes;
- an experiment with **no run** — this bench's own copy of the file
  (`<home>/run/<experiment>/config/…`), which new runs start from. The
  module's files are never written: they change only through its repository.

**Save** changes only the values you edited, each on its own line, so the
file's comments and layout stay as they were.

**Device Setup** — the benches the experiment runs across and the devices on
each. What it means is in [Run an experiment](../usage/experiment.md#the-benches-and-the-shared-disk).

```{image} ../imgs/gui/dialog-configure-tab2.png
:width: 760px
:alt: The Device Setup tab: a Benches table with name, address, token and shared data, and a group per device
```

- **Benches** — a row per bench: **Name**, **Address** of its agent,
  **Token**, and **Shared data** — where that bench sees the lab's shared
  disk. The first row is the machine the experiment runs on. **Add** and
  **Remove** change the list; hovering a cell shows the variable its value is
  saved under.
- A group per **device**: **Package**, **Host** (which bench runs it),
  **Repository**, **Ref**, **Version**, **Arguments**, **Autostart** and
  **Environment**.

## The panes

A run that has not started has nothing in any pane yet.

### Log

![The Log pane of a run](../imgs/gui/run-log.png){width="100%"}

The output of the run's job on this bench. When this bench has no job for the
run — it was measured on another bench, or an uninstall emptied this one's
home — the pane shows the copy the run kept in its `job-logs/` folder.

### Data

![The Data pane](../imgs/gui/run-data.png){width="100%"}

The last 50 records the run has committed, one row per step; open a row to
see its values. ![Expand all](../imgs/gui/btn-data-expand.png){height=22px}
![Collapse all](../imgs/gui/btn-data-collapse.png){height=22px} open or close
every level.

### Report

![The Report pane](../imgs/gui/run-report.png){width="100%"}

- **Report** — the `report.html` the run wrote into its folder when it ended,
  when and how big.
- **Notes** — what the operator recorded during the run.
- **Measured by**, **Package versions** — what produced the data.

Two buttons at the bottom:

- **Export HTML** asks where to save, and writes the run's report there — data,
  analysis, notes and device setup in one file.
- **Add report** asks *What happened?* and records the answer in the run's
  journal, between the steps it happened between: a helium top-up, a
  realignment. Available while the run is going; *Experiment ▸ Report…* does
  the same.

What the report contains is in [Run results](../usage/experiment.md#run-results).

### Visualization

![The Visualization pane](../imgs/gui/run-visualization.png){width="100%"}

The experiment's own views of the run, when its module declares them;
otherwise plots of the run's recorded numbers.

- **Open in its own window** runs the module's viewer as a separate program —
  the way in when the console cannot load the views itself, which the pane
  then explains.
- On the views' own menu bar, *Console ▸ Open these views in a window* floats
  them all out of the pane; **Bring the views back here** returns them.