# DensityMatrix

`qiskit.quantum_info.DensityMatrix(data, dims=None)`

Bases: `QuantumState`

, `TolerancesMixin`

DensityMatrix class

Initialize a density matrix object.

**Parameters**

**or**(*data (np.ndarray or**list*(opens in a new tab)*or matrix_like or**QuantumCircuit*) – qiskit.circuit.Instruction): A statevector, quantum instruction or an object with a`to_operator`

or`to_matrix`

method from which the density matrix can be constructed. If a vector the density matrix is constructed as the projector of that vector. If a quantum instruction, the density matrix is constructed by assuming all qubits are initialized in the zero state.**dims**(*int*(opens in a new tab)*or**tuple*(opens in a new tab)*or**list*(opens in a new tab)) – 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`

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.

## Attributes

### atol

`= 1e-08`

### data

Return data.

### dim

Return total state dimension.

### num_qubits

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

### rtol

`= 1e-05`

### settings

Return settings.

## Methods

### conjugate

`conjugate()`

Return the conjugate of the density matrix.

### copy

`copy()`

Make a copy of current operator.

### dims

`dims(qargs=None)`

Return tuple of input dimension for specified subsystems.

### draw

`draw(output=None, **drawer_args)`

Return a visualization of the Statevector.

**repr**: ASCII TextMatrix of the state’s `__repr__`

.

**text**: ASCII TextMatrix that can be printed in the console.

**latex**: An IPython Latex object for displaying in Jupyter Notebooks.

**latex_source**: Raw, uncompiled ASCII source to generate array using LaTeX.

**qsphere**: Matplotlib figure, rendering of density matrix using plot_state_qsphere().

**hinton**: Matplotlib figure, rendering of density matrix using plot_state_hinton().

**bloch**: Matplotlib figure, rendering of density matrix using plot_bloch_multivector().

**Parameters**

**output**(*str*(opens in a new tab)) – Select the output method to use for drawing the state. Valid choices are repr, text, latex, latex_source, qsphere, hinton, or bloch. Default is repr. Default can be changed by adding the line`state_drawer = <default>`

to`~/.qiskit/settings.conf`

under`[default]`

.**drawer_args**– Arguments to be passed directly to the relevant drawing function or constructor (TextMatrix(), array_to_latex(), plot_state_qsphere(), plot_state_hinton() or plot_bloch_multivector()). See the relevant function under qiskit.visualization for that function’s documentation.

**Returns**

`matplotlib.Figure`

or `str`

(opens in a new tab) or `TextMatrix`

or `IPython.display.Latex`

: Drawing of the Statevector.

**Raises**

**ValueError** (opens in a new tab) – when an invalid output method is selected.

### evolve

`evolve(other, qargs=None)`

Evolve a quantum state by an operator.

**Parameters**

**QuantumChannel**(*other (Operator or*) – or Instruction or Circuit): The operator to evolve by.**qargs**(*list*(opens in a new tab)) – a list of QuantumState subsystem positions to apply the operator on.

**Returns**

the output density matrix.

**Return type**

**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*(opens in a new tab)) – subsystems to apply the operator on.

**Returns**

the expectation value.

**Return type**

### from_instruction

`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.

**Parameters**

**instruction** (*qiskit.circuit.Instruction* *or**QuantumCircuit*) – 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*(opens in a new tab)) – the basis state element.**dims**(*int*(opens in a new tab)*or**tuple*(opens in a new tab)*or**list*(opens in a new tab)) – The subsystem dimensions of the statevector (See additional information).

**Returns**

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

**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"` | $\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}$ |

**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* (opens in a new tab) *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**

### partial_transpose

`partial_transpose(qargs)`

Return partially transposed density matrix.

**Parameters**

**qargs** (*list* (opens in a new tab)) – The subsystems to be transposed.

**Returns**

The partially transposed density matrix.

**Return type**

### 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*(opens in a new tab)) – subsystems to return probabilities for, if None return for all subsystems (Default: None).**decimals**(*None or**int*(opens in a new tab)) – 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 $\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

`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*(opens in a new tab)) – subsystems to return probabilities for, if None return for all subsystems (Default: None).**decimals**(*None or**int*(opens in a new tab)) – 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**

### purity

`purity()`

Return the purity of the quantum state.

### reset

`reset(qargs=None)`

Reset state or subsystems to the 0-state.

**Parameters**

**qargs** (*list* (opens in a new tab) *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.

### reverse_qargs

`reverse_qargs()`

Return a DensityMatrix with reversed subsystem ordering.

For a tensor product state this is equivalent to reversing the order of tensor product subsystems. For a density matrix $\rho = \rho_{n-1} \otimes ... \otimes \rho_0$ the returned state will be $\rho_0 \otimes ... \otimes \rho_{n-1}$.

**Returns**

the state with reversed subsystem order.

**Return type**

### sample_counts

`sample_counts(shots, qargs=None)`

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

**Parameters**

**shots**(*int*(opens in a new tab)) – number of samples to generate.**qargs**(*None or**list*(opens in a new tab)) – subsystems to sample measurements for, if None sample measurement of all subsystems (Default: None).

**Returns**

sampled counts dictionary.

**Return type**

Additional Information:

This function

samplesmeasurement 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*(opens in a new tab)) – number of samples to generate.**qargs**(*None or**list*(opens in a new tab)) – 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

samplesmeasurement 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.

### 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_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* (opens in a new tab)) – 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**

## Examples

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 delimiters 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

**Return type**

### to_statevector

`to_statevector(atol=None, rtol=None)`

Return a statevector from a pure density matrix.

**Parameters**

**atol**(*float*(opens in a new tab)) – Absolute tolerance for checking operation validity.**rtol**(*float*(opens in a new tab)) – 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.