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

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

purity

purity() -> float

Return the purity $\mathrm{Tr}({\rho }^2)$ of the density matrix. A pure state has purity 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.

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() -> StateVector

If the density matrix represents a pure state (purity = 1), return the corresponding StateVector. This is equivalent to extracting the eigenvector associated with the eigenvalue 1.

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

# 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

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

# Convert back to a state vector (pure states only)
sv_back = dm.to_statevector()

# Get numpy array
arr = dm.ndarray()

See Also

• StateVector
• QuantumChannel
• Matrix