--- title: QkTranspiler (latest version) description: API reference for QkTranspiler in the latest version of qiskit-c source: https://quantum.cloud.ibm.com/docs/en/api/qiskit-c/qk-transpiler --- # QkTranspiler The [`qk_transpile()`](#qk_transpile "qk_transpile") function exposes Qiskit’s tranpsiler ([`qiskit.transpiler`](/docs/api/qiskit/transpiler#module-qiskit.transpiler "qiskit.transpiler")) to C. The basic functionality is using the same underlying code as the Python-space version, but the transpiler as exposed to C has more limitations than what is exposed to Python. The transpiler assumes a circuit built constructed using solely the C API and is intended to work solely in the case of a standalone C API. It will potentially not work correctly when in a mixed Python/C use case. If you’re mixing C and Python you should call the [`generate_preset_pass_manager()`](/docs/api/qiskit/qiskit.transpiler.generate_preset_pass_manager#qiskit.transpiler.generate_preset_pass_manager "qiskit.transpiler.generate_preset_pass_manager") or [`transpile()`](/docs/api/qiskit/compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") functions for those circuits. ## Data Types ### QkTranspileResult `struct QkTranspileResult` The container result object from `qk_transpile` When the transpiler successfully compiles a quantum circuit for a given target it returns the transpiled circuit and the layout. The `qk_transpile` function will write pointers to the fields in this struct when it successfully executes, you can initialize this struct with null pointers or leave them unset as the values are never read by `qk_transpile` and only written to. After calling `qk_transpile` you are responsible for calling `qk_circuit_free` and `qk_transpile_layout_free` on the members of this struct. #### QkCircuit \*circuit The compiled circuit. #### QkTranspileLayout \*layout Metadata about the initial and final virtual-to-physical layouts. ### QkTranspileOptions `struct QkTranspileOptions` The options for running the transpiler #### uint8\_t optimization\_level The optimization level to run the transpiler with. Valid values are 0, 1, 2, or 3. #### int64\_t seed The seed for the transpiler. If set to a negative number this means no seed will be set and the RNGs used in the transpiler will be seeded from system entropy. #### double approximation\_degree The approximation degree a heuristic dial where 1.0 means no approximation (up to numerical tolerance) and 0.0 means the maximum approximation. A `NAN` value indicates that approximation is allowed up to the reported error rate for an operation in the target. ### QkTranspilerStageState `struct QkTranspilerStageState` A container collecting individual attributes shared by the transpiler stages. When transpiling correctly, each individual stage writes specific attributes to this container that will be needed by other stages in sequence. If the container is not initialized, each stage will initialize a new object when necessary. > ### qk\_transpile\_state\_new > > `void qk_transpile_state_new(QkTranspilerStageState **state)` > > Create a pointer to an empty `QkTranspilerStageState` object > > #### Safety > > Behavior is undefined if `state` is not a valid pointer allocated. > > **Parameters** > > - **state** – a pointer to the allocated memory space to store the pointer in. > > ### qk\_transpile\_state\_free > > `void qk_transpile_state_free(QkTranspilerStageState *state)` > > Free a `QkTranspilerStageState` object > > #### Safety > > Behavior is undefined if `state` is not a valid, non-null pointer to a `QkTranspilerStageState`. > > **Parameters** > > - **state** – a pointer to the state to free > > ### qk\_transpile\_state\_layout > > `QkTranspileLayout *qk_transpile_state_layout(QkTranspilerStageState *state)` > > Obtains a `QkTranspileLayout` object from a `QkTranspilerStageState` object. > > This pointer is owned by the `state` object and should not be freed using `qk_transpile_layout_free`. Instead, free the original `state` object using `qk_transpile_state_free`. > > #### Safety > > Behavior is undefined if `state` is not a valid, non-null pointer to a `QkTranspilerStageState`. > > **Parameters** > > - **state** – a pointer to the state to retrieve the layout from. > > **Returns** > > a pointer to a `QkTranspileLayout` object owned by the state. > > ### qk\_transpile\_state\_layout\_set > > `void qk_transpile_state_layout_set(QkTranspilerStageState *state, QkTranspileLayout *layout)` > > Sets a `QkTranspileLayout` object as the layout for a `QkTranspilerStageState` object. > > Calling this method consumes the `QkTranspileLayout` object which means the user will not need to call `qk_transpile_layout_free`. The user should still de-allocate the space allotted for it using `free`. > > #### Safety > > Behavior is undefined if `state` is not a valid, non-null pointer to a `QkTranspilerStageState`. Behavior is undefined if `state` is not a valid pointer to a `QkTranspileLayout`. > > **Parameters** > > - **state** – a pointer to the state to set the layout for. > - **layout** – a pointer to the layout to use. May be `NULL` to unset the layout. ## Functions ### qk\_transpiler\_default\_options `QkTranspileOptions qk_transpiler_default_options(void)` Generate transpiler options defaults This function generates a [QkTranspileOptions](#structqktranspileoptions) with the default settings This currently is `optimization_level` 2, no seed, and no approximation. **Returns** A `QkTranspileOptions` object with default settings. ### qk\_transpile\_stage\_init `QkExitCode qk_transpile_stage_init(QkDag *dag, const QkTarget *target, const QkTranspileOptions *options, QkTranspilerStageState **state, char **error)` Run the preset init stage of the transpiler on a circuit The Qiskit transpiler is a quantum circuit compiler that rewrites a given input circuit to match the constraints of a QPU and optimizes the circuit for execution. This function runs the first stage of the transpiler, **init**, which runs abstract-circuit optimizations, and reduces multi-qubit operations into one- and two-qubit operations. You can refer to [Initialization stage](/docs/api/qiskit/transpiler#transpiler-preset-stage-init) for more details. This function should only be used with circuits constructed using Qiskit’s C API. It makes assumptions on the circuit only using features exposed via C, if you are in a mixed Python and C environment it is typically better to invoke the transpiler via Python. This function is multithreaded internally and will launch a thread pool with threads equal to the number of CPUs reported by the operating system by default. This will include logical cores on CPUs with simultaneous multithreading. You can tune the number of threads with the `RAYON_NUM_THREADS` environment variable. For example, setting `RAYON_NUM_THREADS=4` would limit the thread pool to 4 threads. #### Safety Behavior is undefined if `dag`, `target`, or `state`, are not valid, non-null pointers to a `QkDag`, `QkTarget`, or a `QkTranspileLayout` pointer respectively. `options` must be a valid pointer a to a `QkTranspileOptions` or `NULL`. `error` must be a valid pointer to a `char` pointer or `NULL`. The value of the inner pointer for `state` will be overwritten by this function. If the value pointed to needs to be freed this must be done outside of this function as it will not be freed by this function. **Parameters** - **dag** – A pointer to the circuit to run the transpiler on. - **target** – A pointer to the target to compile the circuit for. - **options** – A pointer to an options object that defines user options. If this is a null pointer the default values will be used. See `qk_transpile_default_options` for more details on the default values. - **state** – A pointer to a pointer to a `QkTranspilerStageState` object. On a successful execution (return code 0) a pointer to the state object created transpiler will be written to this pointer. - **error** – A pointer to a pointer with an nul terminated string with an error description. If the transpiler fails a pointer to the string with the error description will be written to this pointer. That pointer needs to be freed with `qk_str_free`. This can be a null pointer in which case the error will not be written out. **Returns** The return code for the transpiler, `QkExitCode_Success` means success and all other values indicate an error. ### qk\_transpile\_stage\_routing `QkExitCode qk_transpile_stage_routing(QkDag *dag, const QkTarget *target, const QkTranspileOptions *options, QkTranspilerStageState *state, char **error)` Run the preset routing stage of the transpiler on a circuit The Qiskit transpiler is a quantum circuit compiler that rewrites a given input circuit to match the constraints of a QPU and optimizes the circuit for execution. This function runs the third stage of the preset pass manager, **routing**, which translates all the instructions in the circuit into those supported by the target. You can refer to [Routing stage](/docs/api/qiskit/transpiler#transpiler-preset-stage-routing) for more details. This function should only be used with circuits constructed using Qiskit’s C API. It makes assumptions on the circuit only using features exposed via C, if you are in a mixed Python and C environment it is typically better to invoke the transpiler via Python. This function is multithreaded internally and will launch a thread pool with threads equal to the number of CPUs reported by the operating system by default. This will include logical cores on CPUs with simultaneous multithreading. You can tune the number of threads with the `RAYON_NUM_THREADS` environment variable. For example, setting `RAYON_NUM_THREADS=4` would limit the thread pool to 4 threads. #### Safety Behavior is undefined if `dag`, `target`, or `layout`, are not valid, non-null pointers to a `QkDag`, `QkTarget`, or a `QkTranspileLayout` pointer respectively. `options` must be a valid pointer a to a `QkTranspileOptions` or `NULL`. `error` must be a valid pointer to a `char` pointer or `NULL`. **Parameters** - **dag** – A pointer to the circuit to run the transpiler on. - **target** – A pointer to the target to compile the circuit for. - **options** – A pointer to an options object that defines user options. If this is a null pointer the default values will be used. See `qk_transpile_default_options` for more details on the default values. - **state** – A pointer to a pointer to a `QkTranspilerStageState` object containing the layout. Typically you will need to run the `qk_transpile_stage_layout` prior to this function and that will provide a `QkTranspilerStageState` object with the initial layout set. You want to take that output state from that function and use it as the input for this. If you don’t have a layout object (e.g. you ran your own layout pass). You can run `qk_transpile_layout_generate_from_mapping` to generate a trivial layout (where virtual qubit 0 in the circuit is mapped to physical qubit 0 in the target, 1->1, 2->2, etc) for the dag at it’s current state. This will enable you to generate a layout object for the routing stage if you generate your own layout. - **error** – A pointer to a pointer with an nul terminated string with an error description. If the transpiler fails a pointer to the string with the error description will be written to this pointer. That pointer needs to be freed with `qk_str_free`. This can be a null pointer in which case the error will not be written out. **Returns** The return code for the transpiler, `QkExitCode_Success` means success and all other values indicate an error. ### qk\_transpile\_stage\_optimization `QkExitCode qk_transpile_stage_optimization(QkDag *dag, const QkTarget *target, const QkTranspileOptions *options, char **error, QkTranspilerStageState *state)` Run the preset optimization stage of the transpiler on a circuit The Qiskit transpiler is a quantum circuit compiler that rewrites a given input circuit to match the constraints of a QPU and optimizes the circuit for execution. This function runs the fourth stage of the preset pass manager, **optimization**, which optimizes the circuit for the given target after the circuit has been transformed into a physical circuit. You can refer to [Optimization stage](/docs/api/qiskit/transpiler#transpiler-preset-stage-optimization) for more details. This function should only be used with circuits constructed using Qiskit’s C API. It makes assumptions on the circuit only using features exposed via C, if you are in a mixed Python and C environment it is typically better to invoke the transpiler via Python. This function is multithreaded internally and will launch a thread pool with threads equal to the number of CPUs reported by the operating system by default. This will include logical cores on CPUs with simultaneous multithreading. You can tune the number of threads with the `RAYON_NUM_THREADS` environment variable. For example, setting `RAYON_NUM_THREADS=4` would limit the thread pool to 4 threads. #### Safety Behavior is undefined if `dag` and `target` are not valid, non-null pointers to a `QkDag`, or a `QkTarget` respectively. `options` must be a valid pointer a to a `QkTranspileOptions` or `NULL`. `error` must be a valid pointer to a `char` pointer or `NULL`. **Parameters** - **dag** – A pointer to the circuit to run the transpiler on. - **target** – A pointer to the target to compile the circuit for. - **options** – A pointer to an options object that defines user options. If this is a null pointer the default values will be used. See `qk_transpile_default_options` for more details on the default values. - **error** – A pointer to a pointer with an nul terminated string with an error description. If the transpiler fails a pointer to the string with the error description will be written to this pointer. That pointer needs to be freed with `qk_str_free`. This can be a null pointer in which case the error will not be written out. - **state** – A pointer to a `QkTranspilerStageState` object contiaining the layout. Typically you will need to run the `qk_transpile_stage_layout` prior to this function and that will provide a `QkTranspileLayout` object with the initial layout set you want to take that output layout from that function and use this as the input for this. If you don’t have a layout object (e.g. you ran your own layout pass). You can run `qk_transpile_layout_generate_from_mapping` to generate a trivial layout (where virtual qubit 0 in the circuit is mapped to physical qubit 0 in the target, 1->1, 2->2, etc) for the dag at it’s current state. This will enable you to generate a layout object for the optimization stage if you generate your own layout. **Returns** The return code for the transpiler, `QkExitCode_Success` means success and all other values indicate an error. ### qk\_transpile\_stage\_translation `QkExitCode qk_transpile_stage_translation(QkDag *dag, const QkTarget *target, const QkTranspileOptions *options, char **error)` Run the preset translation stage of the transpiler on a circuit The Qiskit transpiler is a quantum circuit compiler that rewrites a given input circuit to match the constraints of a QPU and optimizes the circuit for execution. This function runs the fourth stage of the preset pass manager, **translation**, which translates all the instructions in the circuit into those supported by the target. You can refer to [Translation stage](/docs/api/qiskit/transpiler#transpiler-preset-stage-translation) for more details. This function should only be used with circuits constructed using Qiskit’s C API. It makes assumptions on the circuit only using features exposed via C, if you are in a mixed Python and C environment it is typically better to invoke the transpiler via Python. This function is multithreaded internally and will launch a thread pool with threads equal to the number of CPUs reported by the operating system by default. This will include logical cores on CPUs with simultaneous multithreading. You can tune the number of threads with the `RAYON_NUM_THREADS` environment variable. For example, setting `RAYON_NUM_THREADS=4` would limit the thread pool to 4 threads. #### Safety Behavior is undefined if `dag` and `target` are not valid, non-null pointers to a `QkDag`, `QkTarget` respectively. `options` must be a valid pointer a to a `QkTranspileOptions` or `NULL`. `error` must be a valid pointer to a `char` pointer or `NULL`. **Parameters** - **dag** – A pointer to the circuit to run the transpiler on. - **target** – A pointer to the target to compile the circuit for. - **options** – A pointer to an options object that defines user options. If this is a null pointer the default values will be used. See `qk_transpile_default_options` for more details on the default values. - **error** – A pointer to a pointer with an nul terminated string with an error description. If the transpiler fails a pointer to the string with the error description will be written to this pointer. That pointer needs to be freed with `qk_str_free`. This can be a null pointer in which case the error will not be written out. **Returns** The return code for the transpiler, `QkExitCode_Success` means success and all other values indicate an error. ### qk\_transpile\_stage\_layout `QkExitCode qk_transpile_stage_layout(QkDag *dag, const QkTarget *target, const QkTranspileOptions *options, QkTranspilerStageState **state, char **error)` Run the preset layout stage of the transpiler on a circuit The Qiskit transpiler is a quantum circuit compiler that rewrites a given input circuit to match the constraints of a QPU and optimizes the circuit for execution. This function runs the second stage of the preset pass manager **layout**, which chooses the initial mapping of virtual qubits to physical qubits, including expansion of the circuit to contain explicit ancillas. You can refer to [Layout stage](/docs/api/qiskit/transpiler#transpiler-preset-stage-layout) for more details. This function should only be used with circuits constructed using Qiskit’s C API. It makes assumptions on the circuit only using features exposed via C, if you are in a mixed Python and C environment it is typically better to invoke the transpiler via Python. This function is multithreaded internally and will launch a thread pool with threads equal to the number of CPUs reported by the operating system by default. This will include logical cores on CPUs with simultaneous multithreading. You can tune the number of threads with the `RAYON_NUM_THREADS` environment variable. For example, setting `RAYON_NUM_THREADS=4` would limit the thread pool to 4 threads. #### Safety Behavior is undefined if `dag` or `target`, are not valid, non-null pointers to a `QkDag`, or a `QkTarget` respectively. Behavior is also undefined if `layout` is not a valid, aligned, pointer to a pointer to a `QkTranspileLayout` or a pointer to a `NULL` pointer. `options` must be a valid pointer a to a `QkTranspileOptions` or `NULL`. `error` must be a valid pointer to a `char` pointer or `NULL`. **Parameters** - **dag** – A pointer to the circuit to run the transpiler on. - **target** – A pointer to the target to compile the circuit for. - **options** – A pointer to an options object that defines user options. If this is a null pointer the default values will be used. See `qk_transpile_default_options` for more details on the default values. - **state** – A pointer to a pointer to a `QkTranspilerStageState` object. On a successful execution (return code 0) the layout object created by the transpiler will be written to the state object in this pointer. The inner pointer for this can be null if there is no existing state or layout object. Typically if you run `qk_transpile_stage_init` you would take the output state from that function and use its layout as the input for this. But if you don’t have a layout, the inner pointer can be null and a new `QkTranspilerStageState`, with a layout, will be allocated and that pointer will be set for the inner value of the layout here. - **error** – A pointer to a pointer with an nul terminated string with an error description. If the transpiler fails a pointer to the string with the error description will be written to this pointer. That pointer needs to be freed with `qk_str_free`. This can be a null pointer in which case the error will not be written out. **Returns** The return code for the transpiler, `QkExitCode_Success` means success and all other values indicate an error. ### qk\_transpile `QkExitCode qk_transpile(const QkCircuit *qc, const QkTarget *target, const QkTranspileOptions *options, QkTranspileResult *result, char **error)` Transpile a single circuit. The Qiskit transpiler is a quantum circuit compiler that rewrites a given input circuit to match the constraints of a QPU and optimizes the circuit for execution. This function should only be used with circuits constructed using Qiskit’s C API. It makes assumptions on the circuit only using features exposed via C, if you are in a mixed Python and C environment it is typically better to invoke the transpiler via Python. This function is multithreaded internally and will launch a thread pool with threads equal to the number of CPUs reported by the operating system by default. This will include logical cores on CPUs with simultaneous multithreading. You can tune the number of threads with the `RAYON_NUM_THREADS` environment variable. For example, setting `RAYON_NUM_THREADS=4` would limit the thread pool to 4 threads. #### Safety Behavior is undefined if `circuit`, `target`, or `result`, are not valid, non-null pointers to a `QkCircuit`, `QkTarget`, or `QkTranspileResult` respectively. `options` must be a valid pointer a to a `QkTranspileOptions` or `NULL`. `error` must be a valid pointer to a `char` pointer or `NULL`. **Parameters** - **qc** – A pointer to the circuit to run the transpiler on. - **target** – A pointer to the target to compile the circuit for. - **options** – A pointer to an options object that defines user options. If this is a null pointer the default values will be used. See `qk_transpile_default_options` for more details on the default values. - **result** – A pointer to the memory location of the transpiler result. On a successful execution (return code 0) the output of the transpiler will be written to the pointer. The members of the result struct are owned by the caller and you are responsible for freeing the members using the respective free functions. - **error** – A pointer to a pointer with an nul terminated string with an error description. If the transpiler fails a pointer to the string with the error description will be written to this pointer. That pointer needs to be freed with `qk_str_free`. This can be a null pointer in which case the error will not be written out. **Returns** The return code for the transpiler, `QkExitCode_Success` means success and all other values indicate an error.