Kipu Quantum Iskay Quantum Optimizer API reference

Inputs

`problem`

タイプ: 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`

タイプ: 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`

タイプ: str

Name of the backend to make the query

Required: Yes
Example: "ibm_fez"

`function_size`

タイプ: str

デフォルト値: "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

タイプ: 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`

タイプ: `int`

デフォルト値: 10000

Quantum measurements per iteration (higher = more accurate)

`num_iterations`

タイプ: `int`

デフォルト値: 10

Algorithm iterations (more iterations can improve solution quality)

`use_session`

タイプ: `bool`

デフォルト値: True

Use IBM sessions for reduced queue times

`seed_transpiler`

タイプ: `int`

デフォルト値: 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`

タイプ: `bool`

デフォルト値: False

Map virtual qubits directly to physical num_qubits

`job_tags`

タイプ: `List[str]`

デフォルト値: None

Custom tags for job tracking

`preprocessing_level`

タイプ: `int`

デフォルト値: 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`

タイプ: `int`

デフォルト値: 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`

タイプ: `int`

デフォルト値: 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`

タイプ: `bool`

デフォルト値: 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

タイプ: `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`

タイプ: `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`

タイプ: `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`

タイプ: `str`

The raw bitstring representation of the solution.

`cost`

タイプ: `float`

The cost/energy value associated with the solution.

`seed_transpiler`

タイプ: `int`

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

`mapping`

タイプ: `Dict[int, int]`

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

`qpu_time`

タイプ: `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`

タイプ: `str`

The type of optimization problem (spin or binary)

Mode: Standard
Example: 'spin'

`transpilation_info`

タイプ: `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`

タイプ: `int`

The optimal seed found for transpilation.

`transpilation_time_seconds`

タイプ: `float`

Time taken for transpilation process.

`transpiled_circuit`

タイプ: `Dict`

Circuit analysis containing the following:

depth

タイプ: `int`

Circuit depth (number of layers)

gate_count

タイプ: `int`

Total number of gates in the circuit.

num_qubits

タイプ: `int`

Number of qubits used.

width

タイプ: `int`

Circuit width.

operations

タイプ: `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.

このページは役に立ちましたか？

バグや誤字の報告、またはコンテンツの要求はGitHubで行ってください。