# How to manage and monitor your calculations

> Learn how to submit, cancel, and track the progress of your calculations

Source: https://docs.q-ctrl.com/boulder-opal/toolkit/discover/set-up/how-to-manage-and-monitor-your-calculations

A Boulder Opal job represents a single calculation.
There are two different ways in which a cloud calculation can be submitted in Boulder Opal.
The default behavior for all Boulder Opal functions is to submit the jobs **synchronously**, where the function waits (or "blocks execution") until the job finishes. However, some Boulder Opal functions support a `run_async` parameter, allowing you to submit the calculation **asynchronously** and retrieve the result at a later time.

In this user guide, we explain how to submit jobs both synchronously and asychronously.
We also introduce the [`BoulderOpalJob`](https://docs.q-ctrl.com/references/boulder-opal/boulderopal/cloud/BoulderOpalJob.md) object, used to manage, track, and cancel jobs.
Finally, we show you the different ways you can monitor your Boulder Opal activity.

## Submitting jobs

### Synchronous job submission

All Boulder Opal functions support **synchronous** job submission.
This is the default behavior, where the function will wait (or "block execution") until the job finishes. Once it's done, the function will return the result as a dictionary.


```python
import numpy as np
import boulderopal as bo

# Create a graph that runs a simple π-pulse simulation.
graph = bo.Graph()
amplitude = np.pi * 1e5  # rad/s
duration = 5e-6  # s
pi_pulse = graph.constant_pwc(amplitude, duration)
infidelity = graph.infidelity_pwc(
    hamiltonian=pi_pulse * graph.pauli_matrix("X"),
    target=graph.target(graph.pauli_matrix("X")),
    name="infidelity",
)

# Submit a synchronous calculation.
result = bo.execute_graph(graph, "infidelity")
print(result)
```

    Your task (action_id="2069183") has completed.
    {'output': {'infidelity': {'value': 4.440892098500626e-16}}, 'metadata': {'action_id': '2069183'}}


### Asynchronous job submission

Some Boulder Opal functions, those relating to [graph execution](https://docs.q-ctrl.com/references/boulder-opal/boulderopal/graph/execution.md) and [graph optimization](https://docs.q-ctrl.com/references/boulder-opal/boulderopal/graph/optimization.md), support a `run_async` parameter (which defaults to `False`), allowing to submit **asynchronous jobs**. In this case, the function doesn't wait for the calculation to finish.

This is particularly useful if you want to submit multiple jobs together or if you plan to retrieve the results later.


```python
# Submit an asynchronous calculation.
job = bo.execute_graph(graph, "infidelity", run_async=True)
print(job)
```

    Your task (action_id="2069184") is queued.
    <BoulderOpalJob: action_id="2069184">


In contrast to synchronous job submission, submitting an asynchronous job does not return the result. Instead, it returns a `BoulderOpalJob` object, which allows you to manage the job, such as checking its status, retrieving the results, and cancelling it. It is also possible to create a `BoulderOpalJob` object for a calculation submitted synchronously by using its Action ID.

We outline the steps for creating a `BoulderOpalJob` objects for a synchronous calculation, and explain how you can use it to manage any calculation below.

### Action IDs

Each call to a Boulder Opal function that involves an call to the Boulder Opal API is assigned a unique action ID, regardless of whether calculation was submited synchronoulsy or asynchronously.
These IDs are usually printed when you call the function, or you can find them in the **activity monitor**.
You can use the action ID later to manage the job.

In case you connection dropped during a calculation, you forgot to save your results, or you want to further manage a synchronous calculation, if you know a job's action ID, you can recreate a [`BoulderOpalJob`](https://docs.q-ctrl.com/references/boulder-opal/boulderopal/cloud/BoulderOpalJob.md) from it using the [`boulderopal.cloud.get_job`](https://docs.q-ctrl.com/references/boulder-opal/boulderopal/cloud/get_job.md) function,

```python
job = bo.cloud.get_job(action_id=2062679)
```

and then use the steps outlined below to retrieve its results, cancel it, ...

## Managing jobs with `BoulderOpalJob` objects

The [`BoulderOpalJob`](https://docs.q-ctrl.com/references/boulder-opal/boulderopal/cloud/BoulderOpalJob.md) object has various methods to manage the calculation they represent.

### Checking calculation status

You can check the status of a job using its [`get_status`](https://docs.q-ctrl.com/references/boulder-opal/boulderopal/cloud/BoulderOpalJob/get_status.md) method, which returns a string indicating the job state.


```python
job.get_status()
```

    Your task (action_id="2069184") has completed.





    'SUCCESS'



### Retrieving results

You can get the result of a job using its [`get_result`](https://docs.q-ctrl.com/references/boulder-opal/boulderopal/cloud/BoulderOpalJob/get_result.md) method.
This will return the calculation result in a dictionary, in the same format as it would have been returned if the calculation was submitted synchronously.

If the job isn't finished yet and you make this call, it will "block execution" and wait until the job is complete before returning the result.
However, if you decide you no longer want to wait for the job to finish, you can interrupt the process by pressing **Ctrl+C**. This will stop the wait in your Python interpreter, but the calculation will continue running on the Boulder Opal server.


```python
job.get_result()
```




    {'output': {'infidelity': {'value': 4.440892098500626e-16}},
     'metadata': {'action_id': '2069184'}}



### Cancelling a job

The [`BoulderOpalJob`](https://docs.q-ctrl.com/references/boulder-opal/boulderopal/cloud/BoulderOpalJob.md) object also has a [`cancel`](https://docs.q-ctrl.com/references/boulder-opal/boulderopal/cloud/BoulderOpalJob/cancel.md) method that you can use to stop the remote execution of the calculation on the Boulder Opal cloud.


```python
job = bo.execute_graph(graph, "infidelity", run_async=True)
job.cancel()
```

    Your task (action_id="2069185") has completed.
    Your task (action_id="2069185") has already completed, and cannot be cancelled.


### Submitting multiple simultaneous calculations

Asynchronous jobs allow you to submit multiple calculations at once without having to wait for each one in sequence.
While you can in principle submit as many asynchronous calculations as you want, the actual number of tasks that will run in parallel depends on your [Boulder Opal plan](https://q-ctrl.com/boulder-opal#boulder-plans) and the number of available machines in your environment.

To submit multiple jobs simultaneously you can, for instance, create a list of jobs, and retrieve their results afterwards.
You can find an example in [this user guide](https://docs.q-ctrl.com/boulder-opal/toolkit/design/design-model-based-controls/tune-optimization-hyperparameters/how-to-tune-the-learning-rate-of-a-stochastic-optimization.md#example-tuning-the-learning-rate-and-iteration-count-for-a-stochastic-optimization).


```python
jobs = [bo.execute_graph(graph, "infidelity", run_async=True) for _ in range(5)]
results = [job.get_result() for job in jobs]
```

    Your task (action_id="2069186") is queued.
    Your task (action_id="2069187") is queued.
    Your task (action_id="2069188") is queued.
    Your task (action_id="2069189") is queued.
    Your task (action_id="2069190") is queued.
    Your task (action_id="2069186") has completed.
    Your task (action_id="2069187") has completed.
    Your task (action_id="2069188") has completed.
    Your task (action_id="2069189") has completed.
    Your task (action_id="2069190") has completed.


## Monitoring calculations

You can track the progress of your current calculations and view a history of past ones using the **activity monitor**. This tool is available both through the **web app** or the **client package**.

### Web app

You can access the **activity monitor** in the [Boulder Opal web app](https://boulder.q-ctrl.com), simply log in.
You'll be able to see the status of both ongoing and past calculations, and you can interact with the interface to cancel any calculations that are queued or running.

### Client package

The activity monitor can also be accessed through the client package using the [`boulderopal.cloud.show_activity_monitor`](https://docs.q-ctrl.com/references/boulder-opal/boulderopal/cloud/show_activity_monitor.md) function.

```python
import boulderopal as bo

bo.cloud.show_activity_monitor()
```

```
                           Activity monitor                            
┏━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━┓
┃   Action name    ┃ Created UTC ┃ Updated UTC ┃ Run time ┃  Status   ┃
┡━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━┩
│ run_optimization │ 2023-10-13  │ 2023-10-13  │ 00:01:21 │ Completed │
│    ID 1628439    │  04:57:42   │  04:59:03   │          │           │
├──────────────────┼─────────────┼─────────────┼──────────┼───────────┤
│ run_optimization │ 2023-10-13  │ 2023-10-13  │ 00:01:21 │ Completed │
│    ID 1628438    │  04:57:41   │  04:59:03   │          │           │
├──────────────────┼─────────────┼─────────────┼──────────┼───────────┤
│   execute_graph  │ 2023-10-13  │ 2023-10-13  │ 00:00:50 │ Completed │
│    ID 1628437    │  04:57:40   │  04:58:30   │          │           │
├──────────────────┼─────────────┼─────────────┼──────────┼───────────┤
│   execute_graph  │ 2023-10-13  │ 2023-10-13  │ 00:00:50 │ Completed │
│    ID 1628436    │  04:57:39   │  04:58:30   │          │           │
├──────────────────┼─────────────┼─────────────┼──────────┼───────────┤
│ run_optimization │ 2023-10-13  │ 2023-10-13  │ 00:00:33 │ Completed │
│    ID 1628435    │  04:57:38   │  04:58:11   │          │           │
└──────────────────┴─────────────┴─────────────┴──────────┴───────────┘
```

Note that the times are displayed in [UTC](https://en.wikipedia.org/wiki/Coordinated_Universal_Time).
By default, the function shows the most recent actions you have run (if no filtering options are provided), but it also supports pagination and filtering by status.
You can learn more in the [`boulderopal.cloud.show_activity_monitor`](https://docs.q-ctrl.com/references/boulder-opal/boulderopal/cloud/show_activity_monitor.md) reference page.

The activity monitor table displays the action IDs of your calculations. You can use the steps outlined above to create a `BoulderOpalJob` from their action IDs and manage them.
