--- title: QkTargetEntry (latest version) description: API reference for QkTargetEntry in the latest version of qiskit-c source: https://quantum.cloud.ibm.com/docs/en/api/qiskit-c/qk-target-entry --- # QkTargetEntry ```c typedef struct QkTargetEntry QkTargetEntry ``` A mapping of qubit arguments and properties representing gate map of the Target. This feature is used due to not having valid native mappings available from C. Here’s an example of how this structure works: ```c #include #include // Create a Target Entry for a CX Gate QkTargetEntry *entry = qk_target_entry_new(QkGate_CX); // Set a name for the entry qk_target_entry_set_name(entry, "cx_gate"); // Add mapping between (0,1) and properties duration of 10e-9 and unknown error. uint32_t qargs[2] = {0, 1}; qk_target_entry_add_property(entry, qargs, 2, 10e-9, NAN); // Add mapping between Global, and no set duration NAN and error of 0.003) qk_target_entry_add_property(entry, NULL, 0, NAN, 0.003); ``` ## Functions ### qk\_target\_entry\_new `QkTargetEntry *qk_target_entry_new(QkGate operation)` Creates an entry to the `QkTarget` based on a `QkGate` instance. #### Example ```c QkTargetEntry *had_entry = qk_target_entry_new(QkGate_H); ``` **Parameters** - **operation** – The `QkGate` whose properties this target entry defines. If the `QkGate` takes parameters (which can be checked with `qk_gate_num_params`) it will be added as a an instruction on the target which accepts any parameter value. If the gate only accepts a fixed parameter value you can use `qk_target_entry_new_fixed` instead. **Returns** A pointer to the new `QkTargetEntry`. ### qk\_target\_entry\_new\_measure `QkTargetEntry *qk_target_entry_new_measure(void)` Creates a new entry for adding a measurement instruction to a `QkTarget`. #### Example ```c QkTargetEntry *entry = qk_target_entry_new_measure(); // Add fixed duration and error rates from qubits at index 0 to 4. for (uint32_t i = 0; i < 5; i++) { // Measure is a single qubit instruction uint32_t qargs[1] = {i}; qk_target_entry_add_property(entry, qargs, 1, 1.928e-10, 7.9829e-11); } // Add the entry to a target with 5 qubits QkTarget *measure_target = qk_target_new(5); qk_target_add_instruction(measure_target, entry); ``` **Returns** A pointer to the new `QkTargetEntry` for a measurement instruction. ### qk\_target\_entry\_new\_reset `QkTargetEntry *qk_target_entry_new_reset(void)` Creates a new entry for adding a reset instruction to a `QkTarget`. #### Example ```c QkTargetEntry *entry = qk_target_entry_new_reset(); // Add fixed duration and error rates from qubits at index 0 to 2. for (uint32_t i = 0; i < 3; i++) { // Reset is a single qubit instruction uint32_t qargs[1] = {i}; qk_target_entry_add_property(entry, qargs, 1, 1.2e-11, 5.9e-13); } // Add the entry to a target with 3 qubits QkTarget *reset_target = qk_target_new(3); qk_target_add_instruction(reset_target, entry); ``` **Returns** A pointer to the new `QkTargetEntry` for a reset instruction. ### qk\_target\_entry\_new\_fixed `QkTargetEntry *qk_target_entry_new_fixed(QkGate operation, double *params, const char *name)` Creates an entry in the `QkTarget` based on a `QkGate` instance with no parameters. #### Example ```c double crx_params[1] = {3.14}; QkTargetEntry *entry = qk_target_entry_new_fixed(QkGate_CRX, crx_params, "crx_fixed")"; ``` #### Safety The `params` type is expected to be a pointer to an array of `double` where the length matches the expectations of the `QkGate`. 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 params for a given gate. You can check `qk_gate_num_params` to determine how many qubits are required for a given gate. The `name` pointer is expected to be either a C string comprising of valid UTF-8 characters or a null pointer. > **Note** > > Adding a `QkGate` with regular parameters is not currently supported. **Parameters** - **operation** – The `QkGate` whose properties this target entry defines. - **params** – A pointer to the parameters that the instruction is calibrated for. - **name** – An optional name for the instruction in the target. If a null pointer is provided, the entry will use the operation’s default name. **Returns** A pointer to the new `QkTargetEntry`. ### qk\_target\_entry\_num\_properties `size_t qk_target_entry_num_properties(const QkTargetEntry *entry)` Retrieves the number of properties stored in the target entry. #### Example ```c // Create an entry for an H gate QkTargetEntry *entry = qk_target_entry_new(QkGate_H); size_t props_size = qk_target_entry_num_properties(entry); ``` #### Safety The behavior is undefined if `entry` is not a valid, non-null pointer to a `QkTargetEntry` object. **Parameters** - **entry** – The pointer to the mapping object. **Returns** The number of properties in the `QkTargetEntry`. ### qk\_target\_entry\_free `void qk_target_entry_free(QkTargetEntry *entry)` Frees the entry. #### Example ```c QkTargetEntry *entry = qk_target_entry_new(QkGate_H); qk_target_entry_free(entry); ``` #### Safety The behavior is undefined if `entry` is not a valid, non-null pointer to a `QkTargetEntry` object. > **Note** > > An entry pointer will be freed when added to a `QkTarget` via `qk_target_add_instruction`, this function is only meant to be used alternatively if an entry is never added to a `QkTarget` instance. **Parameters** - **entry** – The pointer to the mapping object to be freed. ### qk\_target\_entry\_add\_property `QkExitCode qk_target_entry_add_property(QkTargetEntry *entry, uint32_t *qargs, uint32_t num_qubits, double duration, double error)` Adds an instruction property instance based on its assigned qargs. #### Example ```c 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); ``` #### Safety The behavior is undefined if `entry` is not a valid, non-null pointer to a `QkTargetEntry` object. **Parameters** - **entry** – The pointer to the entry object. - **qargs** – A pointer to the array of `uint32_t` qubit indices to add the gate on, can be a null pointer to check for global properties. - **num\_qubits** – The length of the qargs array. - **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** An exit code. ### qk\_target\_entry\_set\_name `QkExitCode qk_target_entry_set_name(QkTargetEntry *entry, const char *name)` Sets a custom name to the target entry. #### Example ```c QkTargetEntry *entry = qk_target_entry_new(QkGate_CX); qk_target_entry_set_name(entry, "cx_gate"); ``` #### Safety The behavior is undefined if `entry` is not a valid, non-null pointer to a `QkTargetEntry` object. The `name` pointer is expected to be either a C string comprising of valid UTF-8 characters or a null pointer. **Parameters** - **entry** – The pointer to the entry object. - **name** – The name to be set for the target entry. **Returns** `QkExitCode` specifying if the operation was successful.