API Reference

bluequbit.init(api_token=None, execution_mode=None)

Returns BQClient instance for managing jobs on BlueQubit platform.

Parameters:

  • api_token (str | None) – API token of the user. If None, the token will be looked in the environment variable BLUEQUBIT_API_TOKEN.

  • execution_mode (str | None) – Execution mode. Can be "cloud", "local" or None. If None, the environment variable BLUEQUBIT_EXECUTION_MODE will be used if set, otherwise "cloud" will be used.

Return type:

BQClient

class bluequbit.BQClient(api_token=None, execution_mode=None)

Client for managing jobs on BlueQubit platform.

Parameters:

  • api_token (str | None) – API token of the user. If None, the token will be looked in the environment variable BLUEQUBIT_API_TOKEN.

  • execution_mode (str | None) – Execution mode. Can be "cloud", "local" or None. If None, the environment variable BLUEQUBIT_EXECUTION_MODE will be used if set, otherwise "cloud" will be used.

estimate(circuits, device='cpu')

Estimate job runtime

Parameters:

  • circuits (Cirq, Qiskit, list) – quantum circuit or circuits

  • device (str) – device for which to estimate the circuit. Can be one of "cpu" | "gpu" | "quantum"

Returns:

result or results estimate metadata

Return type:

EstimateResult | list[EstimateResult]

run(circuits, device='cpu', *, asynchronous=False, job_name=None, shots=None, pauli_sum=None, options=None)

Submit a job to run on BlueQubit platform

Parameters:

  • circuits (Cirq, Qiskit, list) – quantum circuit or list of circuits

  • device (str) – device on which to run the circuit. Can be one of "cpu" | "gpu" | "quantum" | "mps.cpu" | "mps.gpu"

  • asynchronous (bool) – if set to False, wait for job completion before returning. If set to True, return immediately

  • job_name (str | None) – customizable job name

  • shots (int | None) – number of shots to run. If device is quantum and shots is None then it is set to 1000. For non quantum devices, if None, full probability distribution will be returned. For mps.cpu and mps.gpu devices it is limited to 1000000, for all other devices it is limited to 100000

  • pauli_sum (list[tuple[str, float]] | str | list[list[tuple[str, float]] | str] | None) – The Pauli sum or a list of Pauli sum which expectation value is the computation result

  • options (dict | None) –

    dictionary of options used to configure the run:

    • mps_bond_dimension (int): Sets a limit on the number of Schmidt coefficients retained at the end of the svd algorithm. Coefficients beyond this limit will be discarded. Default: None (no limit on the bond dimension). Applicable only to "mps.cpu" and "mps.gpu" devices.

    • mps_truncation_threshold (float): Discard the smallest coefficients for which the sum of their squares is smaller than this threshold. Default: 1e-16. Applicable only to "mps.cpu" and "mps.gpu" devices.

Returns:

job or jobs metadata

Return type:

JobResult | list[JobResult]

wait(job_ids)

Wait for job completion

Parameters:

job_ids (str | list[str] | JobResult | list[JobResult]) – job IDs that can be found as property of JobResult metadata of run() method, or JobResult instances from which job IDs will be extracted

Returns:

job metadata

Return type:

JobResult | list[JobResult]

get(job_ids)

Get current metadata of jobs

Parameters:

job_ids (str | list[str] | JobResult | list[JobResult]) – job IDs that can be found as property of JobResult metadata of run() method

Returns:

jobs metadata

Return type:

JobResult | list[JobResult]

cancel(job_ids)

Submit jobs cancel request

Parameters:

job_ids (str | list[str] | JobResult | list[JobResult]) – job IDs that can be found as property of JobResult metadata of run() method

Returns:

job or jobs metadata

Return type:

JobResult | list[JobResult]

search(run_status=None, created_later_than=None, batch_id=None)

Search jobs

Parameters:

  • run_status (str | None) – if not None, run status of jobs to filter. Can be one of "FAILED_VALIDATION" | "PENDING" | "QUEUED" | "RUNNING" | "TERMINATED" | "CANCELED" | "NOT_ENOUGH_FUNDS" | "COMPLETED"

  • created_later_than (str | datetime.datetime | None) – if not None, filter by latest job creation datetime. Please add timezone for clarity, otherwise UTC will be assumed

  • batch_id (str | None) – if not None, filter by batch ID

Returns:

metadata of jobs

Return type:

list[JobResult]

class bluequbit.JobResult(data, _backend_connection=None)

This class contains information from a job run on quantum hardware or quantum simulators. Mainly it contains the resulting statevector from the run. It might contain only partial information, such as job ID, when BQClient.run() is called with asynchronous=True.

job_id

str: job id

batch_id

str: batch id

job_name

str: job name

device

str: run device

estimated_runtime

int: estimated runtime in milliseconds

estimated_cost

float: estimated cost in US dollars

created_on

datetime: job creation date in UTC timezone

top_100k_results

dict: top 131072 (2^17) results

top_128_results

dict: top 128 results

num_qubits

int: number of qubits

num_qubits_used

int: number of used qubits

pauli_sum

list[tuple[str, float]]: expectation value

expectation_value

float | list[float]: expectation value

queue_time_ms

int: job queue time in milliseconds

run_time_ms

int: job runtime in milliseconds

error_message

str: error message if failed

cost

float: job cost in US dollars

has_statevector

bool: if statevector available

circuit

Cirq, Qiskit, dict: original circuit

shots

int: number of shots specified during the job submission

get_statevector()

Return statevector of the job. If the statevector is too large then throws exception.

Return type:

NumPy array

get_counts()

If shots argument in bq.run() was not None, return a number of samples from the measurements, otherwise, measurement probabilities of the computation result, without any statistical fluctuation are returned. In both cases only top 131072 (2^17) results are returned.

Return type:

dict[str, float]

property ok: bool

True, if job’s current run status is "COMPLETED", else False.

class bluequbit.EstimateResult(data)

This class contains information about the estimated runtime/cost that will be incurred from running the given circuit on the given quantum machine/simulator. WARNING: this is just an estimate, the actual runtime/cost may be less or more.

estimated_runtime

int: estimated runtime in milliseconds

estimated_cost

float: estimated cost in US dollars

num_qubits

int: number of qubits

warning_message

str: warning message

error_message

str: error message if available

class bluequbit.BlueQubitProvider(api_token=None)

A Qiskit provider for accessing BlueQubit backend.

Parameters:

api_token (str | None) – API token of the user. If None, the token will be looked in the environment variable BLUEQUBIT_API_TOKEN.

get_backend(execution_mode=None)
Parameters:

execution_mode (str | None) – Execution mode. Can be "cloud", "local" or None. If None, the environment variable BLUEQUBIT_EXECUTION_MODE will be used if set, otherwise "cloud" will be used.

Exceptions

All exceptions reside in bluequbit.exceptions module and inherit from base bluequbit.exceptions.BQError class.

  • BQJobInvalidDeviceTypeError

  • BQJobNotCompleteError

  • BQJobStatevectorTooLargeError

  • BQJobHasNotFinishedYetError

  • BQJobDoesNotContainCountsError

  • BQJobCouldNotCancelError

  • BQAPIError

  • BQUnauthorizedAccessError