org.soulspace.qclojure.domain.state — org.soulspace/qclojure 0.1.0-SNAPSHOT

Core quantum state representation and operations

bits-to-index clj

(bits-to-index bits)

Convert a vector of bits to the corresponding state vector index.

For n qubits with bits [b0, b1, ..., b(n-1)], the index is: index = b02^(n-1) + b12^(n-2) + ... + b(n-1)*2^0

This maps computational basis states to their positions in the state vector.

Parameters:

• bits: Vector of 0s and 1s representing the computational basis state

Returns: Integer index into the state vector (0 to 2^n - 1)

Examples: (bits-to-index [0 0 0]) ;=> 0 ; |000⟩ corresponds to index 0 (bits-to-index [0 0 1]) ;=> 1 ; |001⟩ corresponds to index 1
(bits-to-index [1 0 1]) ;=> 5 ; |101⟩ corresponds to index 5

complex? clj

(complex? z)

Check if value is a fastmath complex number (Vec2).

FastMath represents complex numbers as 2D vectors where the x component is the real part and the y component is the imaginary part.

Parameters:

• z: Value to test for complex number type

Returns: Boolean true if z is a fastmath Vec2 complex number, false otherwise

Example: (complex? (fc/complex 1 2)) ;=> true

(complex? 42) ;=> false

computational-basis-state clj

(computational-basis-state n bits)

Create a computational basis state |b₀b₁...bₙ₋₁⟩ from a vector of bits.

Creates a pure quantum state where one specific computational basis state has amplitude 1 and all others have amplitude 0. This represents a classical bit string in quantum form.

The bits are ordered from most significant to least significant (left to right), so [1,0,1] represents the state |101⟩. This is consistent with standard quantum computing notation.

Parameters:

• n: Number of qubits (must match length of bits vector)
• bits: Vector of 0s and 1s representing the desired basis state

Returns: Quantum state map representing the computational basis state

Throws: AssertionError if n doesn't match bits length or bits contains invalid values

Examples: (computational-basis-state 3 [0 0 0]) ;=> |000⟩ state (same as zero-state) (computational-basis-state 3 [1 0 1]) ;=> |101⟩ state
(computational-basis-state 2 [1 1]) ;=> |11⟩ state

measure-specific-qubits clj

(measure-specific-qubits state measurement-qubits)

Perform quantum measurement on specific qubits with proper partial measurement.

This implements proper partial measurement by:

1. Computing probabilities for all possible outcomes of the measured qubits
2. Selecting an outcome probabilistically according to Born rule
3. Collapsing the measured qubits while preserving quantum coherence in unmeasured qubits
4. Properly renormalizing the remaining state

For a full quantum simulator, this correctly handles:

• Entangled states where measurement affects the entire system
• Proper probability calculations for partial measurements
• Correct post-measurement state normalization
• Preservation of quantum correlations in unmeasured subsystems

Parameters:

• state: Quantum state to measure
• measurement-qubits: Vector of qubit indices to measure (0-indexed)

Returns: Map containing:

• :outcomes - Vector of measurement outcomes (0 or 1) for each measured qubit
• :collapsed-state - Properly normalized quantum state after partial measurement
• :probabilities - Map of outcome -> probability for each possible measurement result

Example: For a Bell state measuring qubit 0: (measure-specific-qubits bell-state [0]) ;=> {:outcomes [0], :collapsed-state normalized-state, :probabilities {...}}

Note: This correctly implements quantum measurement theory

measure-state clj

(measure-state state)

Perform a complete quantum measurement in the computational basis.

Simulates a quantum measurement by:

1. Computing measurement probabilities for each basis state according to Born rule
2. Randomly selecting an outcome based on these probabilities
3. Collapsing the state to the measured basis state

This implements the fundamental quantum measurement postulate where the system collapses from superposition to a definite classical state.

Parameters:

• state: Quantum state to measure

Returns: Map containing:

• :outcome - Integer index of the measured basis state (0 to 2^n-1)
• :collapsed-state - New quantum state after measurement collapse
• :probability - Probability of the measured outcome

Example: (measure-state |+⟩) ;=> {:outcome 0, :collapsed-state |0⟩, :probability 0.5}

Note: This is probabilistic - repeated calls may yield different results

measure-state-statistics clj

(measure-state-statistics state num-measurements)

Perform multiple measurements and collect statistical data.

Simulates running the same quantum measurement many times to gather statistical information about measurement outcomes, frequencies, and empirical probabilities.

Parameters:

• state: Quantum state to measure repeatedly
• num-measurements: Number of measurements to perform

Returns: Map containing:

• :total-measurements - Total number of measurements performed
• :outcomes - Vector of all measurement outcomes
• :frequencies - Map of outcome -> count
• :probabilities - Map of outcome -> empirical probability
• :expected-probabilities - Map of outcome -> theoretical probability

Example: (measure-state-statistics |+⟩ 1000) ;=> {:total-measurements 1000, :outcomes [...], :frequencies {0 501, 1 499}, ...}

measurement-outcomes-to-bits clj

(measurement-outcomes-to-bits outcome n-qubits)

Convert a measurement outcome integer to its binary bit representation.

This is the inverse of bits-to-index. Converts an integer measurement outcome back to the corresponding bit vector representation.

Parameters:

• outcome: Integer measurement outcome (0 to 2^n-1)
• n-qubits: Number of qubits (determines bit vector length)

Returns: Vector of bits [b₀ b₁ ... bₙ₋₁] representing the measurement outcome

Examples: (measurement-outcomes-to-bits 0 1) ;=> [0] (measurement-outcomes-to-bits 1 1) ;=> [1]
(measurement-outcomes-to-bits 5 3) ;=> [1 0 1] ; 5 = 4+1 = 101₂

measurement-probabilities clj

(measurement-probabilities state)

Calculate measurement probabilities for all computational basis states.

Returns a vector of probabilities for measuring each computational basis state, computed using the Born rule: P(|i⟩) = |αᵢ|² where αᵢ is the amplitude for basis state |i⟩.

Parameters:

• state: Quantum state to analyze

Returns: Vector of probabilities, one for each computational basis state

Example: (measurement-probabilities |+⟩) ;=> [0.5 0.5] ; Equal probability for |0⟩ and |1⟩

minus-state clj

(minus-state)

Create the |-⟩ superposition state.

Creates the |-⟩ = (|0⟩ - |1⟩)/√2 state, which is an equal superposition of the computational basis states with a relative phase of π between them. This state also has 50% probability of measuring either 0 or 1, but the negative amplitude creates different interference patterns.

The |-⟩ state is an eigenstate of the Pauli-X operator (with eigenvalue -1) and demonstrates quantum phase relationships.

Parameters: None

Returns: Single-qubit quantum state map representing |-⟩

Example: (minus-state) ;=> {:state-vector [0.707+0i, -0.707+0i], :num-qubits 1}

multi-qubit-state clj

(multi-qubit-state amplitudes)

Create a multi-qubit quantum state from a vector of complex amplitudes.

Constructs a quantum state for n qubits where n is determined by the logarithm base 2 of the amplitude vector length. The amplitudes represent the probability amplitudes for each computational basis state.

For n qubits, the basis states are ordered as: |00...0⟩, |00...1⟩, |00...10⟩, ..., |11...1⟩

Parameters:

• amplitudes: Vector of complex amplitudes (each a fastmath Vec2) Length must be a power of 2 (2^n for n qubits)

Returns: Quantum state map with :state-vector and :num-qubits keys

Example: (multi-qubit-state [(fc/complex 0.707 0) (fc/complex 0 0) (fc/complex 0 0) (fc/complex 0.707 0)]) ;=> 2-qubit Bell state (|00⟩ + |11⟩)/√2

normalize-state clj

(normalize-state state)

Normalize a quantum state vector to unit length.

Quantum states must be normalized such that the sum of squared magnitudes of all amplitudes equals 1. This ensures that the total probability of all measurement outcomes is 100%.

The normalization process:

1. Calculate the norm: √(Σ|αᵢ|²) where αᵢ are the amplitudes
2. Divide each amplitude by the norm: αᵢ' = αᵢ/norm

Parameters:

• state: Quantum state map to normalize

Returns: Normalized quantum state with the same relative amplitudes but unit norm

Example: (normalize-state (multi-qubit-state [(fc/complex 3 0) (fc/complex 4 0)])) ;=> Normalized state with amplitudes [0.6, 0.8] since 3²+4²=25, norm=5

one-state clj

(one-state)

Create the |1⟩ computational basis state.

Creates a single-qubit quantum state |1⟩ = [0, 1] where there is 100% probability of measuring the qubit in the excited state.

Parameters: None

Returns: Single-qubit quantum state map representing |1⟩

Example: (one-state) ;=> {:state-vector [0+0i, 1+0i], :num-qubits 1}

partial-trace clj

(partial-trace state trace-qubit)

Compute the partial trace of a quantum state over specified qubits.

The partial trace operation reduces a multi-qubit quantum state to a subsystem by 'tracing out' or summing over the unwanted qubits. This is essential for analyzing subsystems of entangled quantum states.

For a 2-qubit state |ψ⟩ = Σ αᵢⱼ|ij⟩, tracing out qubit j gives: ρᵢ = Σⱼ |αᵢⱼ|² for the reduced single-qubit state

This implementation supports tracing out a single qubit from a multi-qubit system.

Parameters:

• state: Multi-qubit quantum state to trace
• trace-qubit: Index of the qubit to trace out (0-indexed)

Returns: Reduced quantum state with one fewer qubit

Example: (partial-trace bell-state 1) ; Trace out second qubit of Bell state ;=> Mixed state of first qubit

plus-state clj

(plus-state)

Create the |+⟩ superposition state.

Creates the |+⟩ = (|0⟩ + |1⟩)/√2 state, which is an equal superposition of the computational basis states. This state has 50% probability of measuring either 0 or 1, representing true quantum superposition.

The |+⟩ state is an eigenstate of the Pauli-X operator and is commonly used in quantum algorithms and quantum information protocols.

Parameters: None

Returns: Single-qubit quantum state map representing |+⟩

Example: (plus-state) ;=> {:state-vector [0.707+0i, 0.707+0i], :num-qubits 1}

probability clj

(probability state basis-index)

Calculate the probability of measuring a quantum state in a specific basis state.

According to the Born rule, the probability of measuring a quantum state in a particular computational basis state is the squared magnitude of the corresponding amplitude: P(|i⟩) = |αᵢ|²

Parameters:

• state: Quantum state to analyze
• basis-index: Integer index of the computational basis state (0-indexed) For n qubits: 0 represents |00...0⟩, 2ⁿ-1 represents |11...1⟩

Returns: Real number between 0 and 1 representing the measurement probability

Examples: (probability |+⟩ 0) ;=> 0.5 ; 50% chance of measuring |0⟩

(probability |+⟩ 1)
;=> 0.5 ; 50% chance of measuring |1⟩

(probability |0⟩ 0) ;=> 1.0 ; 100% chance of measuring |0⟩

single-qubit-state clj

(single-qubit-state amplitude)

Create a single qubit state with given amplitude for |1⟩ component.

Creates a normalized single-qubit quantum state where the amplitude parameter determines the probability amplitude for the |1⟩ basis state. The |0⟩ amplitude is computed to ensure normalization.

Parameters:

• amplitude: Complex amplitude for the |1⟩ component (fastmath Vec2)

Returns: Quantum state map with :state-vector and :num-qubits keys

Example: (single-qubit-state (fc/complex 0.707 0)) ;=> State approximately equal to |+⟩ = (|0⟩ + |1⟩)/√2

tensor-product clj

(tensor-product state1 state2)

Compute the tensor product of two quantum states.

The tensor product (⊗) combines two quantum systems into a single composite system. For states |ψ⟩ ⊗ |φ⟩, the resulting state has dimensionality equal to the product of the individual state dimensions.

The tensor product is fundamental for:

• Creating multi-qubit states from single-qubit states
• Building composite quantum systems
• Representing non-entangled product states

Mathematical operation: If |ψ⟩ = α|0⟩ + β|1⟩ and |φ⟩ = γ|0⟩ + δ|1⟩, then |ψ⟩ ⊗ |φ⟩ = αγ|00⟩ + αδ|01⟩ + βγ|10⟩ + βδ|11⟩

Parameters:

• state1: First quantum state
• state2: Second quantum state

Returns: Composite quantum state representing state1 ⊗ state2

Example: (tensor-product |0⟩ |1⟩) ;=> 2-qubit state |01⟩ = [0, 1, 0, 0]

zero-state clj

(zero-state)

(zero-state n)

Create the |0⟩ computational basis state.

For single qubit: Creates |0⟩ = [1, 0] state For n qubits: Creates |00...0⟩ state with all qubits in |0⟩

The |0⟩ state is a fundamental computational basis state where:

• Single qubit: 100% probability of measuring 0
• Multi-qubit: 100% probability of measuring all 0s

Parameters:

• (no args): Creates single-qubit |0⟩ state
• n: (optional) Number of qubits for multi-qubit |00...0⟩ state

Returns: Quantum state map representing the |0⟩^⊗n state

Examples: (zero-state) ;=> {:state-vector [1+0i, 0+0i], :num-qubits 1} ; |0⟩

(zero-state 3) ;=> 3-qubit state |000⟩

|+⟩ clj

Single-qubit |+⟩ = (|0⟩ + |1⟩)/√2 superposition state.

|-⟩ clj

Single-qubit |-⟩ = (|0⟩ - |1⟩)/√2 superposition state.

|00⟩ clj

Two-qubit |00⟩ computational basis state.

|01⟩ clj

Two-qubit |01⟩ computational basis state.

|0⟩ clj

Single-qubit |0⟩ computational basis state.

|10⟩ clj

Two-qubit |10⟩ computational basis state.

|11⟩ clj

Two-qubit |11⟩ computational basis state.

|1⟩ clj

Single-qubit |1⟩ computational basis state.