Copy page

• View as Markdown
• Open in Claude
• Open in ChatGPT
• Connect via MCP

qaoa

eigenkit.optimization.qaoa

The Quantum Approximate Optimization Algorithm (QAOA) with the core of the library.

It builds the standard QAOA ansatz from the qubit Hamiltonian of a problem, optimises the angles (γ, β) with minimize_expectation, and then reads the distribution of bitstrings of the optimised state (probabilities) to find a solution. It uses only NumPy and SciPy, needs no PyTorch, and works with any backend that can return the probabilities of the basis states.

eigenkit.optimization.qaoa.QAOA

Bases: BaseQuantumSolver

The Quantum Approximate Optimization Algorithm (QAOA) solver.

It solves an Ising or QUBO problem.

Parameters:

Name	Type	Description	Default
layers	int	The depth p of QAOA. Default: 1.	1
provider	ProviderSpec	The backend. Default: "numpy", the reference NumPy simulator.	'numpy'
optimizer	Optimizer	A SciPy method name, "spsa", or a custom callable (see minimize_expectation). Default: "L-BFGS-B".	'L-BFGS-B'
random_state	int | None	The seed of the random initial angles. With None, they are not seeded. Default: 42.	42

solve(problem, *, initial_parameters=None, top_k=None, **minimize_kwargs)

Optimise the QAOA angles and read the answer from the final state.

Parameters:

Name	Type	Description	Default
problem	QUBO | Ising	The problem to minimise.	required
initial_parameters	ndarray | None	The initial angles γ and β, of shape (2 * layers,). They are random when they are not given. Default: None.	None
top_k	int | None	How many of the most probable bitstrings to score with the energy of the problem. The best of them is returned as best_bitstring, and the others are not returned. Default: None, which scores the 64 most probable bitstrings, or all of them when there are fewer.	None
**minimize_kwargs	Any	Other keyword arguments, passed to minimize_expectation, for example max_iterations.	{}

Returns:

Type	Description
OptimizationResult	An OptimizationResult with the best bitstring, its energy and the final distribution.

Raises:

Type	Description
ValueError	If top_k is smaller than 1.

eigenkit.optimization.qaoa.OptimizationResult dataclass

Bases: ValueEquality

The result of a run of the Quantum Approximate Optimization Algorithm (QAOA).

The result is read-only. Assigning to a field raises FrozenInstanceError, and writing into an array field raises ValueError. This prevents a mistyped = (instead of ==) or an in-place edit from leaving a result whose scalar fields describe a different run from the arrays it holds. To get a writable copy of an array, use np.array(result.field).

Results compare by value, including their arrays. They are not hashable, because a result is a collection of numbers and not a key, and a correct hash of a float array is expensive to compute.

Attributes:

Name	Type	Description
best_bitstring	tuple[int, ...]	The configuration with the lowest energy that was found, as a tuple of bits.
best_energy	float	Its energy for the problem being solved. This is the answer to report: QAOA samples, so the best sample is better than the average.
expectation	float	The mean energy of the final state. Compare it with best_energy to see how concentrated the distribution is.
optimal_parameters	ndarray	The angles γ and β that the optimiser settled on.
probabilities	ndarray	The probability of every basis state, of length 2**n.
n_iterations	int	The number of iterations of the optimiser.
success	bool	Whether the optimiser reported convergence.

__post_init__()

Make the array fields read-only.

Freezing the dataclass prevents a field from being reassigned, but it does not prevent writing into the array that the field holds, and a result that has been written into still reports the scalar values of the original run. The result therefore keeps its own copies, so the arrays it was built from can still be changed by the caller. To get a writable copy, use np.array(result.optimal_parameters).

eigenkit.optimization.qaoa.qaoa_ansatz(hamiltonian, num_qubits, layers)

Build the standard QAOA circuit.

QAOA is the Quantum Approximate Optimization Algorithm. The circuit starts in |+⟩^n, then applies layers repetitions of the cost unitary exp(-i γ_l H_C) and the mixer exp(-i β_l Σ_i X_i). It has 2 * layers weights, in the order [γ_0, β_0, γ_1, β_1, ...].

Parameters:

Name	Type	Description	Default
hamiltonian	Observable	The cost Hamiltonian.	required
num_qubits	int	The number of qubits, one per variable.	required
layers	int	The depth of QAOA, which is the number of pairs of a cost layer and a mixer layer.	required

Returns:

Type	Description
CircuitSpec	The ansatz, as a CircuitSpec with 2 * layers trainable angles.