QRMI Task Runner#

GitHub

QRMI Task Runner is an executable to run a quantum workload on the specified QPU resource. This is designed to be used in a Slurm job, configuration parameters such as endpoint URL and access credentials are taken from the process environment variables. Users can run a quantum workload in the form of Qiskit Primitive input (EstimatorV2, SamplerV2) for IBM Quantum System or Quantum Compute Service, or Pulser Sequence for Pasqal Cloud:

EstimatorV2 Schema (Body Parameter -> Schema 0 -> params -> EstimatorV2 input)
SamplerV2 Schema (Body Parameter -> Schema 0 > params -> SamplerV2 input)
Pulser Sequence

This executable receives SIGCONT/SIGTERM signals sent by Slurm infrastructure and cancels the running quantum workload.

Prerequisites#

Python 3.11, 3.12 or 3.13
Ensure the QRMI Python package is installed on your Python virtual environment.

Note

This document assumes your Python virtual environment is created under ~/py312_qrmi_venv directory.

How to run#

source ~/py312_qrmi_venv/bin/activate
task_runner -h
usage: task_runner [-h] name input [output]

qrmi_task_runner - Command to run a QRMI task

positional arguments:
  name        QPU resource name
  input       Input file
  output      Write output to <file> instead of stdout

options:
  -h, --help  show this help message and exit

Preparing input payload#

JSON schema definition is available in qrmi_payload_v1_schema.json.

Example - IBM Quantum System & Quantum Compute Service#

{
   "parameters": {"pubs": [["OPENQASM 3.0;\ninclude \"stdgates.inc\";\nrz(1.5707963267948966)...\n"]], "version": 2, "options": {"default_shots": 5000}},
   "program_id": "estimator"
}

Sample input files can be generated using the relevant tools.

Example - Pasqal Cloud#

{
   "sequence": {"version": "1", "name": "Sequence_with_defaults", "register": [{"name": "control..."}]},
   "job_runs": 1000
}

Sample input files can be generated by Pulser or the Qiskit-Pasqal-Provider.

Running QRMI task runner from Slurm job script#

The QPU resource name specified for task_runner must be one of those specified with the --qpu option. In the following example, 2 QPU resources are defined (ibm_torino and ibm_marrakesh) in the -qpu option, and one of them (ibm_marrakesh) is specified for task_runner.
The input payload must be specified as a file accessible from the compute nodes of the Slurm cluster.
The environment variables required for execution are set by the spank_qrmi at runtime. Users can override the settings by setting the environment variables ({backend_name}_QRMI_xxxx) listed in the following sections when executing the sbatch command.
By default, task results are output to stdout and written to the slurm-N.out file; if --output <file> is specified as task_runner arguments, results are written to that file.

IBM Quantum System or Quantum Compute Service#

Run estimator primitive on ibm_marrakesh.

#!/bin/bash

#SBATCH --job-name=qrmi_job
#SBATCH --ntasks=1
#SBATCH --cpus-per-task=1
#SBATCH --qpu=ibm_torino,ibm_marrakesh

source ~/py312_qrmi_venv/bin/activate
srun task_runner ibm_marrakesh /shared/input/estimator_input.json

Pasqal Cloud#

Run Pulser sequence on FRESNEL. This sequence can also be generated via the Qiskit Pasqal Provider, as shown in the examples.

#!/bin/bash

#SBATCH --job-name=qrmi_job
#SBATCH --ntasks=1
#SBATCH --cpus-per-task=1
#SBATCH --qpu=FRESNEL

source ~/py312_qrmi_venv/bin/activate
srun task_runner FRESNEL /shared/input/sequence_input_FRESNEL.json

Run locally for your testing#

You can run task_runner on your host locally for your development or testing by specifying parameters via environment variable setting like below.

IBM Quantum System#

Environment variables	Descriptions
`QRMI_JOB_QPU_RESOURCES`	Quantum backend name
`QRMI_JOB_QPU_TYPES`	Should be `ibm-quantum-system`
`{backend_name}_QRMI_IBM_QS_ENDPOINT`	Quantum System API endpoint URL
`{backend_name}_QRMI_IBM_QS_IAM_ENDPOINT`	IBM Cloud IAM endpoint URL (e.g. `https://iam.cloud.ibm.com`)
`{backend_name}_QRMI_IBM_QS_IAM_APIKEY`	IBM Cloud IAM API Key
`{backend_name}_QRMI_IBM_QS_SERVICE_CRN`	Cloud Resource Name (CRN) of the provisioned Quantum System API instance, starting with `crn:v1:`.
`{backend_name}_QRMI_IBM_QS_AWS_ACCESS_KEY_ID`	AWS Access Key ID to access S3 bucket
`{backend_name}_QRMI_IBM_QS_AWS_SECRET_ACCESS_KEY`	AWS Secret Access Key to access S3 bucket
`{backend_name}_QRMI_IBM_QS_S3_ENDPOINT`	S3 endpoint URL
`{backend_name}_QRMI_IBM_QS_S3_BUCKET`	S3 bucket name
`{backend_name}_QRMI_IBM_QS_S3_REGION`	S3 bucket region name (e.g. `us-east`)
`{backend_name}_QRMI_JOB_TIMEOUT_SECONDS`	Time (in seconds) after which job should time out and get cancelled. It is based on system execution time (not wall clock time). System execution time is the amount of time that the system is dedicated to processing your job.

Example:

source ~/py312_qrmi_venv/bin/activate

export QRMI_JOB_QPU_RESOURCES=test_heron
export QRMI_JOB_QPU_TYPES=ibm-quantum-system
export test_heron_QRMI_IBM_QS_ENDPOINT=http://localhost:8080
export test_heron_QRMI_IBM_QS_IAM_ENDPOINT=https://iam.cloud.ibm.com
export test_heron_QRMI_IBM_QS_IAM_APIKEY=<your API key>
export test_heron_QRMI_IBM_QS_SERVICE_CRN=<your instance>
export test_heron_QRMI_IBM_QS_AWS_ACCESS_KEY_ID=<your AWS access key ID>
export test_heron_QRMI_IBM_QS_AWS_SECRET_ACCESS_KEY=<your AWS secret access key>
export test_heron_QRMI_IBM_QS_S3_ENDPOINT=https://s3.us-east.cloud-object-storage.appdomain.cloud
export test_heron_QRMI_IBM_QS_S3_REGION=us-east
export test_heron_QRMI_IBM_QS_S3_BUCKET=<your bucket name>
export test_heron_QRMI_JOB_TIMEOUT_SECONDS=3600

task_runner test_heron /shared/input/estimator_input.json

Quantum Compute Service#

Environment variables	Descriptions
`QRMI_JOB_QPU_RESOURCES`	Quantum backend name
`QRMI_JOB_QPU_TYPES`	Should be `ibm-quantum-compute-service`
`{backend_name}_QRMI_IBM_QCS_ENDPOINT`	IBM Quantum Compute Service endpoint URL (e.g. `https://quantum.cloud.ibm.com/api/v1`)
`{backend_name}_QRMI_IBM_QCS_IAM_ENDPOINT`	IBM Cloud IAM endpoint URL (e.g. `https://iam.cloud.ibm.com`)
`{backend_name}_QRMI_IBM_QCS_IAM_APIKEY`	IBM Cloud IAM API Key
`{backend_name}_QRMI_IBM_QCS_SERVICE_CRN`	Cloud Resource Name (CRN) of the provisioned Quantum Compute Service instance, starting with `crn:v1:`.
`{backend_name}_QRMI_IBM_QCS_TIMEOUT_SECONDS`	(Optional) Cost of the job as the estimated time it should take to complete (in seconds). Should not exceed the cost of the program, default: `None`.

Example:

source ~/py312_qrmi_venv/bin/activate

export QRMI_JOB_QPU_RESOURCES=ibm_marrakesh
export QRMI_JOB_QPU_TYPES=ibm-quantum-compute-service
export test_heron_QRMI_IBM_QCS_ENDPOINT=https://quantum.cloud.ibm.com/api/v1
export test_heron_QRMI_IBM_QCS_IAM_ENDPOINT=https://iam.cloud.ibm.com
export test_heron_QRMI_IBM_QCS_IAM_APIKEY=<your API key>
export test_heron_QRMI_IBM_QCS_SERVICE_CRN=<your instance>

task_runner ibm_marrakesh /shared/input/estimator_input.json

Pasqal Cloud#

Environment variables	Descriptions
`QRMI_JOB_QPU_RESOURCES`	Backend name
`QRMI_JOB_QPU_TYPES`	Should be `pasqal-cloud`
`{backend_name}_QRMI_PASQAL_CLOUD_PROJECT_ID`	Pasqal Cloud Project ID to access the QPU
`{backend_name}_QRMI_PASQAL_CLOUD_AUTH_TOKEN`	Pasqal Cloud Auth Token
`{backend_name}_QRMI_PASQAL_CLOUD_CLIENT_ID`	Pasqal Cloud service account client ID (optional)
`{backend_name}_QRMI_PASQAL_CLOUD_CLIENT_SECRET`	Pasqal Cloud service account client secret (optional)
`{backend_name}_QRMI_PASQAL_CLOUD_AUTH_ENDPOINT`	(Optional) Auth endpoint URL/path for token retrieval. Default: `authenticate.pasqal.cloud/oauth/token`

Pasqal Cloud auth can also be provided via ~/.pasqal/config (token or username/password). PASQAL_CONFIG_ROOT may point elsewhere and takes priority over <backend_name>_PASQAL_CONFIG_ROOT; QRMI expands ~, $VAR, and ${VAR} before appending .pasqal/config. # pragma: allowlist secret

Example:

config#

username=<your username>
password=<your password>
# or:
# token=<your token>
# or:
# client_id=<your client id>
# client_secret=<your client secret>
#
# optional override:
# project_id=<your project id>
# auth_endpoint=<auth endpoint URL/path>

Example:

source ~/py312_qrmi_venv/bin/activate

export QRMI_JOB_QPU_RESOURCES=FRESNEL
export QRMI_JOB_QPU_TYPES=pasqal-cloud
export FRESNEL_QRMI_PASQAL_CLOUD_PROJECT_ID=<your project ID>
export FRESNEL_QRMI_PASQAL_CLOUD_AUTH_TOKEN=<your auth token>

task_runner FRESNEL /shared/input/sequence_input_FRESNEL.json

Alice & Bob#

Environment variables	Descriptions
`QRMI_JOB_QPU_RESOURCES`	Backend name
`QRMI_JOB_QPU_TYPES`	Should be `alice-bob-felis`
`{backend_name}_QRMI_AB_FELIS_BASE_ENDPOINT`	Felis URL
`{backend_name}_QRMI_AB_FELIS_API_KEY`	Felis API Key

Example:

source ~/py312_qrmi_venv/bin/activate

export QRMI_JOB_QPU_RESOURCES=ab_emu_1q_lescanne_2020
export QRMI_JOB_QPU_TYPES=alice-bob-felis
export ab_emu_1q_lescanne_2020_QRMI_AB_FELIS_BASE_ENDPOINT=<Felis URL>
export ab_emu_1q_lescanne_2020_QRMI_AB_FELIS_API_KEY=<Felis API Key>

task_runner ab_emu_1q_lescanne_2020 /shared/input/alice_bob_felis_input.json

License#

Apache-2.0