147 lines
8.1 KiB
Plaintext
147 lines
8.1 KiB
Plaintext
---
|
||
title: primitives
|
||
description: API reference for qiskit.primitives
|
||
in_page_toc_min_heading_level: 2
|
||
python_api_type: module
|
||
python_api_name: qiskit.primitives
|
||
---
|
||
|
||
<span id="module-qiskit.primitives" />
|
||
|
||
<span id="qiskit-primitives" />
|
||
|
||
<span id="module-qiskit.primitives.base.base_estimator" />
|
||
|
||
<span id="primitives-qiskit-primitives" />
|
||
|
||
# Primitives
|
||
|
||
<span id="module-qiskit.primitives" />
|
||
|
||
`qiskit.primitives`
|
||
|
||
## Overview of Estimator
|
||
|
||
Estimator class estimates expectation values of quantum circuits and observables.
|
||
|
||
An estimator is initialized with an empty parameter set. The estimator is used to create a [`JobV1`](qiskit.providers.JobV1 "qiskit.providers.JobV1"), via the [`qiskit.primitives.Estimator.run()`](qiskit.primitives.Estimator#run "qiskit.primitives.Estimator.run") method. This method is called with the following parameters
|
||
|
||
* quantum circuits ($\psi_i(\theta)$): list of (parameterized) quantum circuits (a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") objects).
|
||
* observables ($H_j$): a list of [`SparsePauliOp`](qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.SparsePauliOp") objects.
|
||
* parameter values ($\theta_k$): list of sets of values to be bound to the parameters of the quantum circuits (list of list of float).
|
||
|
||
The method returns a [`JobV1`](qiskit.providers.JobV1 "qiskit.providers.JobV1") object, calling [`qiskit.providers.JobV1.result()`](qiskit.providers.JobV1#result "qiskit.providers.JobV1.result") yields the a list of expectation values plus optional metadata like confidence intervals for the estimation.
|
||
|
||
$$
|
||
\langle\psi_i(\theta_k)|H_j|\psi_i(\theta_k)\rangle
|
||
$$
|
||
|
||
Here is an example of how the estimator is used.
|
||
|
||
```python
|
||
from qiskit.primitives import Estimator
|
||
from qiskit.circuit.library import RealAmplitudes
|
||
from qiskit.quantum_info import SparsePauliOp
|
||
|
||
psi1 = RealAmplitudes(num_qubits=2, reps=2)
|
||
psi2 = RealAmplitudes(num_qubits=2, reps=3)
|
||
|
||
H1 = SparsePauliOp.from_list([("II", 1), ("IZ", 2), ("XI", 3)])
|
||
H2 = SparsePauliOp.from_list([("IZ", 1)])
|
||
H3 = SparsePauliOp.from_list([("ZI", 1), ("ZZ", 1)])
|
||
|
||
theta1 = [0, 1, 1, 2, 3, 5]
|
||
theta2 = [0, 1, 1, 2, 3, 5, 8, 13]
|
||
theta3 = [1, 2, 3, 4, 5, 6]
|
||
|
||
estimator = Estimator()
|
||
|
||
# calculate [ <psi1(theta1)|H1|psi1(theta1)> ]
|
||
job = estimator.run([psi1], [H1], [theta1])
|
||
job_result = job.result() # It will block until the job finishes.
|
||
print(f"The primitive-job finished with result {job_result}"))
|
||
|
||
# calculate [ <psi1(theta1)|H1|psi1(theta1)>,
|
||
# <psi2(theta2)|H2|psi2(theta2)>,
|
||
# <psi1(theta3)|H3|psi1(theta3)> ]
|
||
job2 = estimator.run([psi1, psi2, psi1], [H1, H2, H3], [theta1, theta2, theta3])
|
||
job_result = job2.result()
|
||
print(f"The primitive-job finished with result {job_result}")
|
||
```
|
||
|
||
<span id="module-qiskit.primitives.base.base_sampler" />
|
||
|
||
## Overview of Sampler
|
||
|
||
Sampler class calculates probabilities or quasi-probabilities of bitstrings from quantum circuits.
|
||
|
||
A sampler is initialized with an empty parameter set. The sampler is used to create a [`JobV1`](qiskit.providers.JobV1 "qiskit.providers.JobV1"), via the [`qiskit.primitives.Sampler.run()`](qiskit.primitives.Sampler#run "qiskit.primitives.Sampler.run") method. This method is called with the following parameters
|
||
|
||
* quantum circuits ($\psi_i(\theta)$): list of (parameterized) quantum circuits. (a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") objects)
|
||
* parameter values ($\theta_k$): list of sets of parameter values to be bound to the parameters of the quantum circuits. (list of list of float)
|
||
|
||
The method returns a [`JobV1`](qiskit.providers.JobV1 "qiskit.providers.JobV1") object, calling [`qiskit.providers.JobV1.result()`](qiskit.providers.JobV1#result "qiskit.providers.JobV1.result") yields a [`SamplerResult`](qiskit.primitives.SamplerResult "qiskit.primitives.SamplerResult") object, which contains probabilities or quasi-probabilities of bitstrings, plus optional metadata like error bars in the samples.
|
||
|
||
Here is an example of how sampler is used.
|
||
|
||
```python
|
||
from qiskit.primitives import Sampler
|
||
from qiskit import QuantumCircuit
|
||
from qiskit.circuit.library import RealAmplitudes
|
||
|
||
# a Bell circuit
|
||
bell = QuantumCircuit(2)
|
||
bell.h(0)
|
||
bell.cx(0, 1)
|
||
bell.measure_all()
|
||
|
||
# two parameterized circuits
|
||
pqc = RealAmplitudes(num_qubits=2, reps=2)
|
||
pqc.measure_all()
|
||
pqc2 = RealAmplitudes(num_qubits=2, reps=3)
|
||
pqc2.measure_all()
|
||
|
||
theta1 = [0, 1, 1, 2, 3, 5]
|
||
theta2 = [0, 1, 2, 3, 4, 5, 6, 7]
|
||
|
||
# initialization of the sampler
|
||
sampler = Sampler()
|
||
|
||
# Sampler runs a job on the Bell circuit
|
||
job = sampler.run(circuits=[bell], parameter_values=[[]], parameters=[[]])
|
||
job_result = job.result()
|
||
print([q.binary_probabilities() for q in job_result.quasi_dists])
|
||
|
||
# Sampler runs a job on the parameterized circuits
|
||
job2 = sampler.run(
|
||
circuits=[pqc, pqc2],
|
||
parameter_values=[theta1, theta2],
|
||
parameters=[pqc.parameters, pqc2.parameters])
|
||
job_result = job2.result()
|
||
print([q.binary_probabilities() for q in job_result.quasi_dists])
|
||
```
|
||
|
||
## Estimator
|
||
|
||
| | |
|
||
| ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
|
||
| [`BaseEstimator`](qiskit.primitives.BaseEstimator "qiskit.primitives.BaseEstimator")(\*\[, options]) | Estimator base class. |
|
||
| [`Estimator`](qiskit.primitives.Estimator "qiskit.primitives.Estimator")(\*\[, options]) | Reference implementation of [`BaseEstimator`](qiskit.primitives.BaseEstimator "qiskit.primitives.BaseEstimator"). |
|
||
| [`BackendEstimator`](qiskit.primitives.BackendEstimator "qiskit.primitives.BackendEstimator")(backend\[, options, ...]) | Evaluates expectation value using Pauli rotation gates. |
|
||
|
||
## Sampler
|
||
|
||
| | |
|
||
| ----------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| [`BaseSampler`](qiskit.primitives.BaseSampler "qiskit.primitives.BaseSampler")(\*\[, options]) | Sampler base class |
|
||
| [`Sampler`](qiskit.primitives.Sampler "qiskit.primitives.Sampler")(\*\[, options]) | Sampler class. |
|
||
| [`BackendSampler`](qiskit.primitives.BackendSampler "qiskit.primitives.BackendSampler")(backend\[, options, ...]) | A [`BaseSampler`](qiskit.primitives.BaseSampler "qiskit.primitives.BaseSampler") implementation that provides an interface for leveraging the sampler interface from any backend. |
|
||
|
||
## Results
|
||
|
||
| | |
|
||
| ------------------------------------------------------------------------------------------------------------ | -------------------- |
|
||
| [`EstimatorResult`](qiskit.primitives.EstimatorResult "qiskit.primitives.EstimatorResult")(values, metadata) | Result of Estimator. |
|
||
| [`SamplerResult`](qiskit.primitives.SamplerResult "qiskit.primitives.SamplerResult")(quasi\_dists, metadata) | Result of Sampler. |
|
||
|