metis-test-runner 0.2.0a0__tar.gz

metis_test_runner-0.2.0a0/.gitignore

@@ -0,0 +1,46 @@
+# External repositories (cloned separately via metis-meta-package bootstrap)
+METIS_Pipeline/
+METIS_Simulations/
+METIS_DRLD/
+metis-meta-package/
+MetisWISE/
+inst_pkgs/
+
+# Test/scratch YAML files (root-level only; examples/ are tracked)
+/*.yaml
+
+# Local test data and pipeline outputs
+data/
+output/
+logs/
+uv-cache/
+EDPS_data/
+
+# Claude Code internal files
+.claude/
+
+# Pipeline environment (generated by Install tab; contains local paths)
+.env
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+dist/
+build/
+*.egg
+uv.lock
+*.log
+
+# FITS files (large binary data)
+*.fits
+*.fits.gz
+
+# OS / editor
+.DS_Store
+*.swp
+*.swo
+*~
+.idea/
+.vscode/

metis_test_runner-0.2.0a0/CHANGELOG.md

@@ -0,0 +1,53 @@
+# Changelog
+
+## 0.2.0
+
+First PyPI release as `metis-test-runner`.
+
+### Changed
+- Restructured the project as a proper Python package under
+  `src/metis_test_runner/`. Modules are now imported as
+  `from metis_test_runner import gui, run_metis, archive`.
+- Switched the build backend from `uv` to `hatchling`. The `[tool.uv]` and
+  `[dependency-groups]` sections are gone. Pipeline dependencies that live on
+  ESO mirrors (`pycpl`, `edps`, `pyesorex`, `adari_core`) are still installed
+  at runtime by the GUI's Install tab — they are not in `[project.dependencies]`
+  because they are not on PyPI.
+- The GUI's Install tab and the Archive tab's MetisWISE installer now shell
+  out to `pip` (via `sys.executable -m pip`) with `--extra-index-url` for the
+  ESO and pycpl mirrors. `uv` is no longer required to use MTR.
+- Runtime data (the `METIS_Pipeline` and `METIS_Simulations` clones, `.env`,
+  instrument packages, DRLD) now lives in a user data directory resolved via
+  `platformdirs` — `~/.local/share/metis-test-runner/` on Linux. Override the
+  location with the `METIS_DATA_DIR` environment variable. The per-asset env
+  vars (`METIS_META_PKG`, `METIS_SIMULATIONS_DIR`, `METIS_INST_PKGS`) still
+  work for back-compat.
+- The CLI is now invoked as `mtr-cli` (or `python -m metis_test_runner.run_metis`)
+  instead of `python src/run_metis.py`.
+
+### Added
+- `mtr` and `mtr-cli` console-script entry points. After installation, both
+  are on `PATH` and can be invoked from any directory.
+- `metis_test_runner.paths` — a single seam for every filesystem location MTR
+  reads or writes outside the package itself.
+- `metis_test_runner.indexes` — ESO mirror URL constants.
+- BSD-3-Clause `LICENSE` file.
+- Trusted-publishing GitHub workflow (`.github/workflows/publish.yml`)
+  publishes to PyPI on `v*.*.*` tag pushes.
+
+### Removed
+- `launch.sh` — superseded by the `mtr` console script. Developers now use
+  `pip install -e .[dev]` to set up a working copy.
+
+### Notes / known limitations
+- The `--runner metapkg` mode of `mtr-cli` still shells out to `uv run --project
+  <metis-meta-package>`. This is the only remaining `uv` dependency and is
+  guarded with a clear error message if `uv` is not installed. It will be
+  removed once `metis-meta-package` is published to PyPI.
+- `gui.REPO_ROOT` is kept as a back-compat alias pointing at `paths.data_dir()`
+  so existing test monkeypatches continue to work. To be removed in a future
+  release.
+
+## 0.1.0
+
+Internal pre-PyPI release. Distributed via `git clone` + `./launch.sh`.

metis_test_runner-0.2.0a0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, AstarVienna
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

metis_test_runner-0.2.0a0/PKG-INFO

@@ -0,0 +1,379 @@
+Metadata-Version: 2.4
+Name: metis-test-runner
+Version: 0.2.0a0
+Summary: GUI and CLI wrapper for end-to-end ESO METIS pipeline testing
+Project-URL: Homepage, https://github.com/AstarVienna/MTR
+Project-URL: Issues, https://github.com/AstarVienna/MTR/issues
+Project-URL: Changelog, https://github.com/AstarVienna/MTR/blob/main/CHANGELOG.md
+Author: AstarVienna
+License: BSD-3-Clause
+License-File: LICENSE
+Keywords: ELT,ESO,METIS,astronomy,pipeline,scopesim
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: X11 Applications :: Qt
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Requires-Python: <3.14,>=3.12
+Requires-Dist: platformdirs>=4.0
+Requires-Dist: pyqt6-qt6==6.6.0
+Requires-Dist: pyqt6==6.6.0
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: pyyaml
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# METIS Test Runner
+
+<p align="center">
+  <a href="https://github.com/eiseleb47/MTR/actions/workflows/unit_tests.yaml"><img src="https://img.shields.io/github/actions/workflow/status/eiseleb47/MTR/unit_tests.yaml?branch=main&label=unit%20tests&style=for-the-badge&labelColor=1e1e2e&color=a6e3a1&logo=github&logoColor=cdd6f4" alt="Unit Tests"></a>
+  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3-89b4fa?style=for-the-badge&labelColor=1e1e2e&logo=python&logoColor=cdd6f4" alt="Python 3"></a>
+  <a href="https://github.com/eiseleb47/MTR/commits/main"><img src="https://img.shields.io/github/last-commit/eiseleb47/MTR?style=for-the-badge&labelColor=1e1e2e&color=cba6f7&logo=git&logoColor=cdd6f4" alt="Last Commit"></a>
+  <a href="https://github.com/eiseleb47/MTR"><img src="https://img.shields.io/badge/platform-linux-fab387?style=for-the-badge&labelColor=1e1e2e&logo=linux&logoColor=cdd6f4" alt="Platform"></a>
+</p>
+
+A graphical front-end for end-to-end testing of the [METIS instrument pipeline](https://github.com/AstarVienna/METIS_Pipeline). It generates synthetic FITS observations via [ScopeSim](https://scopesim.readthedocs.io/) and then runs the matching [EDPS](https://www.eso.org/sci/software/edps/) reduction workflow — all from a single, self-contained GUI. A command-line interface (`mtr-cli`) is also shipped as a fallback for scripted or headless use.
+
+## Install
+
+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):
+
+```bash
+# 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**:
+
+```bash
+pipx install metis-test-runner
+mtr                                  # launches the GUI from anywhere
+mtr-cli examples/LMS_RAD_06.yaml     # CLI equivalent
+```
+
+If you'd rather not install pipx, use Python's built-in venv module:
+
+```bash
+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.
+
+## System Dependencies
+
+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**
+
+```bash
+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**
+
+```bash
+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:
+
+```bash
+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:
+> ```bash
+> QT_DEBUG_PLUGINS=1 mtr
+> ```
+> The output will list exactly which shared library failed to load.
+
+## The GUI
+
+The GUI is the recommended way to drive the test runner. It exposes every CLI flag through labelled controls, remembers your settings between sessions, and streams colour-coded live output from the pipeline.
+
+Launch it with:
+
+```bash
+mtr
+```
+
+A **Light / Dark theme** button lives in the toolbar and toggles on the fly.
+
+### Install tab
+
+The Install tab performs the full pipeline bootstrap non-interactively. Use it if you do **not** already have the pipeline installed. Clicking **Install / Update** will:
+
+1. Clone (or update, if already present) `METIS_Pipeline` and `METIS_Simulations` into the user data directory (`~/.local/share/metis-test-runner/` by default)
+2. `pip install` all ESO pipeline Python dependencies — `pycpl`, `edps`, `pyesorex`, `adari_core`, `scopesim`, `scopesim_templates` — into the same isolated venv that hosts MTR (via `--extra-index-url` against the ESO mirrors). Out-of-band installs such as MetisWISE from the Archive tab are preserved.
+3. Write `.env` into the user data directory (environment variables for PYTHONPATH, plugin directories, etc.)
+4. Initialise and configure EDPS on port 4444
+
+Re-running is safe — existing repositories are updated in place rather than re-cloned.
+
+**Skip this tab** if you already have the pipeline installed via one of these paths — jump straight to the Run tab instead:
+
+- **metis-meta-package** — choose runner `metapkg` and set *Meta-package dir* to your `metis-meta-package` folder
+- **Bare-metal / ESO docs install** — choose runner `native`
+- **Pipeline container** (Docker / Podman) — choose runner `docker` or `podman` and supply the container name
+
+### Archive tab
+
+The Archive tab connects to the remote METIS AIT archive via the
+[MetisWISE](https://github.com/AstarVienna/MetisWISE) client. It has two pages:
+
+1. **Install & Configure** — paste the OmegaCEN credentials from the
+   [METIS wiki](https://metis.strw.leidenuniv.nl/wiki/doku.php?id=ait:archive)
+   and click **Install MetisWISE** to pip-install the package into the same
+   isolated venv that hosts MTR. Then fill in the five `[global]` fields (`database_user`,
+   `database_password`, `project`, `database_tablespacename`, `database_name`)
+   and click **Save & Test Connection**. The values are written to
+   `~/.awe/Environment.cfg`; `data_server`, port and protocol are inherited
+   from the MetisWISE-packaged default (`metis-ds.hpc.rug.nl:8013`, https).
+
+2. **Query & Download** — filter by raw classification tag or master
+   `PRO.CATG`, click **Search**, select files and download them to a local
+   directory.
+
+To auto-pull missing master calibrations during a pipeline run, add
+`--auto-fetch-calibrations` to the Run tab's options (or the CLI).
+
+### Run tab
+
+The Run tab wraps `mtr-cli` in a file-picker UI. All CLI options are exposed as form controls; runner-specific fields (container name, meta-package path) show and hide based on the selected runner.
+
+Workflow:
+
+1. **Add input files** via the file browser — YAML observation blocks (`*.yaml`, `*.yml`) and AIT-format CSV test sequences (`*.csv`) may be added freely and mixed in a single run. A live tally (e.g. `2 YAML  ·  1 CSV`) appears below the list.
+2. **Tune options** — output directory, CPU cores, auto-calibration, runner mode, pipeline mode (simulate + run, simulate only, pipeline only), simulations directory, instrument packages directory
+3. **Pick a workflow** (only for CSV-only runs that include the pipeline) — workflow auto-detection reads YAML content, so when the list contains only CSV files and you intend to run the pipeline, the *Workflow* dropdown appears and must be set; otherwise it stays hidden
+4. **Click Run** — the Run button becomes Stop, and pipeline output streams into the log view with ANSI colouring stripped and stderr highlighted
+5. **Inspect output** — the pane below the option form shows exactly where simulation frames and pipeline products will be written, updating live as you edit the output path
+
+Settings are persisted via `QSettings` and restored on next launch, so you can re-run the last configuration with two clicks.
+
+## Prerequisites (runner modes)
+
+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 — consolidated install** (runner `metapkg`, 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), and writes a `.env` file
+there. The runner reads that `.env` automatically.
+
+Use the GUI's *Meta-package dir* field (or `--meta-pkg` / `--simulations-dir`)
+to point at an external installation if needed.
+
+**Option B — Docker or Podman container** (runner `docker` / `podman`)
+
+Build and start the pipeline container from [METIS_Pipeline/toolbox/](https://github.com/AstarVienna/METIS_Pipeline/tree/main/toolbox):
+
+```bash
+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.
+
+## Input Formats
+
+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. Because MTR does **not** inspect CSV content itself, CSV-only runs that execute the pipeline require an explicit workflow choice (the GUI's *Workflow* dropdown, or `--workflow NAME` on the CLI).
+
+See [`examples/small_test.csv`](examples/small_test.csv) for a minimal CSV; the rest of this section covers YAML.
+
+### 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:
+
+```yaml
+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 `examples/LMS_RAD_06.yaml` for a complete IFU example covering the full calibration + science chain.
+
+## Supported Workflows
+
+| EDPS Workflow | `tech` values |
+|---|---|
+| `metis_lm_img_wkf` | `IMAGE,LM` |
+| `metis_n_img_wkf` | `IMAGE,N` |
+| `metis_ifu_wkf` | `LMS`, `IFU`, `RAVC,IFU` |
+| `metis_lm_lss_wkf` | `LSS,LM` |
+| `metis_n_lss_wkf` | `LSS,N` |
+| `metis_lm_ravc_wkf` | `RAVC,LM` |
+| `metis_lm_app_wkf` | `APP,LM` |
+| `metis_pupil_imaging_wkf` | `PUP,LM`, `PUP,N` |
+
+## Output Layout
+
+Output is written under the chosen output directory (default: `./output/<timestamp>/`):
+
+- `<output-dir>/sim/` — synthetic FITS frames from ScopeSim
+- `<output-dir>/pipeline/` — reduced data products from EDPS
+
+The GUI displays the resolved paths live under the *Output directory* field so you can see exactly where products will land before you hit Run.
+
+## Command-Line Fallback
+
+`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.
+
+```bash
+mtr-cli [OPTIONS] input1.yaml [input2.csv ...]
+```
+
+YAML and CSV inputs may be mixed in any combination.
+
+### Options
+
+| Flag | Default | Description |
+|---|---|---|
+| `-o / --output` | `./output/<timestamp>` | Root directory for all outputs (env: `METIS_OUTPUT_DIR`) |
+| `--runner {metapkg,native,docker,podman}` | `metapkg` | Execution mode (see below; env: `METIS_RUNNER`) |
+| `--container NAME` | — | Container name/ID for `docker` / `podman` runners (env: `METIS_CONTAINER`) |
+| `--calib [N]` | `1` | Auto-generate N calibration frames (dark/flat) per unique config, inferred from input content. Pass `--calib 0` to disable. |
+| `--workflow NAME` | auto-detect | Force EDPS workflow name (e.g. `metis.metis_lm_img_wkf`). Required when all inputs are `.csv` and the pipeline will run, because workflow auto-detection is YAML-only. Overrides auto-detection when YAML is also present. |
+| `--cores N` | `4` | CPU cores used for parallel simulations |
+| `--no-sim` | off | Skip simulation; run pipeline on existing FITS data (source defaults to `<output>/sim/` — override with `--pipeline-input`) |
+| `--pipeline-input DIR` | `<output>/sim/` | Directory containing FITS files to feed the pipeline (only with `--no-sim`; env: `METIS_PIPELINE_INPUT`) |
+| `--no-pipeline` | off | Run simulation only; skip EDPS pipeline |
+| `--meta-pkg PATH` | `.` (repo root) | Path to the pipeline environment directory (`metapkg` runner only). Falls back to `./pipeline/` then `./metis-meta-package/`. (env: `METIS_META_PKG`) |
+| `--simulations-dir PATH` | `./METIS_Simulations` (host) or `/home/metis/METIS_Simulations` (container) | Path to ScopeSim scripts (env: `METIS_SIMULATIONS_DIR`) |
+| `--inst-pkgs PATH` | see below | Path to ScopeSim instrument packages (Armazones, ELT, METIS). Defaults to `./inst_pkgs` for `metapkg`/`native`, and container-resolved `./inst_pkgs` for `docker`/`podman` (env: `METIS_INST_PKGS`) |
+| `--auto-fetch-calibrations` | off | Before running the pipeline, query the remote METIS archive (via MetisWISE) for any master calibrations the input set is missing and download them into the pipeline input directory. Requires MetisWISE to be installed and `~/.awe/Environment.cfg` to hold valid credentials — see the Archive tab. |
+| `--prefer-masters` | off | Set EDPS `association_preference` to `master_per_quality_level` for this run, preferring master calibrations over reduced raw data. |
+
+### Runner modes
+
+| Mode | When to use |
+|---|---|
+| `metapkg` (default) | You used the GUI's Install tab (or an external `metis-meta-package` install). Pipeline tools are pip-installed alongside MTR in the same isolated venv. For external `metis-meta-package` checkouts, `uv` must be on PATH (`pipx install uv`). |
+| `native` | Tools (`edps`, `python`, ScopeSim) are installed directly on PATH — e.g. you are running **inside** a Docker/Podman container, or have a bare-metal install. |
+| `docker` / `podman` | Tools live inside a container and you are running the script **outside** it. The runner wraps every command with `docker exec` / `podman exec`. |
+
+> **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`).
+
+### Examples
+
+```bash
+# Full run with metis-meta-package (default)
+mtr-cli examples/LMS_RAD_06.yaml
+
+# Inside a container or bare-metal install (tools on PATH)
+mtr-cli --runner native examples/LMS_RAD_06.yaml
+
+# Exec into a running Docker container from the host
+mtr-cli --runner docker --container metis-pipeline 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 examples/LMS_RAD_06.yaml
+
+# Multiple YAML files, custom output dir, with auto-calibration frames
+mtr-cli -o /tmp/myrun --calib obs1.yaml obs2.yaml
+
+# Crank up parallelism for big simulation batches
+mtr-cli --cores 12 examples/LMS_RAD_06.yaml
+
+# Only simulate, inspect the FITS files manually
+mtr-cli --no-pipeline examples/LMS_RAD_06.yaml
+
+# Only run the pipeline on previously simulated data
+mtr-cli --no-sim -o /tmp/myrun 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 examples/small_test.csv
+
+# CSV-only input, full simulate + pipeline run (workflow must be explicit)
+mtr-cli --workflow metis.metis_lm_img_wkf examples/small_test.csv
+
+# Mixed YAML + CSV in a single run
+mtr-cli examples/small_test.yaml examples/small_test.csv
+```
+
+## Repository Layout
+
+```
+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
+│   ├── paths.py            # User data directory resolution (platformdirs)
+│   ├── indexes.py          # ESO mirror pip-index URL constants
+│   └── examples/           # Bundled YAML / CSV example inputs
+├── container/
+│   ├── Dockerfile          # Ubuntu 24.04 GUI container (Qt6 / Wayland)
+│   └── compose.yml         # Podman / Docker Compose for the GUI service
+├── tests/                  # Unit tests (pytest)
+└── pyproject.toml          # Project metadata (hatchling build backend)
+```
+
+## Related Repositories
+
+This runner is designed to work alongside the following repos, which are installed via the GUI's Install tab:
+
+- **[METIS_Pipeline](https://github.com/AstarVienna/METIS_Pipeline)** — the core Python/C pipeline, EDPS workflows, and PyEsoRex recipes
+- **[METIS_Simulations](https://github.com/AstarVienna/METIS_Simulations)** — ScopeSim scripts that generate synthetic FITS observations for each observing mode
+- **[metis-meta-package](https://github.com/eiseleb47/metis-meta-package)** — legacy standalone meta-installer (still supported as a fallback; the Install tab now installs pipeline dependencies directly into the main virtual environment)