Struct DensityMatrixN 

pub struct DensityMatrixN {
    pub dim: usize,
    pub entries: Vec<Complex>,
    /* private fields */
}

Arbitrary-dimension density matrix (NxN, row-major). Pre-allocated scratch buffers for zero-allocation hot-path operations.

Fields

dim: usize

entries: Vec<Complex>

Implementations

impl DensityMatrixN

pub fn maximally_mixed(dim: usize) -> Self

Create the maximally mixed state I/N.

pub fn pure_state(k: usize, dim: usize) -> Self

Create a pure state |k⟩⟨k|.

pub fn equal_superposition(dim: usize) -> Self

Create an equal superposition: |ψ⟩ = (1/√N) Σ|k⟩ → ρ = |ψ⟩⟨ψ|.

pub fn populations(&self) -> Vec<f32>

Diagonal populations (probabilities).

pub fn coherence_magnitude(&self) -> f32

Sum of off-diagonal magnitudes (coherence).

pub fn purity(&self) -> f32

Tr(ρ²) — purity. 1.0 = pure, 1/N = maximally mixed.

pub fn von_neumann_entropy(&self) -> f32

Von Neumann entropy via eigenvalue decomposition. S = -Σ λ_i ln(λ_i) where λ_i are eigenvalues of ρ. Uses Jacobi rotation solver from dreamwell-math.

pub fn free_energy(&self, energies: &[f32]) -> f32

Helmholtz free energy: F = ⟨H⟩ - T·S. H is given as diagonal energies. Temperature T = 1/(1 + φ·coherence_magnitude) — φ-scaled thermal partition. Higher coherence → lower temperature → free energy dominated by energy (ordered). Lower coherence → higher temperature → free energy dominated by entropy (disordered).

pub fn dephase(&mut self, epsilon: f32)

Apply partial dephasing: ρ → (1-ε)ρ + εΔ(ρ).

pub fn couple_dephase(&mut self, other: &DensityMatrixN, strength: f32)

Apply shared dephasing with another density matrix (Model 4 coupling).

pub fn evolve(&mut self, unitary: &[Complex])

Unitary evolution: ρ → UρU†. Adaptive dispatch (Clean Compute: explicit hardware separation): dim < 32: serial cgemm (L1 cache, compiler vectorizes) dim ≥ 32: CPU parallel rows via rayon (no contention, scales with cores)

GPU compute (BA-60) is available via GpuTrainingContext::batched_evolve() for bulk operations where all matrices can be dispatched in a single submission. Per-call GPU dispatch is slower than CPU parallel due to Mutex serialization and buffer mapping overhead (~5ms per round-trip vs ~0.3ms for CPU cgemm_par at dim=86).

pub fn hamiltonian_unitary(h: &[f32], dim: usize, dt: f32) -> Vec<Complex>

Build unitary U = exp(-iHdt) from a real symmetric Hamiltonian. Uses scaling-and-squaring with Padé approximant (numerically stable at any dim).

pub fn born_sample(&self, seed: u64) -> usize

Born rule measurement: sample a mode index from diagonal populations.

pub fn trace(&self) -> f32

Trace (should always be ~1.0 for valid density matrix).

Trait Implementations

impl Clone for DensityMatrixN

fn clone(&self) -> DensityMatrixN

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.