@spec basis_state(non_neg_integer(), pos_integer(), Nx.Type.t()) :: Nx.Tensor.t()

Creates a basis state |i⟩ in an n-dimensional Hilbert space.

The basis state has amplitude 1.0 at the specified index and 0.0 everywhere else.

Parameters

• index - The basis state index (0-based)
• dimension - The dimension of the Hilbert space (2^num_qubits)
• type - Tensor type (default: :c64)

Examples

# Create |0⟩ state
iex> state = Qx.StateInit.basis_state(0, 2)
iex> probs = Qx.Math.probabilities(state) |> Nx.to_flat_list()
iex> [Enum.at(probs, 0), Enum.at(probs, 1)]
[1.0, 0.0]

# Create |11⟩ for 2 qubits (dimension 4, index 3)
iex> state = Qx.StateInit.basis_state(3, 4)
iex> probs = Qx.Math.probabilities(state) |> Nx.to_flat_list()
iex> Enum.at(probs, 3)
1.0

# Create |101⟩ for 3 qubits (dimension 8, index 5)
iex> state = Qx.StateInit.basis_state(5, 8)
iex> probs = Qx.Math.probabilities(state) |> Nx.to_flat_list()
iex> Enum.at(probs, 5)
1.0

Raises

• Qx.BasisError - If dimension is not a positive integer, index is not an integer, index is negative, or index >= dimension

@spec bell_state_vector(bell_state_which(), Nx.Type.t()) :: Nx.Tensor.t()

Creates one of the four Bell states as a state vector.

Accepts an optional atom to select which Bell state to prepare, and an optional tensor type (:c64 or :c128):

Examples

iex> state = Qx.StateInit.bell_state_vector()
iex> probs = Qx.Math.probabilities(state) |> Nx.to_flat_list()
iex> abs(Enum.at(probs, 0) - 0.5) < 0.01 and abs(Enum.at(probs, 3) - 0.5) < 0.01
true

iex> state = Qx.StateInit.bell_state_vector(:phi_minus)
iex> probs = Qx.Math.probabilities(state) |> Nx.to_flat_list()
iex> abs(Enum.at(probs, 0) - 0.5) < 0.01 and abs(Enum.at(probs, 3) - 0.5) < 0.01
true

iex> state = Qx.StateInit.bell_state_vector(:psi_plus)
iex> probs = Qx.Math.probabilities(state) |> Nx.to_flat_list()
iex> abs(Enum.at(probs, 1) - 0.5) < 0.01 and abs(Enum.at(probs, 2) - 0.5) < 0.01
true

iex> state = Qx.StateInit.bell_state_vector(:psi_minus)
iex> probs = Qx.Math.probabilities(state) |> Nx.to_flat_list()
iex> abs(Enum.at(probs, 1) - 0.5) < 0.01 and abs(Enum.at(probs, 2) - 0.5) < 0.01
true

See Also

• Qx.bell_state/1 — returns a circuit recipe (%Qx.QuantumCircuit{}) that prepares the Bell state when run, rather than the state vector directly. Use that when you want a circuit to execute, this when you want the mathematical state.

@spec ghz_state_vector(pos_integer(), Nx.Type.t()) :: Nx.Tensor.t()

Creates a GHZ state for n qubits: (|00...0⟩ + |11...1⟩)/√2

The Greenberger-Horne-Zeilinger (GHZ) state is a maximally entangled state for multiple qubits.

Parameters

• num_qubits - Number of qubits; must be >= 2 (a single-qubit GHZ state is undefined). Smaller values raise FunctionClauseError.
• type - Tensor type (default: :c64)

Examples

# GHZ state for 2 qubits (same as Bell state)
iex> state = Qx.StateInit.ghz_state_vector(2)
iex> probs = Qx.Math.probabilities(state) |> Nx.to_flat_list()
iex> abs(Enum.at(probs, 0) - 0.5) < 0.01 and abs(Enum.at(probs, 3) - 0.5) < 0.01
true

# GHZ state for 3 qubits: (|000⟩ + |111⟩)/√2
iex> state = Qx.StateInit.ghz_state_vector(3)
iex> probs = Qx.Math.probabilities(state) |> Nx.to_flat_list()
iex> abs(Enum.at(probs, 0) - 0.5) < 0.01 and abs(Enum.at(probs, 7) - 0.5) < 0.01
true

# All other states have zero probability
iex> state = Qx.StateInit.ghz_state_vector(3)
iex> probs = Qx.Math.probabilities(state) |> Nx.to_flat_list()
iex> Enum.sum(Enum.slice(probs, 1..6))
0.0

See Also

• Qx.ghz_state/0 — returns a circuit recipe (hardcoded 3-qubit) rather than the state vector. Use that for a runnable circuit; this for the mathematical state at any qubit count.

Creates the |-⟩ state: (|0⟩ - |1⟩)/√2

Examples

iex> state = Qx.StateInit.minus_state()
iex> probs = Qx.Math.probabilities(state) |> Nx.to_flat_list()
iex> [p0, p1] = probs
iex> abs(p0 - 0.5) < 0.01 and abs(p1 - 0.5) < 0.01
true

Creates the |1⟩ state for a single qubit.

Examples

iex> state = Qx.StateInit.one_state()
iex> probs = Qx.Math.probabilities(state) |> Nx.to_flat_list()
iex> Enum.at(probs, 1)
1.0

Creates the |+⟩ state: (|0⟩ + |1⟩)/√2

Examples

iex> state = Qx.StateInit.plus_state()
iex> probs = Qx.Math.probabilities(state) |> Nx.to_flat_list()
iex> [p0, p1] = probs
iex> abs(p0 - 0.5) < 0.01 and abs(p1 - 0.5) < 0.01
true

Creates a random normalized quantum state.

Generates random complex amplitudes and normalizes them to ensure the state is valid (|ψ|² = 1).

Parameters

• num_qubits - Number of qubits
• type - Tensor type (default: :c64)

Examples

# Create random single qubit state
iex> state = Qx.StateInit.random_state(1)
iex> Qx.Validation.valid_qubit?(state)
true

# Create random 3-qubit state
iex> state = Qx.StateInit.random_state(3)
iex> probs = Qx.Math.probabilities(state)
iex> total = Nx.sum(probs) |> Nx.to_number()
iex> abs(total - 1.0) < 1.0e-6
true

Creates an equal superposition state for n qubits.

The state is (1/√(2^n)) Σ|i⟩ where i ranges over all basis states. Each basis state has equal probability 1/(2^n).

Parameters

• num_qubits - Number of qubits
• type - Tensor type (default: :c64)

Examples

# Single qubit: (|0⟩ + |1⟩)/√2
iex> state = Qx.StateInit.superposition_state(1)
iex> probs = Qx.Math.probabilities(state) |> Nx.to_flat_list()
iex> Enum.all?(probs, &(abs(&1 - 0.5) < 0.01))
true

# Two qubits: (|00⟩ + |01⟩ + |10⟩ + |11⟩)/2
iex> state = Qx.StateInit.superposition_state(2)
iex> probs = Qx.Math.probabilities(state) |> Nx.to_flat_list()
iex> Enum.all?(probs, &(abs(&1 - 0.25) < 0.01))
true

# Three qubits: each state has probability 1/8
iex> state = Qx.StateInit.superposition_state(3)
iex> probs = Qx.Math.probabilities(state) |> Nx.to_flat_list()
iex> Enum.all?(probs, &(abs(&1 - 0.125) < 0.01))
true

Creates a W state for n qubits.

The W state is another type of entangled state where exactly one qubit is |1⟩ and the rest are |0⟩, in superposition.

For 3 qubits: (|001⟩ + |010⟩ + |100⟩)/√3

Examples

# W state for 3 qubits
iex> state = Qx.StateInit.w_state(3)
iex> probs = Qx.Math.probabilities(state) |> Nx.to_flat_list()
iex> expected_prob = 1.0 / 3.0
iex> abs(Enum.at(probs, 1) - expected_prob) < 0.01 and
...> abs(Enum.at(probs, 2) - expected_prob) < 0.01 and
...> abs(Enum.at(probs, 4) - expected_prob) < 0.01
true

Creates the zero state |00...0⟩ for n qubits.

This is equivalent to basis_state(0, 2^num_qubits).

Parameters

• num_qubits - Number of qubits
• type - Tensor type (default: :c64)

Examples

# Create |0⟩ for single qubit
iex> state = Qx.StateInit.zero_state(1)
iex> Nx.shape(state)
{2}

# Create |00⟩ for 2 qubits
iex> state = Qx.StateInit.zero_state(2)
iex> probs = Qx.Math.probabilities(state) |> Nx.to_flat_list()
iex> Enum.at(probs, 0)
1.0

# Verify all other amplitudes are zero
iex> state = Qx.StateInit.zero_state(3)
iex> probs = Qx.Math.probabilities(state) |> Nx.to_flat_list()
iex> Enum.sum(Enum.drop(probs, 1))
0.0