How to get started

Getting started with Q-CTRL Boulder Opal

The Q-CTRL Python package provides an intuitive and convenient Python interface to Q-CTRL's quantum control solutions for customers of Q-CTRL.


  • To use the Q-CTRL Python package you will need a Q-CTRL account
  • The Q-CTRL Python package requires Python 3.6.4 or later

Summary workflow

1. Installation

To get started quickly and easily, we recommend Anaconda—a free and open-source distribution of the Python and R programming languages for scientific computing that aims to simplify package management and deployment.

Once you're set up with a valid Python version, run the following command in your terminal application:

$ pip install qctrl

If you have trouble installing the Q-CTRL Python package with the above command due to dependency errors with scipy (this is a known issue for systems with Apple M1 processors), you can try installing it first from conda-forge by running

$ conda install -c conda-forge scipy

and then installing the Q-CTRL Python package with

$ pip install qctrl

Note that doing this might result in slightly different versions of some packages being installed.

Several of the Boulder Opal User guides and Application notes use the Q-CTRL Python Visualizer and Q-CTRL Python Open Controls packages, which you can install by running:

$ pip install qctrl-visualizer qctrl-open-controls

2. Initialization

All usage of the Q-CTRL Python package begins by importing the qctrl package and starting a session.

from qctrl import Qctrl

# Starting a session with the API
qctrl = Qctrl()

3. Authentication

Interactive authentication

To authenticate your session, you will need the email and password used to create your Q-CTRL account.

The interactive authentication method is a command line utility that authenticates your credentials and saves an authentication file that gets used in all future interactions with the Python package.

This utility can be invoked from the terminal as follows:

$ qctrl auth

If you would like to store the automatically generated authentication file in a different place to the default location, you can do so through the use of the path command.

$ qctrl auth --path <your_custom_path>

You can use the following command to see all qctrl authentication options:

$ qctrl auth --help

The interactive authentication method can also be invoked using Python as shown below:

$ python
>>> from qctrl import Qctrl
>>> qctrl = Qctrl()

    This is an interactive Q-CTRL Authentication setup tool.

    For non-interactive or alternative options check our help:

        $ qctrl auth --help


Authenticating to
Successfully authenticated!
Authentication file created at /Users/me/.config/qctrl/99a605c91232cda79437e2908bdf0837

Note: You only need to do the above once. Subsequent invocations of Qctrl() will use the created authentication file.

Non-interactive authentication

For usage when interactive authentication is not available, you can authenticate by providing your credentials to the Qctrl() object as shown below.

$ python
>>> from qctrl import Qctrl
>>> qctrl = Qctrl(email='', password='mypassword')

4. Upgrading

If you already have the qctrl package installed and wish to upgrade to the latest version, run:

$ pip install --upgrade qctrl

You can similarly upgrade the qctrl-visualizer and qctrl-open-controls packages.