Aqarios Constrained Quantum Optimizer API reference

Type: str

The serialized optimization problem to solve. Three formats are supported:

• LP (*.lp): Standard LP file format exported as a string, for example via DOcplex's export_as_lp_string()
• MPS (*.mps): Standard MPS file format exported as a string, for example via DOcplex's export_as_mps_string()
• Luna Model: Base64-encoded serialization of an Aqarios Luna Model object, obtained via model.encode_b64()

The model must represent a binary optimization problem, either as a maximization or minimization. Constraints can be inequalities or equalities over binary variables. Integer variables are only supported when clear upper and lower bounds are specified. Continuous (real-valued) variables are not supported, and a model that contains them fails with error code 4710. The objective and constraints can be higher order and do not need to be linear only.

• Required: Yes
• Example LP:

\Problem name: MIS
Minimize
  obj: ...
Subject To
  c1: ...
  ...
Binaries
  x_0 x_1
End

Type: str or None

Valeur par défaut: None

The name of the IBM Quantum backend to run on (for example "ibm_phoenix"). When set to None, the function automatically selects the least-busy available device.

• Required: No
• Example: "ibm_phoenix"

Type: dict or None

Valeur par défaut: None

Algorithm configuration options controlling the behavior of the iterative warm-starting QAOA. Options are specified as a dictionary. See the options list below for all available keys and their default values.

• Required: No
• Example: {"reps": 2, "num_parallel": 10, "postprocessing_level": 1}

Type: int

Valeur par défaut: 1

Number of QAOA layer repetitions (circuit depth parameter $p$). Higher values increase solution quality at the cost of deeper circuits and longer execution time, which can inflict more noise.

• Choices: Integer in range [1, 10]

Type: int

Valeur par défaut: 5

Number of independent warm-start chains run in parallel. Increasing this value improves the probability of finding high-quality solutions but raises the total shot budget consumed.

• Choices: Integer in range [1, 100]

Type: int

Valeur par défaut: 500

Number of measurement shots per iteration per chain.

• Choices: Integer in range [1, 10000]

Type: int

Valeur par défaut: 5000

Total shot budget across all iterations for a single warm-start chain. The iteration loop terminates for a chain once this budget is exhausted.

• Choices: Integer in range [1, 1000000]

Type: float

Valeur par défaut: 0.1

Regularization parameter for the warm-start probabilities. Prevents the probability distribution from collapsing to a deterministic state, preserving exploration across iterations.

• Choices: Float in range (0.01, 1)

Type: float

Valeur par défaut: 10

Inverse temperature for the Boltzmann weighting used to derive new warm-start states from measurement samples. Higher values concentrate probability mass on lower-energy samples.

• Choices: Float satisfying beta > 0

Type: float

Valeur par défaut: 1.0

Controls the approximation level applied to the cost function and during transpilation. Lower values reduce circuit depth by introducing approximations, which can affect solution quality.

• Choices: Float in range [0.0, 1.0]

Type: int

Valeur par défaut: 3

Strength of the classical postprocessing applied after each sampling step to improve solution quality. Higher levels apply more aggressive local search at the cost of additional classical compute time.

• Choices: Integer in range [0, 3]
  • 0: Disable postprocessing.
  • 1: Single-pass local search. Try to flip every bit once in random order and keep flips that reduce energy.
  • 2: Three-pass local search. Apply level 1 three times with different random orders.
  • 3: Greedy local search. Repeatedly apply the bit-flip that reduces energy the most until no further improvement is possible.

Type: float or None

Valeur par défaut: None

Manually overrides the penalty value used when converting constraints into penalty terms added to the objective. By default, the penalty is derived automatically from the problem structure. Use this option only if the automatic value produces infeasible results.

• Choices: Float satisfying penalty_override > 0, or None to use the automatic value

Type: bool

Valeur par défaut: False

Whether to use IBM Quantum Compute Service session mode for job execution. Enabling sessions reduces circuit execution overhead by keeping a dedicated connection to the QPU open across iterations, which can lower overall wall-clock time.

• Choices: True / False

Type: int or None

Valeur par défaut: None

Seed passed to the transpiler that maps the circuit onto the selected backend. Set a fixed value to make circuit synthesis and routing reproducible across runs. When set to None, the transpiler seeds itself non-deterministically, so repeated runs of the same problem can yield different circuit layouts.

• Choices: Any integer, or None for a non-deterministic seed

Type: list[str]

Valeur par défaut: []

Extra tags attached to every Quantum Compute job that the function submits to the QPU. The function always tags its jobs with "aqarios/constrained-quantum-optimizer", the function job ID, and the problem name; the entries given here are appended to that list. Use this to group or filter the underlying primitive jobs in your workload list.

• Choices: List of strings
• Example: ["my-experiment", "mis-benchmark"]

Type: dict[str, Any]

Result dictionary with solution assignments, objective value, feasibility status, and runtime metadata.

Example:

{
    'solutions': [{'x_1': 0, 'x_2': 1, 'x_3': 0, 'x_4': 1, 'x_5': 1}],
    'solution_bitstrings': ['01011'],
    'raw_energy': -6.0,
    'objective_value': -6.0,
    'feasible': True,
    'metadata': {
        'resource_usage': {
            'RUNNING: MAPPING': {'CPU': 5.405},
            'RUNNING: OPTIMIZING_FOR_HARDWARE': {'CPU': 9.902},
            'RUNNING: WAITING_FOR_QPU': {'CPU': 25.456},
            'RUNNING: EXECUTING_QPU': {'QPU': 25.202},
            'RUNNING: POST_PROCESSING': {'CPU': 6.481}
        },
        'circuit_metrics': {
            'before_transpilation': {
                'num_qubits': 6,
                'gate_count': 42,
                'depth': 15,
                'two_qubit_gate_count': 12,
                'two_qubit_gate_depth': 7,
                'operations': {'rz': 12, 'p': 8, 'ry': 7, 'rzz': 4, 'cx': 3,
                               'xx_plus_yy': 3, 'global_phase': 2, 'cry': 2, 'x': 1}
            },
            'after_transpilation': {
                'num_qubits': 6,
                'gate_count': 254,
                'depth': 100,
                'two_qubit_gate_count': 48,
                'two_qubit_gate_depth': 33,
                'operations': {'rz': 78, 'sx': 122, 'cz': 48, 'measure': 6, 'x': 0}
            }
        },
        'solver_info': {
            'variable_mapping': {'x_1': 0, 'x_2': 1, 'x_3': 2, 'x_4': 3, 'x_5': 4}
        }
    }
}