Kipu Quantum Iskay Quantum Optimizer API reference

Inputs

`problem`

Type: Dict[str, float]

The coefficients of the optimization problem formulated as QUBO/HUBO or spin format. For more information on the problem specification, see Accepted problem formats.

Required: Yes
Example: {"()": -21.0, "(0, 4)": 0.5,"(0, 2)": 0.5,"(0, 1)": 0.5,"(1, 3)": 0.5}

`problem_type`

Type: str

Specify whether the problem coefficients are in binary (QUBO/HUBO) or spin format. The two possibilities are "spin" or "binary". For more information on the problem specification, see Accepted problem formats.

Required: Yes
Example: "spin"

`backend_name`

Type: str

Name of the backend to make the query

Required: Yes
Example: "ibm_fez"

`function_size`

Type: str

Default value: "M"

Size for the job, which is "S", "M", or "L". The required size depends on the number of variables in the problem and how densely they interact. To calculate the size before you submit a job, see Function sizes in the guide. 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[str, Any]

Options to handle the hardware submission, such as number of shots. Options for this function are specified as a nested dictionary. See the full list of options and their default values.

Required: No
Example: {"shots": 5000, "num_iterations": 3, "use_session": True, "seed_transpiler": 42}

Accepted problem formats

The problem and problem_type arguments encode an optimization problem of the form

\begin{align} \min_{(x_1, x_2, \ldots, x_n) \in D} C(x_1, x_2, \ldots, x_n) \nonumber \end{align}

where

C(x_1, ... , x_n) = a + \sum_{i} b_i x_i + \sum_{i, j} c_{i, j} x_i x_j + ... + \sum_{k_1, ..., k_m} g_{k_1, ..., k_m} x_{k_1} ... x_{k_m}

By choosing problem_type = "binary", you specify that the cost function is in binary format, which means that $D = \{0, 1\}^{n}$ , as in, the cost function is written in QUBO/HUBO formulation.
On the other hand, by choosing problem_type = "spin", the cost function is written in Ising formulation, where $D = \{-1, 1\}^{n}$ .

The coefficients of the problem should be encoded in a dictionary as follows:

\begin{align} \nonumber &\texttt{\{} \\ \nonumber &\texttt{"()"}&: \quad &a, \\ \nonumber &\texttt{"(i,)"}&: \quad &b_i, \\ \nonumber &\texttt{"(i, j)"}&: \quad &c_{i, j}, \\ \nonumber &\quad \vdots \\ \nonumber &\texttt{"(} k_1, ..., k_m \texttt{)"} &: \quad &g_{k_1, ..., k_m}, \\ \nonumber &\texttt{\}} \end{align}

Please note that the keys of the dictionary must be strings containing a valid tuple of non-repeating integers.

Options list

Iskay provides fine-tuning capabilities through optional parameters. While the defaults work well for most problems, you can customize the behavior for specific requirements:

`shots`

Type: `int`

Default value: 10000

Quantum measurements per iteration (higher = more accurate)

`num_iterations`

Type: `int`

Default value: 10

Algorithm iterations (more iterations can improve solution quality)

`use_session`

Type: `bool`

Default value: True

Use IBM sessions for reduced queue times

`seed_transpiler`

Type: `int`

Default value: None

Set for reproducible quantum circuit compilation.

Seed optimization: By default, seed_transpiler is None, and transpilation level 2 searches over transpiler seeds to find the circuit with the best depth. If you set a seed, the function skips that search and the transpilation is reproducible.

`direct_qubit_mapping`

Type: `bool`

Default value: False

Map virtual qubits directly to physical num_qubits

`job_tags`

Type: `List[str]`

Default value: None

Custom tags for job tracking

`preprocessing_level`

Type: `int`

Default value: 0

Problem preprocessing intensity (0-3).

Preprocessing Levels (0-3): Specially important for larger problems that cannot currently fit on the coherence times of the hardware. Higher preprocessing levels achieve shallower circuit depths by approximations in the problem transpilation:

Level 0: Exact, longer circuits
Level 1: Good balance between accuracy and approximation, cutting out only the gates with angles in the lowest 10th percentile
Level 2: Slightly higher approximation, cutting out the gates with angles in the lowest 20th percentile and using approximation_degree=0.95 in the transpilation
Level 3: Maximum approximation level, cutting out the gates in the lowest 30th percentile and using approximation_degree=0.90 in the transpilation

`postprocessing_level`

Type: `int`

Default value: 2

Solution refinement level (0-2).

Postprocessing Levels (0-2): Control how much classical optimization, compensating for bit-flip errors with different number of greedy passes of a local search:

Level 0: 1 pass
Level 1: 2 passes
Level 2: 3 passes

`transpilation_level`

Type: `int`

Default value: 2

Transpilation method (1-3).

Transpilation levels (1-3): The level selects the transpilation method.

Level 1: Standard Qiskit transpiler.
Level 2 (default): Improved transpiler that searches over 15 transpiler seeds and keeps the best circuit. If you set seed_transpiler, the function skips the search.
Level 3: Line routing with the swap strategy for a linear coupling map that is described in Section 2.2.1 of Weidenfeller et al. Line routing follows a fixed swap schedule, so its circuit depth grows linearly with the number of variables. For densely connected problems, line routing typically produces shallower circuits than levels 1 and 2 and transpiles faster. Level 3 supports at most 127 variables on Heron r2 and r3 processors, 112 variables on Heron r1, and 120 variables on Nighthawk.

Version 3.0.0 removed levels 0, 4, and 5. A job that requests one of them fails with error 1221.

`transpilation_only`

Type: `bool`

Default value: False

Available for users who want to analyze circuit optimization without running the full quantum algorithm execution. Useful for circuit analysis, depth optimization studies, and understanding transpilation effects before committing to full execution.

Output

Type: `Dict[str, Any]`

Solution and metadata. Structure varies based on the transpilation_only option.

Result dictionary

The result dictionary structure depends on the execution mode:

`solution`

Type: `Dict[str, int]`

The sorted mapped solution where keys are variable indices (as strings) sorted numerically and values are the corresponding variable values (1/-1 for spin problems, 1/0 for binary problems).

Mode: Standard
Example: {'0': -1, '1': -1, '2': -1, '3': 1, '4': 1}

`solution_info`

Type: `Dict[str, Any]`

Detailed information about the solution.

Mode: Standard
Example: {'bitstring': '11100', 'cost': -13.8, 'seed_transpiler': 42, 'mapping': {0: 0, 1: 1, 2: 2, 3: 3, 4: 4}}
Standard execution: When the optional parameter transpilation_only=False, see the dictionary that follows.

`bitstring`

Type: `str`

The raw bitstring representation of the solution.

`cost`

Type: `float`

The cost/energy value associated with the solution.

`seed_transpiler`

Type: `int`

The random seed used for the transpiler that produced this result.

`mapping`

Type: `Dict[int, int]`

The original qubit-to-variable mapping used in the computation.

`qpu_time`

Type: `float`, optional

The QPU execution time in seconds.

Variable mapping notes

The solution dictionary is obtained from the solution bitstring, using the mapping object for indexing the variables.
When problem_type=spin we use the assignment $1 \rightarrow -1, \quad 0 \rightarrow 1$ .
Keys in the solution dictionary are variable indices sorted numerically as strings.

`prob_type`

Type: `str`

The type of optimization problem (spin or binary)

Mode: Standard
Example: 'spin'

`transpilation_info`

Type: `Dict[str, Any]`

Circuit analysis and transpilation details.

Mode: Transpile-only
Example: {'best_seed': 42, 'transpilation_time_seconds': 50.06, 'transpiled_circuit': {'depth': 576, 'gate_count': 4177, 'num_qubits': 156, 'width': 176, 'operations': {'sx': 1325, 'rx': 891, 'cz': 783, 'rz': 650, 'rzz': 466, 'x': 42, 'measure': 20}}}
Transpilation analysis: When the optional parameter transpilation_only=True, see the dictionary that follows:

`best_seed`

Type: `int`

The optimal seed found for transpilation.

`transpilation_time_seconds`

Type: `float`

Time taken for transpilation process.

`transpiled_circuit`

Type: `Dict`

Circuit analysis containing the following:

depth

Type: `int`

Circuit depth (number of layers)

gate_count

Type: `int`

Total number of gates in the circuit.

num_qubits

Type: `int`

Number of qubits used.

width

Type: `int`

Circuit width.

operations

Type: `Dict[str, int]`

Count of each gate type used.

Error handling

Caution

4600: The function_size is too small for the problem. The job fails, and the error message names the size to use.
4601: The function_size is larger than the problem needs. The job runs normally and records an advisory event that you can read with job.events().
1221: An input is not valid, such as a transpilation_level value outside the range 1-3. The error message names the field and the accepted values.

Was this page helpful?

Report a bug, typo, or request content on GitHub.