solve_qaoa

fireopal.solve_qaoa(problem, credentials, problem_type=None, backend_name=None, run_options=None, constraint=None)

Run a hybrid quantum-classical QAOA solver that iterates between quantum circuit execution and classical parameter optimization until convergence.

For a detailed description of the methods used, see: Sachdeva et al. (2024).

Parameters

  • problem (Expr or nx.Graph or PauliOperator) –

    The optimization problem to solve. Accepts three forms:

    • nx.Graph: A graph over binary node variables. Requires problem_type to be set to either "maxcut" or a Max-k-Cut problem type of the form "max-<k>-cut" (for example "max-3-cut").
    • sympy.Expr: A polynomial cost function with binary variables to minimize. Must contain at least one nonlinear (quadratic or higher-degree) term; purely linear problems are rejected (see Raises).
    • PauliOperator: A diagonal Ising Hamiltonian composed of only I and Z Pauli operators with real coefficients, representing a spin glass problem. Converted to a binary polynomial internally via Zi=1−2xiZ_i = 1 - 2x_i.

    • credentials (Credentials) – The credentials for running circuits on an IBM or IonQ backend. Use either make_credentials_for_ibm_cloud or make_credentials_for_ionq from the credentials module to generate properly formatted credentials.

    • problem_type (str , optional) –

      The class of graph problem to solve. Only used when problem is an nx.Graph and gets ignored otherwise. Accepts two forms:

      • "maxcut": A Max-Cut problem.
      • "max-<k>-cut": A Max-k-Cut problem, where k is an integer greater than or equal to 2 (for example "max-3-cut"). For k > 2, the required Hamming-weight constraints are generated internally and any constraint argument is ignored. For k = 2, the problem is treated as Max-Cut and user-provided constraints are respected.

    • backend_name (str , optional) – The backend device that should be used to run circuits. Defaults to None.

    • run_options (RunOptions or None , optional) – Additional options for circuit execution. See the run_options module for classes to store run options for your desired provider. Defaults to None.

    • constraint (dict [ tuple , int ] or None , optional) –

      Optional Hamming-weight constraints for the problem variables. Each constraint specifies a group of variables that must sum to exactly 1 (i.e., exactly one variable in the group is 1 and the rest are 0). If not provided, the solver will consider this an unconstrained problem search over all possible bitstrings. Defaults to None. For Max-k-Cut problems with k > 2, constraints are generated internally and any value provided here is ignored.

      • nx.Graph: keys are tuples of integer node indices.
      • sympy.Expr: keys are tuples of either variable names or variable indices.

      Graph constraints example:

      >>> constraint_dict = {
...     (0, 1): 1,       # exactly one of nodes 0,1 must be 1
...     (4, 5, 6): 1,    # exactly one of nodes 4,5,6 must be 1
... }

      For a polynomial with variables x, y, and z, either form is valid:

      >>> constraint_dict_by_name = {
...     ("x", "y", "z"): 1,
... }
      >>> constraint_dict_by_index = {
...     (0, 1, 2): 1,  # indices correspond to x, y, z
... }

Returns

FireOpalJob – A job object containing results and warnings from the execution. The results have the following keys:

solution_bitstring (str) : The solution bitstring with the best cost found, across all iterations.

solution_bitstring_cost (float) : The cost of the solution bitstring.

final_bitstring_distribution (dict[str, int]) : The bitstring counts dictionary associated with the minimum cost across all iterations.

iteration_count (int) : The total number of QAOA iterations performed by the optimizer.

variables_to_bitstring_index_map (dict[str, int]) : The mapping from the variables to the equivalent bit in the bitstring.

best_parameters (list[float]) : The optimized beta and gamma parameters across all iterations.

warnings (list[str]) : The warnings produced while compiling or running QAOA.

Raises

  • QctrlArgumentsValueError – If the problem polynomial has only degree-1 (linear) terms. Linear problems have trivially classical solutions and do not require quantum resources.
  • QctrlArgumentsValueError – If problem is an nx.Graph with fewer than 2 nodes.
  • QctrlArgumentsValueError – If problem is an nx.Graph and problem_type is not provided.
  • QctrlArgumentsValueError – If problem_type is a Max-k-Cut problem type of the form "max-<k>-cut" with k less than 2.
  • QctrlArgumentsValueError – If problem is a PauliOperator containing non-diagonal terms (i.e., any Pauli other than I or Z).

Was this useful?