QkTranspiler

The qk_transpile() function exposes Qiskit’s tranpsiler (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() or 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 heurstic 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 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 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 for more details.

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 for more details.

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 for more details.

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 for more details.

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.

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.

Was this page helpful?

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