# qiskit.quantum_info.DensityMatrix¶

class DensityMatrix(data, dims=None)[ソース]

DensityMatrix class

Initialize a density matrix object.

パラメータ
• data (matrix_like or vector_like) – a density matrix or statevector. If a vector the density matrix is constructed as the projector of that vector.

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

QiskitError – if input data is not valid.

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 leading dimension of the input matrix 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 density matrix object.

パラメータ
• data (matrix_like or vector_like) – a density matrix or statevector. If a vector the density matrix is constructed as the projector of that vector.

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

QiskitError – if input data is not valid.

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 leading dimension of the input matrix 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 density matrix object. add(other) Return the linear combination self + other. Return the conjugate of the density matrix. Make a copy of current operator. dims([qargs]) Return tuple of input dimension for specified subsystems. evolve(other[, qargs]) Evolve a quantum state by an 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 density matrix of an instruction. from_int(i, dims) Return a computational basis state density matrix. from_label(label) Return a tensor product of Pauli X,Y,Z eigenstates. is_valid([atol, rtol]) Return True if trace 1 and positive semidefinite. 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. 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. Returns the density matrix as a counts dict of probabilities. to_dict([decimals]) Convert the density matrix to dictionary form. Convert to Operator to_statevector([atol, rtol]) Return a statevector from a pure density matrix. Return the trace of the 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.

パラメータ

other (QuantumState) – a quantum state object.

the linear combination self + other.

LinearOperator

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 density matrix.

copy()

Make a copy of current operator.

property data

Return data.

property dim

dims(qargs=None)

Return tuple of input dimension for specified subsystems.

evolve(other, qargs=None)[ソース]

Evolve a quantum state by an operator.

パラメータ
• (Operator or QuantumChannel (other) – or Instruction or Circuit): The operator to evolve by.

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

the output quantum state.

QuantumState

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

expand(other)[ソース]

Return the tensor product state other ⊗ self.

パラメータ

other (DensityMatrix) – a quantum state object.

the tensor product state other ⊗ self.

DensityMatrix

QiskitError – if other is not a quantum state.

expectation_value(oper, qargs=None)[ソース]

Compute the expectation value of an operator.

パラメータ
• oper (Operator) – an operator to evaluate expval.

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

the expectation value.

complex

classmethod from_instruction(instruction)[ソース]

Return the output density matrix 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.

パラメータ

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

the final density matrix.

DensityMatrix

QiskitError – if the instruction contains invalid instructions for density matrix simulation.

static from_int(i, dims)[ソース]

Return a computational basis state density matrix.

パラメータ
• i (int) – the basis state element.

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

The computational basis state $$|i\rangle\!\langle i|$$.

DensityMatrix

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 16 Single-qubit state labels

Label

Statevector

"0"

$$\begin{pmatrix} 1 & 0 \\ 0 & 0 \end{pmatrix}$$

"1"

$$\begin{pmatrix} 0 & 0 \\ 0 & 1 \end{pmatrix}$$

"+"

$$\frac{1}{2}\begin{pmatrix} 1 & 1 \\ 1 & 1 \end{pmatrix}$$

"-"

$$\frac{1}{2}\begin{pmatrix} 1 & -1 \\ -1 & 1 \end{pmatrix}$$

"r"

$$\frac{1}{2}\begin{pmatrix} 1 & -i \\ i & 1 \end{pmatrix}$$

"l"

$$\frac{1}{2}\begin{pmatrix} 1 & i \\ -i & 1 \end{pmatrix}$$

パラメータ

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

The N-qubit basis state density matrix.

Statevector

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 trace 1 and positive semidefinite.

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.

パラメータ

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

the pair (outcome, state) where outcome is the

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

tuple

multiply(other)

Return the scalar multipled state other * self.

パラメータ

other (complex) – a complex number.

the scalar multipled state other * self.

QuantumState

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.

パラメータ
• 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).

The Numpy vector array of probabilities.

np.array

サンプル

Consider a 2-qubit product state $$\rho=\rho_1\otimes\rho_0$$ with $$\rho_1=|+\rangle\!\langle+|$$, $$\rho_0=|0\rangle\!\langle0|$$.

from qiskit.quantum_info import DensityMatrix

rho = DensityMatrix.from_label('+0')

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

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

# Probabilities for measuring only qubit-1
probs_qubit_1 = rho.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 DensityMatrix

rho = DensityMatrix.from_label('+0')

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

# Probabilities for measuring both qubits
# but swapping qubits 0 and 1 in output
probs_swapped = rho.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.

パラメータ
• 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).

The measurement probabilities in dict (ket) form.

dict

purity()[ソース]

Return the purity of the quantum state.

reset(qargs=None)[ソース]

Reset state or subsystems to the 0-state.

パラメータ

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

the reset state.

DensityMatrix

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 evolution by the reset SuperOp of the reset subsystems.

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.

パラメータ
• 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).

sampled counts dictionary.

Counts

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.

パラメータ
• 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).

list of sampled counts if the order sampled.

np.array

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.

パラメータ

other (QuantumState) – a quantum state object.

the linear combination self - other.

LinearOperator

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

tensor(other)[ソース]

Return the tensor product state self ⊗ other.

パラメータ

other (DensityMatrix) – a quantum state object.

the tensor product operator self ⊗ other.

DensityMatrix

QiskitError – if other is not a quantum state.

to_counts()[ソース]

Returns the density matrix as a counts dict of probabilities.

DEPRECATED: use probabilities_dict() instead.

Counts of probabilities.

dict

to_dict(decimals=None)[ソース]

Convert the density matrix 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.

パラメータ

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

the dictionary form of the DensityMatrix.

dict

サンプル

The ket-form of a 2-qubit density matrix $$rho = |-\rangle\!\langle -|\otimes |0\rangle\!\langle 0|$$

from qiskit.quantum_info import DensityMatrix

rho = DensityMatrix.from_label('-0')
print(rho.to_dict())

{'00|00': (0.4999999999999999+0j), '10|00': (-0.4999999999999999-0j), '00|10': (-0.4999999999999999+0j), '10|10': (0.4999999999999999+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 DensityMatrix

mat = np.zeros((9, 9))
mat[0, 0] = 0.25
mat[3, 3] = 0.25
mat[6, 6] = 0.25
mat[-1, -1] = 0.25
rho = DensityMatrix(mat, dims=(3, 3))
print(rho.to_dict())

{'00|00': (0.25+0j), '10|10': (0.25+0j), '20|20': (0.25+0j), '22|22': (0.25+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 DensityMatrix

mat = np.zeros((2 * 10, 2 * 10))
mat[0, 0] = 0.5
mat[-1, -1] = 0.5
rho = DensityMatrix(mat, dims=(2, 10))
print(rho.to_dict())

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

to_operator()[ソース]

Convert to Operator

to_statevector(atol=None, rtol=None)[ソース]

Return a statevector from a pure density matrix.

パラメータ
• atol (float) – Absolute tolerance for checking operation validity.

• rtol (float) – Relative tolerance for checking operation validity.

The pure density matrix’s corresponding statevector.

Corresponds to the eigenvector of the only non-zero eigenvalue.

Statevector

QiskitError – if the state is not pure.

trace()[ソース]

Return the trace of the density matrix.