quri_parts.qiskit.backend package#

class QiskitSamplingBackend(backend, circuit_converter=<function convert_circuit>, circuit_transpiler=None, enable_shots_roundup=True, qubit_mapping=None, run_kwargs={}, save_data_while_sampling=False)#

Bases: SamplingBackend

A Qiskit backend for a sampling measurement.

Parameters:

  • backend (Backend) – A Qiskit qiskit.providers.backend.Backend for circuit execution.

  • circuit_converter (QiskitCircuitConverter) – A function converting NonParametricQuantumCircuit to a Qiskit qiskit.circuit.QuantumCircuit.

  • circuit_transpiler (Optional[CircuitTranspiler]) – A transpiler applied to the circuit before running it. QiskitSetTranspiler is used when not specified.

  • enable_shots_roundup (bool) – If True, when a number of shots specified to sample() is smaller than the minimum number of shots supported by the device, it is rounded up to the minimum. In this case, it is possible that shots more than specified are used. If it is strictly not allowed to exceed the specified shot count, set this argument to False.

  • qubit_mapping (Optional[Mapping[int, int]]) – If specified, indices of qubits in the circuit are remapped before running it on the backend. It can be used when you want to use specific backend qubits, e.g. those with high fidelity. The mapping should be specified with “from” qubit indices as keys and “to” qubit indices as values. For example, if you want to map qubits 0, 1, 2, 3 to backend qubits as 0 → 4, 1 → 2, 2 → 5, 3 → 0, then the qubit_mapping should be {0: 4, 1: 2, 2: 5, 3: 0}.

  • run_kwargs (Mapping[str, Any]) – Additional keyword arguments for qiskit.providers.backend.Backend.run() method.

  • save_data_while_sampling (bool) – If True, the circuit, n_shots and the sampling counts will be saved. Please use the .jobs or .jobs_json to access the saved data.

sample(circuit, n_shots)#

Perform a sampling measurement of a circuit.

Parameters:
Return type:

SamplingJob

property jobs: Sequence[QiskitSavedDataSamplingJob]#

Convert saved data to a list of QiskitSavedDataSamplingJob objects.

property jobs_json: str#

Encodes the list of QiskitSavedDataSamplingJob objects to a json string.

class QiskitSamplingJob(qiskit_job)#

Bases: SamplingJob

A job for a Qiskit sampling measurement.

Parameters:

qiskit_job (Job) –

result()#

Returns the result of the sampling job.

If the job is not complete, this method waits until the job finishes.

Return type:

SamplingResult

class QiskitSamplingResult(qiskit_result)#

Bases: SamplingResult

A result of a Qiskit sampling job.

Parameters:

qiskit_result (Result) –

property counts: backend.SamplingCounts#

Measurement counts obtained by a sampling measurement.

class QiskitRuntimeSamplingBackend(backend, service=None, circuit_converter=<function convert_circuit>, circuit_transpiler=None, enable_shots_roundup=True, qubit_mapping=None, sampler_options=None, run_kwargs={}, save_data_while_sampling=False, total_time_limit=None, single_job_max_execution_time=None, strict_time_limit=False)#

Bases: SamplingBackend

A Qiskit backend for a sampling measurement.

Parameters:

  • backend (IBMBackend) – A Qiskit qiskit_ibm_runtime.ibm_backend that interfaces with IBM quantum backend.

  • service (Optional[QiskitRuntimeService]) – A Qiskit

  • circuit_converter (QiskitCircuitConverter) –

  • circuit_transpiler (Optional[CircuitTranspiler]) –

  • enable_shots_roundup (bool) –

  • qubit_mapping (Optional[Mapping[int, int]]) –

  • sampler_options (Union[None, Options, Dict[str, Any]]) –

  • run_kwargs (Mapping[str, Any]) –

  • save_data_while_sampling (bool) –

  • total_time_limit (Optional[int]) –

  • single_job_max_execution_time (Optional[int]) –

  • strict_time_limit (bool) –

:param qiskit_ibm_runtime.qiskit_runtime_service.QiskitRuntimeService: :param that interacts with the Qiskit Runtime service.: :param circuit_converter: A function converting

NonParametricQuantumCircuit to a Qiskit qiskit.circuit.QuantumCircuit.

Parameters:

  • circuit_transpiler (Optional[CircuitTranspiler]) – A transpiler applied to the circuit before running it. QiskitTranspiler is used when not specified.

  • enable_shots_roundup (bool) – If True, when a number of shots specified to sample() is smaller than the minimum number of shots supported by the device, it is rounded up to the minimum. In this case, it is possible that shots more than specified are used. If it is strictly not allowed to exceed the specified shot count, set this argument to False.

  • qubit_mapping (Optional[Mapping[int, int]]) – If specified, indices of qubits in the circuit are remapped before running it on the backend. It can be used when you want to use specific backend qubits, e.g. those with high fidelity. The mapping should be specified with “from” qubit indices as keys and “to” qubit indices as values. For example, if you want to map qubits 0, 1, 2, 3 to backend qubits as 0 → 4, 1 → 2, 2 → 5, 3 → 0, then the qubit_mapping should be {0: 4, 1: 2, 2: 5, 3: 0}.

  • sampler_options (Union[None, Options, Dict[str, Any]]) – Options for providing sampler. It can be a dictionary or a qiskit_ibm_runtime.Options.

  • run_kwargs (Mapping[str, Any]) – Additional keyword arguments for qiskit.providers.backend.Backend.run() method.

  • save_data_while_sampling (bool) – If True, the circuit, n_shots and the sampling counts will be saved. Please use the .jobs or .jobs_json to access the saved data.

  • total_time_limit (Optional[int]) –

    The total time limit the jobs submitted by this backend can use.

    • A Tracker is created when the time limit is set. The tracker can be accessed by the .tracker attribute.

    • If the job execution time exceeds the time limit, new call to the sample() will be rejected and all current running jobs will be cancelled.

  • single_job_max_execution_time (Optional[int]) – Maximum execution time limit of a submitted (circuit, n_shot) pair. The value should be greater or equal to 300 seconds.

  • strict_time_limit (bool) – The Runtime backend can only abort jobs that has been executed longer than 300 seconds or above. If this option is set to True, the sampling backend will reject jobs whose time limit setting is less than 300 seconds.

  • backend (IBMBackend) –

  • service (Optional[QiskitRuntimeService]) –

  • circuit_converter (QiskitCircuitConverter) –

close()#

Close the IBM session.

This will terminate all unfinished jobs.

Return type:

None

sample(circuit, n_shots)#

Perform a sampling measurement of a circuit.

Parameters:
Return type:

SamplingJob

property jobs: Sequence[QiskitSavedDataSamplingJob]#

Convert saved data to a list of QiskitSavedDataSamplingJob objects.

property jobs_json: str#

Encodes the list of QiskitSavedDataSamplingJob objects to a json string.

class QiskitRuntimeSamplingJob(qiskit_job)#

Bases: SamplingJob

A job for a Qiskit sampling measurement.

Parameters:

qiskit_job (RuntimeJob) –

result()#

Returns the result of the sampling job.

If the job is not complete, this method waits until the job finishes.

Return type:

SamplingResult

class QiskitRuntimeSamplingResult(qiskit_result)#

Bases: SamplingResult

Class for the results by Qiskit sampler job.

Parameters:

qiskit_result (SamplerResult) –

property counts: backend.SamplingCounts#

Measurement counts obtained by a sampling measurement.

class QiskitRuntimeSavedDataSamplingResult(quasi_dist, n_shots)#

Bases: SamplingResult

An object that holds quasi disttribution and total shot count from qiskit runtime output and converts it into quri-parts sampling count.

Parameters:

  • quasi_dist (dict[int, float]) – The first element of the quasi_dists attribute of a qiskit.primitives.SamplerResult object.

  • n_shots (int) – The metadata[0][“shots”] output of a qiskit.primitives.SamplerResult object.

quasi_dist: dict[int, float]#
n_shots: int#
property counts: backend.SamplingCounts#

Measurement counts obtained by a sampling measurement.

device_connectivity_graph(device)#
Parameters:

device (BackendV1 | BackendV2) –

Return type:

Graph

class QiskitSavedDataSamplingJob(circuit_qasm, n_shots, saved_result)#

Bases: SamplingJob

An object that represents a saved sampling job.

Parameters:

  • circuit_qasm (str) – A string that represents the circuit used in a sampling job. Note that it should take in the qasm string of a qiskit quantum circuit. It can be accessed by qiskit.qasm3.dumps(qiskit_circuit).

  • n_shots (int) – The total shots of a sampling job.

  • saved_result (QiskitSavedDataSamplingResult | QiskitRuntimeSavedDataSamplingResult) – A QiskitSavedDataSamplingResult instance that represents the result when (circuit_str, n_shots) is passed into the sampler.

circuit_qasm: str#
n_shots: int#
saved_result: QiskitSavedDataSamplingResult | QiskitRuntimeSavedDataSamplingResult#
result()#

Returns the result of the sampling job.

If the job is not complete, this method waits until the job finishes.

Return type:

QiskitSavedDataSamplingResult | QiskitRuntimeSavedDataSamplingResult

class QiskitSavedDataSamplingResult(raw_data)#

Bases: SamplingResult

An object that holds a sampling count from qiskit backend output and converts it into quri-parts sampling count.

The raw_data should take in the output of qiskit_result.get_counts(), which is a counter that uses str as its key.

Parameters:

raw_data (dict[str, int]) –

raw_data: dict[str, int]#
property counts: backend.SamplingCounts#

Convert the raw data to quri-parts sampling count.

The quri-parts sampling count is a counter that uses int as its key.

class QiskitSavedDataSamplingBackend(backend, saved_data, circuit_converter=<function convert_circuit>, circuit_transpiler=None, enable_shots_roundup=True, qubit_mapping=None, run_kwargs={})#

Bases: SamplingBackend

A Qiskit backend for replaying saved sampling experiments. When a sampler is created with a QiskitSavedDataSamplingBackend object, the sequence of (circuit, n_shots) pairs should be passed in to the sampler the same order as the orginal experiment.

Example

  1. Sampling experiment

1-a: Sampling mode with data saving

>>> backend_device = AerSimulator()
>>> sampling_backend = QiskitSamplingBackend(
...     backend_device, save_data_while_sampling=True
... )
>>> sampler = create_sampler_from_sampling_backend(sampling_backend)

1-b: Perform sampling experiments

>>> sampling_count_1 = sampler(circuit_1, n_shots_1)
>>> sampling_count_2 = sampler(circuit_2, n_shots_2)
>>> sampling_count_3 = sampler(circuit_3, n_shots_3)

1-c: Dump sampling data

>>> experiment_json_str = sampling_backend.jobs_json()

  1. Replay sampling experiment

2-a: Create sampling backend and sampler with saved data.

>>> saved_data_sampling_backend = QiskitSavedDataSamplingBackend(
...     backend = backend_device,
...     saved_data = experiment_json_str
... )

>>> saved_data_sampler = create_sampler_from_sampling_backend(
...    saved_data_sampling_backend
... )

2-b: Replay sampling experiment.

(circuit, n_shots) pairs are passed in to the saved_data_sampler the same order as they were passed in to the sampler.

>>> replayed_sampling_count_1 = sampler(circuit_1, n_shots_1)
>>> replayed_sampling_count_2 = sampler(circuit_2, n_shots_2)
>>> replayed_sampling_count_3 = sampler(circuit_3, n_shots_3)
Parameters:

  • backend (Backend) – A Qiskit qiskit.providers.backend.Backend for circuit execution.

  • saved_data (str) – A json string output by the .json_str property of :class:`~quri_parts.qiskit.backend.QiskitSamplingBackend.

  • circuit_converter (QiskitCircuitConverter) – A function converting NonParametricQuantumCircuit to a Qiskit qiskit.circuit.QuantumCircuit.

  • circuit_transpiler (Optional[CircuitTranspiler]) – A transpiler applied to the circuit before running it. QiskitSetTranspiler is used when not specified.

  • enable_shots_roundup (bool) – If True, when a number of shots specified to sample() is smaller than the minimum number of shots supported by the device, it is rounded up to the minimum. In this case, it is possible that shots more than specified are used. If it is strictly not allowed to exceed the specified shot count, set this argument to False.

  • qubit_mapping (Optional[Mapping[int, int]]) – If specified, indices of qubits in the circuit are remapped before running it on the backend. It can be used when you want to use specific backend qubits, e.g. those with high fidelity. The mapping should be specified with “from” qubit indices as keys and “to” qubit indices as values. For example, if you want to map qubits 0, 1, 2, 3 to backend qubits as 0 → 4, 1 → 2, 2 → 5, 3 → 0, then the qubit_mapping should be {0: 4, 1: 2, 2: 5, 3: 0}.

  • run_kwargs (Mapping[str, Any]) – Additional keyword arguments for qiskit.providers.backend.Backend.run() method.

sample(circuit, n_shots)#

Perform a sampling measurement of a circuit.

Parameters:
Return type:

SamplingJob

get_job_mapper_and_circuit_transpiler(qubit_mapping=None, circuit_transpiler=None)#
Creates
  1. A job mapper that maps the qubits of raw sampling job from the backend to

    a SamplingJob according to the specified qubit_mapping.

  2. A circuit transpiler.

Parameters:

  • qubit_mapping (Mapping[int, int] | None) – If specified, indices of qubits in the circuit are remapped before running it on the backend. It can be used when you want to use specific backend qubits, e.g. those with high fidelity. The mapping should be specified with “from” qubit indices as keys and “to” qubit indices as values. For example, if you want to map qubits 0, 1, 2, 3 to backend qubits as 0 → 4, 1 → 2, 2 → 5, 3 → 0, then the qubit_mapping should be {0: 4, 1: 2, 2: 5, 3: 0}.

  • circuit_transpiler (circuit.transpile.transpiler.CircuitTranspiler | None) – A transpiler applied to the circuit before running it. QiskitSetTranspiler is used when not specified.

Return type:

tuple[Callable[[SamplingJob], SamplingJob], circuit.transpile.transpiler.CircuitTranspiler]

get_backend_min_max_shot(backend)#

Get the selected qiskit backend’s minimum and maximum shot number allowed in a single sampling job.

Parameters:

backend (Backend) –

Return type:

tuple[int, int | None]

distribute_backend_shots(n_shots, min_shots, max_shots, enable_shots_roundup=True)#

Distributes the n_shots into batches of smaller shot numbers according to the max_shots value.

Parameters:

  • n_shots (int) – Total number of shots.

  • min_shots (int) – Minimal number of shots of a single batch.

  • max_shots (int | None) – Maximal number of shots of a single batch.

  • enable_shots_roundup (bool | None) – If True, when a number of shots of a batch is smaller than min_shots, it is rounded up to the minimum. In this case, it is possible that shots more than specified are used. If it is strictly not allowed to exceed the specified shot count, set this argument to False.

Return type:

Sequence[int]

convert_qiskit_sampling_count_to_qp_sampling_count(qiskit_counts)#

Converts the raw counter returned from qiskit backends to quri-parts couter.

Note that the qiskit counter uses a string that represents a binary number as the key.

Parameters:

qiskit_counts (Mapping[str, int]) –

Return type:

backend.SamplingCounts

class Tracker#

Bases: object

A tracker that tracks how much billable time is used by jobs executed on IBM Backends.

property total_run_time: float#

The total run time that is billable.

property finished_jobs: Sequence['QiskitRuntimeSamplingJob']#

All the jobs that are finished by the IBM backend.

property running_jobs: Sequence['QiskitRuntimeSamplingJob']#

All the jobs that are still runnign on the IBM backend.

add_job_for_tracking(runtime_job)#

Register QiskitRuntimeSamplingJob to the tracker for tracking billable job execution time.

Parameters:

runtime_job (QiskitRuntimeSamplingJob) –

Return type:

None

Submodules#