sampling ¶

A module to execute sampling on OQTOPUS Cloud.

Before sampling, sign up for OQTOPUS Cloud and create a configuration file in path ~/.oqtopus. See the description of :meth:OqtopusConfig.from_file method for how to write ~/.oqtopus file.

Examples:

To execute sampling 1000 shots on OQTOPUS Cloud, run the following code:

.. highlight:: python .. code-block:: python

from quri_parts.circuit import QuantumCircuit
from quri_parts_oqtopus.backend import OqtopusSamplingBackend

circuit = QuantumCircuit(2)
circuit.add_H_gate(0)
circuit.add_CNOT_gate(0, 1)

backend = OqtopusSamplingBackend()
job = backend.sample(circuit, n_shots=1000)
counts = job.result().counts
print(counts)

To execute with the transpiler setting on OQTOPUS Cloud, run the following code:

.. highlight:: python .. code-block:: python

from quri_parts.circuit import QuantumCircuit
from quri_parts_oqtopus.backend import OqtopusSamplingBackend

circuit = QuantumCircuit(2)
circuit.add_H_gate(0)
circuit.add_CNOT_gate(0, 1)

backend = OqtopusSamplingBackend()
job = backend.sample(circuit, n_shots=10000, transpiler="normal")
counts = job.result().counts
print(counts)

The specifications of the transpiler setting is as follows:

"none": no transpiler
"pass": use the "do nothing transpiler" (same as "none")
"normal": use default transpiler (by default)

You can also input OpenQASM 3.0 program.

.. highlight:: python .. code-block:: python

from quri_parts.circuit import QuantumCircuit
from quri_parts_oqtopus.backend import OqtopusSamplingBackend

qasm = """OPENQASM 3;
include "stdgates.inc";
qubit[2] q;

h q[0];
cx q[0], q[1];"""

backend = OqtopusSamplingBackend()
job = backend.sample_qasm(qasm, n_shots=1000)
counts = job.result().counts
print(counts)

To retrieve jobs already sent to OQTOPUS Cloud, run the following code:

.. highlight:: python .. code-block:: python

from quri_parts_oqtopus.backend import OqtopusSamplingBackend

job = backend.retrieve_job("<put target job id>")
counts = job.result().counts
print(counts)

Classes:

OqtopusSamplingBackend –

A OQTOPUS backend for a sampling measurement.
OqtopusSamplingJob –

A job for a sampling measurement.
OqtopusSamplingResult –

A result of a sampling job.

OqtopusSamplingBackend ¶

OqtopusSamplingBackend(config: OqtopusConfig | None = None)

A OQTOPUS backend for a sampling measurement.

Parameters:

config ¶
(OqtopusConfig | None, default: None ) –

A :class:OqtopusConfig for circuit execution. If this parameter is None and both environment variables OQTOPUS_URL and OQTOPUS_API_TOKEN exist, create a :class:OqtopusConfig using the values of the OQTOPUS_URL, OQTOPUS_API_TOKEN, and OQTOPUS_PROXY environment variables.

If this parameter is None and the environment variables do not exist, the default section in the ~/.oqtopus file is read.

Methods:

retrieve_job –

Retrieve the job with the given id from OQTOPUS Cloud.
sample –

Execute a sampling measurement of a circuit.
sample_qasm –

Execute sampling measurement of the program.

retrieve_job ¶

retrieve_job(job_id: str) -> OqtopusSamplingJob

Retrieve the job with the given id from OQTOPUS Cloud.

Parameters:

job_id ¶
(str) –

The id of the job to retrieve.

Returns:

OqtopusSamplingJob –

The job with the given job_id.

Raises:

BackendError –

If job cannot be found or if an authentication error occurred, etc.

sample ¶

sample(
    program: NonParametricQuantumCircuit
    | list[NonParametricQuantumCircuit],
    device_id: str,
    shots: int,
    name: str | None = None,
    description: str | None = None,
    transpiler_info: dict | None = None,
    simulator_info: dict | None = None,
    mitigation_info: dict | None = None,
) -> OqtopusSamplingJob

Execute a sampling measurement of a circuit.

The circuit is transpiled on OQTOPUS Cloud. The QURI Parts transpiling feature is not supported. The circuit is converted to OpenQASM 3.0 format and sent to OQTOPUS Cloud.

Parameters:

program ¶
(NonParametricQuantumCircuit | list[NonParametricQuantumCircuit]) –

The circuit to be sampled.
device_id ¶
(str) –

The device id to be executed.
shots ¶
(int) –

Number of repetitions of each circuit, for sampling.
name ¶
(str | None, default: None ) –

The name to be assigned to the job. Defaults to None.
description ¶
(str | None, default: None ) –

The description to be assigned to the job. Defaults to None.
transpiler_info ¶
(dict | None, default: None ) –

The transpiler information. Defaults to None.
simulator_info ¶
(dict | None, default: None ) –

The simulator information. Defaults to None.
mitigation_info ¶
(dict | None, default: None ) –

The mitigation information. Defaults to None.

Returns:

OqtopusSamplingJob –

The job to be executed.

sample_qasm ¶

sample_qasm(
    program: str | list[str],
    device_id: str,
    shots: int,
    name: str | None = None,
    description: str | None = None,
    transpiler_info: dict | None = None,
    simulator_info: dict | None = None,
    mitigation_info: dict | None = None,
    job_type: str | None = None,
) -> OqtopusSamplingJob

Execute sampling measurement of the program.

The program is transpiled on OQTOPUS Cloud. QURI Parts OQTOPUS does not support QURI Parts transpiling feature.

Parameters:

program ¶
(str | list[str]) –

The program to be sampled.
device_id ¶
(str) –

The device id to be executed.
shots ¶
(int) –

Number of repetitions of each circuit, for sampling.
name ¶
(str | None, default: None ) –

The name to be assigned to the job. Defaults to None.
description ¶
(str | None, default: None ) –

The description to be assigned to the job. Defaults to None.
transpiler_info ¶
(dict | None, default: None ) –

The transpiler information. Defaults to None.
simulator_info ¶
(dict | None, default: None ) –

The simulator information. Defaults to None.
mitigation_info ¶
(dict | None, default: None ) –

The mitigation information. Defaults to None.
job_type ¶
(str | None, default: None ) –

The job type. Defaults to None.

Returns:

OqtopusSamplingJob ( OqtopusSamplingJob ) –

The job to be executed.

Raises:

ValueError –

If shots is not a positive integer.
BackendError –

If job is wrong or if an authentication error occurred, etc.

OqtopusSamplingJob ¶

OqtopusSamplingJob(job: JobsJobDef, job_api: JobApi)

A job for a sampling measurement.

Parameters:

job ¶
(JobsJobDef) –

A result of dict type.
job_api ¶
(JobApi) –

A result of dict type.

Raises:

ValueError –

If job or job_api is None.

Methods:

cancel –

Cancel the job.
refresh –

Retrieve the latest job information from OQTOPUS Cloud.
result –

Wait until the job progress to the end and returns the result of the job.
to_json –

Return a json string representation of the OqtopusSamplingJob.
wait_for_completion –

Wait until the job progress to the end.

Attributes:

description (str) –

The description of the job.
device_id (str) –

The device id of the job.
ended_at (datetime) –

The ended_at of the job.
execution_time (float) –

The execution time of the job.
job_id (str) –

The id of the job.
job_info (dict) –

The detail information of the job.
job_type (str) –

The job type of the job.
mitigation_info (dict) –

The mitigation info of the job.
name (str) –

The name of the job.
ready_at (datetime) –

The ready_at of the job.
running_at (datetime) –

The running_at of the job.
shots (int) –

The shots of the job.
simulator_info (dict) –

The simulator info of the job.
status (str) –

The status of the job.
submitted_at (datetime) –

The submitted_at of the job.
transpiler_info (dict) –

The transpiler info of the job.

description `property` ¶

description: str

The description of the job.

Returns:

str ( str ) –

The description of the job.

device_id `property` ¶

device_id: str

The device id of the job.

Returns:

str ( str ) –

The device id of the job.

ended_at `property` ¶

ended_at: datetime

The ended_at of the job.

Returns:

datetime ( datetime ) –

The ended_at of the job.

execution_time `property` ¶

execution_time: float

The execution time of the job.

Returns:

float ( float ) –

The execution time of the job.

job_id `property` ¶

job_id: str

The id of the job.

Returns:

str ( str ) –

The id of the job.

job_info `property` ¶

job_info: dict

The detail information of the job.

Returns:

dict ( dict ) –

The detail information of the job.

job_type `property` ¶

job_type: str

The job type of the job.

Returns:

str ( str ) –

The job type of the job.

mitigation_info `property` ¶

mitigation_info: dict

The mitigation info of the job.

Returns:

dict ( dict ) –

The mitigation info of the job.

name `property` ¶

name: str

The name of the job.

Returns:

str ( str ) –

The name of the job.

ready_at `property` ¶

ready_at: datetime

The ready_at of the job.

Returns:

datetime ( datetime ) –

The ready_at of the job.

running_at `property` ¶

running_at: datetime

The running_at of the job.

Returns:

datetime ( datetime ) –

The running_at of the job.

shots `property` ¶

shots: int

The shots of the job.

Returns:

int ( int ) –

The shots of the job.

simulator_info `property` ¶

simulator_info: dict

The simulator info of the job.

Returns:

dict ( dict ) –

The simulator info of the job.

status `property` ¶

status: str

The status of the job.

Returns:

str ( str ) –

The status of the job.

submitted_at `property` ¶

submitted_at: datetime

The submitted_at of the job.

Returns:

datetime ( datetime ) –

The submitted_at of the job.

transpiler_info `property` ¶

transpiler_info: dict

The transpiler info of the job.

Returns:

dict ( dict ) –

The transpiler info of the job.

cancel ¶

cancel() -> None

Cancel the job.

If the job statuses are success, failure, or cancelled, then cannot be cancelled and an error occurs.

Raises:

BackendError –

If job cannot be found or if an authentication error occurred or if job cannot be cancelled, etc.

refresh ¶

refresh() -> None

Retrieve the latest job information from OQTOPUS Cloud.

Raises:

BackendError –

If job cannot be found or if an authentication error occurred or timeout occurs, etc.

result ¶

result(
    timeout: float | None = None, wait: float = 10.0
) -> OqtopusSamplingResult

Wait until the job progress to the end and returns the result of the job.

If the status of job is not succeeded or failed, or cancelled, the job is retrieved from OQTOPUS Cloud at intervals of wait seconds. If the job does not progress to the end after timeout seconds, raise :class:BackendError.

Parameters:

timeout ¶
(float | None, default: None ) –

The number of seconds to wait for job.
wait ¶
(float, default: 10.0 ) –

Time in seconds between queries.

Returns:

OqtopusSamplingResult ( OqtopusSamplingResult ) –

the result of the sampling job.

Raises:

BackendError –

If job cannot be found or if an authentication error occurred or timeout occurs, etc.

to_json ¶

to_json() -> str

Return a json string representation of the OqtopusSamplingJob.

Returns:

str ( str ) –

A json string representation of the OqtopusSamplingJob.

wait_for_completion ¶

wait_for_completion(
    timeout: float | None = None, wait: float = 10.0
) -> JobsJobDef | None

Wait until the job progress to the end.

Calling this function waits until the job progress to the end such as succeeded or failed, cancelled.

Parameters:

timeout ¶
(float | None, default: None ) –

The number of seconds to wait for job.
wait ¶
(float, default: 10.0 ) –

Time in seconds between queries.

Returns:

JobsJobDef | None –

JobsJobDef | None: If a timeout occurs, it returns None. Otherwise, it returns the Job.

OqtopusSamplingResult ¶

OqtopusSamplingResult(result: dict[str, Any])

A result of a sampling job.

Parameters:

result ¶
(dict[str, Any]) –

A result of dict type. This dict should have the key counts. The value of counts is the dict input for the counts. Where the keys represent a measured classical value and the value is an integer the number of shots with that result.

If the keys of counts is expressed as a bit string, then properties is a mapping from the index of bit string to the index of the quantum circuit.

Raises:

ValueError –

If counts does not exist in result.

Examples:

An example of a dict of result is as below:

.. code-block::

{
    "counts": {
        "0": 600,
        "1": 300,
        "3": 100,
    }
}

In the above case, the bit string representation of 0, 1, and 3 in the keys of counts is "00", "01", and "11" respectively. The LSB (Least Significant Bit) of the bit string representation is classical index=0.

Attributes:

counts (SamplingCounts) –

Returns the dict input for the counts.
divided_counts (dict | None) –

Returns divided_counts.

counts `property` ¶

counts: SamplingCounts

Returns the dict input for the counts.

divided_counts `property` ¶

divided_counts: dict | None

Returns divided_counts.

sampling ¶

OqtopusSamplingBackend ¶

config ¶

retrieve_job ¶

job_id ¶

sample ¶

program ¶

device_id ¶

shots ¶

name ¶

description ¶

transpiler_info ¶

simulator_info ¶

mitigation_info ¶

sample_qasm ¶

program ¶

device_id ¶

shots ¶

name ¶

description ¶

transpiler_info ¶

simulator_info ¶

mitigation_info ¶

job_type ¶

OqtopusSamplingJob ¶

job ¶

job_api ¶

description property ¶

device_id property ¶

ended_at property ¶

execution_time property ¶

job_id property ¶

job_info property ¶

job_type property ¶

mitigation_info property ¶

name property ¶

ready_at property ¶

running_at property ¶

shots property ¶

simulator_info property ¶

status property ¶

submitted_at property ¶

transpiler_info property ¶

cancel ¶

refresh ¶

result ¶

timeout ¶

wait ¶

to_json ¶

wait_for_completion ¶

timeout ¶

wait ¶

OqtopusSamplingResult ¶

result ¶

counts property ¶

divided_counts property ¶

`config` ¶

`job_id` ¶

`program` ¶

`device_id` ¶

`shots` ¶

`name` ¶

`description` ¶

`transpiler_info` ¶

`simulator_info` ¶

`mitigation_info` ¶

`program` ¶

`device_id` ¶

`shots` ¶

`name` ¶

`description` ¶

`transpiler_info` ¶

`simulator_info` ¶

`mitigation_info` ¶

`job_type` ¶

`job` ¶

`job_api` ¶

description `property` ¶

device_id `property` ¶

ended_at `property` ¶

execution_time `property` ¶

job_id `property` ¶

job_info `property` ¶

job_type `property` ¶

mitigation_info `property` ¶

name `property` ¶

ready_at `property` ¶

running_at `property` ¶

shots `property` ¶

simulator_info `property` ¶

status `property` ¶

submitted_at `property` ¶

transpiler_info `property` ¶

`timeout` ¶

`wait` ¶

`timeout` ¶

`wait` ¶

`result` ¶

counts `property` ¶

divided_counts `property` ¶