646 lines
27 KiB
Plaintext
646 lines
27 KiB
Plaintext
---
|
||
title: DensityMatrix (v1.2)
|
||
description: API reference for qiskit.quantum_info.DensityMatrix in qiskit v1.2
|
||
in_page_toc_min_heading_level: 1
|
||
python_api_type: class
|
||
python_api_name: qiskit.quantum_info.DensityMatrix
|
||
---
|
||
|
||
# DensityMatrix
|
||
|
||
<Class id="qiskit.quantum_info.DensityMatrix" isDedicatedPage={true} github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/quantum_info/states/densitymatrix.py#L41-L845" signature="qiskit.quantum_info.DensityMatrix(data, dims=None)" modifiers="class">
|
||
Bases: `QuantumState`, `TolerancesMixin`
|
||
|
||
DensityMatrix class
|
||
|
||
Initialize a density matrix object.
|
||
|
||
**Parameters**
|
||
|
||
* **or** (*data (np.ndarray or* [*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)") *or matrix\_like or*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.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*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *or*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)")) – Optional. The subsystem dimension of the state (See additional information).
|
||
|
||
**Raises**
|
||
|
||
[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.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
|
||
|
||
<Attribute id="qiskit.quantum_info.DensityMatrix.atol" attributeValue="1e-08" />
|
||
|
||
### data
|
||
|
||
<Attribute id="qiskit.quantum_info.DensityMatrix.data">
|
||
Return data.
|
||
</Attribute>
|
||
|
||
### dim
|
||
|
||
<Attribute id="qiskit.quantum_info.DensityMatrix.dim">
|
||
Return total state dimension.
|
||
</Attribute>
|
||
|
||
### num\_qubits
|
||
|
||
<Attribute id="qiskit.quantum_info.DensityMatrix.num_qubits">
|
||
Return the number of qubits if a N-qubit state or None otherwise.
|
||
</Attribute>
|
||
|
||
### rtol
|
||
|
||
<Attribute id="qiskit.quantum_info.DensityMatrix.rtol" attributeValue="1e-05" />
|
||
|
||
### settings
|
||
|
||
<Attribute id="qiskit.quantum_info.DensityMatrix.settings">
|
||
Return settings.
|
||
</Attribute>
|
||
|
||
## Methods
|
||
|
||
### conjugate
|
||
|
||
<Function id="qiskit.quantum_info.DensityMatrix.conjugate" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/quantum_info/states/densitymatrix.py#L212-L214" signature="conjugate()">
|
||
Return the conjugate of the density matrix.
|
||
</Function>
|
||
|
||
### copy
|
||
|
||
<Function id="qiskit.quantum_info.DensityMatrix.copy" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/quantum_info/states/quantum_state.py#L74-L76" signature="copy()">
|
||
Make a copy of current operator.
|
||
</Function>
|
||
|
||
### dims
|
||
|
||
<Function id="qiskit.quantum_info.DensityMatrix.dims" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/quantum_info/states/quantum_state.py#L70-L72" signature="dims(qargs=None)">
|
||
Return tuple of input dimension for specified subsystems.
|
||
</Function>
|
||
|
||
### draw
|
||
|
||
<Function id="qiskit.quantum_info.DensityMatrix.draw" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/quantum_info/states/densitymatrix.py#L136-L176" signature="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*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)")) – 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`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)") or `TextMatrix` or `IPython.display.Latex`: Drawing of the Statevector.
|
||
|
||
**Raises**
|
||
|
||
[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – when an invalid output method is selected.
|
||
</Function>
|
||
|
||
### evolve
|
||
|
||
<Function id="qiskit.quantum_info.DensityMatrix.evolve" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/quantum_info/states/densitymatrix.py#L304-L343" signature="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*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)")) – a list of QuantumState subsystem positions to apply the operator on.
|
||
|
||
**Returns**
|
||
|
||
the output density matrix.
|
||
|
||
**Return type**
|
||
|
||
[DensityMatrix](#qiskit.quantum_info.DensityMatrix "qiskit.quantum_info.DensityMatrix")
|
||
|
||
**Raises**
|
||
|
||
[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the operator dimension does not match the specified QuantumState subsystem dimensions.
|
||
</Function>
|
||
|
||
### expand
|
||
|
||
<Function id="qiskit.quantum_info.DensityMatrix.expand" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/quantum_info/states/densitymatrix.py#L247-L264" signature="expand(other)">
|
||
Return the tensor product state other ⊗ self.
|
||
|
||
**Parameters**
|
||
|
||
**other** ([*DensityMatrix*](#qiskit.quantum_info.DensityMatrix "qiskit.quantum_info.DensityMatrix")) – a quantum state object.
|
||
|
||
**Returns**
|
||
|
||
the tensor product state other ⊗ self.
|
||
|
||
**Return type**
|
||
|
||
[DensityMatrix](#qiskit.quantum_info.DensityMatrix "qiskit.quantum_info.DensityMatrix")
|
||
|
||
**Raises**
|
||
|
||
[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if other is not a quantum state.
|
||
</Function>
|
||
|
||
### expectation\_value
|
||
|
||
<Function id="qiskit.quantum_info.DensityMatrix.expectation_value" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/quantum_info/states/densitymatrix.py#L400-L421" signature="expectation_value(oper, qargs=None)">
|
||
Compute the expectation value of an operator.
|
||
|
||
**Parameters**
|
||
|
||
* **oper** ([*Operator*](qiskit.quantum_info.Operator "qiskit.quantum_info.Operator")) – an operator to evaluate expval.
|
||
* **qargs** (*None or* [*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)")) – subsystems to apply the operator on.
|
||
|
||
**Returns**
|
||
|
||
the expectation value.
|
||
|
||
**Return type**
|
||
|
||
[complex](https://docs.python.org/3/library/functions.html#complex "(in Python v3.13)")
|
||
</Function>
|
||
|
||
### from\_instruction
|
||
|
||
<Function id="qiskit.quantum_info.DensityMatrix.from_instruction" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/quantum_info/states/densitymatrix.py#L600-L627" signature="from_instruction(instruction)" modifiers="classmethod">
|
||
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*](qiskit.circuit.Instruction "qiskit.circuit.Instruction") *or*[*QuantumCircuit*](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – instruction or circuit
|
||
|
||
**Returns**
|
||
|
||
the final density matrix.
|
||
|
||
**Return type**
|
||
|
||
[DensityMatrix](#qiskit.quantum_info.DensityMatrix "qiskit.quantum_info.DensityMatrix")
|
||
|
||
**Raises**
|
||
|
||
[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the instruction contains invalid instructions for density matrix simulation.
|
||
</Function>
|
||
|
||
### from\_int
|
||
|
||
<Function id="qiskit.quantum_info.DensityMatrix.from_int" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/quantum_info/states/densitymatrix.py#L572-L598" signature="from_int(i, dims)" modifiers="static">
|
||
Return a computational basis state density matrix.
|
||
|
||
**Parameters**
|
||
|
||
* **i** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – the basis state element.
|
||
* **dims** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *or*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)")) – The subsystem dimensions of the statevector (See additional information).
|
||
|
||
**Returns**
|
||
|
||
The computational basis state $|i\rangle\!\langle i|$.
|
||
|
||
**Return type**
|
||
|
||
[DensityMatrix](#qiskit.quantum_info.DensityMatrix "qiskit.quantum_info.DensityMatrix")
|
||
|
||
**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.
|
||
</Function>
|
||
|
||
### from\_label
|
||
|
||
<Function id="qiskit.quantum_info.DensityMatrix.from_label" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/quantum_info/states/densitymatrix.py#L536-L570" signature="from_label(label)" modifiers="classmethod">
|
||
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**
|
||
|
||
[DensityMatrix](#qiskit.quantum_info.DensityMatrix "qiskit.quantum_info.DensityMatrix")
|
||
|
||
**Raises**
|
||
|
||
[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the label contains invalid characters, or the length of the label is larger than an explicitly specified num\_qubits.
|
||
</Function>
|
||
|
||
### is\_valid
|
||
|
||
<Function id="qiskit.quantum_info.DensityMatrix.is_valid" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/quantum_info/states/densitymatrix.py#L192-L205" signature="is_valid(atol=None, rtol=None)">
|
||
Return True if trace 1 and positive semidefinite.
|
||
</Function>
|
||
|
||
### measure
|
||
|
||
<Function id="qiskit.quantum_info.DensityMatrix.measure" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/quantum_info/states/quantum_state.py#L306-L341" signature="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()`](#qiskit.quantum_info.DensityMatrix.seed "qiskit.quantum_info.DensityMatrix.seed") method.
|
||
|
||
**Parameters**
|
||
|
||
**qargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)") *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](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")
|
||
</Function>
|
||
|
||
### partial\_transpose
|
||
|
||
<Function id="qiskit.quantum_info.DensityMatrix.partial_transpose" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/quantum_info/states/densitymatrix.py#L828-L845" signature="partial_transpose(qargs)">
|
||
Return partially transposed density matrix.
|
||
|
||
**Parameters**
|
||
|
||
**qargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)")) – The subsystems to be transposed.
|
||
|
||
**Returns**
|
||
|
||
The partially transposed density matrix.
|
||
|
||
**Return type**
|
||
|
||
[DensityMatrix](#qiskit.quantum_info.DensityMatrix "qiskit.quantum_info.DensityMatrix")
|
||
</Function>
|
||
|
||
### probabilities
|
||
|
||
<Function id="qiskit.quantum_info.DensityMatrix.probabilities" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/quantum_info/states/densitymatrix.py#L423-L503" signature="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*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)")) – subsystems to return probabilities for, if None return for all subsystems (Default: None).
|
||
* **decimals** (*None or* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – 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|$.
|
||
|
||
```python
|
||
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))
|
||
```
|
||
|
||
```python
|
||
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
|
||
|
||
```python
|
||
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))
|
||
```
|
||
|
||
```python
|
||
probs: [0.5 0. 0.5 0. ]
|
||
Swapped probs: [0.5 0.5 0. 0. ]
|
||
```
|
||
</Function>
|
||
|
||
### probabilities\_dict
|
||
|
||
<Function id="qiskit.quantum_info.DensityMatrix.probabilities_dict" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/quantum_info/states/quantum_state.py#L220-L244" signature="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*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)")) – subsystems to return probabilities for, if None return for all subsystems (Default: None).
|
||
* **decimals** (*None or* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – 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](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.13)")
|
||
</Function>
|
||
|
||
### purity
|
||
|
||
<Function id="qiskit.quantum_info.DensityMatrix.purity" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/quantum_info/states/densitymatrix.py#L220-L226" signature="purity()">
|
||
Return the purity of the quantum state.
|
||
</Function>
|
||
|
||
### reset
|
||
|
||
<Function id="qiskit.quantum_info.DensityMatrix.reset" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/quantum_info/states/densitymatrix.py#L505-L534" signature="reset(qargs=None)">
|
||
Reset state or subsystems to the 0-state.
|
||
|
||
**Parameters**
|
||
|
||
**qargs** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)") *or None*) – subsystems to reset, if None all subsystems will be reset to their 0-state (Default: None).
|
||
|
||
**Returns**
|
||
|
||
the reset state.
|
||
|
||
**Return type**
|
||
|
||
[DensityMatrix](#qiskit.quantum_info.DensityMatrix "qiskit.quantum_info.DensityMatrix")
|
||
|
||
**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`](qiskit.quantum_info.SuperOp "qiskit.quantum_info.SuperOp") of the reset subsystems.
|
||
</Function>
|
||
|
||
### reverse\_qargs
|
||
|
||
<Function id="qiskit.quantum_info.DensityMatrix.reverse_qargs" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/quantum_info/states/densitymatrix.py#L345-L365" signature="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**
|
||
|
||
[DensityMatrix](#qiskit.quantum_info.DensityMatrix "qiskit.quantum_info.DensityMatrix")
|
||
</Function>
|
||
|
||
### sample\_counts
|
||
|
||
<Function id="qiskit.quantum_info.DensityMatrix.sample_counts" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/quantum_info/states/quantum_state.py#L277-L304" signature="sample_counts(shots, qargs=None)">
|
||
Sample a dict of qubit measurement outcomes in the computational basis.
|
||
|
||
**Parameters**
|
||
|
||
* **shots** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – number of samples to generate.
|
||
* **qargs** (*None or* [*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)")) – subsystems to sample measurements for, if None sample measurement of all subsystems (Default: None).
|
||
|
||
**Returns**
|
||
|
||
sampled counts dictionary.
|
||
|
||
**Return type**
|
||
|
||
[Counts](qiskit.result.Counts "qiskit.result.Counts")
|
||
|
||
Additional Information:
|
||
|
||
> This function *samples* measurement outcomes using the measure [`probabilities()`](#qiskit.quantum_info.DensityMatrix.probabilities "qiskit.quantum_info.DensityMatrix.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()`](#qiskit.quantum_info.DensityMatrix.seed "qiskit.quantum_info.DensityMatrix.seed") method.
|
||
</Function>
|
||
|
||
### sample\_memory
|
||
|
||
<Function id="qiskit.quantum_info.DensityMatrix.sample_memory" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/quantum_info/states/quantum_state.py#L246-L275" signature="sample_memory(shots, qargs=None)">
|
||
Sample a list of qubit measurement outcomes in the computational basis.
|
||
|
||
**Parameters**
|
||
|
||
* **shots** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – number of samples to generate.
|
||
* **qargs** (*None or* [*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)")) – 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()`](#qiskit.quantum_info.DensityMatrix.probabilities "qiskit.quantum_info.DensityMatrix.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()`](#qiskit.quantum_info.DensityMatrix.seed "qiskit.quantum_info.DensityMatrix.seed") method.
|
||
</Function>
|
||
|
||
### seed
|
||
|
||
<Function id="qiskit.quantum_info.DensityMatrix.seed" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/quantum_info/states/quantum_state.py#L78-L85" signature="seed(value=None)">
|
||
Set the seed for the quantum state RNG.
|
||
</Function>
|
||
|
||
### tensor
|
||
|
||
<Function id="qiskit.quantum_info.DensityMatrix.tensor" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/quantum_info/states/densitymatrix.py#L228-L245" signature="tensor(other)">
|
||
Return the tensor product state self ⊗ other.
|
||
|
||
**Parameters**
|
||
|
||
**other** ([*DensityMatrix*](#qiskit.quantum_info.DensityMatrix "qiskit.quantum_info.DensityMatrix")) – a quantum state object.
|
||
|
||
**Returns**
|
||
|
||
the tensor product operator self ⊗ other.
|
||
|
||
**Return type**
|
||
|
||
[DensityMatrix](#qiskit.quantum_info.DensityMatrix "qiskit.quantum_info.DensityMatrix")
|
||
|
||
**Raises**
|
||
|
||
[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if other is not a quantum state.
|
||
</Function>
|
||
|
||
### to\_dict
|
||
|
||
<Function id="qiskit.quantum_info.DensityMatrix.to_dict" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/quantum_info/states/densitymatrix.py#L629-L707" signature="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*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – 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](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.13)")
|
||
|
||
**Examples**
|
||
|
||
The ket-form of a 2-qubit density matrix $rho = |-\rangle\!\langle -|\otimes |0\rangle\!\langle 0|$
|
||
|
||
```python
|
||
from qiskit.quantum_info import DensityMatrix
|
||
|
||
rho = DensityMatrix.from_label('-0')
|
||
print(rho.to_dict())
|
||
```
|
||
|
||
```python
|
||
{
|
||
'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
|
||
|
||
```python
|
||
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())
|
||
```
|
||
|
||
```python
|
||
{'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.
|
||
|
||
```python
|
||
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())
|
||
```
|
||
|
||
```python
|
||
{'00|00': (0.5+0j), '91|91': (0.5+0j)}
|
||
```
|
||
</Function>
|
||
|
||
### to\_operator
|
||
|
||
<Function id="qiskit.quantum_info.DensityMatrix.to_operator" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/quantum_info/states/densitymatrix.py#L207-L210" signature="to_operator()">
|
||
Convert to Operator
|
||
|
||
**Return type**
|
||
|
||
[*Operator*](qiskit.quantum_info.Operator "qiskit.quantum_info.operators.operator.Operator")
|
||
</Function>
|
||
|
||
### to\_statevector
|
||
|
||
<Function id="qiskit.quantum_info.DensityMatrix.to_statevector" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/quantum_info/states/densitymatrix.py#L796-L826" signature="to_statevector(atol=None, rtol=None)">
|
||
Return a statevector from a pure density matrix.
|
||
|
||
**Parameters**
|
||
|
||
* **atol** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")) – Absolute tolerance for checking operation validity.
|
||
* **rtol** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")) – 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**
|
||
|
||
[Statevector](qiskit.quantum_info.Statevector "qiskit.quantum_info.Statevector")
|
||
|
||
**Raises**
|
||
|
||
[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – if the state is not pure.
|
||
</Function>
|
||
|
||
### trace
|
||
|
||
<Function id="qiskit.quantum_info.DensityMatrix.trace" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/quantum_info/states/densitymatrix.py#L216-L218" signature="trace()">
|
||
Return the trace of the density matrix.
|
||
</Function>
|
||
</Class>
|
||
|