Behaviour for multi-qubit quantum state manipulation.

Enforces a consistent gate-application API across modules whose state is indexed by qubit number — currently Qx.Register (calc-mode multi-qubit) and, by convention, Qx.QuantumCircuit via Qx.Operations. Implementing modules must provide the standard gate set + state inspection.

Single-qubit modules

Qx.Qubit is intentionally not an implementor — its gate functions take a single-state argument (Qx.Qubit.h(qubit)) rather than the (state, qubit_index) shape this behaviour requires. Unifying both paradigms under one behaviour would force a structural redesign of Qx.Qubit and is deferred to a future major version.

Optional callbacks

Three-qubit gates (ccx, cswap) and a small handful of less-common two-qubit gates are marked as @optional_callbacks — implementations with fewer than 3 qubits (or that omit a gate) can leave them undefined without a compile warning.

Example

defmodule MyMultiQubitState do
  @behaviour Qx.Behaviours.QuantumState

  @impl true
  def h(state, qubit), do: # ... implementation

  @impl true
  def cx(state, control, target), do: # ... implementation

  # ... other required callbacks
end