How to use Qibocal?

In this section we present the different commands implemented in Qibocal and how to use them.

qq acquire

qq acquire is used to perform the data acquisition for each protocol. You can execute the qq acquire command using the following syntax:

qq acquire <path_to_runcard>

where <path_to_runcard> is the relative path to runcard, a yaml file containing all the instructions required to execute a set of protocols. The runcard layout is specified in the this section.

The data will be collected in an output folder, in the same directory where the command was executed, with a default name YYYY-MM-DD-xxx-username where xyz are three integers starting from 000 and username is the name of the user that is launching. If a folder with the same name already exists the program will try to create folder where the combination xyz is incremented by 1, until a new folder is created.

There is also the option to specify the name of the output folder through the -o option.

qq acquire <path_to_runcard> -o <output_folder>

It is possible to overwrite an existing folder using the option -f.

qq fit

This command is used to perform a post-processing analysis on a given output folder generated by qq acquire.

qq fit <output_folder>

If the <output-folder> already contains post-processing files they can be overwritten using -f. It is also possible to generate a separate folder with the output folder generated by qibocal with the updated fitting parameters using -o <new_output_folder>. If such folder exists it can be overwritten with -f.

qq report

This command produces an index.html file inside the output folder which contains a report with all the information regarding the protocols executed.

qq report <output_folder>

Session and protocol notes

Qibocal stores comment histories separately from acquisition data and fitting results. notes.json in the output folder contains session comments; data/<task-id>/notes.json contains comments for one protocol execution (including its iteration, for example data/flipping-0/notes.json). Each file is a JSON array of objects with content, an ISO 8601 timestamp in UTC, and an optional author (null when unspecified). Regular execution leaves these histories empty. Older outputs without these files load with empty histories.

Comments can be appended explicitly through the Python API:

from pathlib import Path
from qibocal import Note
from qibocal.auto.output import Output

path = Path("output_folder")
output = Output.load(path)
output.notes.append(Note(content="Calibration session reviewed."))
output.dump_notes(path)

task_id = next(iter(output.history))
completed = output.history[task_id]
completed.notes.append(Note(content="Fit reviewed.", author="calibration-agent"))
completed.notes.append(Note(content="Follow-up: additional acquisition needed."))
completed.dump_notes()

Output.dump also saves session and protocol histories. Notes are retained when fitting or refitting existing outputs, including fitting into a copied output folder. Executor.notes holds session notes during managed execution, while Completed.notes is also available for direct protocol execution; saving protocol notes requires an output folder set as Completed.path.

Notes are immutable records; append new notes to retain earlier findings. Nonempty content and timezone-aware timestamps are required. Timestamps default to the current UTC time, and supplied timestamps are normalized to UTC. Author identity is supplied by callers, not authenticated by Qibocal. These APIs replace the stored list when saving; callers managing concurrent writes must coordinate them. Report display, authenticated editing, and automatic agent annotation are handled outside this persistence API.

qq run

The previous commands are put together using qq run which will perform data acquisition, post-processing and report generation. When executing multiple protocols they are executed following the actions specified in the runcard.

qq run <path_to_runcard> -o <output_folder>

qq update

Using qq update it is possible to update the platform calibrated by Qibocal. The correct syntax is the following

qq update <output_folder>

which will copy the configuration of the platform in the corresponding directory specified using the environment variable QIBOLAB_PLATFORMS. See the Qibolab documentation for more details.

Note

It is possible to skip the update for certain qubits, which might be helpful when the fitting is failing only for some qubits, using the --skip-qubits options. For example to skip the update on qubit 0 it is sufficient to use the following command:

qq update <output_folder> --skip-qubits 0

qq upload

Using qq upload it is possible to upload the output folder generated by qq on this web page, which collects all reports uploaded by other users as well.

qq upload <output_folder>

In order to upload the report to a centralized server, send to the server administrators your public ssh key (from the machine(s) you are planning to upload the report) and then use the qq upload <output_folder> command. You can also add a tag to be displayed on the server using qq upload <output_folder> --tag <tag_name>. This program will upload your report to the server and generate an unique URL.

qq compare

Using qq compare it is possible to compare together two Qibocal reports.

qq compare <output_folder_1> <output_folder_2>

The folder with the report comparison can be specified with the option -o, otherwise a default name will be assigned similarly to the qq acquire command.