# Installation

## Requirements

ARCADE targets Python 3.10 or newer. The core install pulls numerical and
scientific dependencies used by nearly every path: NumPy, SciPy, h5py,
scikit-learn, Matplotlib, Seaborn, PyYAML, Pydantic, and tqdm. Neural methods
need PyTorch. Path signature features need ``iisignature``. FPGA-oriented
export helpers need ``hls4ml``. Quantum error correction curves need Stim,
Sinter, and PyMatching. Documentation builds need Sphinx and the Read the Docs
theme. Development installs add pytest and ruff.

You do not need every optional stack on day one. Install the core package
first, confirm the command line works, then add extras as you enable the
corresponding YAML sections.

## Create an environment and install

From the repository root:

```bash
cd ARCADE
python -m venv .venv
source .venv/bin/activate
pip install -e ".[torch,signature]"
bash scripts/link_paper_data.sh
```

The editable install links the ``arcade`` package into the environment so
local edits apply without a reinstall. The ``torch`` extra enables neural
classifiers such as FNN, HERQULES, leakage, and multilevel networks. The
``signature`` extra enables the path signature classifier. The
``link_paper_data.sh`` script creates the ``data/`` symlinks that bundled paper
configs expect for the public Readout 2019 HDF5 files.

## Optional extras

| Extra | Install command | What it unlocks |
|-------|-----------------|-----------------|
| Core only | ``pip install -e .`` | Threshold and scikit-learn baselines |
| ``torch`` | ``pip install -e ".[torch]"`` | Neural classifiers |
| ``signature`` | ``pip install -e ".[signature]"`` | Path signature method |
| ``hardware`` | ``pip install -e ".[hardware]"`` | HLS4ML-oriented helpers |
| ``qec`` | ``pip install -e ".[qec]"`` | Stim-based LER and FTQC curves |
| ``dev`` | ``pip install -e ".[dev]"`` | pytest and ruff |
| ``docs`` | ``pip install -e ".[docs]"`` | Sphinx build via ``make -C doc html`` |
| ``export`` | ``pip install -e ".[export]"`` | PDF figure export with PyMuPDF |
| ``all`` | ``pip install -e ".[all]"`` | Full dependency set |

For a documentation-only contributor who will not train networks, ``pip
install -e ".[docs]"`` is enough to build this manual. For a zoo run that
matches the public multi-method benchmark, install at least ``torch`` and
``signature``. For QEC pages and configs, add ``qec``.

## Command line entry point

The project exposes a console script named ``arcade``. After a successful
editable install you should be able to run:

```bash
arcade list
arcade describe threshold
```

``arcade list`` prints registered classifier names. ``arcade describe`` prints
a short description string from the registry. The full pipeline entry point is
``arcade run path/to/config.yaml``, which loads configuration, runs stages in
order, and writes outputs under the directory named in the visualization
section.

## Building this documentation

```bash
pip install -e ".[docs]"
make -C doc html
python -m http.server -d doc/_build/html 8000
```

Open ``http://127.0.0.1:8000/`` in a browser. The HTML theme is the Read the
Docs theme chosen for a fixed, reference-manual look with low visual noise.

## Next

Continue with {doc}`pipeline` for a stage-by-stage map of what happens after
``arcade run``. Then use {doc}`verification` to smoke-test the environment.