--- title: QkTarget (v2.1) description: API reference for QkTarget in qiskit-c v2.1 source: https://eu-de.quantum.cloud.ibm.com/docs/en/api/qiskit-c/2.1/qk-target --- # QkTarget ```c typedef struct QkTarget QkTarget ``` A mapping of instructions and properties representing the particular constraints of a backend. Its purpose is to provide the compiler with information that allows it to compile an input circuit into another that is optimized taking in consideration the `QkTarget`’s specifications. This structure represents a low level interface to the main Target data structure in Rust, which represents the base class for its Python counterpart, [`Target`](/docs/api/qiskit/2.1/qiskit.transpiler.Target#qiskit.transpiler.Target "qiskit.transpiler.Target"). Here’s an example of how this structure works: ```c #include #include // Create a Target with 2 qubits QkTarget *target = qk_target_new(2); // Create an entry for a CX Gate with qargs (0, 1) and properties // duration = 0.0123 // error = NaN uint32_t qargs[2] = {0, 1}; QkTargetEntry *entry = qk_target_entry_new(QkGate_CX); qk_target_entry_add_property(entry, qargs, 2, 0.0123, NAN); // Add a CX Gate to the target qk_target_add_instruction(target, entry); // Add a global H gate qk_target_add_instruction(target, qk_target_entry_new(QkGate_H)); // Free the created target. qk_target_free(target); ``` The Target C API currently only supports additions of `QkGate` instances with either no parameters or fixed parameters. Support for regular parameters will be added in the future. The functionality will keep expanding over time as we improve our Rust data model capabilities. ## Functions ### qk\_target\_new `QkTarget *qk_target_new(uint32_t num_qubits)` Construct a new `QkTarget` with the given number of qubits. The number of qubits is bound to change if an instruction is added with properties that apply to a collection of qargs in which any index is higher than the specified number of qubits #### Example ```c QkTarget *target = qk_target_new(5); ``` **Parameters** **num\_qubits** – The number of qubits the `QkTarget` will explicitly support. **Returns** A pointer to the new `QkTarget` ### qk\_target\_num\_qubits `uint32_t qk_target_num_qubits(const QkTarget *target)` Returns the number of qubits of this `QkTarget`. #### Example ```c QkTarget *target = qk_target_new(5); uint32_t num_qubits = qk_target_num_qubits(target); ``` #### Safety Behavior is undefined if `QkTarget` is not a valid, non-null pointer to a `QkTarget`. **Parameters** **target** – A pointer to the `QkTarget`. **Returns** The number of qubits this target can use. ### qk\_target\_dt `double qk_target_dt(const QkTarget *target)` Returns the dt value of this `QkTarget`. #### Example ```c QkTarget *target = qk_target_new(5); qk_target_set_dt(target, 10e-9); double dt = qk_target_dt(target); ``` #### Safety Behavior is undefined if `QkTarget` is not a valid, non-null pointer to a `QkTarget`. **Parameters** **target** – A pointer to the `QkTarget`. **Returns** The dt value of this `QkTarget` or `NAN` if not assigned. ### qk\_target\_granularity `uint32_t qk_target_granularity(const QkTarget *target)` Returns the granularity value of this `QkTarget`. #### Example ```c QkTarget *target = qk_target_new(5); // The value defaults to 1 uint32_t granularity = qk_target_granularity(target); ``` #### Safety Behavior is undefined if `QkTarget` is not a valid, non-null pointer to a `QkTarget`. **Parameters** **target** – A pointer to the `QkTarget`. **Returns** The `granularity` value of this `QkTarget`. ### qk\_target\_min\_length `uint32_t qk_target_min_length(const QkTarget *target)` Returns the `min_length` value of this `QkTarget`. #### Example ```c QkTarget *target = qk_target_new(5); // The value defaults to 1 size_t min_length = qk_target_min_length(target); ``` #### Safety Behavior is undefined if `QkTarget` is not a valid, non-null pointer to a `QkTarget`. **Parameters** **target** – A pointer to the `QkTarget`. **Returns** The `min_length` value of this `QkTarget`. ### qk\_target\_pulse\_alignment `uint32_t qk_target_pulse_alignment(const QkTarget *target)` Returns the `pulse_alignment` value of this `QkTarget`. #### Example ```c QkTarget *target = qk_target_new(5); // The value defaults to 1 uint32_t pulse_alignment = qk_target_pulse_alignment(target); ``` #### Safety Behavior is undefined if `QkTarget` is not a valid, non-null pointer to a `QkTarget`. **Parameters** **target** – A pointer to the `QkTarget`. **Returns** The `pulse_alignment` value of this `QkTarget`. ### qk\_target\_acquire\_alignment `uint32_t qk_target_acquire_alignment(const QkTarget *target)` Returns the `acquire_alignment` value of this `QkTarget`. #### Example ```c QkTarget *target = qk_target_new(5); // The value defaults to 0 uint32_t acquire_alignment = qk_target_pulse_alignment(target); ``` #### Safety Behavior is undefined if `QkTarget` is not a valid, non-null pointer to a `QkTarget`. **Parameters** **target** – A pointer to the `QkTarget`. **Returns** The `acquire_alignment` value of this `QkTarget`. ### qk\_target\_set\_dt `QkExitCode qk_target_set_dt(QkTarget *target, double dt)` Sets the dt value of this `QkTarget`. #### Example ```c QkTarget *target = qk_target_new(5); double dt = qk_target_set_dt(target, 10e-9); ``` #### Safety Behavior is undefined if `QkTarget` is not a valid, non-null pointer to a `QkTarget`. **Parameters** - **target** – A pointer to the `QkTarget`. - **dt** – The `dt` value for the system time resolution of input. **Returns** `QkExitCode` specifying if the operation was successful. ### qk\_target\_set\_granularity `QkExitCode qk_target_set_granularity(QkTarget *target, uint32_t granularity)` Sets the `granularity` value of this `QkTarget`. #### Example ```c QkTarget *target = qk_target_new(5); // The value defaults to 1 qk_target_set_granularity(target, 2); ``` #### Safety Behavior is undefined if `QkTarget` is not a valid, non-null pointer to a `QkTarget`. **Parameters** - **target** – A pointer to the `QkTarget`. - **granularity** – The value for the minimum pulse gate resolution in units of `dt`. **Returns** `QkExitCode` specifying if the operation was successful. ### qk\_target\_set\_min\_length `QkExitCode qk_target_set_min_length(QkTarget *target, uint32_t min_length)` Sets the `min_length` value of this `QkTarget`. #### Example ```c QkTarget *target = qk_target_new(5); // The value defaults to 1 qk_target_set_min_length(target, 3); ``` #### Safety Behavior is undefined if `QkTarget` is not a valid, non-null pointer to a `QkTarget`. **Parameters** - **target** – A pointer to the `QkTarget`. - **min\_length** – The minimum pulse gate length value in units of `dt`. **Returns** `QkExitCode` specifying if the operation was successful. ### qk\_target\_set\_pulse\_alignment `QkExitCode qk_target_set_pulse_alignment(QkTarget *target, uint32_t pulse_alignment)` Returns the `pulse_alignment` value of this `QkTarget`. #### Example ```c QkTarget *target = qk_target_new(5); // The value defaults to 1 qk_target_set_pulse_alignment(target, 4); ``` #### Safety Behavior is undefined if `QkTarget` is not a valid, non-null pointer to a `QkTarget`. **Parameters** - **target** – A pointer to the `QkTarget`. - **pulse\_alignment** – value representing a time resolution of gate. **Returns** `QkExitCode` specifying if the operation was successful. ### qk\_target\_set\_acquire\_alignment `QkExitCode qk_target_set_acquire_alignment(QkTarget *target, uint32_t acquire_alignment)` Sets the `acquire_alignment` value of this `QkTarget`. #### Example ```c QkTarget *target = qk_target_new(5); // The value defaults to 0 qk_target_set_acquire_alignment(target, 5); ``` #### Safety Behavior is undefined if `QkTarget` is not a valid, non-null pointer to a `QkTarget`. **Parameters** - **target** – A pointer to the `QkTarget`. - **acquire\_alignment** – value representing a time resolution of measure instruction starting time. **Returns** `QkExitCode` specifying if the operation was successful. ### qk\_target\_copy `QkTarget *qk_target_copy(QkTarget *target)` Creates a copy of the `QkTarget`. #### Example ```c QkTarget *target = qk_target_new(5); QkTargetEntry *entry = qk_target_entry_new(QkGate_CX); uint32_t qargs[2] = {0, 1}; qk_target_entry_add_property(entry, qargs, 2, 0.0, 0.1); QkExitCode result = qk_target_add_instruction(target, entry); QkTarget *copied = qk_target_copy(target); ``` #### Safety Behavior is undefined if `QkTarget` is not a valid, non-null pointer to a `QkTarget`. **Parameters** **target** – A pointer to the `QkTarget` to copy. **Returns** A pointer to the new copy of the `QkTarget`. ### qk\_target\_free `void qk_target_free(QkTarget *target)` Free the `QkTarget`. #### Example ```c QkTarget *target = qk_target_new(5); qk_target_free(target); ``` #### Safety Behavior is undefined if `QkTarget` is not a valid, non-null pointer to a `QkTarget`. **Parameters** **target** – A pointer to the `QkTarget` to free. ### qk\_target\_add\_instruction `QkExitCode qk_target_add_instruction(QkTarget *target, QkTargetEntry *target_entry)` Adds a gate to the `QkTarget` through a `QkTargetEntry`. #### Example ```c QkTarget *target = qk_target_new(5); QkTargetEntry *entry = qk_target_entry_new(QkGate_CX); uint32_t qargs[2] = {0, 1}; qk_target_entry_add_property(entry, qargs, 2, 0.0, 0.1); QkExitCode result = qk_target_add_instruction(target, entry); ``` #### Safety Behavior is undefined if `QkTarget` is not a valid, non-null pointer to a `QkTarget`. Behavior is undefined if `entry` is not a valid, non-null pointer to a `QkTargetEntry`. **Parameters** - **target** – A pointer to the `QkTarget`. - **target\_entry** – A pointer to the `QkTargetEntry`. The pointer gets freed when added to the `QkTarget`. **Returns** `QkExitCode` specifying if the operation was successful. ### qk\_target\_update\_property `QkExitCode qk_target_update_property(QkTarget *target, QkGate instruction, uint32_t *qargs, uint32_t num_qubits, double duration, double error)` Modifies the properties of a gate in the `QkTarget`. #### Example ```c QkTarget *target = qk_target_new(5); double params[1] = {3.1415}; QkTargetEntry *entry = qk_target_entry_new_fixed(QkGate_CRX, params); uint32_t qargs[2] = {0, 1}; qk_target_entry_add_property(entry, qargs, 2, 0.0, 0.1); qk_target_add_instruction(target, entry); qk_target_update_property(target, QkGate_CRX, qargs, 2, 0.0012, 1.1); ``` #### Safety Behavior is undefined if `QkTarget` is not a valid, non-null pointer to a `QkTarget`. The `qargs` type is expected to be a pointer to an array of `uint32_t` where the length matches is specified by `num_qubits` and has to match the expectation of the gate. If the array is insufficiently long the behavior of this function is undefined as this will read outside the bounds of the array. It can be a null pointer if there are no qubits for a given gate. You can check `qk_gate_num_qubits` to determine how many qubits are required for a given gate. **Parameters** - **target** – A pointer to the `QkTarget`. - **instruction** – The instruction to modify. - **qargs** – The pointer to the array of `uint32_t` values to use as qargs. Can be `NULL` if global. - **num\_qubits** – The number of qubits of the instruction.. - **duration** – The instruction’s duration in seconds on the specific set of qubits. - **error** – The instruction’s average error rate on the specific set of qubits. **Returns** `QkExitCode` specifying if the operation was successful. ### qk\_target\_num\_instructions `uintptr_t qk_target_num_instructions(const QkTarget *target)` Returns the number of instructions tracked by a `QkTarget`. #### Example ```c QkTarget *target = qk_target_new(5); QkTargetEntry *target_entry = qk_target_entry_new(QkGate_H); qk_target_add_instruction(target, target_entry); size_t num_instructions = qk_target_num_instructions(target); ``` #### Safety Behavior is undefined if `QkTarget` is not a valid, non-null pointer to a `QkTarget`. **Parameters** **target** – A pointer to the `QkTarget`. **Returns** The length of the target.