Ion CONtrol Software (ICON)

The Ion Control Software (ICON) is a control and data-acquisition framework developed in the Trapped Ion Quantum Computing research group at ETH Zurich. It is designed for laboratories that run experiments written in Python (with the pycrystal framework) on M-Action/Quench hardware.

ICON acts as the interface between user-defined Python experiments and the laboratory control hardware. It provides:

• An overview of available experiments by parsing the experiment library (a repository containing hardware and experiment descriptions).
• Access to all experiment parameters, including those from external devices integrated via pydase services.
• A job history and live data visualisation for running and past experiments.
• Support for parameter scans, including device parameters from connected services.

The system is built with:

• Backend: Python (API server, scheduler, pre-/post-processing, hardware orchestration).
• Frontend: React/TypeScript (configuration, monitoring, visualisation).
• Databases:
  • SQLite - job and device history
  • InfluxDB - parameter time series
  • HDF5 - experiment results

Getting Started

ICON runs on Linux and requires Python 3 to start. The easiest way to start is by downloading the binary from the releases page. Make it executable and run it:

$ chmod +x icon-linux-amd64
$ ./icon-linux-amd64 --help
Usage: icon-linux-amd64 [OPTIONS]

  Start the ICON server

Options:
  -V, --version      Print version.
  -v, --verbose      Increase verbosity (-v, -vv)
  -q, --quiet        Decrease verbosity (-q)
  -c, --config FILE  Path to the configuration file [default: ~/.config/icon/config.yaml]
  -h, --help         Show this message and exit

If you prefer to run ICON from source, clone the repository, build the frontend with pnpm and use uv as the dependency manager for the python project:

git clone --recursive https://github.com/tiqi-group/icon.git
cd icon
(cd frontend; pnpm install; pnpm build)
uv sync --extra server
uv run python -m icon.server

Configuration

ICON uses a YAML configuration file, located at ~/.config/icon/config.yaml by default. You can override this path with the -c flag.

• If the file does not exist, ICON will create it with default values.
• You can adjust settings either in the file or through the frontend settings page.

For more information about the configuration, see Configuration File.

Frontend

The web frontend is served automatically by the ICON backend. By default it is available at http://localhost:8004. The port and address can be changed in the config file.

Development

Backend

Set up the development environment:

uv sync --all-extras --group dev

Start a development InfluxDB instance:

podman kube play k8s/dev.yml

In a separate terminal, run the ICON server:

uv run python -m icon.server

Frontend

The frontend source code is located in the frontend/ folder, organised as a pnpm workspace. See frontend/README.md for details.

Important

sequence-visualizer is a git submodule, clone the icon repository with --recursive or run git submodule update --init --recursive after cloning.

To run ICON from source, the UI packages must be built first:

cd frontend
pnpm install    # installs dependencies
pnpm build      # builds the packages

Distributables

All three artifacts embed the built UI assets. The version is derived from the git tag.

Prepare the build process:

git submodule update --init               # Ensure sequence-visualizer submodule is initalized
git fetch --tags                          # Ensure version tag is present
cd frontend && pnpm install && pnpm build && cd ..      # Build front-end

Build source distribution and wheel:

uv build          # Builds dist/icon-<version>.tar.gz and dist/icon-<version>-py3-none-any.whl

Build standalone binary:

uv sync --extra server --group build
uv run pyinstaller icon.spec   # builds dist/icon

SQLite

ICON uses SQLite to store job history and device metadata.

• Models are defined using SQLAlchemy.
• Migrations are managed with Alembic.
• On startup, ICON automatically runs alembic upgrade head.

For details on updating schemas, see Alembic README.

PlantUML Diagrams

The design of the software is laid out in PlantUML diagrams located in the docs/plantuml_diagrams directory.

Acknowledgements

This work was funded by the ETH Zurich-PSI Quantum Computing Hub.

License

ICON is licensed under the MIT License.