--- title: Kipu Quantum Iskay Quantum Optimizer API reference description: API reference for Iskay Quantum Optimizer, a Qiskit Function by Kipu Quantum source: https://eu-de.quantum.cloud.ibm.com/docs/en/api/functions/kipu-optimization --- # Kipu Quantum Iskay Quantum Optimizer API reference - [**Qiskit Functions**](/docs/guides/kipu-optimization) — Qiskit Functions — pre-built tools created by partner organizations — abstract away parts of the software development workflow to simplify and accelerate utility-scale algorithm discovery and application development. Click to view the guide for this Qiskit Function. ## 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"` ### 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**: Note that `seed_transpiler` is set to `None` by default. This enables the transpiler's automatic optimization process. When `None`, the system will start a trial with multiple seeds and select the one that produces the best circuit depth, leveraging the full power of the `max_trials` parameter for each transpilation level. ##### `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: `0` Transpiler optimization trials (0-5). **Transpilation Levels (0-5)**: Control the advanced transpiler optimization trials for quantum circuit compilation. This can lead to an increase in classical overhead, and for some cases it might not change the circuit depth. The default value `2` in general leads to the smallest circuit and is relatively fast. - **Level 0**: Optimization of the decomposed DCQO circuit (layout, routing, scheduling) - **Level 1**: Optimization of `PauliEvolutionGate` and then the decomposed DCQO circuit (max\_trials=10) - **Level 2**: Optimization of `PauliEvolutionGate` and then the decomposed DCQO circuit (max\_trials=15) - **Level 3**: Optimization of `PauliEvolutionGate` and then the decomposed DCQO circuit (max\_trials=20) - **Level 4**: Optimization of `PauliEvolutionGate` and then the decomposed DCQO circuit (max\_trials=25) - **Level 5**: Optimization of `PauliEvolutionGate` and then the decomposed DCQO circuit (max\_trials=50) ##### `transpile_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. > **Transpilation level performance** > > Increasing the number of `max_trials` with higher values for [`transpilation_level`](#transpilation_level) will unavoidably increase the transpilation time, but it might not always change the final circuit - this depends heavily on the specific circuit structure and complexity. For some circuits/problems, however, the difference between 10 trials (level 1) and 50 trials (level 5) can be dramatic, so exploring these parameters might be the key to successfully finding a solution. ## Output Type: `` `Dict[str, Any]` `` Solution and metadata. Structure varies based on [`transpile_only`](#transpile_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 [`transpile_only=False`](#transpile_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 [`transpile_only=True`](#transpile_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.