Welcome to the repository for the Quantum Inspire tool. The goal of this project to offer basic support for interacting with the Quantum Inspire platform. For example, you can manage your projects, algorithms and jobs on the Quantum Inspire system from your command line, or using the API directly in your Python code.
The tool is required for logging in to the Quantum Inspire systems. For example, if you would like to use the QI Qiskit or Pennylane plugins.
The recommended way of installing the CLI is to use pipx. (Conda users should refer to the subsection below). After following the pipx installation instructions, run the following command:
pipx install quantuminspireAfterwards, running qi --help should show a help menu.
Note
If your python version is newer then supported by quantuminspire, please run the following command: pipx install quantuminspire --python /path/to/python3.12.
Check which versions of python are supported by the tool.
Warning
Installing quantuminspire using pipx inside a conda environment may cause conflicts with other packages. This can result in unexpected behavior and prevent you from using the tool correctly. To avoid these issues, it is recommended to instead create a Conda environment from an environment.yml file.
Check you Conda version with conda --version, then run the appropriate command:
Conda >= 26.3:
conda create --file https://conda.quantum-inspire.com/cli.ymlConda < 26.3:
conda env create --file https://conda.quantum-inspire.com/cli.ymlBy default, the environment that will be created will be named quantuminspire; use the -n/--name <CUSTOM-ENV-NAME> option to overwrite this.
After creating the environment, you need to activate it (use your custom environment name if you have defined it):
conda activate quantuminspireIn order to login to the platform, run the following command:
qi loginThis will open a browser window that will allow you to login or create an account. By default this command will login to the production environment, but the command accepts an argument for a different host URL if needed (e.g. for beta testing purposes).
Warning
If after installing latest version, you recieve errors with respect to token validity, please run qi logout and then again log in using qi login
To log out from the platform, run:
qi logoutIf no hostname is specified, the default host is used.
To run a job on Quantum Inspire without persisting any settings, provide a file and a backend type ID:
qi run --file <path to .cq or .py file> --backend-type-id <int>This will return a job ID. You can optionally specify --num-shots, --store-raw-data, and --name. Use --persist together with --name to store the project and algorithm settings locally for repeated use.
If you use the --persist flag, you first have to initialize a project with qi projects init <name>.
IMPORTANT: Submitting a (python) .py file for hybrid algorithms requires a specific format.
Not all .py files are valid for submission.
Create a new project on the platform and store its settings locally in the current working directory (project root):
qi projects init <name> [description]Initialize a project with only a name:
qi projects init "My Project"Initialize a project with a name and description:
qi projects init "My Project" "Optional description"List all projects belonging to the current user. You can optionally filter projects by name, either using substring matching (default) or exact matching.
qi projects list-
--quiet, -qOnly print the IDs of the projects. -
--name <name>Filter projects by name or description using substring matching. -
--exactWhen used with--name, only return projects whose name exactly matches the given value.
List all projects:
qi projects listList projects whose name or description contains "quantum":
qi projects list --name quantumList projects whose name is exactly "my-project":
qi projects list --name my-project --exactPrint only the project IDs:
qi projects list --quietDelete one or more projects by ID, by name, or delete all projects after confirmation.
⚠️ Deleting projects is irreversible. You will always be prompted for confirmation before deletion.
qi projects delete [PROJECT_IDS...]-
PROJECT_IDSOne or more project IDs to delete. -
--name <name>Delete projects matching this name or description pattern. -
--exactWhen used with--name, only delete projects whose name exactly matches the given value.
-
If project IDs are provided,
--nameand--exactare ignored. -
If no IDs are provided:
--namefilters projects by substring match--name+--exactperforms an exact name match
-
If no IDs and no name are provided, all projects will be deleted after confirmation.
Delete projects by ID:
qi projects delete 1 2 3Delete projects whose name or description contains "quantum":
qi projects delete --name quantumDelete the project with the exact name "my-project":
qi projects delete --name my-project --exactUse list and delete together to delete projects by name:
qi projects delete $(qi projects list --name quantum --quiet)Delete all projects:
qi projects deleteAlgorithms allow you to persist settings (file path, backend type, number of shots, raw-data flag) locally for repeated job submission. Algorithms must belong to a project initialized with qi projects init.
You can get the status, results and final result using the algorithm name. This will retrieve the specified resource for the latest job that was run using the algorithm. If you want to retrieve a resource for a specific job, use the qi jobs commands instead.
qi algorithms init <name> <path> <backend_type_id>qi algorithms status <algorithm_name>Use --wait and --timeout <seconds> to wait for the job to complete.
qi algorithms logs <algorithm_name>Use --n-logs to return early if you already know how many logs you expected, --poll-interval <seconds> to set the polling interval (default: 5s) and --timeout <seconds> to set the timeout (default: 30s).
qi algorithms results <algorithm_name>Use --save to save the results to a JSON file in the current directory.
qi algorithms final-result <algorithm_name>Use --save to save the final result to a JSON file in the current directory.
Note: This object will always be generated. In the case of a quantum circuit, the result and final result will be the same. For hybrid algorithms, the final result is a free form datastructure that could for example be used for the aggregation of data. This is generated in the finalize step.
Jobs are created when you run qi run. Use the job ID printed by that command to check status and retrieve results.
You can also get the status, results and final result using the algorithm name with the qi algorithms commands. This will retrieve the specified resource for the latest job that was run using the algorithm.
Show all properties of a specific job:
qi jobs inspect <job_id>qi jobs status <job_id>Use --wait to wait for the job to complete before returning, and --timeout <seconds> to set the timeout (default: 60).
qi jobs logs <job_id>Use --n-logs to return early if you already know how many logs you expected, --poll-interval <seconds> to set the polling interval (default: 5s) and --timeout <seconds> to set the timeout (default: 30s).
qi jobs results <job_id>Use --save to save the results to a JSON file in the current directory.
A job also always contains a final result. This object can be queried with the following command.
qi jobs final-result <job_id>Use --save to save the final result to a JSON file in the current directory.
Note: This object will always be generated. In the case of a quantum circuit, the result and final result will be the same. For hybrid algorithms, the final result is a free form datastructure that could for example be used for the aggregation of data. This is generated in the finalize step.
The list of backends (and some of their properties) can be retrieved using the following command, from which the id field can be read.
qi backends listTo see all properties of a specific backend, use:
qi backends get <backend-type-id>The CLI can be used to compile cQASM (.cq) files against a specific backend type.
IMPORTANT: Hybrid Python (.py) files are not supported for compilation.
qi files compile --file <filename> --backend-type-id <int>You can optionally specify a --compile-stage to control up to which stage the algorithm is compiled (default: Decomposition). Alternatively, provide --name to use the settings of a previously initialized algorithm.
qi config get <key>Use --algorithm <name> to retrieve a setting for a specific algorithm.
qi config set <key> <value>Use --algorithm <name> to set a setting for a specific algorithm, or --user to set a global user-level setting (e.g. default_host).