Installation

MQT IonShuttler is a Python package available on PyPI. It can be installed on all major operating systems with all officially supported Python versions.

Tip

We recommend using uv. It is a fast Python package and project manager by Astral (creators of ruff). It can replace pip and virtualenv, automatically manages virtual environments, installs packages, and can install Python itself. It is significantly faster than pip.

If you do not have uv installed, install it with:

$ curl -LsSf https://astral.sh/uv/install.sh | sh

$ powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

See the uv documentation for more information.

$ uv pip install mqt.ionshuttler

(.venv) $ python -m pip install mqt.ionshuttler

Verify the installation:

(.venv) $ python -c "import mqt.ionshuttler; print(mqt.ionshuttler.__version__)"

This prints the installed package version.

Integrating MQT IonShuttler into Your Project

To use the MQT IonShuttler Python package in your project, add it as a dependency in your pyproject.toml or setup.py. This ensures the package is installed when your project is installed.

$ uv add mqt.ionshuttler

[project]
# ...
dependencies = ["mqt.ionshuttler>=<version>"]
# ...

from setuptools import setup

setup(
    # ...
    install_requires=["mqt.ionshuttler>=<version>"],
    # ...
)

Development Setup

Set up a reproducible development environment for MQT IonShuttler. This is the recommended starting point for both bug fixes and new features. For detailed guidelines and workflows, see Contributing.

  1. Get the code:

    If you do not have write access to the munich-quantum-toolkit/ionshuttler repository, fork the repository on GitHub (see https://docs.github.com/en/get-started/quickstart/fork-a-repo) and clone your fork locally.

    $ git clone git@github.com:your_name_here/ionshuttler.git mqt-ionshuttler

    If you have write access to the munich-quantum-toolkit/ionshuttler repository, clone the repository locally.

    $ git clone git@github.com/munich-quantum-toolkit/ionshuttler.git mqt-ionshuttler

  2. Change into the project directory:

    $ cd mqt-ionshuttler

  3. Create a branch for local development:

    $ git checkout -b name-of-your-bugfix-or-feature

    Now you can make your changes locally.

  4. Install development tools:

    We highly recommend using modern, fast tooling for the development workflow. We recommend using uv. If you don’t have uv, follow the installation instructions in the recommendation above (see tip above). See the uv documentation for more information.

    We also recommend installing pre-commit to automatically run checks before each commit and nox to automate common development tasks.

    The easiest way to install pre-commit and nox is via uv:

    $ uv tool install pre-commit
$ uv tool install nox

    On macOS with Homebrew, you can install pre-commit and nox with:

    $ brew install pre-commit nox

    If you prefer to use pipx, you can install pre-commit and nox with:

    $ pipx install pre-commit
$ pipx install nox

    If you prefer to use regular pip (preferably in a virtual environment), you can install pre-commit and nox with:

    $ pip install pre-commit nox

    Then enable the pre-commit hooks with:

    $ pre-commit install