---
title: Q-CTRL Optimization Solver by Global Data Quantum API reference
description: API reference for Optimization Solver by Q-CTRL Fire Opal
source: https://eu-de.quantum.cloud.ibm.com/docs/en/functions/q-ctrl-optimization-solver/api-reference
---

# Q-CTRL Optimization Solver by Global Data Quantum API reference

## Inputs

### `problem`

Type: `str or SparsePauliOp`

Default value: `None`

One of the representations listed under "Accepted problem formats".

- Required: Yes
- Example: `Poly(2.0*n[0]*n[1] + 2.0*n[0]*n[2] - 3.13520241298341*n[0] + 2.0*n[1]*n[2] - 3.14469748506794*n[1] - 3.18897660121566*n[2] + 6.0, n[0], n[1], n[2], domain='RR')`

### `problem_type`

Type: `str`

Default value: `None`

Name of the problem class; only used for graph and spin chain problem definitions, which are limited to `"maxcut"` or `"spin_chain"`; not required for arbitrary objective function problem definitions.

- Required: No
- Example: `"maxcut"`

### `backend_name`

Type: `str`

Default value: `Least busy backend`

Name of the backend to use.

- Required: No
- Example: `"ibm_fez"`

### `constraint`

Type: `dict[tuple, int]`

Default value: `None`

Optional Hamming-weight constraints for the problem variables. Each constraint specifies a group of variables that must sum to exactly 1 (that is, exactly one variable in the group is 1 and the rest are 0). If not provided, the solver treats the problem as unconstrained and searches over all possible bitstrings. You do not need to constrain every variable — variables left out of `constraint` remain unconstrained, so partially constrained problems are supported. Keys are tuples of variable indices, or variable names when using a polynomial `problem` input.

- Required: No
- Example: `{("n[0,0]", "n[0,1]", "n[0,2]"): 1}`

### `function_size`

Type: `str`

Default value: `"M"`

Size the job runs at: `"S"`, `"M"`, or `"L"`. The required size depends on the number of binary decision variables and the interaction density, the fraction of variable pairs that interact: up to 50 variables and 10% density is `"S"`, up to 100 variables and 25% density is `"M"`, and anything larger is `"L"`. To calculate the size before you submit a job, see [Function sizes](/docs/functions/q-ctrl-optimization-solver#function-sizes). If the size is too small, the job fails with error `4600`. If the size is larger than the job needs, the job runs normally and records a `4601` advisory event.

- Required: No
- Example: `"L"`

### Options

Type: `dict`

Default value: `None`

Input options, including the following: (Optional) `session_id`: `str`; default behavior creates a new Session. Options are specified as a nested dictionary. See the full [list of options](#options-list) and their default values.

- Required: No
- Example: `{"session_id": "cw2q70c79ws0008z6g4g"}`

#### Options list

##### `session_id`

Type: `str`

Default value: `None`

An existing IBM Quantum Compute Service session ID.

- Default: `None`
- Example: `"cw4r3je6f0t010870y3g"`

##### `job_tags`

Type: `list[str]`

Default value: `None`

A list of job tags.

- Default: `None`
- Example: `["job_tag1", "job_tag2"]`

## Outputs

### `result`

Type: `dict[str, Any]`

Solution and metadata listed under [Result dictionary contents](#result-dictionary-contents).

Example: `{'solution_bitstring_cost': 3.0, `final\_bitstring\_distribution`: {`000001`: 100, `000011`: 2}, `iteration\_count`: 3, 'solution_bitstring': `000001`,  'variables_to_bitstring_index_map': {n[1]': 5, 'n[2]': 4, 'n[3]': 3, 'n[4]': 2, 'n[5]': 1}, 'best_parameters': [0.19628831763697097, -1.047052334523102], 'warnings': []}`

### Result dictionary contents

#### `solution_bitstring_cost`

Type: `float`

The best minimum cost across all iterations.

#### `final_bitstring_distribution`

Type: `CountsDict`

The bitstring counts dictionary associated with the minimum cost.

#### `solution_bitstring`

Type: `str`

Bitstring with the best cost in the final distribution.

#### `iteration_count`

Type: `int`

The total number of QAOA iterations performed by the Solver.

#### `variables_to_bitstring_index_map`

Type: `float`

The mapping from the variables to the equivalent bit in the bitstring.

#### `best_parameters`

Type: `list[float]`

The optimized beta and gamma parameters across all iterations.

#### `warnings`

Type: `list[str]`

Default value: `None`

The warnings produced while compiling or running QAOA.

## Error handling

The function reports the following errors that relate to `function_size`. For all error codes, see the [IBM Quantum error codes](/docs/errors).

| Code   | Cause                                                                                                                                                               |
| :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `4600` | The [`function_size`](#function_size) is too small for the workload. The job fails, and the message names the size to use.                                          |
| `4601` | The [`function_size`](#function_size) is larger than the workload needs. The job runs normally and records an advisory event that you can read with `job.events()`. |