uniqc.algorithms.core.ansatz.qaoa_ansatz module

QAOA (Quantum Approximate Optimization Algorithm) ansatz.

Constructs the alternating-operator ansatz used in QAOA for solving combinatorial optimisation problems.

uniqc.algorithms.core.ansatz.qaoa_ansatz.qaoa_ansatz(cost_hamiltonian, p=1, qubits=None, betas=None, gammas=None, *, mixer='x', initial_state=None, multi_angle=False)[source]

Build a QAOA ansatz circuit.

The ansatz alternates between the cost unitary \(U_C(\gamma) = e^{-i\gamma H_C}\) and the mixer unitary \(U_M(\beta)\) for p layers.

Parameters:

  • cost_hamiltonian (list[tuple[str, float]]) – List of (pauli_string, coefficient) tuples. Pauli strings use the format "Z0Z1", "X0Y1Z2", etc.

  • p (int) – Number of QAOA layers.

  • qubits (list[int] | None) – Qubit indices. None → auto-detect from hamiltonian.

  • betas (Parameters | ndarray | None) – Mixer angles, length p. None → random.

  • gammas (Parameters | ndarray | None) – Cost angles, length p. None → random.

  • mixer (str) – Mixer type. Options: - "x": Standard X mixer: \(\sum X_i\) (default) - "xy": XY mixer for constrained optimization

  • initial_state (Circuit | None) – Custom initial state circuit. None → uniform superposition (Hadamards).

  • multi_angle (bool) – If True, use MA-QAOA: each Pauli term gets its own gamma and each qubit gets its own beta. Overrides betas and gammas.

Returns:

A Circuit object.

Raises:

ValueError – Angle arrays have wrong length.

Return type:

Circuit

Example

>>> from uniqc.algorithms.core.ansatz import qaoa_ansatz
>>> H = [("Z0Z1", 1.0), ("Z1Z2", 1.0), ("Z0Z2", 0.5)]
>>> c = qaoa_ansatz(H, p=2)

XY mixer for constrained optimization: >>> c = qaoa_ansatz(H, p=2, mixer=”xy”)

Warm-start with custom initial state: >>> from uniqc.circuit_builder import Circuit >>> init = Circuit() >>> init.x(0) # custom initial state >>> c = qaoa_ansatz(H, p=2, initial_state=init)