How to manage and monitor your calculations
Learn how to submit, cancel, and track the progress of 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 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.
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 and graph optimization, 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.
# 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 from it using the boulderopal.cloud.get_job function,
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 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 method, which returns a string indicating the job state.
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 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.
job.get_result(){'output': {'infidelity': {'value': 4.440892098500626e-16}},
'metadata': {'action_id': '2069184'}}
Cancelling a job
The BoulderOpalJob object also has a cancel method that you can use to stop the remote execution of the calculation on the Boulder Opal cloud.
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 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.
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, 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 function.
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.
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 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.
