qiskit.quantum_info.Statevector

class Statevector(data, dims=None)

Statevector class

Initialize a statevector object.

Parameter

• data (vector_like) – a complex statevector.

• dims (int or tuple or list) – Optional. The subsystem dimension of the state (See additional information).

Verursacht

QiskitError – if input data is not valid.

Additional Information:

The dims kwarg can be None, an integer, or an iterable of integers.

• Iterable – the subsystem dimensions are the values in the list with the total number of subsystems given by the length of the list.

• Int or None – the length of the input vector specifies the total dimension of the density matrix. If it is a power of two the state will be initialized as an N-qubit state. If it is not a power of two the state will have a single d-dimensional subsystem.

__init__(data, dims=None)

Initialize a statevector object.

Parameter

• data (vector_like) – a complex statevector.

• dims (int or tuple or list) – Optional. The subsystem dimension of the state (See additional information).

Verursacht

QiskitError – if input data is not valid.

Additional Information:

The dims kwarg can be None, an integer, or an iterable of integers.

• Iterable – the subsystem dimensions are the values in the list with the total number of subsystems given by the length of the list.

• Int or None – the length of the input vector specifies the total dimension of the density matrix. If it is a power of two the state will be initialized as an N-qubit state. If it is not a power of two the state will have a single d-dimensional subsystem.

Methods

__init__(data[, dims])	Initialize a statevector object.
add(other)	Return the linear combination self + other.
conjugate()	Return the conjugate of the operator.
copy()	Make a copy of current operator.
dims([qargs])	Return tuple of input dimension for specified subsystems.
equiv(other[, rtol, atol])	Return True if statevectors are equivalent up to global phase.
evolve(other[, qargs])	Evolve a quantum state by the operator.
expand(other)	Return the tensor product state other ⊗ self.
expectation_value(oper[, qargs])	Compute the expectation value of an operator.
from_instruction(instruction)	Return the output statevector of an instruction.
from_int(i, dims)	Return a computational basis statevector.
from_label(label)	Return a tensor product of Pauli X,Y,Z eigenstates.
is_valid([atol, rtol])	Return True if a Statevector has norm 1.
measure([qargs])	Measure subsystems and return outcome and post-measure state.
multiply(other)	Return the scalar multipled state other * self.
probabilities([qargs, decimals])	Return the subsystem measurement probability vector.
probabilities_dict([qargs, decimals])	Return the subsystem measurement probability dictionary.
purity()	Return the purity of the quantum state.
reset([qargs])	Reset state or subsystems to the 0-state.
sample_counts(shots[, qargs])	Sample a dict of qubit measurement outcomes in the computational basis.
sample_memory(shots[, qargs])	Sample a list of qubit measurement outcomes in the computational basis.
seed([value])	Set the seed for the quantum state RNG.
set_atol(value)	Set the class default absolute tolerance parameter for float comparisons.
set_rtol(value)	Set the class default relative tolerance parameter for float comparisons.
subtract(other)	Return the linear operator self - other.
tensor(other)	Return the tensor product state self ⊗ other.
to_counts()	Returns the statevector as a counts dict of probabilities.
to_dict([decimals])	Convert the statevector to dictionary form.
to_operator()	Convert state to a rank-1 projector operator
trace()	Return the trace of the quantum state as a density matrix.

Attributes

atol	The absolute tolerance parameter for float comparisons.
data	Return data.
dim	Return total state dimension.
num_qubits	Return the number of qubits if a N-qubit state or None otherwise.
rtol	The relative tolerance parameter for float comparisons.

add(other)

Return the linear combination self + other.

DEPRECATED: use state + other instead.

Parameter

other (QuantumState) – a quantum state object.

Rückgabe

the linear combination self + other.

Rückgabetyp

LinearOperator

Verursacht

QiskitError – if other is not a quantum state, or has incompatible dimensions.

property atol

The absolute tolerance parameter for float comparisons.

conjugate()

Return the conjugate of the operator.

copy()

Make a copy of current operator.

property data

Return data.

property dim

Return total state dimension.

dims(qargs=None)

Return tuple of input dimension for specified subsystems.

equiv(other, rtol=None, atol=None)

Return True if statevectors are equivalent up to global phase.

Parameter

• other (Statevector) – a statevector object.

• rtol (float) – relative tolerance value for comparison.

• atol (float) – absolute tolerance value for comparison.

Rückgabe

True if statevectors are equivalent up to global phase.

Rückgabetyp

bool

evolve(other, qargs=None)

Evolve a quantum state by the operator.

Parameter

• other (Operator) – The operator to evolve by.

• qargs (list) – a list of Statevector subsystem positions to apply the operator on.

Rückgabe

the output quantum state.

Rückgabetyp

Statevector

Verursacht

QiskitError – if the operator dimension does not match the specified Statevector subsystem dimensions.

expand(other)

Return the tensor product state other ⊗ self.

Parameter

other (Statevector) – a quantum state object.

Rückgabe

the tensor product state other ⊗ self.

Rückgabetyp

Statevector

Verursacht

QiskitError – if other is not a quantum state.

expectation_value(oper, qargs=None)

Compute the expectation value of an operator.

Parameter

• oper (Operator) – an operator to evaluate expval of.

• qargs (None or list) – subsystems to apply operator on.

Rückgabe

the expectation value.

Rückgabetyp

complex

classmethod from_instruction(instruction)

Return the output statevector of an instruction.

The statevector is initialized in the state \(|{0,\ldots,0}\rangle\) of the same number of qubits as the input instruction or circuit, evolved by the input instruction, and the output statevector returned.

Parameter

instruction (qiskit.circuit.Instruction or QuantumCircuit) – instruction or circuit

Rückgabe

The final statevector.

Rückgabetyp

Statevector

Verursacht

QiskitError – if the instruction contains invalid instructions for the statevector simulation.

static from_int(i, dims)

Return a computational basis statevector.

Parameter

• i (int) – the basis state element.

• dims (int or tuple or list) – The subsystem dimensions of the statevector (See additional information).

Rückgabe

The computational basis state \(|i\rangle\).

Rückgabetyp

Statevector

Additional Information:

The dims kwarg can be an integer or an iterable of integers.

• Iterable – the subsystem dimensions are the values in the list with the total number of subsystems given by the length of the list.

• Int – the integer specifies the total dimension of the state. If it is a power of two the state will be initialized as an N-qubit state. If it is not a power of two the state will have a single d-dimensional subsystem.

classmethod from_label(label)

Return a tensor product of Pauli X,Y,Z eigenstates.

Table 15 Single-qubit state labels

Label	Statevector
"0"	\([1, 0]\)
"1"	\([0, 1]\)
"+"	\([1 / \sqrt{2}, 1 / \sqrt{2}]\)
"-"	\([1 / \sqrt{2}, -1 / \sqrt{2}]\)
"r"	\([1 / \sqrt{2}, i / \sqrt{2}]\)
"l"	\([1 / \sqrt{2}, -i / \sqrt{2}]\)

Parameter

label (string) – a eigenstate string ket label (see table for allowed values).

Rückgabe

The N-qubit basis state density matrix.

Rückgabetyp

Statevector

Verursacht

QiskitError – if the label contains invalid characters, or the length of the label is larger than an explicitly specified num_qubits.

is_valid(atol=None, rtol=None)

Return True if a Statevector has norm 1.

measure(qargs=None)

Measure subsystems and return outcome and post-measure state.

Note that this function uses the QuantumStates internal random number generator for sampling the measurement outcome. The RNG seed can be set using the seed() method.

Parameter

qargs (list or None) – subsystems to sample measurements for, if None sample measurement of all subsystems (Default: None).

Rückgabe

the pair (outcome, state) where outcome is the

measurement outcome string label, and state is the collapsed post-measurement state for the corresponding outcome.

Rückgabetyp

tuple

multiply(other)

Return the scalar multipled state other * self.

Parameter

other (complex) – a complex number.

Rückgabe

the scalar multipled state other * self.

Rückgabetyp

QuantumState

Verursacht

QiskitError – if other is not a valid complex number.

property num_qubits

Return the number of qubits if a N-qubit state or None otherwise.

probabilities(qargs=None, decimals=None)

Return the subsystem measurement probability vector.

Measurement probabilities are with respect to measurement in the computation (diagonal) basis.

Parameter

• qargs (None or list) – subsystems to return probabilities for, if None return for all subsystems (Default: None).

• decimals (None or int) – the number of decimal places to round values. If None no rounding is done (Default: None).

Rückgabe

The Numpy vector array of probabilities.

Rückgabetyp

np.array

Examples

Consider a 2-qubit product state \(|\psi\rangle=|+\rangle\otimes|0\rangle\).

from qiskit.quantum_info import Statevector

psi = Statevector.from_label('+0')

# Probabilities for measuring both qubits
probs = psi.probabilities()
print('probs: {}'.format(probs))

# Probabilities for measuring only qubit-0
probs_qubit_0 = psi.probabilities([0])
print('Qubit-0 probs: {}'.format(probs_qubit_0))

# Probabilities for measuring only qubit-1
probs_qubit_1 = psi.probabilities([1])
print('Qubit-1 probs: {}'.format(probs_qubit_1))

probs: [0.5 0.  0.5 0. ]
Qubit-0 probs: [1. 0.]
Qubit-1 probs: [0.5 0.5]

We can also permute the order of qubits in the qargs list to change the qubit position in the probabilities output

from qiskit.quantum_info import Statevector

psi = Statevector.from_label('+0')

# Probabilities for measuring both qubits
probs = psi.probabilities([0, 1])
print('probs: {}'.format(probs))

# Probabilities for measuring both qubits
# but swapping qubits 0 and 1 in output
probs_swapped = psi.probabilities([1, 0])
print('Swapped probs: {}'.format(probs_swapped))

probs: [0.5 0.  0.5 0. ]
Swapped probs: [0.5 0.5 0.  0. ]

probabilities_dict(qargs=None, decimals=None)

Return the subsystem measurement probability dictionary.

Measurement probabilities are with respect to measurement in the computation (diagonal) basis.

This dictionary representation uses a Ket-like notation where the dictionary keys are qudit strings for the subsystem basis vectors. If any subsystem has a dimension greater than 10 comma delimiters are inserted between integers so that subsystems can be distinguished.

Parameter

• qargs (None or list) – subsystems to return probabilities for, if None return for all subsystems (Default: None).

• decimals (None or int) – the number of decimal places to round values. If None no rounding is done (Default: None).

Rückgabe

The measurement probabilities in dict (ket) form.

Rückgabetyp

dict

purity()

Return the purity of the quantum state.

reset(qargs=None)

Reset state or subsystems to the 0-state.

Parameter

qargs (list or None) – subsystems to reset, if None all subsystems will be reset to their 0-state (Default: None).

Rückgabe

the reset state.

Rückgabetyp

Statevector

Additional Information:

If all subsystems are reset this will return the ground state on all subsystems. If only a some subsystems are reset this function will perform a measurement on those subsystems and evolve the subsystems so that the collapsed post-measurement states are rotated to the 0-state. The RNG seed for this sampling can be set using the seed() method.

property rtol

The relative tolerance parameter for float comparisons.

sample_counts(shots, qargs=None)

Sample a dict of qubit measurement outcomes in the computational basis.

Parameter

• shots (int) – number of samples to generate.

• qargs (None or list) – subsystems to sample measurements for, if None sample measurement of all subsystems (Default: None).

Rückgabe

sampled counts dictionary.

Rückgabetyp

Counts

Additional Information:

This function samples measurement outcomes using the measure probabilities() for the current state and qargs. It does not actually implement the measurement so the current state is not modified.

The seed for random number generator used for sampling can be set to a fixed value by using the stats seed() method.

sample_memory(shots, qargs=None)

Sample a list of qubit measurement outcomes in the computational basis.

Parameter

• shots (int) – number of samples to generate.

• qargs (None or list) – subsystems to sample measurements for, if None sample measurement of all subsystems (Default: None).

Rückgabe

list of sampled counts if the order sampled.

Rückgabetyp

np.array

Additional Information:

This function samples measurement outcomes using the measure probabilities() for the current state and qargs. It does not actually implement the measurement so the current state is not modified.

The seed for random number generator used for sampling can be set to a fixed value by using the stats seed() method.

seed(value=None)

Set the seed for the quantum state RNG.

classmethod set_atol(value)

Set the class default absolute tolerance parameter for float comparisons.

DEPRECATED: use operator.atol = value instead

classmethod set_rtol(value)

Set the class default relative tolerance parameter for float comparisons.

DEPRECATED: use operator.rtol = value instead

subtract(other)

Return the linear operator self - other.

DEPRECATED: use state - other instead.

Parameter

other (QuantumState) – a quantum state object.

Rückgabe

the linear combination self - other.

Rückgabetyp

LinearOperator

Verursacht

QiskitError – if other is not a quantum state, or has incompatible dimensions.

tensor(other)

Return the tensor product state self ⊗ other.

Parameter

other (Statevector) – a quantum state object.

Rückgabe

the tensor product operator self ⊗ other.

Rückgabetyp

Statevector

Verursacht

QiskitError – if other is not a quantum state.

to_counts()

Returns the statevector as a counts dict of probabilities.

DEPRECATED: use probabilities_dict() instead.

Rückgabe

Counts of probabilities.

Rückgabetyp

dict

to_dict(decimals=None)

Convert the statevector to dictionary form.

This dictionary representation uses a Ket-like notation where the dictionary keys are qudit strings for the subsystem basis vectors. If any subsystem has a dimension greater than 10 comma delimiters are inserted between integers so that subsystems can be distinguished.

Parameter

decimals (None or int) – the number of decimal places to round values. If None no rounding is done (Default: None).

Rückgabe

the dictionary form of the Statevector.

Rückgabetyp

dict

Example

The ket-form of a 2-qubit statevector \(|\psi\rangle = |-\rangle\otimes |0\rangle\)

from qiskit.quantum_info import Statevector

psi = Statevector.from_label('-0')
print(psi.to_dict())

{'00': (0.7071067811865475+0j), '10': (-0.7071067811865475+0j)}

For non-qubit subsystems the integer range can go from 0 to 9. For example in a qutrit system

import numpy as np
from qiskit.quantum_info import Statevector

vec = np.zeros(9)
vec[0] = 1 / np.sqrt(2)
vec[-1] = 1 / np.sqrt(2)
psi = Statevector(vec, dims=(3, 3))
print(psi.to_dict())

{'00': (0.7071067811865475+0j), '22': (0.7071067811865475+0j)}

For large subsystem dimensions delimeters are required. The following example is for a 20-dimensional system consisting of a qubit and 10-dimensional qudit.

import numpy as np
from qiskit.quantum_info import Statevector

vec = np.zeros(2 * 10)
vec[0] = 1 / np.sqrt(2)
vec[-1] = 1 / np.sqrt(2)
psi = Statevector(vec, dims=(2, 10))
print(psi.to_dict())

{'00': (0.7071067811865475+0j), '91': (0.7071067811865475+0j)}

to_operator()

Convert state to a rank-1 projector operator

trace()

Return the trace of the quantum state as a density matrix.