Get started

Boulder Opal at a glance and quickstart.

Boulder Opal overview

Boulder Opal is a versatile toolkit that provides everything you need to improve and automate the performance of quantum hardware. The core capabilities of Boulder Opal fall under the framework of quantum control—the discipline that addresses the question, “How can systems that obey the laws of quantum mechanics be efficiently manipulated to create desired behaviors?”

The quantum control functionality underlying Boulder Opal comprises three core activities:

  • System identification: characterizing key system parameters by probing the quantum system and performing analysis on the resulting data. This information allows you to build a model of your system which you can use to inform how to design suitable controls for your system.

  • Control design: creating control solutions to manipulate quantum systems so they are resilient to noise, to cancel particular Hamiltonian terms, or to minimize control duration. This can be performed using either a Hamiltonian model of the system or via closed-loop experimental interrogation, and will generally involve critical calibration steps on the hardware.

  • Performance verification: analyzing the control solutions to gain insights into their functionality or effectiveness. This includes techniques to both probe the expected response and action of the control via simulation under realistic conditions and experimental probing of performance through specific validation routines known to highlight or amplify certain errors for easy tuneup.

If you want to know more about the capabilities of Boulder Opal, you can read our Boulder Opal overview topic or our introductions to the application of Boulder Opal to quantum computing and quantum sensing.

The Q-CTRL Python package

To get started with Boulder Opal, you should first install the Q-CTRL Python package. It provides an intuitive and convenient interface to Q-CTRL’s quantum control solutions for customers of Q-CTRL. Here you will learn how to set up your system to use Boulder Opal, authenticate your credentials, and start a Boulder Opal session.


  • 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.

1. Install Q-CTRL packages

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, install the Q-CTRL Python package using pip on the command line.

$ pip install qctrl

If you have trouble installing 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 scipy first from conda-forge.

$ conda install -c conda-forge scipy

and then installing the Q-CTRL Python package with pip.

$ 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 Visualizer and Q-CTRL Open Controls packages. You can also install them using pip.

$ pip install qctrl-visualizer qctrl-open-controls

If you already have the qctrl package installed and wish to update to the latest version, use the upgrade flag in pip.

$ pip install --upgrade qctrl

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

2. Authenticate your credentials

Call the authentication tool from your command-line interface with qctrl auth.

An authentication link will open up automatically, or be provided for you to copy and open in your browser of choice. You will be asked to enter your credentials if you are not already authenticated on our web app.

It should look something like this:

$ qctrl auth

Authentication URL:

The URL above should be automatically opened in your default web browser.
(Please copy and paste if it doesn’t open automatically).

Authenticate your credentials in your browser...

Finalizing authentication...
Successful authentication!

3. Start a Q-CTRL session

Import the Q-CTRL Python package in your Python script or Jupyter notebook, and start a session by creating a Qctrl object.

Note: authenticating by providing an email and password to the Qctrl() object has been deprecated in favor of a URL-based process. To authenticate, simply call qctrl = Qctrl() without any additional arguments.

# Import Q-CTRL Python package.
from qctrl import Qctrl

# Start a session with the API.
qctrl = Qctrl()

Authentication will happen automatically in the background where it’s possible. Otherwise you will be redirected to your web browser for further action.

You are now ready to use Boulder Opal and start running your calculations.

Boulder Opal documentation

You will find everything that you need to work with Boulder Opal in our documentation. Our topics provide background information, explanation, and high-level discussion of key Boulder Opal concepts.

Our tutorials will introduce you to the essential Boulder Opal features through detailed step-by-step exercises.

Our user guides will help you take that basic knowledge to the next level. They provide a summary workflow to follow and worked examples, containing fully executable code solving real-world problems using Boulder Opal.

In addition, we provide application notes which highlight new research results realized through use of a range of Boulder Opal capabilities. These push the limits of published literature on quantum control and also demonstrate how flexibly incorporating different parts of the Boulder Opal toolset can solve major control challenges in the field.

You can also consult the technical reference documentation for details about the Q-CTRL Python package API.