MTR is distributed on PyPI. The recommended installer is pipx, which creates an isolated venv per application and never touches your system Python.

Step 1 — install pipx (one-time, skip if you already have it):

# Debian / Ubuntu
sudo apt install pipx && pipx ensurepath

# Fedora
sudo dnf install pipx && pipx ensurepath

# macOS (Homebrew)
brew install pipx && pipx ensurepath

# Any platform with Python ≥ 3.12 (fallback)
python -m pip install --user pipx && pipx ensurepath

Step 2 — install MTR:

pipx install metis-test-runner
mtr                                  # launches the GUI from anywhere

# The example inputs ship inside the package, so copy them out first:
mtr-cli --copy-examples ~/mtr-examples
mtr-cli ~/mtr-examples/LMS_RAD_06.yaml    # CLI equivalent

Tip: mtr-cli --examples-dir prints where the bundled examples live if you would rather reference them in place than copy them.

Tip: MTR supports Python 3.12–3.13. On a newer default python3 (e.g. 3.14) the ESO pipeline dependencies (scopesim, pycpl, …) have no matching wheels yet, so the Install tab fails to build them. Pin MTR to a supported interpreter: pipx install metis-test-runner --python python3.12.

If you'd rather not install pipx, use Python's built-in venv module:

python -m venv ~/.venvs/mtr
~/.venvs/mtr/bin/pip install metis-test-runner
~/.venvs/mtr/bin/mtr                 # or: source ~/.venvs/mtr/bin/activate && mtr

On first launch, open the Install tab and click Install / Update to fetch the METIS_Pipeline, METIS_Simulations, and ESO pipeline dependencies into ~/.local/share/metis-test-runner/ (override with METIS_DATA_DIR=/path). All pipeline dependencies install into the same isolated venv that MTR itself lives in — they never leak into your system Python.

The GUI requires a handful of system libraries for Qt6 / OpenGL rendering. Python, Git, and basic CLI tools (curl, tar, …) are assumed to already be present.

Debian / Ubuntu

sudo apt install \
  libgl1 libegl1 libglib2.0-0 libxkbcommon0 \
  libfontconfig1 libfreetype6 libdbus-1-3 \
  libxkbcommon-x11-0 libxcb-cursor0 libxcb-keysyms1 libxcb-icccm4 libxcb-shape0

Fedora

sudo dnf install \
  mesa-libGL mesa-libEGL glib2 libxkbcommon \
  fontconfig freetype dbus-libs \
  libxkbcommon-x11 xcb-util-cursor xcb-util-keysyms xcb-util-wm

macOS (Homebrew)

On macOS, Qt uses the native Cocoa backend so X11/xcb packages are not needed:

brew install freetype fontconfig glib

Tip: if the GUI crashes at startup with "could not find or load the Qt platform plugin", set QT_DEBUG_PLUGINS=1 to get detailed diagnostics:

QT_DEBUG_PLUGINS=1 mtr

The output will list exactly which shared library failed to load.

Regardless of whether you drive the runner from the GUI or the CLI, the underlying pipeline tools have to live somewhere. Three layouts are supported — pick the one that matches your install:

Option A — pipx install (runner default, the default)

The Install tab takes care of this automatically. It pip-installs all pipeline dependencies (pycpl, edps, pyesorex, adari_core, scopesim, scopesim_templates) into the same isolated venv that hosts MTR, clones METIS_Pipeline and METIS_Simulations into the user data directory (~/.local/share/metis-test-runner/ by default). The default runner then derives the environment (PYTHONPATH, recipe directories, instrument-packages path) from those locations automatically and invokes every subprocess with the MTR venv's Python interpreter — no .env file required.

Option B — Docker or Podman container (runner docker / podman)

Build and start the pipeline container from METIS_Pipeline/toolbox/:

cd METIS_Pipeline/toolbox
docker build -t metispipeline .
docker run -d --name metis-pipeline --net=host \
  --mount type=bind,source=/path/to/output,target=/output \
  metispipeline

Then in the GUI, set runner to docker (or podman) and enter the container name. The output directory must be bind-mounted into the container so EDPS can write products back to the host.

Option C — bare-metal or inside a container (runner native)

If the pipeline tools (edps, python, ScopeSim) are already on your PATH — either because you are running inside a container, or have installed everything directly — no extra setup is needed. Select runner native.

ScopeSim instrument packages (Armazones, ELT, METIS) will be downloaded into ./inst_pkgs/ in your current working directory on first use. Set the GUI's Instrument packages field (or --inst-pkgs PATH) to download or reuse packages from a fixed location instead.

Tip: always launch the GUI (or invoke mtr-cli) from the same directory — otherwise ScopeSim will download a fresh copy of the instrument packages into every new directory, cluttering your filesystem.

Reference

Note for docker / podman runners: the output directory (-o) must be bind-mounted into the container so EDPS can write pipeline products to it. The --simulations-dir flag should point to the path of METIS_Simulations/Simulations inside the container (default: /home/metis/METIS_Simulations).

Two input formats are supported and may be mixed in a single run:

• YAML observation blocks (*.yaml, *.yml) — the primary, human-authored format. Workflow auto-detection works on YAML content.
• AIT-format CSV test sequences (*.csv) — the AIT performance-test sheet exported as CSV. Parsed by metis_simulations.csvParser at simulation time. MTR does not inspect CSV content itself, so for CSV-only runs the workflow is auto-detected from the simulated FITS headers (after the simulation step).

See small_test_img_lm.csv (IMAGE,LM) and small_test_img_n.csv (IMAGE,N) for minimal CSVs; the rest of this section covers YAML. All of these ship inside the package — mtr-cli --copy-examples DIR writes them somewhere you can edit them.

YAML Format

Each top-level key in the YAML is one observation block. The workflow (lm_img, n_img, ifu, lm_lss, n_lss, …) and the deepest pipeline target task are inferred automatically from the YAML content — primarily from properties.tech, falling back to mode.

Required fields per block:

BLOCK_NAME:
  do.catg: <EDPS classification tag>   # e.g. DETLIN_IFU_RAW, IFU_SCI_RAW
  mode: <scopesim mode>                 # e.g. wcu_lms, lms
  source:
    name: <scopesim source name>        # e.g. empty_sky, star
    kwargs: {}
  properties:
    dit: <float>          # detector integration time (s)
    ndit: <int>           # number of integrations
    catg: <CALIB|SCIENCE>
    tech: <LMS|IMAGE,LM|LSS,LM|…>
    type: <DETLIN|DARK|FLAT|…>
    tplname: <ESO template name>
    nObs: <int>           # number of exposures to simulate

See LMS_RAD_06.yaml (see mtr-cli --examples-dir) for a complete IFU example covering the full calibration + science chain.

The small per-mode examples — small_test.yaml (IFU), small_test_img_lm.yaml / small_test_img_lm.csv (IMAGE,LM), and small_test_img_n.yaml / small_test_img_n.csv (IMAGE,N) — are minimal inputs that exercise the detector linearity + gain step (metis_det_lingain) and the master-dark step (metis_det_dark). Each provides the DETLIN frames that recipe requires: six distinct DITs, each with two illuminated (ON) and two dark (OFF) frames (the OFF frames use filter_name: "closed"), plus ≥2 dark frames for the dark step. Six DITs are used because metis_det_lingain's gain fit — np.polyfit(deg=1, cov=True) — needs at least four DIT points below the linearity limit (len > order+2); fewer raises "the number of data points must exceed order to scale the covariance matrix."

mtr-cli is the headless interface that the GUI drives under the hood. It is useful for scripting, CI jobs, and SSH sessions without a display. It accepts the same options as the GUI.

mtr-cli [OPTIONS] input1.yaml [input2.csv ...]

YAML and CSV inputs may be mixed in any combination.

Options

Overriding the environment

For the default runner, the environment (PYTHONPATH, PYCPL_RECIPE_DIR, PYESOREX_PLUGIN_DIR, METIS_INST_PKGS, …) is derived automatically from the install locations — there is no env file to maintain. The same resolved environment is shared by mtr-cli, the GUI, and the mtr-exec / mtr-shell commands.

If you need to override or add a variable, create a .env file in the user data directory (~/.local/share/metis-test-runner/.env); any keys in it take precedence over the derived defaults. For example, to raise the pyesorex log verbosity:

PYESOREX_MSG_LEVEL=info
PYESOREX_LOG_LEVEL=info

The file is entirely optional — it is read if present and ignored if absent.

Examples

# Full run with the pipx-installed pipeline (default runner)
mtr-cli ~/mtr-examples/LMS_RAD_06.yaml

# Inside a container or bare-metal install (tools on PATH)
mtr-cli --runner native ~/mtr-examples/LMS_RAD_06.yaml

# Exec into a running Docker container from the host
mtr-cli --runner docker --container metis-pipeline ~/mtr-examples/LMS_RAD_06.yaml

# Exec into a running Podman container; set runner via env var
METIS_RUNNER=podman METIS_CONTAINER=metis-pipeline mtr-cli ~/mtr-examples/LMS_RAD_06.yaml

# Multiple YAML files, custom output dir, 2 auto-calibration frames per config
mtr-cli -o /tmp/myrun --calib 2 obs1.yaml obs2.yaml

# Skip the auto-generated calibration frames entirely
mtr-cli --no-calib obs1.yaml obs2.yaml

# Crank up parallelism for big simulation batches
mtr-cli --cores 12 ~/mtr-examples/LMS_RAD_06.yaml

# Only simulate, inspect the FITS files manually
mtr-cli --no-pipeline ~/mtr-examples/LMS_RAD_06.yaml

# Only run the pipeline on previously simulated data
mtr-cli --no-sim -o /tmp/myrun ~/mtr-examples/LMS_RAD_06.yaml

# Pipeline-only with FITS files from a custom location
mtr-cli --no-sim --pipeline-input /data/sim_fits -o /tmp/myrun

# CSV-only input, simulate only (workflow auto-detection not needed)
mtr-cli --no-pipeline ~/mtr-examples/small_test_img_lm.csv

# CSV-only input, full simulate + pipeline run (workflow auto-detected from the
# simulated FITS headers)
mtr-cli ~/mtr-examples/small_test_img_lm.csv

# Dry run: translate a CSV test sheet to YAML (writes my_sheet.yaml next to it),
# no simulation and no pipeline
mtr-cli --csv-to-yaml /path/to/my_sheet.csv

# Mixed YAML + CSV in a single run
mtr-cli ~/mtr-examples/small_test.yaml examples/small_test_img_lm.csv

For developers who want to drive the pipeline tools themselves — bypassing MTR's simulation, workflow detection, and EDPS server lifecycle — two commands hand you the fully-resolved environment with no env file to pass (PYTHONPATH, recipe dirs, instrument-packages path, and the MTR venv on PATH are all set for you):

# Run a single command in MTR's environment (everything after -- is verbatim)
mtr-exec -- edps -w metis.metis_wkf -t metis_ifu_dark -i ./sim -o ./out
mtr-exec -- pyesorex --recipes
mtr-exec -- python my_scopesim_probe.py

# Open an interactive shell with the environment pre-applied
mtr-shell
# then, inside it:
(mtr) $ edps -lw
(mtr) $ pyesorex metis_ifu_dark ...
(mtr) $ python        # scopesim importable, instrument packages resolved

Both accept --runner {default,native,docker,podman} and --container NAME (same semantics and env vars as mtr-cli); for docker/podman the command or shell runs inside the named container. These replace the old uv run --env-file .env … workflow.

MTR/
├── src/metis_test_runner/
│   ├── gui.py              # Graphical front-end (PyQt6) — primary entry point
│   ├── run_metis.py        # Headless CLI (used directly or wrapped by the GUI)
│   ├── archive.py          # MetisWISE archive integration
│   ├── credentials.py      # OS-keyring storage for archive credentials
│   ├── direct.py           # mtr-exec / mtr-shell direct environment access
│   ├── env.py              # Shared runtime-environment resolution
│   ├── paths.py            # User data directory resolution (platformdirs)
│   ├── indexes.py          # ESO mirror pip-index URL constants
│   └── examples/           # Bundled YAML / CSV example inputs
├── tests/                  # Unit tests (pytest)
└── pyproject.toml          # Project metadata (hatchling build backend)