Crate dreamwell_quantum 

dreamwell-quantum — Quantum Simulation for Classical Hardware

Implements the formal quantum-simulation spec from QUANTUM.md:

• Density matrices (rho in C^{N x N}, Hermitian, trace-1, positive semidefinite)
• Hamiltonian evolution (U = exp(-iH dt/hbar), applied as rho -> U rho U_dag)
• CPTP quantum channels (dephasing, amplitude damping, depolarization)
• Born rule measurement (p_k = rho_kk, stochastic or deterministic)
• Interference kernels (kappa_{n,ij} in C^3, the decisive coherence test)
• Superposition state machine (Active/Decohering/Superposed/Dormant)
• Decoherence fields (Lindblad kernel exp(-Gamma t) with spatial falloff)

The Decisive Test (QUANTUM.md S7)

A system is a genuine quantum simulation (not just quantum-inspired) if: exists n: x_n(rho) != x_n(Delta(rho)) where Delta is the dephasing map that zeros off-diagonal entries. The ablation_test function verifies this.

Clean Compute Compliance

• Pre-allocated buffers reused every frame
• No heap allocation in tick/measure/evolve functions
• Deterministic from seed

Modules

qft

Quantum Field Theory Extensions

toy_models

Toy models for attention-as-locomotion-decode.

wave_animator

ProceduralWaveAnimator — wave-state morph controller.

wave_controller

WaveController — wave-based procedural input and locomotion runtime.

Structs

Complex

Complex number z = re + i·im.

DecoherenceField

A spatial decoherence field attached to a zone or POI. When the observer enters the field radius, the wave form begins collapsing into the target form at rate gamma.

DecoherenceState

Tracks the observer’s current decoherence state.

DensityMatrix5

5x5 density matrix for a Hilbert space H = C^5.

InterferenceKernels

Interference kernel kappa_{n,ij} in C^3 for particle n between modes i and j. Controls how off-diagonal coherence rho_{ij} affects particle geometry.

LocomotionHamiltonian

Locomotion Hamiltonian H_loc = H_bias + H_input + H_couple + H_phase. Generates the unitary U_tick = exp(-i H dt / hbar_eff) each frame.

LocomotionObservables

Named class of frame-collapsed decohering player locomotion observables. Each variant computes from the full density matrix. The GPU bridge evaluates the same observables from B(ρ_t). Bounded-error validation compares the two.

ObservableDecodeContract

Observable Decode Contract — formalizes GPU shaders as constrained decoders.

ObservableErrors

Per-observable error magnitudes from bounded-error validation.

ObservableSpec

A single named observable in the decode contract.

QuantumLocomotionState

Full quantum locomotion state — wraps density matrix, Hamiltonian, kernels. Satisfies the quantum-simulation spec (QUANTUM.md S11).

QuantumStateSnapshot

Serializable snapshot of a quantum locomotion state for BLAKE3 attestation. Contains the density matrix populations + coherence magnitude + measured mode.

SuperBody

SuperBody — the authoritative, collision-safe, deterministic gameplay body.

SuperpositionObserver

Observer that classifies nearby bodies into superposition states based on distance thresholds.

WaveBody

WaveBody — the expressive, procedural, observer-facing presentation body.

Enums

DecoherenceTagValue

Parsed result from a decoherence PropertyTag string.

SuperpositionState

Superposition state classification for observer-aware systems.

WaveForm

The observer’s physical representation form. Transitions between forms are governed by DecoherenceFields on zones.

Functions

ablation_test

Run the decisive ablation test: verify that for at least one particle, the quantum position differs from the dephased (classical) position. Returns the maximum squared displacement difference across all particles. Should be > 0 for a state with nonzero off-diagonal coherence.

amplitude_damp

Amplitude damping (T1 relaxation): drains excited states toward ground state |0>.

dephase

Partial dephasing: rho -> (1-epsilon) rho + epsilon Delta(rho). Equivalent to DensityMatrix5::apply_dephasing but as a free function.

depolarize

Depolarizing channel: rho -> (1-p) rho + p I/N. Drives the state toward the maximally mixed state I/5.

fidelity_approx

Quantum fidelity between two density matrices: F(rho, sigma). Approximated via population overlap: F ~ (sum_k sqrt(p_k * q_k))^2

fully_dephase

Full dephasing: rho -> Delta(rho). Zeros all off-diagonal elements.

parse_decoherence_tag

Parse a decoherence PropertyTag string. Format: “decohere:form[:clip]” or “gamma:rate”

quantum_mutual_information

Quantum mutual information: I(A:B) = S(A) + S(B) - S(AB). Measures total correlations (classical + quantum) between subsystems. Inputs are Von Neumann entropies of subsystem A, B, and joint AB.

thermal_relaxation

Thermal relaxation channel: combined T1 (energy) and T2 (dephasing) decay.