# How to run circuits on Fire Opal

> Learning the basics of running circuits with Fire Opal

Source: https://docs.q-ctrl.com/fire-opal/discover/adopt/how-to-run-circuits-on-fire-opal

If you want to run a circuit or a list of circuits, Fire Opal's `execute` function is designed for straightforward job submission to quantum hardware. As your workload scales, and you need to run several hundred circuits at once or multiple consecutive circuits, you can use the `iterate` function, which is optimized for handling several jobs or executing multiple consecutive circuits, such as variational or batch workflows. The `iterate` function minimizes preprocessing and queuing delays when jobs are submitted in immediate succession. 

In this user guide, you will learn how to run circuits using both the `execute` and `iterate` functions.

## 1. Imports and initialization
To run these examples, you'll first need to set up your account information for Fire Opal and your hardware provider.

### 1.1 Fire Opal import and initialization


```python
import fireopal as fo
```


```python
# Replace "YOUR_QCTRL_API_KEY" with your API key, which you can find at https://accounts.q-ctrl.com/security
api_key = "YOUR_QCTRL_API_KEY"
fo.authenticate_qctrl_account(api_key=api_key)
```

### 1.2 IBM Quantum import and initialization

If you are using an IBM Quantum device, first you will need to  [setup your IBM account](https://docs.q-ctrl.com/fire-opal/discover/start-using/get-started-with-fire-opal-on-ibm-quantum.md), then import the required libraries for this user guide.


```python
from qiskit import QuantumCircuit, qasm3
```

You can access devices on IBM Quantum via Fire Opal by signing up for an [IBM Quantum account](https://quantum.cloud.ibm.com/) and using your token and credentials to authenticate.


```python
# Insert your token and instance information
token = "YOUR_IBM_CLOUD_API_KEY"
instance = "YOUR_IBM_CRN"

# Create your credentials dictionary for hardware platform authentication
ibm_credentials = fo.credentials.make_credentials_for_ibm_cloud(
    token=token, instance=instance
)
```

### 1.3 IonQ through Amazon Braket import and initialization

If you are using an IonQ device, first you will need to [setup your AWS Braket environment](https://docs.q-ctrl.com/fire-opal/discover/start-using/get-started-with-fire-opal-on-ibm-quantum.md), then import the required libraries for this user guide.


```python
from braket.circuits.serialization import IRType
from braket.circuits import Circuit
from braket.aws import AwsDevice
```

On [Amazon Braket](https://aws.amazon.com/braket/), you can use the function `make_credentials_for_braket` to generate the credentials dictionary needed to execute jobs.


```python
arn = "your_role_arn"
braket_credentials = fo.credentials.make_credentials_for_braket(arn=arn)
```

## 2. Running a single job in Fire Opal

The following [entanglement](https://www.youtube.com/watch?v=JotTK1QoKUU) circuit demonstrates a basic example of how to code and run a job using the `execute` function. This function is limited to 300 circuits per batch.

### 2.1 Submitting a circuit with `execute` on IBM Quantum


```python
# Create a basic circuit with a Hadamard and a CNOT gate
qc = QuantumCircuit(2)
qc.h(0)
qc.cx(0, 1)
qc.measure_all()
qc.draw("mpl")
```

Be sure to [choose a backend](https://quantum.cloud.ibm.com/docs/en/guides/get-qpu-information) and replace `"desired_backend"` with the target name.


```python
# Define shots and desired backend (replace "desired_backend" with your backend)
shot_count = 1024
backend_name = "desired_backend"
```


```python
# Run the circuit with the execute function
fire_opal_job = fo.execute(
    circuits=[qasm3.dumps(qc)],
    shot_count=shot_count,
    credentials=ibm_credentials,
    backend_name=backend_name,
)
```


```python
fire_opal_job.result()
```

### 2.2 Submitting a circuit with `execute` on IonQ


```python
# Create a basic circuit with a Hadamard and a CNOT gate
qc = """
OPENQASM 3.0;
include "stdgates.inc";
bit[2] b;
qubit[2] q;
h q[0];
cx q[0], q[1];
b[0] = measure q[0];
b[1] = measure q[1];
"""
```


```python
circuit = Circuit.from_ir(qc)
print(circuit)
```

Use the function `show_supported_devices` to list the devices that are supported by Fire Opal and accessible to you, and choose a backend device.


```python
supported_devices = fo.show_supported_devices(credentials=braket_credentials)[
    "supported_devices"
]
for name in supported_devices:
    print(name)
```


```python
# Enter your desired IonQ backend here
shot_count = 1024
backend_name = "desired_backend"
print(f"Will run on backend: {backend_name}")
```


```python
fire_opal_job = fo.execute(
    circuits=[qc],
    shot_count=shot_count,
    credentials=braket_credentials,
    backend_name=backend_name,
)
```


```python
fire_opal_result = fire_opal_job.result()
```

## 3. Running multiple jobs in Fire Opal

The following code demonstrates a basic example of using iterate to submit multiple jobs on IBM Quantum. You can also refer to more in-depth guides on using `iterate` to run [batch workloads](https://docs.q-ctrl.com/fire-opal/execute/submit-jobs/how-to-run-batch-workloads.md) and [variational algorithms](https://docs.q-ctrl.com/fire-opal/execute/run-algorithms/how-to-run-custom-variational-algorithms.md).


```python
# Creating a parameterized circuit
from qiskit.circuit import Parameter

angle = Parameter("alpha")
param_qc = QuantumCircuit(1)
param_qc.rx(angle, 0)
param_qc.measure_all()
param_qc.draw("mpl")
```


```python
import numpy as np

# Generate sets of random values for the parameters
random_values = np.random.rand(500, 2)
parameter_dicts = [
    {param.name: val for param, val in zip(param_qc.parameters, values)}
    for values in random_values
]

# Split the dictionary of parameters to account for the max job size.
max_size = 300
result_arrays = np.array_split(
    parameter_dicts, np.ceil(len(parameter_dicts) / max_size)
)
```


```python
# Define the backend (replace "desired_backend" with your backend)
backend_name = "desired_backend"
# Submit jobs for each list of parameters
jobs = []
for param_array in result_arrays:
    fire_opal_job = fo.iterate(
        circuits=[qasm3.dumps(param_qc)],
        shot_count=1024,
        credentials=ibm_credentials,
        backend_name=backend_name,
        parameters=param_array.tolist(),
    )
    jobs.append(fire_opal_job)
```


```python
# Poll for results
results = []
for job in jobs:
    results.append(job.result()["results"])

# Stop iterating after all results are obtained
fo.stop_iterate(ibm_credentials, backend_name)
```

Using the `iterate` function in the manner shown above will group your jobs together in a single IBM Quantum session. Using a session reduces time spent in the hardware queue for multiple jobs, but may incur additional costs if the session is not closed by using `stop_iterate` promptly after results are obtained. If your workflow does not involve dependent iterations, an alternative is to submit your batches with `execute`.
