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 and use uv as the dependency manager:

git clone https://github.com/tiqi-group/icon.git
cd icon
uv sync --extra server --extra zedboard
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. To start development:

cd frontend
npm install
npm run dev

This uses Vite.js with hot-reloading enabled.

Project structure:

frontend
└── src
    ├── components  # React components
    ├── contexts    # React contexts
    ├── hooks       # React hooks
    ├── layouts     # Layouts for MUI Toolpad
    ├── pages       # Page definitions
    ├── stores      # State stores (e.g. parameter store)
    ├── types       # Type definitions
    └── utils       # Utility functions

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.