qiskit.quantum_info.DensityMatrix
class DensityMatrix(data, dims=None)
DensityMatrix class
Initialize a density matrix object.
Parameters
- 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).
Raises
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
orNone
– 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__
__init__(data, dims=None)
Initialize a density matrix object.
Parameters
- 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).
Raises
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
orNone
– 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. |
conjugate () | Return the conjugate of the density matrix. |
copy () | 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. |
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 density matrix as a counts dict of probabilities. |
to_dict ([decimals]) | Convert the density matrix to dictionary form. |
to_operator () | Convert to Operator |
to_statevector ([atol, rtol]) | Return a statevector from a pure density matrix. |
trace () | 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
add(other)
Return the linear combination self + other.
DEPRECATED: use state + other
instead.
Parameters
other (QuantumState) – a quantum state object.
Returns
the linear combination self + other.
Return type
LinearOperator
Raises
QiskitError – if other is not a quantum state, or has incompatible dimensions.
atol
The absolute tolerance parameter for float comparisons.
conjugate
conjugate()
Return the conjugate of the density matrix.
copy
copy()
Make a copy of current operator.
data
Return data.
dim
Return total state dimension.
dims
dims(qargs=None)
Return tuple of input dimension for specified subsystems.
evolve
evolve(other, qargs=None)
Evolve a quantum state by an operator.
Parameters
- **(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.
Returns
the output quantum state.
Return type
QuantumState
Raises
QiskitError – if the operator dimension does not match the specified QuantumState subsystem dimensions.
expand
expand(other)
Return the tensor product state other ⊗ self.
Parameters
other (DensityMatrix) – a quantum state object.
Returns
the tensor product state other ⊗ self.
Return type
Raises
QiskitError – if other is not a quantum state.
expectation_value
expectation_value(oper, qargs=None)
Compute the expectation value of an operator.
Parameters
- oper (Operator) – an operator to evaluate expval.
- qargs (None or list) – subsystems to apply the operator on.
Returns
the expectation value.
Return type
complex
from_instruction
classmethod from_instruction(instruction)
Return the output density matrix of an instruction.
The statevector is initialized in the state of the same number of qubits as the input instruction or circuit, evolved by the input instruction, and the output statevector returned.
Parameters
instruction (qiskit.circuit.Instruction orQuantumCircuit) – instruction or circuit
Returns
the final density matrix.
Return type
Raises
QiskitError – if the instruction contains invalid instructions for density matrix simulation.
from_int
static from_int(i, dims)
Return a computational basis state density matrix.
Parameters
- i (int) – the basis state element.
- dims (int or tuple or list) – The subsystem dimensions of the statevector (See additional information).
Returns
The computational basis state .
Return type
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.
from_label
classmethod from_label(label)
Return a tensor product of Pauli X,Y,Z eigenstates.
Label | Statevector |
---|
| "0"
| |
| "1"
| |
| "+"
| |
| "-"
| |
| "r"
| |
| "l"
| |
Parameters
label (string) – a eigenstate string ket label (see table for allowed values).
Returns
The N-qubit basis state density matrix.
Return type
Raises
QiskitError – if the label contains invalid characters, or the length of the label is larger than an explicitly specified num_qubits.
is_valid
is_valid(atol=None, rtol=None)
Return True if trace 1 and positive semidefinite.
measure
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.
Parameters
qargs (list or None) – subsystems to sample measurements for, if None sample measurement of all subsystems (Default: None).
Returns
the pair (outcome, state)
where outcome
is the
measurement outcome string label, and state
is the collapsed post-measurement state for the corresponding outcome.
Return type
tuple
multiply
multiply(other)
Return the scalar multipled state other * self.
Parameters
other (complex) – a complex number.
Returns
the scalar multipled state other * self.
Return type
QuantumState
Raises
QiskitError – if other is not a valid complex number.
num_qubits
Return the number of qubits if a N-qubit state or None otherwise.
probabilities
probabilities(qargs=None, decimals=None)
Return the subsystem measurement probability vector.
Measurement probabilities are with respect to measurement in the computation (diagonal) basis.
Parameters
- 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).
Returns
The Numpy vector array of probabilities.
Return type
np.array
Examples
Consider a 2-qubit product state with , .
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
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.
Parameters
- 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).
Returns
The measurement probabilities in dict (ket) form.
Return type
dict
purity
purity()
Return the purity of the quantum state.
reset
reset(qargs=None)
Reset state or subsystems to the 0-state.
Parameters
qargs (list or None) – subsystems to reset, if None all subsystems will be reset to their 0-state (Default: None).
Returns
the reset state.
Return type
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 evolution by the reset SuperOp
of the reset subsystems.
rtol
The relative tolerance parameter for float comparisons.
sample_counts
sample_counts(shots, qargs=None)
Sample a dict of qubit measurement outcomes in the computational basis.
Parameters
- 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).
Returns
sampled counts dictionary.
Return type
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
sample_memory(shots, qargs=None)
Sample a list of qubit measurement outcomes in the computational basis.
Parameters
- 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).
Returns
list of sampled counts if the order sampled.
Return type
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
seed(value=None)
Set the seed for the quantum state RNG.
set_atol
classmethod set_atol(value)
Set the class default absolute tolerance parameter for float comparisons.
DEPRECATED: use operator.atol = value instead
set_rtol
classmethod set_rtol(value)
Set the class default relative tolerance parameter for float comparisons.
DEPRECATED: use operator.rtol = value instead
subtract
subtract(other)
Return the linear operator self - other.
DEPRECATED: use state - other
instead.
Parameters
other (QuantumState) – a quantum state object.
Returns
the linear combination self - other.
Return type
LinearOperator
Raises
QiskitError – if other is not a quantum state, or has incompatible dimensions.
tensor
tensor(other)
Return the tensor product state self ⊗ other.
Parameters
other (DensityMatrix) – a quantum state object.
Returns
the tensor product operator self ⊗ other.
Return type
Raises
QiskitError – if other is not a quantum state.
to_counts
to_counts()
Returns the density matrix as a counts dict of probabilities.
DEPRECATED: use probabilities_dict()
instead.
Returns
Counts of probabilities.
Return type
dict
to_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.
Parameters
decimals (None or int) – the number of decimal places to round values. If None no rounding is done (Default: None).
Returns
the dictionary form of the DensityMatrix.
Return type
dict
Examples
The ket-form of a 2-qubit density matrix
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
to_operator()
Convert to Operator
to_statevector
to_statevector(atol=None, rtol=None)
Return a statevector from a pure density matrix.
Parameters
- atol (float) – Absolute tolerance for checking operation validity.
- rtol (float) – Relative tolerance for checking operation validity.
Returns
The pure density matrix’s corresponding statevector.
Corresponds to the eigenvector of the only non-zero eigenvalue.
Return type
Raises
QiskitError – if the state is not pure.
trace
trace()
Return the trace of the density matrix.