{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "6ab6622e",
   "metadata": {},
   "source": [
    "# Notebook: debugging the ARCADE pipeline\n",
    "\n",
    "This notebook is a playbook for broken runs. It shows how to raise log levels,\n",
    "validate YAML early, run stages one at a time, and map common error strings to\n",
    "fixes. Keep it open beside a failing zoo job.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2219744f",
   "metadata": {},
   "source": [
    "## Mental model\n",
    "\n",
    "```text\n",
    "validate YAML \u2192 data stage \u2192 classify one method \u2192 add methods \u2192 hardware \u2192 report\n",
    "```\n",
    "\n",
    "Do not start by re-tuning neural hyperparameters when Stage 1 label packing is\n",
    "wrong. Fix the earliest stage that emits a WARNING or unexpected INFO line.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1aede37b",
   "metadata": {},
   "outputs": [],
   "source": [
    "from pathlib import Path\n",
    "import logging\n",
    "import traceback\n",
    "\n",
    "from arcade._logging import configure_logging, get_logger\n",
    "from arcade.config import load_config, validate_and_explain\n",
    "\n",
    "configure_logging(logging.INFO)\n",
    "log = get_logger(\"tutorial.debug\")\n",
    "\n",
    "CONFIG = Path(\"configs/example.yaml\")\n",
    "if not CONFIG.is_file():\n",
    "    CONFIG = Path(\"configs/paper_all_methods_benchmark.yaml\")\n",
    "\n",
    "errors = validate_and_explain(CONFIG)\n",
    "print(\"config valid:\", not errors)\n",
    "for m in errors:\n",
    "    print(\" \", m)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a4018787",
   "metadata": {},
   "source": [
    "## Log levels that matter\n",
    "\n",
    "| Level | When to use |\n",
    "|-------|-------------|\n",
    "| `WARNING` | Default library quietness before `configure_logging` |\n",
    "| `INFO` | Normal pipeline banners and per-method metrics |\n",
    "| `DEBUG` | Loader internals, demod helpers, unexpected branches |\n",
    "\n",
    "```python\n",
    "configure_logging(\"DEBUG\")  # string form also accepted\n",
    "```\n",
    "\n",
    "ARCADE formats logs as:\n",
    "\n",
    "```text\n",
    "[LEVEL] logger.name: message\n",
    "```\n",
    "\n",
    "Filter on `arcade.stages.data`, `arcade.stages.classify`, `arcade.stages.hardware`,\n",
    "or `arcade.stages.visualization` when the full zoo scrollback is too long.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "50cf1d2a",
   "metadata": {},
   "outputs": [],
   "source": [
    "from arcade.stages import DefaultDataStage, DefaultClassifyStage\n",
    "\n",
    "cfg = load_config(CONFIG)\n",
    "# Minimal reproduction: one classical method, no long neural training.\n",
    "cfg.classifiers.run[:] = [\"threshold\"]  # mutate list in place\n",
    "\n",
    "try:\n",
    "    data_out = DefaultDataStage().run(cfg)\n",
    "    print(\"data stage OK\")\n",
    "except Exception as exc:\n",
    "    log.error(\"data stage failed: %s\", exc)\n",
    "    traceback.print_exc()\n",
    "else:\n",
    "    try:\n",
    "        classify_out = DefaultClassifyStage().run(cfg, data_out)\n",
    "        print(\"classify stage OK\")\n",
    "        print(classify_out.get(\"classifiers\", {}).get(\"threshold\", {}).get(\"metrics\"))\n",
    "    except Exception as exc:\n",
    "        log.error(\"classify stage failed: %s\", exc)\n",
    "        traceback.print_exc()\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9d1db3c9",
   "metadata": {},
   "source": [
    "## Symptom \u2192 stage \u2192 fix\n",
    "\n",
    "| What you see | Stage | First fix |\n",
    "|--------------|-------|-----------|\n",
    "| Missing HDF5 / path errors | Data | Fix `data.path`; run `link_paper_data.sh` |\n",
    "| Demod / frequency / sampling errors | Data | Align `data.demodulation` with the file |\n",
    "| Split sizes are zero or tiny | Data | Check `data.split` and label coverage |\n",
    "| `FEATURE_KIND` / shape mismatches | Classify | `arcade describe`; shrink `classifiers.run` |\n",
    "| ImportError for torch / iisignature | Classify | Install matching extras |\n",
    "| Hardware disabled or empty LUTs | Hardware | Set `hardware.enabled: true` |\n",
    "| No summary report | Visualization | Confirm metrics exist; check `output_dir` permissions |\n",
    "| Joint accuracy absurd, per-qubit fine | Data labels | Flip / correct `qubit_bit_order` |\n",
    "\n",
    "### CLI helpers\n",
    "\n",
    "```bash\n",
    "arcade validate configs/my.yaml\n",
    "arcade explore data/my.h5 --qubits 5\n",
    "arcade list\n",
    "arcade describe fnn\n",
    "arcade run configs/my.yaml\n",
    "```\n",
    "\n",
    "### Python helpers\n",
    "\n",
    "```python\n",
    "import arcade\n",
    "arcade.describe(\"threshold\")\n",
    "# arcade.explore(\"data/my.h5\", num_qubits=5)  # when available in your install\n",
    "```\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d6a7bbf8",
   "metadata": {},
   "source": [
    "## Minimal reproduction template\n",
    "\n",
    "Copy this pattern when filing a bug or asking for help:\n",
    "\n",
    "1. Exact config path and the `classifiers.run` list.\n",
    "2. First ERROR or traceback, not only the last line.\n",
    "3. Whether demod cache was cold or warm.\n",
    "4. Output of `arcade describe` for the failing method.\n",
    "5. Whether `arcade validate` passed.\n",
    "\n",
    "Re-run with a single classical method before claiming a neural method is broken.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8fffedf2",
   "metadata": {},
   "source": [
    "## Related tutorials\n",
    "\n",
    "- [Data stage](stage_data.ipynb)\n",
    "- [Classify stage](stage_classify.ipynb)\n",
    "- [Hardware and report](stage_hardware_report.ipynb)\n",
    "- [First zoo run](first_zoo_run.md)\n",
    "- [Read the report](read_the_report.md)\n"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "name": "python",
   "pygments_lexer": "ipython3"
  },
  "nbsphinx": {
   "execute": "never"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}