How to set up and install Fire Opal

In this guide, you will learn how to:

Set up a Python conda environment.
Install the Fire Opal Python package into that environment.
Authenticate your Q-CTRL account.
Create credentials to use IBM Quantum devices with Fire Opal.

1. Set up a Python conda environment

To get started quickly and easily with Fire Opal and other Python packages, it's recommended to use Anaconda—a free and open-source distribution of the Python and other scientific computing languages that aims to simplify package management.

Once you have Anaconda downloaded, you may use it to create virtual environments, which isolate installations of Python packages to prevent unwanted interference across projects if you use Python for other projects.

Fire Opal is compatible with Python versions 3.9 to and including 3.12. You can either use Anaconda from the command line or through their visual Anaconda Navigator to create a Python environment with an appropriate version. For example, if you are using command line, you may replace your_env_name with any desired name and run:

conda create --name your_env_name python=3.11 -y
conda activate your_env_name

2. Install the Fire Opal Python package in your environment

Now that you've create a virtual environment to house the installation, you may go ahead and install the Fire Opal Python package.

If using a command line interface, the package can be installed using Python's package manager pip by running

pip install fire-opal

If pip is unable to find the package, please ensure that you are using a compatible version of Python as noted in Step 1.

3. Authenticate your Q-CTRL account

To use Fire Opal, you'll need a Q-CTRL account. Once you have your account, there are two ways in which you can authenticate your account:

Using a web browser.
Using an API key.

A web browser may be used only when running Fire Opal from a local environment, as opposed to a web-based development environment such as Google Colab or qBraid Lab. Upon your first use of Fire Opal, a web browser will automatically pop up and allow you to sign into your account. Once authorized, you will not have to repeat this process for 30 days.

Alternatively, to use an API key, start by signing in to your Q-CTRL Accounts page. Under Sign in and security, copy the pre-generated API key. You also have the ability to generate additional keys.

To use this API key to authenticate your account programmatically, you may use the authenticate_qctrl_account function

import fireopal as fo

api_key = "YOUR_QCTRL_API_KEY"
fo.authenticate_qctrl_account(api_key=api_key)

Note: When using a browser-based development platform, you must authenticate using an API key.

3.1. (Optional) Configure your Q-CTRL organization

If you are a member of multiple Q-CTRL organizations which can be viewed on the Q-CTRL Accounts page, you must specify your organization_slug, which is the unique ID used to identify this the organization with access to Fire Opal.

Once you have your organization_slug, you may set this organization using

fo.config.configure_organization(organization_slug="paste_organization_slug_here")

4. Create credentials to use real devices

Fire Opal supports submission of circuits to IBM Quantum Platform and Amazon Braket. The following sections demonstrate how to create credentials for each platform.

4.1 Create credentials for IBM Quantum

To create credentials for the IBM Quantum Platform, all you need is your IBM Quantum API token, which is accessible directly once signed into your IBM Quantum Account. Copy this token and replace your_IBMQ_token_here below. Note that these credentials must be passed with every call to Fire Opal.

# Enter your IBM token here.
ibm_token = "your_IBMQ_token_here"

# These are the properties for the publicly available provider for IBM backends.
# If you have access to a private provider and wish to use it, replace these values.
hub = "ibm-q"
group = "open"
project = "main"

ibm_credentials = fo.credentials.make_credentials_for_ibmq(
    token=ibm_token, hub=hub, group=group, project=project
)

4.2 Create credentials for AWS Braket

To use AWS Braket, you must first configure your AWS account to allow Fire Opal to run Braket jobs on your behalf. Please see how to configure your AWS account for Braket first.

Once your AWS account is properly configured, creating credentials for AWS Braket should be done with the function make_credentials_for_braket. All that is needed for this is your ARN.

arn = "your_role_arn"
credentials = fo.credentials.make_credentials_for_braket(arn=arn)

Congratulations! You have now set up your environment to run Fire Opal and have created the credentials needed to run on IBM Quantum or AWS Braket. Next, try running jobs on real quantum hardware with Fire Opal!