Quantum density matrix Ï for mixed-state representation. More...

#include <density_matrix.h>

Inheritance diagram for squander::density::DensityMatrix:

Public Member Functions
void	apply_local_unitary (const matrix_base< QGD_Complex16 > &u_kernel, const std::vector< int > &target_qbits)
	Apply k-qubit unitary using local kernel (general case) More...

void	apply_single_qubit_unitary (const matrix_base< QGD_Complex16 > &u_2x2, int target_qbit)
	Apply single-qubit unitary using local kernel (optimized) More...

void	apply_two_qubit_unitary (const matrix_base< QGD_Complex16 > &u_2x2, int target_qbit, int control_qbit)
	Apply two-qubit controlled unitary using local kernel (optimized) More...

void	apply_unitary (const matrix_base< QGD_Complex16 > &U)
	Apply unitary transformation: Ï â UÏUâ More...

DensityMatrix	clone () const
	Create deep copy. More...

void	conjugate ()
	Call to conjugate (or un-conjugate) the matrix for CBLAS functions. More...

matrix_base< QGD_Complex16 >	copy () const
	Call to create a copy of the matrix. More...

void	copy_to (matrix_base< QGD_Complex16 > &target) const
	Copy the current matrix storage into a reusable target matrix. More...

	DensityMatrix (int qbit_num)
	Create density matrix for n qubits. More...

	DensityMatrix (const matrix_base< QGD_Complex16 > &state_vector)
	Create from state vector: Ï = \|Ïâ©â¨Ï\|. More...

	DensityMatrix (QGD_Complex16 *data, int dim)
	Wrap existing data (non-owning wrapper) More...

	DensityMatrix (const DensityMatrix &other)
	Copy constructor. More...

	DensityMatrix (DensityMatrix &&other) noexcept
	Move constructor. More...

std::vector< double >	eigenvalues () const
	Get eigenvalues (sorted descending) More...

void	ensure_aligned ()

double	entropy () const
	von Neumann entropy: S(Ï) = -Tr(Ï logâ Ï) More...

QGD_Complex16 *	get_data () const
	Call to get the pointer to the stored data. More...

int	get_dim () const
	Get matrix dimension (2^qbit_num) More...

int	get_qbit_num () const
	Get number of qubits. More...

bool	is_conjugated () const
	Call to get whether the matrix should be conjugated in CBLAS functions or not. More...

bool	is_transposed () const
	Call to get whether the matrix should be conjugated in CBLAS functions or not. More...

bool	is_valid (double tol=1e-10) const
	Check if valid density matrix. More...

QGD_Complex16 &	operator() (int i, int j)
	Element access: Ï(i,j) More...

const QGD_Complex16 &	operator() (int i, int j) const

bool	operator< (const matrix_base< QGD_Complex16 > &other) const

DensityMatrix &	operator= (const DensityMatrix &other)

DensityMatrix &	operator= (DensityMatrix &&other) noexcept

QGD_Complex16 &	operator[] (int idx) const
	Operator [] to access elements in array style (does not check the boundaries of the stored array) More...

DensityMatrix	partial_trace (const std::vector< int > &trace_out) const
	Compute partial trace over specified qubits. More...

void	print () const
	Print matrix with properties. More...

void	print_matrix () const
	Call to prints the stored matrix on the standard output. More...

double	purity () const
	Calculate purity: Tr(ÏÂ²) More...

void	release_data ()
	Call to release the data stored by the matrix. More...

void	replace_data (QGD_Complex16 *data_in, bool owner_in)
	Call to replace the stored data by an another data array. More...

void	set_owner (bool owner_in)
	Call to set the current class instance to be (or not to be) the owner of the stored data array. More...

int	size () const
	Call to get the number of the allocated elements. More...

QGD_Complex16	trace () const
	Calculate trace: Tr(Ï) More...

void	transpose ()
	Call to transpose (or un-transpose) the matrix for CBLAS functions. More...

	~DensityMatrix ()=default
	Destructor (uses base class default) More...

Static Public Member Functions
static DensityMatrix	maximally_mixed (int qbit_num)
	Create maximally mixed state: Ï = I/2^n. More...

Public Attributes
int	cols
	The number of columns. More...

QGD_Complex16 *	data
	pointer to the stored data More...

int	rows
	The number of rows. More...

int	stride
	The column stride of the array. (The array elements in one row are a_0, a_1, ... a_{cols-1}, 0, 0, 0, 0. The number of zeros is stride-cols) More...

Protected Attributes
bool	conjugated
	logical variable indicating whether the matrix needs to be conjugated in CBLAS operations More...

bool	owner
	logical value indicating whether the class instance is the owner of the stored data or not. (If true, the data array is released in the destructor) More...

std::atomic< int64_t > *	references
	the number of the current references of the present object More...

bool	transposed
	logical variable indicating whether the matrix needs to be transposed in CBLAS operations More...

Private Member Functions
bool	is_hermitian (double tol) const

void	validate_dimensions () const

Private Attributes
int	qbit_num_
	Number of qubits. More...

Detailed Description

Quantum density matrix Ï for mixed-state representation.

Inherits from matrix_base<QGD_Complex16> to reuse:

Automatic memory management (reference counting)
BLAS integration via dot()
Cache-line aligned memory
Thread-safe operations with TBB spin_mutex

Adds density matrix specific:

Validation (Hermitian, Tr(Ï)=1, Ïâ¥0)
Quantum properties (purity, entropy)
Unitary evolution (Ï â UÏUâ )
Partial trace operations

Mathematical properties:

Ï = Ïâ (Hermitian)
Tr(Ï) = 1 (normalized)
Ï â¥ 0 (positive semi-definite)
Tr(ÏÂ²) â [1/2^n, 1] (purity)

Example:

using namespace squander::density;
DensityMatrix rho(2);  // 2 qubits, initialized to |00â©â¨00|
std::cout << "Purity: " << rho.purity() << std::endl;  // 1.0

Definition at line 53 of file density_matrix.h.

Constructor & Destructor Documentation

◆ DensityMatrix() [1/5]

squander::density::DensityMatrix::DensityMatrix ( int qbit_num )

explicit

Create density matrix for n qubits.

Parameters

qbit_num Number of qubits (must be >= 1)

Exceptions

std::invalid_argument if qbit_num < 1

Initializes to pure ground state: Ï = |0...0â©â¨0...0| Matrix dimension is 2^qbit_num Ã 2^qbit_num

Definition at line 56 of file density_matrix.cpp.

◆ DensityMatrix() [2/5]

squander::density::DensityMatrix::DensityMatrix ( const matrix_base< QGD_Complex16 > & state_vector )

explicit

Create from state vector: Ï = |Ïâ©â¨Ï|.

Parameters

state_vector Pure state (column vector, inherits from matrix_base)

Exceptions

std::invalid_argument if state_vector is not column vector or dim not power of 2

Computes outer product to create density matrix. Resulting matrix represents a pure state with Tr(ÏÂ²) = 1.

Definition at line 73 of file density_matrix.cpp.

◆ DensityMatrix() [3/5]

squander::density::DensityMatrix::DensityMatrix	(	QGD_Complex16 *	data,
		int	dim
	)

Wrap existing data (non-owning wrapper)

Parameters

data	Pointer to matrix data (row-major, size dim Ã dim)
dim	Matrix dimension (must be power of 2)

Exceptions

std::invalid_argument if dim is not power of 2

Creates non-owning view of existing memory. Caller is responsible for lifetime management of data.

Definition at line 97 of file density_matrix.cpp.

◆ DensityMatrix() [4/5]

squander::density::DensityMatrix::DensityMatrix ( const DensityMatrix & other )

Copy constructor.

Parameters

other Density matrix to copy

Uses matrix_base reference counting - shares memory until modified.

Definition at line 112 of file density_matrix.cpp.

◆ DensityMatrix() [5/5]

squander::density::DensityMatrix::DensityMatrix ( DensityMatrix && other )

noexcept

Move constructor.

Parameters

other Density matrix to move from

Takes ownership of other's data, leaving other in valid but empty state.

Definition at line 115 of file density_matrix.cpp.

◆ ~DensityMatrix()

squander::density::DensityMatrix::~DensityMatrix ( )

default

Destructor (uses base class default)

Member Function Documentation

◆ apply_local_unitary()

void squander::density::DensityMatrix::apply_local_unitary	(	const matrix_base< QGD_Complex16 > &	u_kernel,
		const std::vector< int > &	target_qbits
	)

Apply k-qubit unitary using local kernel (general case)

Parameters

u_kernel	The 2^k Ã 2^k unitary kernel
target_qbits	Vector of target qubit indices (size k)

General optimized local application for arbitrary k-qubit gates. Complexity: O(2^{2N+k}) instead of O(2^{3N})

For k << N, this is much faster than full matrix multiplication.

Definition at line 553 of file density_matrix.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ apply_single_qubit_unitary()

void squander::density::DensityMatrix::apply_single_qubit_unitary	(	const matrix_base< QGD_Complex16 > &	u_2x2,
		int	target_qbit
	)

Apply single-qubit unitary using local kernel (optimized)

Parameters

u_2x2	The 2Ã2 unitary kernel
target_qbit	Target qubit index

Optimized local application that avoids constructing full 2^N Ã 2^N matrix. Complexity: O(2^{2N}) instead of O(2^{3N})

This is the critical optimization for density matrix simulation. Speedup: ~2^N times faster than apply_unitary() for single-qubit gates.

Definition at line 314 of file density_matrix.cpp.

Here is the caller graph for this function:

◆ apply_two_qubit_unitary()

void squander::density::DensityMatrix::apply_two_qubit_unitary	(	const matrix_base< QGD_Complex16 > &	u_2x2,
		int	target_qbit,
		int	control_qbit
	)

Apply two-qubit controlled unitary using local kernel (optimized)

Parameters

u_2x2	The 2Ã2 unitary kernel to apply when control is \|1â©
target_qbit	Target qubit index
control_qbit	Control qubit index

Optimized local application for controlled gates (CNOT, CZ, CRX, etc.) Complexity: O(2^{2N}) instead of O(2^{3N})

Speedup: ~2^N times faster than apply_unitary() for two-qubit gates.

Definition at line 441 of file density_matrix.cpp.

Here is the caller graph for this function:

◆ apply_unitary()

void squander::density::DensityMatrix::apply_unitary ( const matrix_base< QGD_Complex16 > & U )

Apply unitary transformation: Ï â UÏUâ

Parameters

U	Unitary matrix (must be matrix_base<QGD_Complex16>)

Exceptions

std::runtime_error if dimension mismatch

Modifies density matrix in-place. Uses BLAS for efficient matrix multiplication:

temp = U * Ï
Ï = temp * Uâ

Computational complexity: O(2^(3n))

Definition at line 282 of file density_matrix.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ clone()

DensityMatrix squander::density::DensityMatrix::clone ( ) const

Create deep copy.

Returns: New density matrix with copied data

Unlike copy constructor (which shares memory), this creates independent copy.

Definition at line 742 of file density_matrix.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ conjugate()

void matrix_base< QGD_Complex16 >::conjugate ( )

inlineinherited

Call to conjugate (or un-conjugate) the matrix for CBLAS functions.

Definition at line 252 of file matrix_base.hpp.

◆ copy()

matrix_base<QGD_Complex16 > matrix_base< QGD_Complex16 >::copy ( ) const

inlineinherited

Call to create a copy of the matrix.

Returns: Returns with the instance of the class.

Definition at line 410 of file matrix_base.hpp.

◆ copy_to()

void matrix_base< QGD_Complex16 >::copy_to ( matrix_base< QGD_Complex16 > & target ) const

inlineinherited

Copy the current matrix storage into a reusable target matrix.

The target is reallocated when dimensions or stride differ; otherwise its existing allocation is reused.

Parameters

target The matrix receiving a deep copy of the current storage.

Definition at line 433 of file matrix_base.hpp.

◆ eigenvalues()

std::vector< double > squander::density::DensityMatrix::eigenvalues ( ) const

Get eigenvalues (sorted descending)

Returns: Vector of eigenvalues (all should be â¥ 0 for valid density matrix)

Uses LAPACK zheev for Hermitian eigenvalue decomposition. Computational complexity: O(2^(3n))

Definition at line 246 of file density_matrix.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ensure_aligned()

void matrix_base< QGD_Complex16 >::ensure_aligned ( )

inlineinherited

Definition at line 448 of file matrix_base.hpp.

◆ entropy()

double squander::density::DensityMatrix::entropy ( ) const

von Neumann entropy: S(Ï) = -Tr(Ï logâ Ï)

Returns

Real number â¥ 0

0 = pure state
logâ(2^n) = n bits = maximally mixed state

Computational complexity: O(2^(3n)) via eigenvalue decomposition

Definition at line 189 of file density_matrix.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ get_data()

QGD_Complex16 * matrix_base< QGD_Complex16 >::get_data ( ) const

inlineinherited

Call to get the pointer to the stored data.

Definition at line 285 of file matrix_base.hpp.

◆ get_dim()

int squander::density::DensityMatrix::get_dim ( ) const

inline

Get matrix dimension (2^qbit_num)

Returns: Matrix dimension

Definition at line 143 of file density_matrix.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ get_qbit_num()

int squander::density::DensityMatrix::get_qbit_num ( ) const

inline

Get number of qubits.

Returns: Number of qubits n (matrix dimension is 2^n)

Definition at line 137 of file density_matrix.h.

Here is the caller graph for this function:

◆ is_conjugated()

bool matrix_base< QGD_Complex16 >::is_conjugated ( ) const

inlineinherited

Call to get whether the matrix should be conjugated in CBLAS functions or not.

Returns: Returns with true if the matrix should be conjugated in CBLAS functions or false otherwise.

Definition at line 245 of file matrix_base.hpp.

◆ is_hermitian()

bool squander::density::DensityMatrix::is_hermitian ( double tol ) const

private

Definition at line 225 of file density_matrix.cpp.

Here is the caller graph for this function:

◆ is_transposed()

bool matrix_base< QGD_Complex16 >::is_transposed ( ) const

inlineinherited

Call to get whether the matrix should be conjugated in CBLAS functions or not.

Returns: Returns with true if the matrix should be conjugated in CBLAS functions or false otherwise.

Definition at line 263 of file matrix_base.hpp.

◆ is_valid()

bool squander::density::DensityMatrix::is_valid ( double tol = 1e-10 ) const

Check if valid density matrix.

Parameters

tol	Numerical tolerance (default: 1e-10)

Returns: true if: Ï=Ïâ , Tr(Ï)=1, Ïâ¥0

Performs three checks:

Hermitian: Ï(i,j) = conj(Ï(j,i))
Normalized: Tr(Ï) = 1
Positive semi-definite: all eigenvalues â¥ 0

Definition at line 202 of file density_matrix.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ maximally_mixed()

DensityMatrix squander::density::DensityMatrix::maximally_mixed ( int qbit_num )

static

Create maximally mixed state: Ï = I/2^n.

Parameters

qbit_num Number of qubits

Returns: Maximally mixed density matrix

Properties:

Purity: 1/2^n (minimal)
Entropy: n bits (maximal)
All eigenvalues equal: 1/2^n

Definition at line 752 of file density_matrix.cpp.

Here is the caller graph for this function:

◆ operator()() [1/2]

QGD_Complex16 & squander::density::DensityMatrix::operator()	(	int	i,
		int	j
	)

Element access: Ï(i,j)

Parameters

i	Row index (0 to dim-1)
j	Column index (0 to dim-1)

Returns: Reference to matrix element

Exceptions

std::out_of_range if indices invalid

Definition at line 141 of file density_matrix.cpp.

◆ operator()() [2/2]

const QGD_Complex16 & squander::density::DensityMatrix::operator()	(	int	i,
		int	j
	)		const

Definition at line 148 of file density_matrix.cpp.

◆ operator<()

bool matrix_base< QGD_Complex16 >::operator< ( const matrix_base< QGD_Complex16 > & other ) const

inlineinherited

Definition at line 394 of file matrix_base.hpp.

◆ operator=() [1/2]

DensityMatrix & squander::density::DensityMatrix::operator= ( const DensityMatrix & other )

Definition at line 124 of file density_matrix.cpp.

Here is the call graph for this function:

◆ operator=() [2/2]

DensityMatrix & squander::density::DensityMatrix::operator= ( DensityMatrix && other )

noexcept

Definition at line 132 of file density_matrix.cpp.

Here is the call graph for this function:

◆ operator[]()

QGD_Complex16 & matrix_base< QGD_Complex16 >::operator[] ( int idx ) const

inlineinherited

Operator [] to access elements in array style (does not check the boundaries of the stored array)

Parameters

idx	the index of the element

Returns: Returns with a reference to the idx-th element.

Definition at line 382 of file matrix_base.hpp.

◆ partial_trace()

DensityMatrix squander::density::DensityMatrix::partial_trace ( const std::vector< int > & trace_out ) const

Compute partial trace over specified qubits.

Parameters

trace_out List of qubit indices to trace out

Returns: Reduced density matrix

Example: For 3 qubits, trace_out={2} gives 2-qubit reduced density matrix. Ï_A = Tr_B(Ï_AB) where B are the traced-out qubits.

Computational complexity: O(2^(2n))

Definition at line 651 of file density_matrix.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ print()

void squander::density::DensityMatrix::print ( ) const

Print matrix with properties.

Displays:

Number of qubits
Matrix dimension
Trace
Purity
Validity
Matrix elements

Definition at line 772 of file density_matrix.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ print_matrix()

void matrix_base< QGD_Complex16 >::print_matrix ( ) const

inlineinherited

Call to prints the stored matrix on the standard output.

Definition at line 471 of file matrix_base.hpp.

◆ purity()

double squander::density::DensityMatrix::purity ( ) const

Calculate purity: Tr(ÏÂ²)

Returns

Real number in [1/2^n, 1]

1 = pure state
1/2^n = maximally mixed state

Computational complexity: O(2^(3n)) via matrix multiplication

Definition at line 173 of file density_matrix.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ release_data()

void matrix_base< QGD_Complex16 >::release_data ( )

inlineinherited

Call to release the data stored by the matrix.

(If the class instance was not the owner of the data, then the data pointer is simply set to NULL pointer.)

Definition at line 311 of file matrix_base.hpp.

◆ replace_data()

void matrix_base< QGD_Complex16 >::replace_data	(	QGD_Complex16 *	data_in,
		bool	owner_in
	)

inlineinherited

Call to replace the stored data by an another data array.

If the class was the owner of the original data array, then it is released.

Parameters

data_in	The data array to be set as a new storage.
owner_in	Set true to set the current class instance to be the owner of the data array, or false otherwise.

Definition at line 297 of file matrix_base.hpp.

◆ set_owner()

void matrix_base< QGD_Complex16 >::set_owner ( bool owner_in )

inlineinherited

Call to set the current class instance to be (or not to be) the owner of the stored data array.

Parameters

owner_in Set true to set the current class instance to be the owner of the data array, or false otherwise.

Definition at line 337 of file matrix_base.hpp.

◆ size()

int matrix_base< QGD_Complex16 >::size ( ) const

inlineinherited

Call to get the number of the allocated elements.

Returns: Returns with the number of the allocated elements (rows*cols)

Definition at line 461 of file matrix_base.hpp.

◆ trace()

QGD_Complex16 squander::density::DensityMatrix::trace ( ) const

Calculate trace: Tr(Ï)

Returns: Complex number (should be 1+0i for valid density matrix)

For valid density matrix: Tr(Ï) = 1 Computational complexity: O(2^n)

Definition at line 159 of file density_matrix.cpp.

Here is the caller graph for this function:

◆ transpose()

void matrix_base< QGD_Complex16 >::transpose ( )

inlineinherited

Call to transpose (or un-transpose) the matrix for CBLAS functions.

Definition at line 273 of file matrix_base.hpp.

◆ validate_dimensions()

void squander::density::DensityMatrix::validate_dimensions ( ) const

private

Definition at line 804 of file density_matrix.cpp.

Member Data Documentation

◆ cols

int matrix_base< QGD_Complex16 >::cols

inherited

The number of columns.

Definition at line 44 of file matrix_base.hpp.

◆ conjugated

bool matrix_base< QGD_Complex16 >::conjugated

protectedinherited

logical variable indicating whether the matrix needs to be conjugated in CBLAS operations

Definition at line 53 of file matrix_base.hpp.

◆ data

QGD_Complex16 * matrix_base< QGD_Complex16 >::data

inherited

pointer to the stored data

Definition at line 48 of file matrix_base.hpp.

◆ owner

bool matrix_base< QGD_Complex16 >::owner

protectedinherited

logical value indicating whether the class instance is the owner of the stored data or not. (If true, the data array is released in the destructor)

Definition at line 57 of file matrix_base.hpp.

◆ qbit_num_

int squander::density::DensityMatrix::qbit_num_

private

Number of qubits.

Definition at line 313 of file density_matrix.h.

◆ references

std::atomic<int64_t>* matrix_base< QGD_Complex16 >::references

protectedinherited

the number of the current references of the present object

Definition at line 59 of file matrix_base.hpp.

◆ rows

int matrix_base< QGD_Complex16 >::rows

inherited

The number of rows.

Definition at line 42 of file matrix_base.hpp.

◆ stride

int matrix_base< QGD_Complex16 >::stride

inherited

The column stride of the array. (The array elements in one row are a_0, a_1, ... a_{cols-1}, 0, 0, 0, 0. The number of zeros is stride-cols)

Definition at line 46 of file matrix_base.hpp.

◆ transposed

bool matrix_base< QGD_Complex16 >::transposed

protectedinherited

logical variable indicating whether the matrix needs to be transposed in CBLAS operations

Definition at line 55 of file matrix_base.hpp.

The documentation for this class was generated from the following files:

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Attributes

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ DensityMatrix() [1/5]

◆ DensityMatrix() [2/5]

◆ DensityMatrix() [3/5]

◆ DensityMatrix() [4/5]

◆ DensityMatrix() [5/5]

◆ ~DensityMatrix()

Member Function Documentation

◆ apply_local_unitary()

◆ apply_single_qubit_unitary()

◆ apply_two_qubit_unitary()

◆ apply_unitary()

◆ clone()

◆ conjugate()

◆ copy()

◆ copy_to()

◆ eigenvalues()

◆ ensure_aligned()

◆ entropy()

◆ get_data()

◆ get_dim()

◆ get_qbit_num()

◆ is_conjugated()

◆ is_hermitian()

◆ is_transposed()

◆ is_valid()

◆ maximally_mixed()

◆ operator()() [1/2]

◆ operator()() [2/2]

◆ operator<()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ operator[]()

◆ partial_trace()

◆ print()

◆ print_matrix()

◆ purity()

◆ release_data()

◆ replace_data()

◆ set_owner()

◆ size()

◆ trace()

◆ transpose()

◆ validate_dimensions()

Member Data Documentation

◆ cols

◆ conjugated

◆ data

◆ owner

◆ qbit_num_

◆ references

◆ rows

◆ stride

◆ transposed