176 lines
7.3 KiB
Plaintext
176 lines
7.3 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="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 object is initialized with multiple quantum circuits and observables and users can specify pairs of quantum circuits and observables to estimate the expectation values.
|
||
|
||
An estimator is initialized with the following elements.
|
||
|
||
* quantum circuits ($\psi_i(\theta)$): list of (parameterized) quantum circuits (a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")))
|
||
* observables ($H_j$): a list of [`SparsePauliOp`](qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.SparsePauliOp").
|
||
|
||
The estimator is called with the following inputs.
|
||
|
||
* circuit indexes: a list of indexes of the quantum circuits.
|
||
* observable indexes: a list of indexes of the observables.
|
||
* parameters: a list of parameters of the quantum circuits. (`ParameterView` or a list of [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter")).
|
||
* 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 output is an [`EstimatorResult`](qiskit.primitives.EstimatorResult "qiskit.primitives.EstimatorResult") which contains 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
|
||
$$
|
||
|
||
The estimator object is expected to be `close()` d after use or accessed inside “with” context and the objects are called with parameter values and run options (e.g., `shots` or number of shots).
|
||
|
||
Here is an example of how estimator is used.
|
||
|
||
```python
|
||
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)
|
||
|
||
params1 = psi1.parameters
|
||
params2 = psi2.parameters
|
||
|
||
H1 = SparsePauliOp.from_list([("II", 1), ("IZ", 2), ("XI", 3)])
|
||
H2 = SparsePauliOp.from_list([("IZ", 1)])
|
||
H3 = SparsePauliOp.from_list([("ZI", 1), ("ZZ", 1)])
|
||
|
||
with Estimator([psi1, psi2], [H1, H2, H3], [params1, params2]) as e:
|
||
theta1 = [0, 1, 1, 2, 3, 5]
|
||
theta2 = [0, 1, 1, 2, 3, 5, 8, 13]
|
||
theta3 = [1, 2, 3, 4, 5, 6]
|
||
|
||
# calculate [ <psi1(theta1)|H1|psi1(theta1)> ]
|
||
result = e([0], [0], [theta1])
|
||
print(result)
|
||
|
||
# calculate [ <psi1(theta1)|H2|psi1(theta1)>, <psi1(theta1)|H3|psi1(theta1)> ]
|
||
result2 = e([0, 0], [1, 2], [theta1]*2)
|
||
print(result2)
|
||
|
||
# calculate [ <psi2(theta2)|H2|psi2(theta2)> ]
|
||
result3 = e([1], [1], [theta2])
|
||
print(result3)
|
||
|
||
# calculate [ <psi1(theta1)|H1|psi1(theta1)>, <psi1(theta3)|H1|psi1(theta3)> ]
|
||
result4 = e([0, 0], [0, 0], [theta1, theta3])
|
||
print(result4)
|
||
|
||
# calculate [ <psi1(theta1)|H1|psi1(theta1)>,
|
||
# <psi2(theta2)|H2|psi2(theta2)>,
|
||
# <psi1(theta3)|H3|psi1(theta3)> ]
|
||
result5 = e([0, 1, 0], [0, 1, 2], [theta1, theta2, theta3])
|
||
print(result5)
|
||
```
|
||
|
||
<span id="module-qiskit.primitives.base_sampler" />
|
||
|
||
## Overview of Sampler
|
||
|
||
Sampler class calculates probabilities or quasi-probabilities of bitstrings from quantum circuits.
|
||
|
||
A sampler is initialized with the following elements.
|
||
|
||
* quantum circuits ($\psi_i(\theta)$): list of (parameterized) quantum circuits. (a list of [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")))
|
||
* parameters: a list of parameters of the quantum circuits. (`ParameterView` or a list of [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter")).
|
||
|
||
The sampler is run with the following inputs.
|
||
|
||
* circuit indexes: a list of indices of the circuits to evaluate.
|
||
* 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 output is a [`SamplerResult`](qiskit.primitives.SamplerResult "qiskit.primitives.SamplerResult") which contains probabilities or quasi-probabilities of bitstrings, plus optional metadata like error bars in the samples.
|
||
|
||
The sampler object is expected to be closed after use or accessed within “with” context and the objects are called with parameter values and run options (e.g., `shots` or number of shots).
|
||
|
||
Here is an example of how sampler is used.
|
||
|
||
```python
|
||
from qiskit import QuantumCircuit
|
||
from qiskit.circuit.library import RealAmplitudes
|
||
|
||
bell = QuantumCircuit(2)
|
||
bell.h(0)
|
||
bell.cx(0, 1)
|
||
bell.measure_all()
|
||
|
||
# executes a Bell circuit
|
||
with Sampler(circuits=[bell], parameters=[[]]) as sampler:
|
||
result = sampler(parameters=[[]], circuits=[0])
|
||
print([q.binary_probabilities() for q in result.quasi_dists])
|
||
|
||
# executes three Bell circuits
|
||
with Sampler([bell]*3, [[]] * 3) as sampler:
|
||
result = sampler([0, 1, 2], [[]]*3)
|
||
print([q.binary_probabilities() for q in result.quasi_dists])
|
||
|
||
# parameterized circuit
|
||
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 = [1, 2, 3, 4, 5, 6]
|
||
theta3 = [0, 1, 2, 3, 4, 5, 6, 7]
|
||
|
||
with Sampler(circuits=[pqc, pqc2], parameters=[pqc.parameters, pqc2.parameters]) as sampler:
|
||
result = sampler([0, 0, 1], [theta1, theta2, theta3])
|
||
|
||
# result of pqc(theta1)
|
||
print(result.quasi_dists[0].binary_probabilities())
|
||
|
||
# result of pqc(theta2)
|
||
print(result.quasi_dists[1].binary_probabilities())
|
||
|
||
# result of pqc2(theta3)
|
||
print(result.quasi_dists[2].binary_probabilities())
|
||
```
|
||
|
||
## Estimator
|
||
|
||
| | |
|
||
| ----------------------------------------------------------------------------------------------------------------- | --------------------- |
|
||
| [`BaseEstimator`](qiskit.primitives.BaseEstimator "qiskit.primitives.BaseEstimator")(circuits, observables\[, …]) | Estimator base class. |
|
||
| [`Estimator`](qiskit.primitives.Estimator "qiskit.primitives.Estimator")(circuits, observables\[, parameters]) | Estimator class |
|
||
|
||
## Sampler
|
||
|
||
| | |
|
||
| ------------------------------------------------------------------------------------------------------- | ------------------ |
|
||
| [`BaseSampler`](qiskit.primitives.BaseSampler "qiskit.primitives.BaseSampler")(circuits\[, parameters]) | Sampler base class |
|
||
| [`Sampler`](qiskit.primitives.Sampler "qiskit.primitives.Sampler")(circuits\[, parameters]) | Sampler class |
|
||
|
||
## 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 |
|
||
|