Skip to main contentIBM Quantum Documentation

Primitives examples

The examples in this section illustrate some common ways to use primitives. Before running these examples, follow the instructions in Install and set up.

Important

To ensure faster and more efficient results, as of 1 March 2024, circuits and observables need to be transformed to only use instructions supported by the system (referred to as instruction set architecture (ISA) circuits and observables) before being submitted to the Qiskit Runtime primitives. See the transpilation documentation for instructions to transform circuits. Due to this change, the primitives will no longer perform layout or routing operations; consequently, transpilation options referring to those tasks will no longer have any effect. Users can still request that the primitives do no optimization of input circuits by specifying options.transpilation.skip_transpilation.

Note

These examples all use the primitives from Qiskit® Runtime, but you could use the base primitives instead.


Estimator examples

Efficiently calculate and interpret expectation values of the quantum operators required for many algorithms with Estimator. Explore uses in molecular modeling, machine learning, and complex optimization problems.

Run a single experiment

Use Estimator to determine the expectation value of a single circuit-observable pair.

import numpy as np
from qiskit.circuit.library import IQP
from qiskit.transpiler.preset_passmanagers import generate_preset_pass_manager
from qiskit.quantum_info import SparsePauliOp, random_hermitian
from qiskit_ibm_runtime import QiskitRuntimeService, Estimator
 
service = QiskitRuntimeService()
 
backend = service.get_backend("ibm_brisbane")
 
n_qubits = 127
 
mat = np.real(random_hermitian(n_qubits, seed=1234))
circuit = IQP(mat)
observable = SparsePauliOp("Z" * n_qubits)
 
pm = generate_preset_pass_manager(backend=backend, optimization_level=1)
isa_circuit = pm.run(circuit)
isa_observable = observable.apply_layout(isa_circuit.layout)
 
estimator = Estimator(backend)
job = estimator.run(isa_circuit, isa_observable)
result = job.result()
 
print(f" > Observable: {observable.paulis}")
print(f" > Expectation value: {result.values}")
print(f" > Metadata: {result.metadata}")

Run multiple experiments in a single job

Use Estimator to determine the expectation values of multiple circuit-observable pairs.

import numpy as np
from qiskit.circuit.library import IQP
from qiskit.transpiler.preset_passmanagers import generate_preset_pass_manager
from qiskit.quantum_info import SparsePauliOp, random_hermitian
from qiskit_ibm_runtime import QiskitRuntimeService, Estimator
 
 
service = QiskitRuntimeService()
 
backend = service.get_backend("ibm_brisbane")
 
n_qubits = 127
 
rng = np.random.default_rng()
mats = [np.real(random_hermitian(n_qubits, seed=rng)) for _ in range(3)]
circuits = [IQP(mat) for mat in mats]
observables = [
    SparsePauliOp("X" * n_qubits),
    SparsePauliOp("Y" * n_qubits),
    SparsePauliOp("Z" * n_qubits),
]
 
pm = generate_preset_pass_manager(backend=backend, optimization_level=1)
isa_circuits = pm.run(circuits)
isa_observables = [ob.apply_layout(isa_circuits[0].layout) for ob in observables]
 
estimator = Estimator(backend)
job = estimator.run(isa_circuits, isa_observables)
result = job.result()
 
print(f" > Expectation values: {result.values}")

Run parameterized circuits

Use Estimator to run three experiments in a single job, leveraging parameter values to increase circuit reusability.

import numpy as np
from qiskit.circuit.library import RealAmplitudes
from qiskit.transpiler.preset_passmanagers import generate_preset_pass_manager
from qiskit.quantum_info import SparsePauliOp
from qiskit_ibm_runtime import QiskitRuntimeService, Estimator
 
service = QiskitRuntimeService()
 
backend = service.get_backend("ibm_brisbane")
 
circuit = RealAmplitudes(num_qubits=127, reps=2)
# Define three sets of parameters for the circuit
rng = np.random.default_rng(1234)
parameter_values = [
    rng.uniform(-np.pi, np.pi, size=circuit.num_parameters) for _ in range(3)
]
observable = SparsePauliOp("Z" * 127)
 
pm = generate_preset_pass_manager(backend=backend, optimization_level=1)
isa_circuit = pm.run(circuit)
isa_observable = observable.apply_layout(isa_circuit.layout)
 
estimator = Estimator(backend)
job = estimator.run([isa_circuit] * 3, [isa_observable] * 3, parameter_values)
result = job.result()
 
print(f" > Expectation values: {result.values}")

Use sessions and advanced options

Explore sessions and advanced options to optimize circuit performance on quantum systems.

import numpy as np
from qiskit.circuit.library import IQP
from qiskit.transpiler.preset_passmanagers import generate_preset_pass_manager
from qiskit.quantum_info import SparsePauliOp, random_hermitian
from qiskit_ibm_runtime import QiskitRuntimeService, Session, Estimator, Options
 
n_qubits = 127
 
rng = np.random.default_rng(1234)
mat = np.real(random_hermitian(n_qubits, seed=rng))
circuit = IQP(mat)
mat = np.real(random_hermitian(n_qubits, seed=rng))
another_circuit = IQP(mat)
observable = SparsePauliOp("X" * n_qubits)
another_observable = SparsePauliOp("Y" * n_qubits)
 
pm = generate_preset_pass_manager(backend=backend, optimization_level=1)
isa_circuit = pm.run(circuit)
another_isa_circuit = pm.run(another_circuit)
isa_observable = observable.apply_layout(isa_circuit.layout)
another_isa_observable = another_observable.apply_layout(another_isa_circuit.layout)
 
options = Options()
options.optimization_level = 2
options.resilience_level = 2
 
service = QiskitRuntimeService()
 
backend = service.get_backend("ibm_brisbane")
 
with Session(service=service, backend=backend) as session:
    estimator = Estimator(session=session, options=options)
    job = estimator.run(isa_circuit, isa_observable)
    another_job = estimator.run(another_isa_circuit, another_isa_observable)
    result = job.result()
    another_result = another_job.result()
 
# first job
print(f" > Expectation values job 1: {result.values}")
 
# second job
print(f" > Expectation values job 2: {another_result.values}")

Sampler examples

Generate entire error-mitigated quasi-probability distributions sampled from quantum circuit outputs. Leverage Sampler’s capabilities for search and classification algorithms like Grover’s and QVSM.

Run a single experiment

Use Sampler to determine the quasi-probability distribution of a single circuit.

import numpy as np
from qiskit.circuit.library import IQP
from qiskit.transpiler.preset_passmanagers import generate_preset_pass_manager
from qiskit.quantum_info import random_hermitian
from qiskit_ibm_runtime import QiskitRuntimeService, Sampler
 
service = QiskitRuntimeService()
 
backend = service.get_backend("ibm_brisbane")
 
n_qubits = 127
 
mat = np.real(random_hermitian(n_qubits, seed=1234))
circuit = IQP(mat)
circuit.measure_all()
 
pm = generate_preset_pass_manager(backend=backend, optimization_level=1)
isa_circuit = pm.run(circuit)
 
sampler = Sampler(backend)
job = sampler.run(isa_circuit)
result = job.result()
 
print(f" > Quasi-probability distribution: {result.quasi_dists}")
print(f" > Metadata: {result.metadata}")

Run multiple experiments in a single job

Use Sampler to determine the quasi-probability distributions of multiple circuits in one job.

import numpy as np
from qiskit.circuit.library import IQP
from qiskit.transpiler.preset_passmanagers import generate_preset_pass_manager
from qiskit.quantum_info import random_hermitian
from qiskit_ibm_runtime import QiskitRuntimeService, Sampler 
 
service = QiskitRuntimeService()
 
backend = service.get_backend("ibm_brisbane")
 
n_qubits = 127
 
rng = np.random.default_rng()
mats = [np.real(random_hermitian(n_qubits, seed=rng)) for _ in range(3)]
circuits = [IQP(mat) for mat in mats]
for circuit in circuits:
    circuit.measure_all()
 
pm = generate_preset_pass_manager(backend=backend, optimization_level=1)
isa_circuits = pm.run(circuits)
 
sampler = Sampler(backend) 
job = sampler.run(isa_circuits)
result = job.result() 
 
print(f" > Quasi-probability distribution: {result.quasi_dists}")

Run parameterized circuits

Run three experiments in a single job, leveraging parameter values to increase circuit reusability.

import numpy as np
from qiskit.circuit.library import RealAmplitudes
from qiskit.transpiler.preset_passmanagers import generate_preset_pass_manager
from qiskit_ibm_runtime import QiskitRuntimeService, Sampler
 
service = QiskitRuntimeService()
 
backend = service.get_backend("ibm_brisbane")
 
circuit = RealAmplitudes(num_qubits=127, reps=2)
circuit.measure_all()
 
pm = generate_preset_pass_manager(backend=backend, optimization_level=1)
isa_circuit = pm.run(circuit)
 
# Define three sets of parameters for the circuit
rng = np.random.default_rng(1234)
parameter_values = [
    rng.uniform(-np.pi, np.pi, size=circuit.num_parameters) for _ in range(3)
]
 
sampler = Sampler(backend) 
job = sampler.run([isa_circuit] * 3, parameter_values) 
result = job.result() 
 
print(f" > Quasi-probability distribution: {result.quasi_dists}")

Use sessions and advanced options

Explore sessions and advanced options to optimize circuit performance on quantum systems.

import numpy as np
from qiskit.circuit.library import IQP
from qiskit.transpiler.preset_passmanagers import generate_preset_pass_manager
from qiskit.quantum_info import random_hermitian
from qiskit_ibm_runtime import QiskitRuntimeService, Sampler, Session, Options
 
n_qubits = 127
 
rng = np.random.default_rng(1234)
mat = np.real(random_hermitian(n_qubits, seed=rng))
circuit = IQP(mat)
circuit.measure_all()
mat = np.real(random_hermitian(n_qubits, seed=rng))
another_circuit = IQP(mat)
another_circuit.measure_all()
 
pm = generate_preset_pass_manager(backend=backend, optimization_level=1)
isa_circuit = pm.run(circuit)
another_isa_circuit = pm.run(another_circuit)
 
options = Options() 
options.optimization_level = 2 
options.resilience_level = 0 
 
service = QiskitRuntimeService()
 
backend = service.get_backend("ibm_brisbane")
 
with Session(service=service, backend=backend) as session: 
    sampler = Sampler(session=session, options=options) 
    job = sampler.run(isa_circuit) 
    another_job = sampler.run(another_isa_circuit) 
    result = job.result()
    another_result = another_job.result() 
 
# first job 
print(f" > Quasi-probability distribution job 1: {result.quasi_dists}") 
 
# second job 
print(f" > Quasi-probability distribution job 2: {another_result.quasi_dists}")

Next steps

Recommendations
Was this page helpful?