uniqc.algorithms.workflows.qaoa_workflow module

Lightweight QAOA workflow built on qaoa_ansatz + pauli_expectation.

Mirrors uniqc.algorithms.workflows.vqe_workflow: scipy-based optimiser, no torch / torchquantum dependency. The cost Hamiltonian is supplied as a list of (pauli_string, coefficient) terms, identical to the VQE workflow.

class uniqc.algorithms.workflows.qaoa_workflow.QAOAResult(energy, gammas, betas, history=<factory>, n_iter=0, success=True, message='')[source]

Bases: object

Outcome of run_qaoa_workflow().

Variables:

  • energy (float) – Minimum cost-function value ⟨H_C⟩ found.

  • gammas (numpy.ndarray) – Optimal γ angles, length p.

  • betas (numpy.ndarray) – Optimal β angles, length p.

  • history (list[float]) – Per-iteration energies (in evaluation order).

  • n_iter (int) – Number of objective evaluations.

  • success (bool) – Whether the underlying scipy optimiser reported success.

  • message (str) – Optimiser termination message.

Parameters:
betas: ndarray
energy: float
gammas: ndarray
history: list[float]
message: str = ''
n_iter: int = 0
success: bool = True
uniqc.algorithms.workflows.qaoa_workflow.run_qaoa_workflow(cost_hamiltonian, *, n_qubits=None, p=1, init_gammas=None, init_betas=None, shots=None, method='COBYLA', options=None)[source]

Run a scipy-driven QAOA on cost_hamiltonian.

Parameters:

  • cost_hamiltonian (Sequence[tuple[str, float]]) – (pauli_string, coefficient) terms of H_C.

  • n_qubits (int | None) – Number of qubits. Inferred from the first Pauli term if None.

  • p (int) – QAOA depth (number of γ/β layers).

  • init_gammas (ndarray | None) – Optional initial γ vector of length p. Defaults to a uniform-random vector in [0, π].

  • init_betas (ndarray | None) – Optional initial β vector of length p. Defaults to a uniform-random vector in [0, π/2].

  • shots (int | None) – Shots per Pauli-term expectation. None uses the analytic statevector estimator.

  • method (str) – scipy.optimize.minimize method. Defaults to COBYLA (gradient-free).

  • options (dict | None) – Optional dict forwarded to scipy.optimize.minimize.

Returns:

QAOAResult with the optimised γ / β and minimum energy.

Return type:

QAOAResult

Example

>>> # MaxCut on a 2-edge path graph 0-1-2:  H_C = (Z0Z1 + Z1Z2 - 2)/2
>>> H = [("ZZI", 0.5), ("IZZ", 0.5), ("III", -1.0)]
>>> result = run_qaoa_workflow(H, n_qubits=3, p=1)
>>> result.energy <= -0.5
True
uniqc.algorithms.workflows.qaoa_workflow.run_qaoa_workflow_example()[source]

Smallest non-trivial example: 3-node path-graph MaxCut, p=1.

Return type:

QAOAResult