harmoniq

What Is This

Harmoniq sonifies a quantum state. You build a quantum circuit in the editor, and a playhead scrubs through it step by step. At each step the full quantum state is reconstructed, and its probability distribution is turned into sound. You hear the quantum state evolve in real time.

The Quantum State

The system starts with all qubits in |0⟩ (default 3 qubits, adjustable from 1 to 8). With n qubits there are 2ⁿ basis states. Each step applies gates that transform the state into a superposition of all basis states, each with a complex probability amplitude. The probabilities always sum to 1. The state vector display shows the full amplitudes — magnitudes and phases — so you can see exactly what the simulator is doing.

Two Measurement Bases

A quantum state looks different depending on how you measure it. Harmoniq reads the state in two complementary bases simultaneously:

• Z-basis (computational basis) — the "natural" measurement. A Hadamard on one qubit gives a 50/50 split between |0⟩ and |1⟩.
• X-basis — the "rotated" measurement. The same state that looks uncertain in Z-basis looks completely definite in X-basis, and vice versa. This is the uncertainty principle made audible.

To read X-basis probabilities without collapsing the state, the simulator applies a Hadamard to each qubit, reads probabilities, then reverses with inverse Hadamard.

How Probability Maps to Sound

Each basis state (2ⁿ for n qubits) is assigned a note from the selected scale, extending into higher octaves as needed. The mapping adapts when you change the scale, root octave, qubit count, or X-basis octave offset in the sound controls.

All oscillators run continuously. The probability of each basis state controls its oscillator's volume: gain = √probability × scale. The square root gives a perceptually linear loudness curve. Zero probability means silence; equal superposition plays all notes as a chord.

Sound Controls

• Z wave / X wave — waveform for each basis layer: sine (pure), triangle (warm overtones), square (hollow, buzzy), or sawtooth (bright, harsh).
• Scale — which musical scale the basis states map onto. Eight options from C major to phrygian.
• Octave — root octave (2–6). Lower octaves produce deep drones; higher octaves are bell-like.
• X octave — pitch offset for the X-basis layer relative to the root. Default +1 separates the two layers.
• Decay — note attenuation. At 0, notes sustain as a drone. Higher values give pad-like tails or short plucks.
• Reverb — delay-feedback reverb with a lowpass filter on the tail.
• Z / X / master volume — independent volume for each basis bus and the master output.

Transport

• Play / Stop — starts the playhead from step 0. Loops continuously.
• Speed — steps per second (0.5–8).
• ± Step — add or remove time steps.
• ± Qubit — add or remove qubit wires (1–8). Doubles or halves the basis states.
• Clear — removes all gates without changing the number of steps.

Presets

• Scale — walks through all basis states sequentially using X gates. Try this with decay turned up for an arpeggio.
• Full Superposition — H on all qubits. Equal probability across all states in Z-basis; single note in X-basis.
• GHZ Entangled — H then two CNOTs, creating (|000⟩ + |111⟩)/√2. Maximally entangled: two notes in Z-basis, complex spread in X-basis.
• Product State — each qubit prepared independently. The non-entangled baseline.
• Classical Corr. — H + CNOT + measurement. Creates a mixed state with classical correlation but no entanglement.

What to Listen For

• Single note → chord: Place H on one qubit. Z-basis splits from one note into two; X-basis collapses from spread to focused. Complementarity in action.
• Entanglement: H then CNOT. Z-basis plays two notes (Bell state), X-basis spreads wider.
• Phase gates (Z, T): These change phase without affecting Z-basis probabilities. But X-basis hears the difference immediately. Something invisible in one basis is loud in the other.
• Scale + decay: Try blues with moderate decay for a jazzy plucked feel. Whole tone with no decay for an eerie drone. Pentatonic always sounds consonant.
• Toffoli: Two controls plus an X (● + ● + X) flips the target only when both controls are |1⟩. A 3-input AND.

The Gates

Controlled Gates

Instead of dedicated CNOT/CZ gates, harmoniq uses a generic control marker (●). Drop a control on one wire and any other gate on another wire at the same step, and the control becomes a predicate for that gate. The control wire and target gate are automatically connected with a vertical line.

This gives you any controlled gate without needing a separate type:

• ● + X = CNOT (controlled-X, the standard entangler)
• ● + Z = CZ (controlled phase flip)
• ● + H = controlled Hadamard
• ● + T = controlled π/8 phase
• ● + ● + X = Toffoli (CCNOT, a universal classical gate)
• ● + ● + ● + X = CCCNOT, and so on

Quantum Forge

All quantum simulation runs through Quantum Forge via the public quantum-forge npm package. Gate operations, probability queries, and density matrix reads are delegated to the WASM backend — there is no custom quantum math in this project.