Skip to main contentIBM Quantum Documentation Mirror

QkTranspiler

The qk_transpile() function lets C access the Qiskit tranpsiler (qiskit.transpiler). 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.

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.

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.

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`. errormust be a valid pointer to acharpointer orNULL``.

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.