@spec bell_state(bell_state_type()) :: circuit()

Creates one of the four Bell state circuits (maximally entangled two-qubit states).

Accepts an optional atom to select which Bell state to prepare:

Examples

iex> bell_circuit = Qx.bell_state()
iex> bell_circuit.num_qubits
2

iex> bell_circuit = Qx.bell_state(:phi_minus)
iex> bell_circuit.num_qubits
2

iex> bell_circuit = Qx.bell_state(:psi_plus)
iex> bell_circuit.num_qubits
2

iex> bell_circuit = Qx.bell_state(:psi_minus)
iex> bell_circuit.num_qubits
2

@spec c_if(circuit(), non_neg_integer(), 0 | 1, (circuit() -> circuit())) :: circuit()

Applies gates conditionally based on a classical bit value.

Enables mid-circuit measurement with classical feedback - a key capability for quantum error correction, quantum teleportation, and adaptive algorithms.

Parameters

• circuit - Quantum circuit
• classical_bit - Classical bit index to check (must have been measured)
• value - Value to compare (0 or 1)
• gate_fn - Function that applies gates when condition is true

Examples

# Apply X gate to qubit 1 if classical bit 0 equals 1
iex> qc = Qx.create_circuit(2, 2)
...> |> Qx.h(0)
...> |> Qx.measure(0, 0)
...> |> Qx.c_if(0, 1, fn c -> Qx.x(c, 1) end)
iex> length(Qx.QuantumCircuit.get_instructions(qc))
3

# Multiple gates in conditional block
iex> qc = Qx.create_circuit(3, 2)
...> |> Qx.measure(0, 0)
...> |> Qx.c_if(0, 1, fn c ->
...>      c |> Qx.x(1) |> Qx.h(2)
...>    end)
iex> length(Qx.QuantumCircuit.get_instructions(qc))
2

See Also

• OpenQASM 3.0 if-statements for hardware compatibility
• Quantum teleportation example in documentation

@spec ccx(circuit(), non_neg_integer(), non_neg_integer(), non_neg_integer()) ::
  circuit()

Applies a controlled-controlled-X (CCNOT/Toffoli) gate.

Flips target qubit if and only if both control qubits are |1⟩

Parameters

• circuit - Quantum circuit
• control1 - First control qubit index
• control2 - Second control qubit index
• target - Target qubit index

Examples

iex> qc = Qx.create_circuit(3) |> Qx.ccx(0, 1, 2)
iex> length(Qx.QuantumCircuit.get_instructions(qc))
1

@spec cp(circuit(), non_neg_integer(), non_neg_integer(), number()) :: circuit()

Applies a controlled-phase (CP) gate.

Applies a phase of e^(i*theta) to the |11⟩ basis state only. All other basis states are unchanged.

Parameters

• circuit - Quantum circuit
• control_qubit - Control qubit index
• target_qubit - Target qubit index
• theta - Phase angle in radians

Examples

iex> qc = Qx.create_circuit(2) |> Qx.cp(0, 1, :math.pi())
iex> length(Qx.QuantumCircuit.get_instructions(qc))
1

Raises

• FunctionClauseError - If qubit indices are out of range or equal
• ArgumentError - If theta is not a number

@spec create_circuit(pos_integer()) :: circuit()

Creates a new quantum circuit with only qubits (no classical bits).

Parameters

• num_qubits - Number of qubits (1-20 recommended)

Examples

iex> qc = Qx.create_circuit(3)
iex> qc.num_qubits
3
iex> qc.num_classical_bits
0

Raises

• FunctionClauseError - If num_qubits <= 0

@spec create_circuit(pos_integer(), non_neg_integer()) :: circuit()

Creates a new quantum circuit with specified qubits and classical bits.

Parameters

• num_qubits - Number of qubits (1-20 recommended)
• num_classical_bits - Number of classical bits for measurements

Examples

iex> qc = Qx.create_circuit(2, 2)
iex> qc.num_qubits
2
iex> qc.num_classical_bits
2

Raises

• FunctionClauseError - If num_qubits <= 0 or num_classical_bits < 0

@spec cswap(circuit(), non_neg_integer(), non_neg_integer(), non_neg_integer()) ::
  circuit()

Applies a Fredkin (controlled-SWAP) gate.

Swaps the quantum states of target_a and target_b when the control qubit is |1⟩. When the control qubit is |0⟩, the targets are unchanged.

Parameters

• circuit - Quantum circuit
• control - Control qubit index (0-based)
• target_a - First target qubit index (0-based)
• target_b - Second target qubit index (0-based)

Examples

iex> qc = Qx.create_circuit(3) |> Qx.cswap(0, 1, 2)
iex> [{:cswap, [0, 1, 2], []}] = Qx.QuantumCircuit.get_instructions(qc)
iex> :ok
:ok

Raises

• ArgumentError - If any two qubit indices are equal or any index is out of range

@spec cx(circuit(), non_neg_integer(), non_neg_integer()) :: circuit()

Applies a controlled-X (CNOT) gate.

Flips target qubit if and only if control qubit is |1⟩

Parameters

• circuit - Quantum circuit
• control_qubit - Control qubit index
• target_qubit - Target qubit index

Examples

iex> qc = Qx.create_circuit(2) |> Qx.cx(0, 1)
iex> length(Qx.QuantumCircuit.get_instructions(qc))
1

Raises

• FunctionClauseError - If qubit indices are out of range or equal

@spec cz(circuit(), non_neg_integer(), non_neg_integer()) :: circuit()

Applies a controlled-Z (CZ) gate.

Applies a Z gate to the target qubit if and only if the control qubit is |1⟩. This is a symmetric two-qubit gate that applies a phase flip when both qubits are |1⟩.

Parameters

• circuit - Quantum circuit
• control_qubit - Control qubit index
• target_qubit - Target qubit index

Examples

iex> qc = Qx.create_circuit(2) |> Qx.cz(0, 1)
iex> length(Qx.QuantumCircuit.get_instructions(qc))
1

@spec draw(
  simulation_result(),
  keyword()
) :: VegaLite.t() | String.t()

Visualizes probability distribution from simulation results.

Convenience function for quickly plotting the probability distribution from a simulation result. The probabilities are automatically extracted from the result map.

For plotting raw probability tensors (e.g., from get_probabilities/1), use histogram/2 instead.

Parameters

• result - Simulation result from run/1 or run/2
• options - Optional plotting parameters

Options

• :format - :vega_lite (default) or :svg
• :title - Plot title
• :width - Plot width (default: 400)
• :height - Plot height (default: 300)

Examples

iex> qc = Qx.create_circuit(2) |> Qx.h(0) |> Qx.cx(0, 1)
iex> result = Qx.run(qc)
iex> plot = Qx.draw(result)
iex> is_map(plot) or is_binary(plot)
true

See Also

• histogram/2 - For plotting raw probability tensors
• draw_counts/2 - For plotting measurement counts

@spec draw_bloch(
  Nx.Tensor.t(),
  keyword()
) :: VegaLite.t() | String.t()

Visualizes a single qubit state on the Bloch sphere.

The Bloch sphere provides a geometric representation of a pure qubit state. This visualization is particularly useful for understanding single-qubit gates and state transformations in calculation mode.

Parameters

• qubit - Single qubit state tensor (from Qx.Qubit)
• options - Optional plotting parameters

Options

• :format - :vega_lite (default) or :svg
• :title - Plot title (default: "Bloch Sphere")
• :size - Sphere size (default: 400)

Examples

# Visualize |0⟩ state
iex> q = Qx.Qubit.new()
iex> plot = Qx.draw_bloch(q)
iex> is_map(plot) or is_binary(plot)
true

# Visualize superposition state
iex> q = Qx.Qubit.new() |> Qx.Qubit.h()
iex> plot = Qx.draw_bloch(q, title: "Superposition State")
iex> is_map(plot) or is_binary(plot)
true

See Also

• Qx.Qubit - Calculation mode for single qubits
• draw_state/2 - Display multi-qubit state as table

@spec draw_counts(
  simulation_result(),
  keyword()
) :: VegaLite.t() | String.t()

Visualizes measurement counts as a bar chart.

Parameters

• result - Simulation result containing measurement data
• options - Optional plotting parameters

Examples

iex> qc = Qx.create_circuit(2, 2) |> Qx.h(0) |> Qx.measure(0, 0)
iex> result = Qx.run(qc)
iex> plot = Qx.draw_counts(result)
iex> is_map(plot) or is_binary(plot)
true

@spec draw_state(
  Qx.Register.t() | Nx.Tensor.t(),
  keyword()
) :: String.t()

Displays a quantum state as a formatted table.

Shows basis states with their amplitudes and probabilities. Useful for inspecting multi-qubit states in calculation mode.

Parameters

• register_or_state - Qx.Register.t() or state tensor
• options - Optional display parameters

Options

• :format - :text (default) or :html
• :precision - Decimal places (default: 3)
• :hide_zeros - Hide zero-amplitude states (default: false)

Examples

# Display Bell state
iex> reg = Qx.Register.new(2) |> Qx.Register.h(0) |> Qx.Register.cx(0, 1)
iex> table = Qx.draw_state(reg)
iex> is_binary(table)
true

# Hide zero states
iex> reg = Qx.Register.new(3) |> Qx.Register.h(0)
iex> table = Qx.draw_state(reg, hide_zeros: true)
iex> is_binary(table)
true

See Also

• Qx.Register - Calculation mode for multi-qubit systems
• draw_bloch/2 - Bloch sphere visualization for single qubits

@spec get_probabilities(
  circuit(),
  keyword()
) :: Nx.Tensor.t()

Gets probability distribution for computational basis states.

Parameters

• circuit - Quantum circuit
• options - Optional parameters

Options

• :backend - Nx backend to use (e.g., {EXLA.Backend, client: :host})

Examples

iex> qc = Qx.create_circuit(1) |> Qx.h(0)
iex> probs = Qx.get_probabilities(qc)
iex> Nx.shape(probs)
{2}

# Specify backend at runtime
# Qx.get_probabilities(qc, backend: {EXLA.Backend, client: :host})

Raises

• Qx.MeasurementError - If circuit contains measurements or conditionals

@spec get_state(
  circuit(),
  keyword()
) :: Nx.Tensor.t()

Executes a circuit and returns only the final quantum state.

Parameters

• circuit - Quantum circuit to execute
• options - Optional parameters

Options

• :backend - Nx backend to use (e.g., {EXLA.Backend, client: :host})

Examples

iex> qc = Qx.create_circuit(1) |> Qx.h(0)
iex> state = Qx.get_state(qc)
iex> Nx.shape(state)
{2}

# Specify backend at runtime
# Qx.get_state(qc, backend: {EXLA.Backend, client: :host})

Raises

• Qx.MeasurementError - If circuit contains measurements or conditionals

@spec ghz_state() :: circuit()

Creates a GHZ state circuit (three-qubit entangled state).

Returns a circuit that prepares |GHZ⟩ = (|000⟩ + |111⟩)/√2.

Examples

iex> ghz_circuit = Qx.ghz_state()
iex> ghz_circuit.num_qubits
3

@spec h(circuit(), non_neg_integer()) :: circuit()

Applies a Hadamard gate to the specified qubit.

Creates superposition: |0⟩ → (|0⟩ + |1⟩)/√2, |1⟩ → (|0⟩ - |1⟩)/√2

Parameters

• circuit - Quantum circuit
• qubit - Target qubit index

Examples

iex> qc = Qx.create_circuit(1) |> Qx.h(0)
iex> length(Qx.QuantumCircuit.get_instructions(qc))
1

Raises

• FunctionClauseError - If qubit index is out of range

@spec histogram(
  Nx.Tensor.t(),
  keyword()
) :: VegaLite.t() | String.t()

Creates a histogram from a raw probability tensor.

Use this function when you have a probability tensor and want to visualize it. This is useful for:

• Plotting probabilities from get_probabilities/1 without running simulation
• Visualizing custom or theoretical probability distributions
• Comparing different probability distributions

For quick visualization of simulation results, use draw/2 instead.

Parameters

• probabilities - Nx tensor of probabilities (should sum to 1.0)
• options - Optional plotting parameters

Examples

# Visualize probabilities without full simulation
iex> qc = Qx.create_circuit(2) |> Qx.h(0)
iex> probs = Qx.get_probabilities(qc)
iex> hist = Qx.histogram(probs)
iex> is_map(hist) or is_binary(hist)
true

See Also

• draw/2 - For plotting from simulation results
• get_probabilities/1 - To obtain probability tensors

@spec iswap(circuit(), non_neg_integer(), non_neg_integer()) :: circuit()

Applies an iSWAP gate, exchanging qubit states while applying an i phase factor to the swapped components.

Native to superconducting qubit hardware (Google Sycamore, Rigetti). Unlike SWAP, applying iSWAP twice is not the identity — it produces a -1 phase.

Parameters

• circuit - Quantum circuit
• qubit_a - Index of the first qubit
• qubit_b - Index of the second qubit

Examples

iex> qc = Qx.create_circuit(2) |> Qx.iswap(0, 1)
iex> length(Qx.QuantumCircuit.get_instructions(qc))
1

Raises

• FunctionClauseError - If qubit indices are out of range or equal

@spec measure(circuit(), non_neg_integer(), non_neg_integer()) :: circuit()

Adds a measurement operation to the circuit.

Parameters

• circuit - Quantum circuit
• qubit - Qubit index to measure
• classical_bit - Classical bit index to store result

Examples

iex> qc = Qx.create_circuit(2, 2) |> Qx.measure(0, 0)
iex> length(Qx.QuantumCircuit.get_measurements(qc))
1

Raises

• FunctionClauseError - If qubit or classical_bit index is out of range

@spec phase(circuit(), non_neg_integer(), float()) :: circuit()

Applies a phase gate with specified phase.

Parameters

• circuit - Quantum circuit
• qubit - Target qubit index
• phi - Phase angle in radians

Examples

iex> qc = Qx.create_circuit(1) |> Qx.phase(0, :math.pi/4)
iex> length(Qx.QuantumCircuit.get_instructions(qc))
1

@spec run(circuit(), pos_integer() | keyword()) :: simulation_result()

Executes the quantum circuit and returns simulation results.

Parameters

• circuit - Quantum circuit to execute
• options - Optional parameters (can be keyword list or integer for backward compatibility)

Options

• :shots - Number of measurement shots (default: 1024)
• :backend - Nx backend to use (e.g., {EXLA.Backend, client: :host})

Returns

A map containing:

• :probabilities - Probability amplitudes for all states
• :classical_bits - List of measurement results
• :state - Final quantum state vector
• :shots - Number of shots performed
• :counts - Frequency count of measurement outcomes

Examples

iex> qc = Qx.create_circuit(1) |> Qx.h(0)
iex> result = Qx.run(qc)
iex> is_map(result)
true
iex> Map.has_key?(result, :probabilities)
true

# Specify backend at runtime
# Qx.run(qc, backend: {EXLA.Backend, client: :host})

# Backward compatible: pass shots as integer
# Qx.run(qc, 2048)

@spec rx(circuit(), non_neg_integer(), float()) :: circuit()

Applies a rotation around the X-axis.

Parameters

• circuit - Quantum circuit
• qubit - Target qubit index
• theta - Rotation angle in radians

Examples

iex> qc = Qx.create_circuit(1) |> Qx.rx(0, :math.pi/2)
iex> length(Qx.QuantumCircuit.get_instructions(qc))
1

@spec ry(circuit(), non_neg_integer(), float()) :: circuit()

Applies a rotation around the Y-axis.

Parameters

• circuit - Quantum circuit
• qubit - Target qubit index
• theta - Rotation angle in radians

Examples

iex> qc = Qx.create_circuit(1) |> Qx.ry(0, :math.pi/2)
iex> length(Qx.QuantumCircuit.get_instructions(qc))
1

@spec rz(circuit(), non_neg_integer(), float()) :: circuit()

Applies a rotation around the Z-axis.

Parameters

• circuit - Quantum circuit
• qubit - Target qubit index
• theta - Rotation angle in radians

Examples

iex> qc = Qx.create_circuit(1) |> Qx.rz(0, :math.pi/2)
iex> length(Qx.QuantumCircuit.get_instructions(qc))
1

@spec s(circuit(), non_neg_integer()) :: circuit()

Applies an S gate (phase gate with π/2 phase).

Parameters

• circuit - Quantum circuit
• qubit - Target qubit index

Examples

iex> qc = Qx.create_circuit(1) |> Qx.s(0)
iex> length(Qx.QuantumCircuit.get_instructions(qc))
1

@spec sdg(circuit(), non_neg_integer()) :: circuit()

Applies an S† (S-dagger) gate (-π/2 phase on |1⟩).

Rotates the Y-basis back to the X-basis. The inverse of s/2.

Parameters

• circuit - Quantum circuit
• qubit - Target qubit index

Examples

iex> qc = Qx.create_circuit(1) |> Qx.sdg(0)
iex> length(Qx.QuantumCircuit.get_instructions(qc))
1

@spec superposition() :: circuit()

Creates a superposition state on a single qubit.

Returns a circuit with a Hadamard gate applied to qubit 0.

Examples

iex> sup_circuit = Qx.superposition()
iex> sup_circuit.num_qubits
1

@spec swap(circuit(), non_neg_integer(), non_neg_integer()) :: circuit()

Applies a SWAP gate, exchanging the quantum states of two qubits.

Both qubits are treated symmetrically — there is no control/target distinction.

Parameters

• circuit - Quantum circuit
• qubit_a - Index of the first qubit
• qubit_b - Index of the second qubit

Examples

iex> qc = Qx.create_circuit(2) |> Qx.swap(0, 1)
iex> length(Qx.QuantumCircuit.get_instructions(qc))
1

Raises

• FunctionClauseError - If qubit indices are out of range or equal

@spec t(circuit(), non_neg_integer()) :: circuit()

Applies a T gate (phase gate with π/4 phase).

Parameters

• circuit - Quantum circuit
• qubit - Target qubit index

Examples

iex> qc = Qx.create_circuit(1) |> Qx.t(0)
iex> length(Qx.QuantumCircuit.get_instructions(qc))
1

@spec tap_circuit(circuit(), (circuit() -> any())) :: circuit()

Inspects the circuit without breaking the pipeline.

See Qx.Operations.tap_circuit/2 for full documentation.

Examples

# Inspect instructions while building circuit
circuit = Qx.create_circuit(2)
  |> Qx.h(0)
  |> Qx.tap_circuit(fn c -> IO.puts("Gates: #{length(c.instructions)}") end)
  |> Qx.cx(0, 1)

@spec tap_probabilities(circuit(), (Nx.Tensor.t() -> any())) :: circuit()

Inspects measurement probabilities without breaking the pipeline.

See Qx.Operations.tap_probabilities/2 for full documentation.

Examples

# Inspect probabilities while building circuit
circuit = Qx.create_circuit(2)
  |> Qx.h(0)
  |> Qx.tap_probabilities(fn p -> IO.puts("Probs: #{inspect(Nx.shape(p))}") end)
  |> Qx.cx(0, 1)

@spec tap_state(circuit(), (Nx.Tensor.t() -> any())) :: circuit()

Inspects the current quantum state without breaking the pipeline.

See Qx.Operations.tap_state/2 for full documentation.

Examples

# Inspect quantum state while building circuit
circuit = Qx.create_circuit(1)
  |> Qx.h(0)
  |> Qx.tap_state(fn s -> IO.puts("State shape: #{inspect(Nx.shape(s))}") end)
  |> Qx.z(0)

@spec u(circuit(), non_neg_integer(), number(), number(), number()) :: circuit()

Applies the general single-qubit unitary gate U(θ,φ,λ) (IBM/OpenQASM 3 convention).

U(θ,φ,λ) = [[cos(θ/2), -e^(iλ)·sin(θ/2) ],

         [e^(iφ)·sin(θ/2),  e^(i(φ+λ))·cos(θ/2) ]]

Parameters

• circuit - Quantum circuit
• qubit - Target qubit index (0-based)
• theta - Polar angle in radians
• phi - Azimuthal angle in radians
• lambda - Additional phase angle in radians

Examples

iex> qc = Qx.create_circuit(1) |> Qx.u(0, :math.pi(), 0, :math.pi())
iex> [{:u, [0], params}] = Qx.QuantumCircuit.get_instructions(qc)
iex> length(params)
3

Raises

• ArgumentError - If theta, phi, or lambda is not a number
• FunctionClauseError - If qubit index is out of range

@spec version() :: String.t()

Returns version information for the Qx library.

Examples

iex> version = Qx.version()
iex> is_binary(version)
true

@spec x(circuit(), non_neg_integer()) :: circuit()

Applies a Pauli-X gate (bit flip) to the specified qubit.

Flips |0⟩ ↔ |1⟩

Parameters

• circuit - Quantum circuit
• qubit - Target qubit index

Examples

iex> qc = Qx.create_circuit(1) |> Qx.x(0)
iex> length(Qx.QuantumCircuit.get_instructions(qc))
1

Raises

• FunctionClauseError - If qubit index is out of range

@spec y(circuit(), non_neg_integer()) :: circuit()

Applies a Pauli-Y gate to the specified qubit.

Combines bit flip and phase flip transformations.

Parameters

• circuit - Quantum circuit
• qubit - Target qubit index

Examples

iex> qc = Qx.create_circuit(1) |> Qx.y(0)
iex> length(Qx.QuantumCircuit.get_instructions(qc))
1

Raises

• FunctionClauseError - If qubit index is out of range

@spec z(circuit(), non_neg_integer()) :: circuit()

Applies a Pauli-Z gate (phase flip) to the specified qubit.

Leaves |0⟩ unchanged, applies -1 phase to |1⟩

Parameters

• circuit - Quantum circuit
• qubit - Target qubit index

Examples

iex> qc = Qx.create_circuit(1) |> Qx.z(0)
iex> length(Qx.QuantumCircuit.get_instructions(qc))
1

Raises

• FunctionClauseError - If qubit index is out of range