DensityMatrix

A general (mixed or pure) quantum state represented as a positive semi-definite, trace-1 density matrix $\rho$ of dimension $2^n\times 2^n$, where $n$ is the number of qubits.

A valid density matrix satisfies:

• Hermiticity: $\rho ={\rho }^{†}$
• Positive semi-definiteness: all eigenvalues $\ge 0$
• Unit trace: $\mathrm{Tr}(\rho )=1$

Constructors

Default constructor

DensityMatrix()

Constructs a single-qubit density matrix for the $|0⟩$ state: $\rho =|0⟩⟨0|=\left(\begin{array}{cc}1& 0\\ 0& 0\end{array}\right)$.

Copy constructor

DensityMatrix(other: DensityMatrix)

Construct a DensityMatrix as a copy of another DensityMatrix.

Parameter	Type	Description
other	DensityMatrix	An existing DensityMatrix to copy.

From a 2-D complex list

DensityMatrix(data: list[list[complex]])

Construct a density matrix from a 2-D list of complex numbers.

Parameter	Type	Description
data	list[list[complex]]	A square 2-D array of complex numbers.

From a numpy array / Eigen matrix

DensityMatrix(data: numpy.ndarray)

Construct a density matrix from a 2-D complex numpy array (or Eigen matrix).

Parameter	Type	Description
data	numpy.ndarray	A square 2-D array of complex numbers.

From qubit count

DensityMatrix(qbit_total: int)

Construct a density matrix for qbit_total qubits initialized to the all-zeros state $|0{⟩}^{\otimes n}$.

Parameter	Type	Description
qbit_total	int	The number of qubits. The resulting matrix has dimension $2^{\mathtt{\text{qbit\_total}}}\times 2^{\mathtt{\text{qbit\_total}}}$.

From a StateVector

DensityMatrix(other: StateVector)

Construct a density matrix as $\rho =|\psi ⟩⟨\psi |$ from an existing StateVector.

Parameter	Type	Description
other	StateVector	A pure quantum state.

Methods

ndarray

ndarray() -> numpy.ndarray[numpy.complex128]

Return the internal density-matrix data as a 2-D numpy.ndarray.

purity

purity() -> complex

Return the purity $\mathrm{Tr}({\rho }^2)$ of the density matrix. A pure state has purity $(1+0j)$ (conceptually $1.0$); a maximally mixed state has purity $1/d$ where $d=2^n$.

evolve

evolve(circuit: QCircuit) -> DensityMatrix

Evolve the density matrix under the given quantum circuit. Returns a new DensityMatrix with the result; the original object is not modified.

NOTE

QCircuit and gate operations are available from pyqpanda3.core:

from pyqpanda3.core import QCircuit, H
circ = QCircuit() << H(0)

Parameter	Type	Description
circuit	QCircuit	The quantum circuit to apply.

update_by_evolve

update_by_evolve(circuit: QCircuit) -> DensityMatrix

Evolve the density matrix under the given quantum circuit in place, updating the internal data. Also returns the resulting DensityMatrix.

Parameter	Type	Description
circuit	QCircuit	The quantum circuit to apply.

is_valid

is_valid() -> bool

Check whether the internal data constitutes a valid density matrix (Hermitian, positive semi-definite, unit trace).

to_statevector

to_statevector() -> list[complex]

If the density matrix represents a pure state (purity = 1), return the corresponding state vector amplitudes as a list of complex numbers. This is equivalent to extracting the eigenvector associated with the eigenvalue 1.

NOTE

Calling to_statevector() on a mixed state returns an empty list [].

at

at(row_idx: int, col_idx: int) -> complex

Return the element at the specified row and column.

Parameter	Type	Description
row_idx	int	Row index (0-based).
col_idx	int	Column index (0-based).

dim

dim() -> int

Return the dimension $2^n$ of the density matrix (number of basis states).

Operators

Equality

dm_a == dm_b -> bool

Return True if the two DensityMatrix objects have identical internal data.

Examples

import numpy as np
from pyqpanda3.quantum_info import DensityMatrix, StateVector

# Construct from a StateVector (pure state)
sv = StateVector([1/np.sqrt(2), 1/np.sqrt(2)])
dm = DensityMatrix(sv)

print(dm.dim())       # 2
print(dm.is_valid())  # True
print(dm.purity())    # (1.0000000000000004+0j)

# Construct from a 2-D array (maximally mixed state)
dm_mixed = DensityMatrix([[0.5+0j, 0+0j], [0+0j, 0.5+0j]])
print(dm_mixed.purity())  # (0.5+0j)

# Access an element
val = dm.at(0, 1)  # (0.5000000000000001+0j)
print(val)

# Convert back to a state vector (pure states only, returns list of complex amplitudes)
sv_back = dm.to_statevector()
# sv_back == [(0.7071067811865475+0j), (0.7071067811865475+0j)]

# Get numpy array
arr = dm.ndarray()
print(arr)

Running the example produces:

2
True
(1.0000000000000004+0j)
(0.5+0j)
(0.5000000000000001+0j)
[[0.5+0.j 0.5+0.j]
 [0.5+0.j 0.5+0.j]]

See Also

• StateVector
• QuantumChannel
• Matrix