--- title: Kipu Quantum Iskay Quantum Optimizer API reference description: API reference for Iskay Quantum Optimizer by Kipu Quantum source: https://quantum.cloud.ibm.com/docs/en/functions/kipu-optimization/api-reference --- # 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](#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](#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](/docs/functions/kipu-optimization#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](#kipu-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 > > where > > - 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: > > - 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](#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`](#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.](https://arxiv.org/abs/2202.03459) 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`](#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`](#transpilation_only), 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`](#transpilation_only), 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`](#function_size) is too small for the problem. The job fails, and the error message names the size to use. > - `4601`: The [`function_size`](#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`](#transpilation_level) value outside the range 1-3. The error message names the field and the accepted values.