--- title: primitives (v0.46) description: API reference for qiskit.primitives in qiskit v0.46 source: https://eu-de.quantum.cloud.ibm.com/docs/en/api/qiskit/0.46/primitives --- # 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`](/docs/api/qiskit/0.46/qiskit.providers.JobV1 "qiskit.providers.JobV1"), via the [`qiskit.primitives.Estimator.run()`](/docs/api/qiskit/0.46/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`](/docs/api/qiskit/0.46/qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") objects). - observables ($H_j$): a list of [`SparsePauliOp`](/docs/api/qiskit/0.46/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`](/docs/api/qiskit/0.46/qiskit.providers.JobV1 "qiskit.providers.JobV1") object, calling [`qiskit.providers.JobV1.result()`](/docs/api/qiskit/0.46/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 [ ] 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 [ , # , # ] 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}") ``` ## 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`](/docs/api/qiskit/0.46/qiskit.providers.JobV1 "qiskit.providers.JobV1"), via the [`qiskit.primitives.Sampler.run()`](/docs/api/qiskit/0.46/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`](/docs/api/qiskit/0.46/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`](/docs/api/qiskit/0.46/qiskit.providers.JobV1 "qiskit.providers.JobV1") object, calling [`qiskit.providers.JobV1.result()`](/docs/api/qiskit/0.46/qiskit.providers.JobV1#result "qiskit.providers.JobV1.result") yields a [`SamplerResult`](/docs/api/qiskit/0.46/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`](/docs/api/qiskit/0.46/qiskit.primitives.BaseEstimator "qiskit.primitives.BaseEstimator")(\*\[, options]) | Estimator base class. | | [`Estimator`](/docs/api/qiskit/0.46/qiskit.primitives.Estimator "qiskit.primitives.Estimator")(\*\[, options]) | Reference implementation of [`BaseEstimator`](/docs/api/qiskit/0.46/qiskit.primitives.BaseEstimator "qiskit.primitives.BaseEstimator"). | | [`BackendEstimator`](/docs/api/qiskit/0.46/qiskit.primitives.BackendEstimator "qiskit.primitives.BackendEstimator")(backend\[, options, ...]) | Evaluates expectation value using Pauli rotation gates. | ## Sampler | | | | --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`BaseSampler`](/docs/api/qiskit/0.46/qiskit.primitives.BaseSampler "qiskit.primitives.BaseSampler")(\*\[, options]) | Sampler base class | | [`Sampler`](/docs/api/qiskit/0.46/qiskit.primitives.Sampler "qiskit.primitives.Sampler")(\*\[, options]) | Sampler class. | | [`BackendSampler`](/docs/api/qiskit/0.46/qiskit.primitives.BackendSampler "qiskit.primitives.BackendSampler")(backend\[, options, ...]) | A [`BaseSampler`](/docs/api/qiskit/0.46/qiskit.primitives.BaseSampler "qiskit.primitives.BaseSampler") implementation that provides an interface for leveraging the sampler interface from any backend. | ## Results | | | | ---------------------------------------------------------------------------------------------------------------------------------- | -------------------- | | [`EstimatorResult`](/docs/api/qiskit/0.46/qiskit.primitives.EstimatorResult "qiskit.primitives.EstimatorResult")(values, metadata) | Result of Estimator. | | [`SamplerResult`](/docs/api/qiskit/0.46/qiskit.primitives.SamplerResult "qiskit.primitives.SamplerResult")(quasi\_dists, metadata) | Result of Sampler. |