diff --git a/docs/api/qiskit-c/dev/_toc.json b/docs/api/qiskit-c/dev/_toc.json index 241fb0a4b78..6045eb57ae1 100644 --- a/docs/api/qiskit-c/dev/_toc.json +++ b/docs/api/qiskit-c/dev/_toc.json @@ -33,6 +33,10 @@ "title": "QkExitCode", "url": "/docs/api/qiskit-c/dev/qk-exit-code" }, + { + "title": "QkNeighbors", + "url": "/docs/api/qiskit-c/dev/qk-neighbors" + }, { "title": "QkObs", "url": "/docs/api/qiskit-c/dev/qk-obs" diff --git a/docs/api/qiskit-c/dev/index.mdx b/docs/api/qiskit-c/dev/index.mdx index b69b6de0c8d..8d51c88b38f 100644 --- a/docs/api/qiskit-c/dev/index.mdx +++ b/docs/api/qiskit-c/dev/index.mdx @@ -42,6 +42,7 @@ Using the transpiler from the C API is intended to only cover circuits created s * [QkTranspiler](qk-transpiler) * [QkTarget](qk-target) * [QkTargetEntry](qk-target-entry) +* [QkNeighbors](qk-neighbors) * [QkTranspileLayout](qk-transpile-layout) * [Transpiler Passes](qk-transpiler-passes) * [VF2 compiler-pass objects](qk-vf-2-layout) diff --git a/docs/api/qiskit-c/dev/qk-bit-term.mdx b/docs/api/qiskit-c/dev/qk-bit-term.mdx index ee408ad70e7..cf20c05de3c 100644 --- a/docs/api/qiskit-c/dev/qk-bit-term.mdx +++ b/docs/api/qiskit-c/dev/qk-bit-term.mdx @@ -86,35 +86,33 @@ The numeric structure of these is that they are all four-bit values of which the ## Functions -### qk\_bitterm\_label +**uint8\_t qk\_bitterm\_label(QkBitTerm bit\_term)** - - Get the label for a bit term. +Get the label for a bit term. - + - #### Example +### Example - ```c - QkBitTerm bit_term = QkBitTerm_Y; - // cast the uint8_t to char - char label = qk_bitterm_label(bit_term); - ``` +```c +QkBitTerm bit_term = QkBitTerm_Y; +// cast the uint8_t to char +char label = qk_bitterm_label(bit_term); +``` - + - #### Safety +### Safety - + - The behavior is undefined if `bit_term` is not a valid `uint8_t` value of a `QkBitTerm`. +The behavior is undefined if `bit_term` is not a valid `uint8_t` value of a `QkBitTerm`. - **Parameters** +**Parameters** - **bit\_term** – The bit term. +* **bit\_term** – The bit term. - **Returns** +**Returns** - The label as `uint8_t`, which can be cast to `char` to obtain the character. - +The label as `uint8_t`, which can be cast to `char` to obtain the character. diff --git a/docs/api/qiskit-c/dev/qk-circuit-library.mdx b/docs/api/qiskit-c/dev/qk-circuit-library.mdx index a079c43e182..9dcf1436b2e 100644 --- a/docs/api/qiskit-c/dev/qk-circuit-library.mdx +++ b/docs/api/qiskit-c/dev/qk-circuit-library.mdx @@ -12,33 +12,31 @@ The Qiskit circuit library contains functions for building commonly used quantum ## Functions -### qk\_circuit\_library\_quantum\_volume +**QkCircuit \*qk\_circuit\_library\_quantum\_volume(uint32\_t num\_qubits, size\_t depth, int64\_t seed)** - - Generate a Quantum Volume model circuit +Generate a Quantum Volume model circuit - The model circuits are random instances of circuits used to measure the Quantum Volume metric, as introduced in \[1]. The model circuits consist of layers of Haar random elements of SU(4) applied between corresponding pairs of qubits in a random bipartition. +The model circuits are random instances of circuits used to measure the Quantum Volume metric, as introduced in \[1]. The model circuits consist of layers of Haar random elements of SU(4) applied between corresponding pairs of qubits in a random bipartition. - This function is multithreaded and will launch a thread pool with threads equal to the number of CPUs by default. 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. +This function is multithreaded and will launch a thread pool with threads equal to the number of CPUs by default. 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. - \[1] A. Cross et al. Validating quantum computers using randomized model circuits, Phys. Rev. A 100, 032328 (2019). [arXiv:1811.12926](https://arxiv.org/abs/1811.12926) +\[1] A. Cross et al. Validating quantum computers using randomized model circuits, Phys. Rev. A 100, 032328 (2019). [arXiv:1811.12926](https://arxiv.org/abs/1811.12926) - + - #### Parameters +### Parameters - + - * `num_qubits`: The number qubits to use for the generated circuit. - * `depth`: The number of layers for the generated circuit. - * `seed`: An RNG seed used for generating the random SU(4) matrices used in the output circuit. If the provided number is negative the seed used will be soured from system entropy. +* `num_qubits`: The number qubits to use for the generated circuit. +* `depth`: The number of layers for the generated circuit. +* `seed`: An RNG seed used for generating the random SU(4) matrices used in the output circuit. If the provided number is negative the seed used will be soured from system entropy. - + - #### Example +### Example - ```c - QkCircuit *qc = qk_circuit_library_quantum_volume(10, 10, -1) - ``` - +```c +QkCircuit *qc = qk_circuit_library_quantum_volume(10, 10, -1) +``` diff --git a/docs/api/qiskit-c/dev/qk-circuit.mdx b/docs/api/qiskit-c/dev/qk-circuit.mdx index 512f3d25265..a53e6061473 100644 --- a/docs/api/qiskit-c/dev/qk-circuit.mdx +++ b/docs/api/qiskit-c/dev/qk-circuit.mdx @@ -39,779 +39,697 @@ The circuit C API currently only supports creating circuits that contain operati ## Data Types -### QkOpCount +**struct QkOpCount** - - An individual operation count represented by the operation name and the number of instances in the circuit. +An individual operation count represented by the operation name and the number of instances in the circuit. - #### const char \*name +**const char \*name** - - A nul terminated string representing the operation name - +A nul terminated string representing the operation name - #### size\_t count +**size\_t count** - - The number of instances of this operation in the circuit - - +The number of instances of this operation in the circuit -### QkOpCounts +**struct QkOpCounts** - - An array of `OpCount` objects representing the total counts of all the operation types in a circuit. +An array of `OpCount` objects representing the total counts of all the operation types in a circuit. - #### QkOpCount \*data +**[QkOpCount](#c.QkOpCount "QkOpCount") \*data** - - A array of size `len` containing `OpCount` objects for each type of operation in the circuit - +A array of size `len` containing `OpCount` objects for each type of operation in the circuit - #### size\_t len +**size\_t len** - - The number of elements in `data` - - +The number of elements in `data` -### QkCircuitInstruction +**struct QkCircuitInstruction** - - A circuit instruction representation. +A circuit instruction representation. - This struct represents the data contained in an individual instruction in a `QkCircuit`. It is not a pointer to the underlying object, but contains a copy of the properties of the instruction for inspection. +This struct represents the data contained in an individual instruction in a `QkCircuit`. It is not a pointer to the underlying object, but contains a copy of the properties of the instruction for inspection. - #### char \*name +**char \*name** - - The instruction name - +The instruction name - #### uint32\_t \*qubits +**uint32\_t \*qubits** - - A pointer to an array of qubit indices this instruction operates on. - +A pointer to an array of qubit indices this instruction operates on. - #### uint32\_t \*clbits +**uint32\_t \*clbits** - - A pointer to an array of clbit indices this instruction operates on. - +A pointer to an array of clbit indices this instruction operates on. - #### double \*params +**double \*params** - - A pointer to an array of parameter values for this instruction. - +A pointer to an array of parameter values for this instruction. - #### uint32\_t num\_qubits +**uint32\_t num\_qubits** - - The number of qubits for this instruction. - +The number of qubits for this instruction. - #### uint32\_t num\_clbits +**uint32\_t num\_clbits** - - The number of clbits for this instruction. - +The number of clbits for this instruction. - #### uint32\_t num\_params +**uint32\_t num\_params** - - The number of parameters for this instruction. - - +The number of parameters for this instruction. ## Functions -### QkDelayUnit +**enum QkDelayUnit** - - Units for circuit delays. +Units for circuit delays. - *Values:* +*Values:* - #### enumerator QkDelayUnit\_S +**enumerator QkDelayUnit\_S** - - Seconds. - +Seconds. - #### enumerator QkDelayUnit\_MS +**enumerator QkDelayUnit\_MS** - - Milliseconds. - +Milliseconds. - #### enumerator QkDelayUnit\_US +**enumerator QkDelayUnit\_US** - - Microseconds. - +Microseconds. - #### enumerator QkDelayUnit\_NS +**enumerator QkDelayUnit\_NS** - - Nanoseconds. - +Nanoseconds. - #### enumerator QkDelayUnit\_PS +**enumerator QkDelayUnit\_PS** - - Picoseconds. - - +Picoseconds. -### qk\_circuit\_new +**QkCircuit \*qk\_circuit\_new(uint32\_t num\_qubits, uint32\_t num\_clbits)** - - Construct a new circuit with the given number of qubits and clbits. +Construct a new circuit with the given number of qubits and clbits. - + - #### Example +### Example - ```c - QkCircuit *empty = qk_circuit_new(100, 100); - ``` +```c +QkCircuit *empty = qk_circuit_new(100, 100); +``` - **Parameters** +**Parameters** - * **num\_qubits** – The number of qubits the circuit contains. - * **num\_clbits** – The number of clbits the circuit contains. +* **num\_qubits** – The number of qubits the circuit contains. +* **num\_clbits** – The number of clbits the circuit contains. - **Returns** +**Returns** - A pointer to the created circuit. - +A pointer to the created circuit. -### qk\_circuit\_add\_quantum\_register +**void qk\_circuit\_add\_quantum\_register(QkCircuit \*circuit, const QkQuantumRegister \*reg)** - - Add a quantum register to a given quantum circuit +Add a quantum register to a given quantum circuit - + - #### Example +### Example - ```c - QkCircuit *qc = qk_circuit_new(0, 0); - QkQuantumRegister *qr = qk_quantum_register_new(1024, "my_little_register"); - qk_circuit_add_quantum_register(qc, qr); - qk_quantum_register_free(qr); - qk_circuit_free(qc); - ``` +```c +QkCircuit *qc = qk_circuit_new(0, 0); +QkQuantumRegister *qr = qk_quantum_register_new(1024, "my_little_register"); +qk_circuit_add_quantum_register(qc, qr); +qk_quantum_register_free(qr); +qk_circuit_free(qc); +``` - + - #### Safety +### Safety - + - Behavior is undefined if `circuit` is not a valid, non-null pointer to a `QkCircuit` and if `reg` is not a valid, non-null pointer to a `QkQuantumRegister`. +Behavior is undefined if `circuit` is not a valid, non-null pointer to a `QkCircuit` and if `reg` is not a valid, non-null pointer to a `QkQuantumRegister`. - **Parameters** +**Parameters** - * **circuit** – A pointer to the circuit. - * **reg** – A pointer to the quantum register - +* **circuit** – A pointer to the circuit. +* **reg** – A pointer to the quantum register -### qk\_circuit\_add\_classical\_register +**void qk\_circuit\_add\_classical\_register(QkCircuit \*circuit, const QkClassicalRegister \*reg)** - - Add a classical register to a given quantum circuit +Add a classical register to a given quantum circuit - + - #### Example +### Example - ```c - QkCircuit *qc = qk_circuit_new(0, 0); - QkClassicalRegister *cr = qk_classical_register_new(24, "my_big_register"); - qk_circuit_add_classical_register(qc, cr); - qk_classical_register_free(cr); - qk_circuit_free(qc); - ``` +```c +QkCircuit *qc = qk_circuit_new(0, 0); +QkClassicalRegister *cr = qk_classical_register_new(24, "my_big_register"); +qk_circuit_add_classical_register(qc, cr); +qk_classical_register_free(cr); +qk_circuit_free(qc); +``` - + - #### Safety +### Safety - + - Behavior is undefined if `circuit` is not a valid, non-null pointer to a `QkCircuit` and if `reg` is not a valid, non-null pointer to a `QkClassicalRegister`. +Behavior is undefined if `circuit` is not a valid, non-null pointer to a `QkCircuit` and if `reg` is not a valid, non-null pointer to a `QkClassicalRegister`. - **Parameters** +**Parameters** - * **circuit** – A pointer to the circuit. - * **reg** – A pointer to the classical register - +* **circuit** – A pointer to the circuit. +* **reg** – A pointer to the classical register -### qk\_circuit\_copy +**QkCircuit \*qk\_circuit\_copy(const QkCircuit \*circuit)** - - Create a copy of a `QkCircuit`. +Create a copy of a `QkCircuit`. - + - #### Example +### Example - ```c - QkCircuit *qc = qk_circuit_new(100, 100); - QkCircuit *copy = qk_circuit_copy(qc); - ``` +```c +QkCircuit *qc = qk_circuit_new(100, 100); +QkCircuit *copy = qk_circuit_copy(qc); +``` - + - #### Safety +### Safety - + - Behavior is undefined if `circuit` is not a valid, non-null pointer to a `QkCircuit`. +Behavior is undefined if `circuit` is not a valid, non-null pointer to a `QkCircuit`. - **Parameters** +**Parameters** - **circuit** – A pointer to the circuit to copy. +* **circuit** – A pointer to the circuit to copy. - **Returns** +**Returns** - A new pointer to a copy of the input `circuit`. - +A new pointer to a copy of the input `circuit`. -### qk\_circuit\_num\_qubits +**uint32\_t qk\_circuit\_num\_qubits(const QkCircuit \*circuit)** - - Get the number of qubits the circuit contains. +Get the number of qubits the circuit contains. - + - #### Example +### Example - ```c - QkCircuit *qc = qk_circuit_new(100, 100); - uint32_t num_qubits = qk_circuit_num_qubits(qc); // num_qubits==100 - ``` +```c +QkCircuit *qc = qk_circuit_new(100, 100); +uint32_t num_qubits = qk_circuit_num_qubits(qc); // num_qubits==100 +``` - + - #### Safety +### Safety - + - Behavior is undefined if `circuit` is not a valid, non-null pointer to a `QkCircuit`. +Behavior is undefined if `circuit` is not a valid, non-null pointer to a `QkCircuit`. - **Parameters** +**Parameters** - **circuit** – A pointer to the circuit. +* **circuit** – A pointer to the circuit. - **Returns** +**Returns** - The number of qubits the circuit is defined on. - +The number of qubits the circuit is defined on. -### qk\_circuit\_num\_clbits +**uint32\_t qk\_circuit\_num\_clbits(const QkCircuit \*circuit)** - - Get the number of clbits the circuit contains. +Get the number of clbits the circuit contains. - + - #### Example +### Example - ```c - QkCircuit *qc = qk_circuit_new(100, 50); - uint32_t num_clbits = qk_circuit_num_clbits(qc); // num_clbits==50 - ``` +```c +QkCircuit *qc = qk_circuit_new(100, 50); +uint32_t num_clbits = qk_circuit_num_clbits(qc); // num_clbits==50 +``` - + - #### Safety +### Safety - + - Behavior is undefined if `circuit` is not a valid, non-null pointer to a `QkCircuit`. +Behavior is undefined if `circuit` is not a valid, non-null pointer to a `QkCircuit`. - **Parameters** +**Parameters** - **circuit** – A pointer to the circuit. +* **circuit** – A pointer to the circuit. - **Returns** +**Returns** - The number of qubits the circuit is defined on. - +The number of qubits the circuit is defined on. -### qk\_circuit\_free +**void qk\_circuit\_free(QkCircuit \*circuit)** - - Free the circuit. +Free the circuit. - + - #### Example +### Example - ```c - QkCircuit *qc = qk_circuit_new(100, 100); - qk_circuit_free(qc); - ``` +```c +QkCircuit *qc = qk_circuit_new(100, 100); +qk_circuit_free(qc); +``` - + - #### Safety +### Safety - + - Behavior is undefined if `circuit` is not either null or a valid pointer to a `QkCircuit`. +Behavior is undefined if `circuit` is not either null or a valid pointer to a `QkCircuit`. - **Parameters** +**Parameters** - **circuit** – A pointer to the circuit to free. - +* **circuit** – A pointer to the circuit to free. -### qk\_circuit\_gate +**QkExitCode qk\_circuit\_gate(QkCircuit \*circuit, QkGate gate, const uint32\_t \*qubits, const double \*params)** - - Append a `QkGate` to the circuit. +Append a `QkGate` to the circuit. - + - #### Example +### Example - ```c - QkCircuit *qc = qk_circuit_new(100, 0); - uint32_t qubit[1] = {0}; - qk_circuit_gate(qc, QkGate_H, qubit, NULL); - ``` +```c +QkCircuit *qc = qk_circuit_new(100, 0); +uint32_t qubit[1] = {0}; +qk_circuit_gate(qc, QkGate_H, qubit, NULL); +``` - + - #### Safety +### Safety - + - The `qubits` and `params` types are expected to be a pointer to an array of `uint32_t` and `double` respectively where the length is matching the expectations for the standard 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 or params for a given gate. You can check `qk_gate_num_qubits` and `qk_gate_num_params` to determine how many qubits and params are required for a given gate. +The `qubits` and `params` types are expected to be a pointer to an array of `uint32_t` and `double` respectively where the length is matching the expectations for the standard 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 or params for a given gate. You can check `qk_gate_num_qubits` and `qk_gate_num_params` to determine how many qubits and params are required for a given gate. - Behavior is undefined if `circuit` is not a valid, non-null pointer to a `QkCircuit`. +Behavior is undefined if `circuit` is not a valid, non-null pointer to a `QkCircuit`. - **Parameters** +**Parameters** - * **circuit** – A pointer to the circuit to add the gate to. - * **gate** – The StandardGate to add to the circuit. - * **qubits** – The pointer to the array of `uint32_t` qubit indices to add the gate on. This can be a null pointer if there are no qubits for `gate` (e.g. `QkGate_GlobalPhase`). - * **params** – The pointer to the array of `double` values to use for the gate parameters. This can be a null pointer if there are no parameters for `gate` (e.g. `QkGate_H`). +* **circuit** – A pointer to the circuit to add the gate to. +* **gate** – The StandardGate to add to the circuit. +* **qubits** – The pointer to the array of `uint32_t` qubit indices to add the gate on. This can be a null pointer if there are no qubits for `gate` (e.g. `QkGate_GlobalPhase`). +* **params** – The pointer to the array of `double` values to use for the gate parameters. This can be a null pointer if there are no parameters for `gate` (e.g. `QkGate_H`). - **Returns** +**Returns** - An exit code. - +An exit code. -### qk\_gate\_num\_qubits +**uint32\_t qk\_gate\_num\_qubits(QkGate gate)** - - Get the number of qubits for a `QkGate`. +Get the number of qubits for a `QkGate`. - + - #### Example +### Example - ```c - uint32_t num_qubits = qk_gate_num_qubits(QkGate_CCX); - ``` +```c +uint32_t num_qubits = qk_gate_num_qubits(QkGate_CCX); +``` - **Parameters** +**Parameters** - **gate** – The `QkGate` to get the number of qubits for. +* **gate** – The `QkGate` to get the number of qubits for. - **Returns** +**Returns** - The number of qubits the gate acts on. - +The number of qubits the gate acts on. -### qk\_gate\_num\_params +**uint32\_t qk\_gate\_num\_params(QkGate gate)** - - Get the number of parameters for a `QkGate`. +Get the number of parameters for a `QkGate`. - + - #### Example +### Example - ```c - uint32_t num_params = qk_gate_num_params(QkGate_R); - ``` +```c +uint32_t num_params = qk_gate_num_params(QkGate_R); +``` - **Parameters** +**Parameters** - **gate** – The `QkGate` to get the number of qubits for. +* **gate** – The `QkGate` to get the number of qubits for. - **Returns** +**Returns** - The number of parameters the gate has. - +The number of parameters the gate has. -### qk\_circuit\_measure +**QkExitCode qk\_circuit\_measure(QkCircuit \*circuit, uint32\_t qubit, uint32\_t clbit)** - - Append a measurement to the circuit +Append a measurement to the circuit - + - #### Example +### Example - ```c - QkCircuit *qc = qk_circuit_new(100, 1); - qk_circuit_measure(qc, 0, 0); - ``` +```c +QkCircuit *qc = qk_circuit_new(100, 1); +qk_circuit_measure(qc, 0, 0); +``` - + - #### Safety +### Safety - + - Behavior is undefined if `circuit` is not a valid, non-null pointer to a `QkCircuit`. +Behavior is undefined if `circuit` is not a valid, non-null pointer to a `QkCircuit`. - **Parameters** +**Parameters** - * **circuit** – A pointer to the circuit to add the measurement to - * **qubit** – The `uint32_t` for the qubit to measure - * **clbit** – The `uint32_t` for the clbit to store the measurement outcome in +* **circuit** – A pointer to the circuit to add the measurement to +* **qubit** – The `uint32_t` for the qubit to measure +* **clbit** – The `uint32_t` for the clbit to store the measurement outcome in - **Returns** +**Returns** - An exit code. - +An exit code. -### qk\_circuit\_reset +**QkExitCode qk\_circuit\_reset(QkCircuit \*circuit, uint32\_t qubit)** - - Append a reset to the circuit +Append a reset to the circuit - + - #### Example +### Example - ```c - QkCircuit *qc = qk_circuit_new(100, 0); - qk_circuit_reset(qc, 0); - ``` +```c +QkCircuit *qc = qk_circuit_new(100, 0); +qk_circuit_reset(qc, 0); +``` - + - #### Safety +### Safety - + - Behavior is undefined if `circuit` is not a valid, non-null pointer to a `QkCircuit`. +Behavior is undefined if `circuit` is not a valid, non-null pointer to a `QkCircuit`. - **Parameters** +**Parameters** - * **circuit** – A pointer to the circuit to add the reset to - * **qubit** – The `uint32_t` for the qubit to reset +* **circuit** – A pointer to the circuit to add the reset to +* **qubit** – The `uint32_t` for the qubit to reset - **Returns** +**Returns** - An exit code. - +An exit code. -### qk\_circuit\_barrier +**QkExitCode qk\_circuit\_barrier(QkCircuit \*circuit, const uint32\_t \*qubits, uint32\_t num\_qubits)** - - Append a barrier to the circuit. +Append a barrier to the circuit. - + - #### Example +### Example - ```c - QkCircuit *qc = qk_circuit_new(100, 1); - uint32_t qubits[5] = {0, 1, 2, 3, 4}; - qk_circuit_barrier(qc, qubits, 5); - ``` +```c +QkCircuit *qc = qk_circuit_new(100, 1); +uint32_t qubits[5] = {0, 1, 2, 3, 4}; +qk_circuit_barrier(qc, qubits, 5); +``` - + - #### Safety +### Safety - + - The length of the array `qubits` points to must be `num_qubits`. If there is a mismatch the behavior is undefined. +The length of the array `qubits` points to must be `num_qubits`. If there is a mismatch the behavior is undefined. - Behavior is undefined if `circuit` is not a valid, non-null pointer to a `QkCircuit`. +Behavior is undefined if `circuit` is not a valid, non-null pointer to a `QkCircuit`. - **Parameters** +**Parameters** - * **circuit** – A pointer to the circuit to add the barrier to. - * **num\_qubits** – The number of qubits wide the barrier is. - * **qubits** – The pointer to the array of `uint32_t` qubit indices to add the barrier on. +* **circuit** – A pointer to the circuit to add the barrier to. +* **num\_qubits** – The number of qubits wide the barrier is. +* **qubits** – The pointer to the array of `uint32_t` qubit indices to add the barrier on. - **Returns** +**Returns** - An exit code. - +An exit code. -### qk\_circuit\_unitary +**QkExitCode qk\_circuit\_unitary(QkCircuit \*circuit, const [QkComplex64](qk-complex-64#c.QkComplex64 "QkComplex64") \*matrix, const uint32\_t \*qubits, uint32\_t num\_qubits, bool check\_input)** - - Append an arbitrary unitary matrix to the circuit. +Append an arbitrary unitary matrix to the circuit. - + - #### Example +### Example - ```c - QkComplex64 c0 = {0, 0}; // 0+0i - QkComplex64 c1 = {1, 0}; // 1+0i +```c +QkComplex64 c0 = {0, 0}; // 0+0i +QkComplex64 c1 = {1, 0}; // 1+0i - const uint32_t num_qubits = 1; - QkComplex64 unitary[2*2] = {c0, c1, // row 0 - c1, c0}; // row 1 +const uint32_t num_qubits = 1; +QkComplex64 unitary[2*2] = {c0, c1, // row 0 + c1, c0}; // row 1 - QkCircuit *circuit = qk_circuit_new(1, 0); // 1 qubit circuit - uint32_t qubit[1] = {0}; // qubit to apply the unitary on - qk_circuit_unitary(circuit, unitary, qubit, num_qubits, true); - ``` +QkCircuit *circuit = qk_circuit_new(1, 0); // 1 qubit circuit +uint32_t qubit[1] = {0}; // qubit to apply the unitary on +qk_circuit_unitary(circuit, unitary, qubit, num_qubits, true); +``` - + - #### Safety +### Safety - + - Behavior is undefined if any of the following is violated: +Behavior is undefined if any of the following is violated: - * `circuit` is a valid, non-null pointer to a `QkCircuit` - * `matrix` is a pointer to a nested array of `QkComplex64` of dimension `2 ^ num_qubits x 2 ^ num_qubits` - * `qubits` is a pointer to `num_qubits` readable element of type `uint32_t` +* `circuit` is a valid, non-null pointer to a `QkCircuit` +* `matrix` is a pointer to a nested array of `QkComplex64` of dimension `2 ^ num_qubits x 2 ^ num_qubits` +* `qubits` is a pointer to `num_qubits` readable element of type `uint32_t` - **Parameters** +**Parameters** - * **circuit** – A pointer to the circuit to append the unitary to. - * **matrix** – A pointer to the `QkComplex64` array representing the unitary matrix. This must be a row-major, unitary matrix of dimension `2 ^ num_qubits x 2 ^ num_qubits`. More explicitly: the `(i, j)`-th element is given by `matrix[i * 2^n + j]`. The contents of `matrix` are copied inside this function before being added to the circuit, so caller keeps ownership of the original memory that `matrix` points to and can reuse it after the call and the caller is responsible for freeing it. - * **qubits** – A pointer to array of qubit indices, of length `num_qubits`. - * **num\_qubits** – The number of qubits the unitary acts on. - * **check\_input** – When true, the function verifies that the matrix is unitary. If set to False the caller is responsible for ensuring the matrix is unitary, if the matrix is not unitary this is undefined behavior and will result in a corrupt circuit. - +* **circuit** – A pointer to the circuit to append the unitary to. +* **matrix** – A pointer to the `QkComplex64` array representing the unitary matrix. This must be a row-major, unitary matrix of dimension `2 ^ num_qubits x 2 ^ num_qubits`. More explicitly: the `(i, j)`-th element is given by `matrix[i * 2^n + j]`. The contents of `matrix` are copied inside this function before being added to the circuit, so caller keeps ownership of the original memory that `matrix` points to and can reuse it after the call and the caller is responsible for freeing it. +* **qubits** – A pointer to array of qubit indices, of length `num_qubits`. +* **num\_qubits** – The number of qubits the unitary acts on. +* **check\_input** – When true, the function verifies that the matrix is unitary. If set to False the caller is responsible for ensuring the matrix is unitary, if the matrix is not unitary this is undefined behavior and will result in a corrupt circuit. -### qk\_circuit\_count\_ops +**[QkOpCounts](#c.QkOpCounts "QkOpCounts") qk\_circuit\_count\_ops(const QkCircuit \*circuit)** - - Return a list of string names for instructions in a circuit and their counts. +Return a list of string names for instructions in a circuit and their counts. - To properly free the memory allocated by the struct, you should call `qk_opcounts_clear`. Dropping the `QkOpCounts` struct without doing so will leave the stored array of `QkOpCount` allocated and produce a memory leak. +To properly free the memory allocated by the struct, you should call `qk_opcounts_clear`. Dropping the `QkOpCounts` struct without doing so will leave the stored array of `QkOpCount` allocated and produce a memory leak. - + - #### Example +### Example - ```c - QkCircuit *qc = qk_circuit_new(100, 0); - uint32_t qubits[1] = {0}; - qk_circuit_gate(qc, QkGate_H, qubits, NULL); - QkOpCounts counts = qk_circuit_count_ops(qc); - // .. once done - qk_opcounts_clear(&counts); - ``` +```c +QkCircuit *qc = qk_circuit_new(100, 0); +uint32_t qubits[1] = {0}; +qk_circuit_gate(qc, QkGate_H, qubits, NULL); +QkOpCounts counts = qk_circuit_count_ops(qc); +// .. once done +qk_opcounts_clear(&counts); +``` - + - #### Safety +### Safety - + - Behavior is undefined if `circuit` is not a valid, non-null pointer to a `QkCircuit`. +Behavior is undefined if `circuit` is not a valid, non-null pointer to a `QkCircuit`. - **Parameters** +**Parameters** - **circuit** – A pointer to the circuit to get the counts for. +* **circuit** – A pointer to the circuit to get the counts for. - **Returns** +**Returns** - An `QkOpCounts` struct containing the circuit operation counts. - +An `QkOpCounts` struct containing the circuit operation counts. -### qk\_circuit\_num\_instructions +**size\_t qk\_circuit\_num\_instructions(const QkCircuit \*circuit)** - - Return the total number of instructions in the circuit. +Return the total number of instructions in the circuit. - + - #### Example +### Example - ```c - QkCircuit *qc = qk_circuit_new(100, 0); - uint32_t qubit[1] = {0}; - qk_circuit_gate(qc, QkGate_H, qubit, NULL); - size_t num = qk_circuit_num_instructions(qc); // 1 - ``` +```c +QkCircuit *qc = qk_circuit_new(100, 0); +uint32_t qubit[1] = {0}; +qk_circuit_gate(qc, QkGate_H, qubit, NULL); +size_t num = qk_circuit_num_instructions(qc); // 1 +``` - + - #### Safety +### Safety - + - Behavior is undefined if `circuit` is not a valid, non-null pointer to a `QkCircuit`. +Behavior is undefined if `circuit` is not a valid, non-null pointer to a `QkCircuit`. - **Parameters** +**Parameters** - **circuit** – A pointer to the circuit to get the total number of instructions for. +* **circuit** – A pointer to the circuit to get the total number of instructions for. - **Returns** +**Returns** - The total number of instructions in the circuit. - +The total number of instructions in the circuit. -### qk\_circuit\_get\_instruction +**void qk\_circuit\_get\_instruction(const QkCircuit \*circuit, size\_t index, [QkCircuitInstruction](#c.QkCircuitInstruction "QkCircuitInstruction") \*instruction)** - - Return the instruction details for an instruction in the circuit. +Return the instruction details for an instruction in the circuit. - This function is used to get the instruction details for a given instruction in the circuit. +This function is used to get the instruction details for a given instruction in the circuit. - This function allocates memory internally for the provided `QkCircuitInstruction` and thus you are responsible for calling `qk_circuit_instruction_clear` to free it. +This function allocates memory internally for the provided `QkCircuitInstruction` and thus you are responsible for calling `qk_circuit_instruction_clear` to free it. - + - #### Example +### Example - ```c - QkCircuitInstruction inst; - QkCircuit *qc = qk_circuit_new(100, 0); - uint32_t qubit[1] = {0}; - qk_circuit_gate(qc, QkGate_H, qubit, NULL); - qk_circuit_get_instruction(qc, 0, &inst); - qk_circuit_instruction_clear(&inst); - ``` +```c +QkCircuitInstruction inst; +QkCircuit *qc = qk_circuit_new(100, 0); +uint32_t qubit[1] = {0}; +qk_circuit_gate(qc, QkGate_H, qubit, NULL); +qk_circuit_get_instruction(qc, 0, &inst); +qk_circuit_instruction_clear(&inst); +``` - + - #### Safety +### Safety - + - Behavior is undefined if `circuit` is not a valid, non-null pointer to a `QkCircuit`. The value for `index` must be less than the value returned by `qk_circuit_num_instructions` otherwise this function will panic. Behavior is undefined if `instruction` is not a valid, non-null pointer to a memory allocation with sufficient space for a `QkCircuitInstruction`. +Behavior is undefined if `circuit` is not a valid, non-null pointer to a `QkCircuit`. The value for `index` must be less than the value returned by `qk_circuit_num_instructions` otherwise this function will panic. Behavior is undefined if `instruction` is not a valid, non-null pointer to a memory allocation with sufficient space for a `QkCircuitInstruction`. - **Parameters** +**Parameters** - * **circuit** – A pointer to the circuit to get the instruction details for. - * **index** – The instruction index to get the instruction details of. - * **instruction** – A pointer to where to write out the `QkCircuitInstruction` - +* **circuit** – A pointer to the circuit to get the instruction details for. +* **index** – The instruction index to get the instruction details of. +* **instruction** – A pointer to where to write out the `QkCircuitInstruction` -### qk\_circuit\_instruction\_clear +**void qk\_circuit\_instruction\_clear([QkCircuitInstruction](#c.QkCircuitInstruction "QkCircuitInstruction") \*inst)** - - Clear the data in circuit instruction object. +Clear the data in circuit instruction object. - This function doesn’t free the allocation for the provided `QkCircuitInstruction` pointer, it only frees the internal allocations for the data contained in the instruction. You are responsible for allocating and freeing the actual allocation used to store a `QkCircuitInstruction`. +This function doesn’t free the allocation for the provided `QkCircuitInstruction` pointer, it only frees the internal allocations for the data contained in the instruction. You are responsible for allocating and freeing the actual allocation used to store a `QkCircuitInstruction`. - + - #### Example +### Example - ```c - QkCircuitInstruction *inst = malloc(sizeof(QkCircuitInstruction)); - QkCircuit *qc = qk_circuit_new(100, 0); - uint32_t q0[1] = {0}; - qk_circuit_gate(qc, QkGate_H, q0, NULL); - qk_circuit_get_instruction(qc, 0, inst); - qk_circuit_instruction_clear(inst); // clear internal allocations - free(inst); // free struct - qk_circuit_free(qc); // free the circuit - ``` +```c +QkCircuitInstruction *inst = malloc(sizeof(QkCircuitInstruction)); +QkCircuit *qc = qk_circuit_new(100, 0); +uint32_t q0[1] = {0}; +qk_circuit_gate(qc, QkGate_H, q0, NULL); +qk_circuit_get_instruction(qc, 0, inst); +qk_circuit_instruction_clear(inst); // clear internal allocations +free(inst); // free struct +qk_circuit_free(qc); // free the circuit +``` - + - #### Safety +### Safety - + - Behavior is undefined if `inst` is not a valid, non-null pointer to a `QkCircuitInstruction`. +Behavior is undefined if `inst` is not a valid, non-null pointer to a `QkCircuitInstruction`. - **Parameters** +**Parameters** - **inst** – A pointer to the instruction to free. - +* **inst** – A pointer to the instruction to free. -### qk\_opcounts\_clear +**void qk\_opcounts\_clear([QkOpCounts](#c.QkOpCounts "QkOpCounts") \*op\_counts)** - - Clear the content in a circuit operation count list. +Clear the content in a circuit operation count list. - + - #### Safety +### Safety - + - Behavior is undefined if `op_counts` is not the object returned by `qk_circuit_count_ops`. +Behavior is undefined if `op_counts` is not the object returned by `qk_circuit_count_ops`. - **Parameters** +**Parameters** - **op\_counts** – The returned op count list from `qk_circuit_count_ops`. - +* **op\_counts** – The returned op count list from `qk_circuit_count_ops`. -### qk\_circuit\_to\_python +**[PyObject](https://docs.python.org/3/c-api/structures.html#c.PyObject "(in Python v3.14)") \*qk\_circuit\_to\_python(QkCircuit \*circuit)** - - Convert to a Python-space `QuantumCircuit`. +Convert to a Python-space `QuantumCircuit`. - This function takes ownership of the pointer and gives it to Python. Using the input `circuit` pointer after it’s passed to this function is undefined behavior. In particular, `qk_circuit_free` should not be called on this pointer anymore. +This function takes ownership of the pointer and gives it to Python. Using the input `circuit` pointer after it’s passed to this function is undefined behavior. In particular, `qk_circuit_free` should not be called on this pointer anymore. - + - #### Safety +### Safety - + - Behavior is undefined if `circuit` is not a valid, non-null pointer to a `QkCircuit` +Behavior is undefined if `circuit` is not a valid, non-null pointer to a `QkCircuit` - It is assumed that the thread currently executing this function holds the Python GIL. This is required to create the Python object returned by this function. +It is assumed that the thread currently executing this function holds the Python GIL. This is required to create the Python object returned by this function. - **Parameters** +**Parameters** - **circuit** – The C-space `QkCircuit` pointer. +* **circuit** – The C-space `QkCircuit` pointer. - **Returns** +**Returns** - A Python `QuantumCircuit` object. - +A Python `QuantumCircuit` object. -### qk\_circuit\_delay +**QkExitCode qk\_circuit\_delay(QkCircuit \*circuit, uint32\_t qubit, double duration, [QkDelayUnit](#c.QkDelayUnit "QkDelayUnit") unit)** - - Append a delay instruction to the circuit. +Append a delay instruction to the circuit. - + - #### Example +### Example - ```c - QkCircuit *qc = qk_circuit_new(1, 0); - qk_circuit_delay(qc, 0, 100.0, QkDelayUnit_NS); - ``` +```c +QkCircuit *qc = qk_circuit_new(1, 0); +qk_circuit_delay(qc, 0, 100.0, QkDelayUnit_NS); +``` - + - #### Safety +### Safety - + - Behavior is undefined if `circuit` is not a valid, non-null pointer to a `QkCircuit`. +Behavior is undefined if `circuit` is not a valid, non-null pointer to a `QkCircuit`. - **Parameters** +**Parameters** - * **circuit** – A pointer to the circuit to add the delay to. - * **qubit** – The `uint32_t` index of the qubit to apply the delay to. - * **duration** – The duration of the delay. - * **unit** – An enum representing the unit of the duration. +* **circuit** – A pointer to the circuit to add the delay to. +* **qubit** – The `uint32_t` index of the qubit to apply the delay to. +* **duration** – The duration of the delay. +* **unit** – An enum representing the unit of the duration. - **Returns** +**Returns** - An exit code. - +An exit code. diff --git a/docs/api/qiskit-c/dev/qk-classical-register.mdx b/docs/api/qiskit-c/dev/qk-classical-register.mdx index f9d2b96e74e..0f74f5e3e3d 100644 --- a/docs/api/qiskit-c/dev/qk-classical-register.mdx +++ b/docs/api/qiskit-c/dev/qk-classical-register.mdx @@ -36,61 +36,57 @@ While circuits track registers, the registers themselves impart almost no behavi ## Functions -### qk\_classical\_register\_free +**void qk\_classical\_register\_free(QkClassicalRegister \*reg)** - - Free a classical register. +Free a classical register. - + - #### Example +### Example - ```c - QkClassicalRegister *cr = qk_classical_register_new(1024, "creg"); - qk_classical_register_free(cr); - ``` +```c +QkClassicalRegister *cr = qk_classical_register_new(1024, "creg"); +qk_classical_register_free(cr); +``` - + - #### Safety +### Safety - + - Behavior is undefined if `reg` is not either null or a valid pointer to a `QkClassicalRegister`. +Behavior is undefined if `reg` is not either null or a valid pointer to a `QkClassicalRegister`. - **Parameters** +**Parameters** - **reg** – A pointer to the register to free. - +* **reg** – A pointer to the register to free. -### qk\_classical\_register\_new +**QkClassicalRegister \*qk\_classical\_register\_new(uint32\_t num\_clbits, const char \*name)** - - Construct a new owning classical register with a given number of clbits and name +Construct a new owning classical register with a given number of clbits and name - + - #### Example +### Example - ```c - QkClassicalRegister *cr = qk_classical_register_new(5, "five_qubits"); - ``` +```c +QkClassicalRegister *cr = qk_classical_register_new(5, "five_qubits"); +``` - + - #### Safety +### Safety - + - The `name` parameter must be a pointer to memory that contains a valid nul terminator at the end of the string. It also must be valid for reads of bytes up to and including the nul terminator. +The `name` parameter must be a pointer to memory that contains a valid nul terminator at the end of the string. It also must be valid for reads of bytes up to and including the nul terminator. - **Parameters** +**Parameters** - * **num\_clbits** – The number of clbits to create the register for - * **name** – The name string for the created register. The name must be comprised of valid UTF-8 characters. +* **num\_clbits** – The number of clbits to create the register for +* **name** – The name string for the created register. The name must be comprised of valid UTF-8 characters. - **Returns** +**Returns** - A pointer to the created register - +A pointer to the created register diff --git a/docs/api/qiskit-c/dev/qk-complex-64.mdx b/docs/api/qiskit-c/dev/qk-complex-64.mdx index 43b2554fbc5..8d7d5bf5a04 100644 --- a/docs/api/qiskit-c/dev/qk-complex-64.mdx +++ b/docs/api/qiskit-c/dev/qk-complex-64.mdx @@ -14,25 +14,23 @@ Explicitly, Qiskit assumes the compiler-native complex number type in C to be `_ ## Data types -### QkComplex64 +**struct QkComplex64** - - A complex double. +A complex double. - See also `qk_complex64_to_native` and `qk_complex64_from_native` to convert this struct to (or from) a compiler-native complex number representation. +See also `qk_complex64_to_native` and `qk_complex64_from_native` to convert this struct to (or from) a compiler-native complex number representation. - #### double re +**double re** - +The real part. - #### double im +**double im** - - +The imaginary part. ## Functions -**static CMPLX\_DOUBLE qk\_complex64\_to\_native(QkComplex64 \*value)** +**static CMPLX\_DOUBLE qk\_complex64\_to\_native([QkComplex64](#c.QkComplex64 "QkComplex64") \*value)** Convert a `QkComplex64` to a compiler-native complex number representation. Note that `CMPLX_DOUBLE` is a placeholder for the compiler-native complex number type, see the top of the page for more details. @@ -57,7 +55,7 @@ Behavior is undefined if `value` is not a valid, non-null pointer to a `QkComple A native representation of the complex number. -**static QkComplex64 qk\_complex64\_from\_native(CMPLX\_DOUBLE \*value)** +**static [QkComplex64](#c.QkComplex64 "QkComplex64") qk\_complex64\_from\_native(CMPLX\_DOUBLE \*value)** Convert a compiler-native complex number to a `QkComplex64`. Note that `CMPLX_DOUBLE` is a placeholder for the compiler-native complex number type, see the top of the page for more details. diff --git a/docs/api/qiskit-c/dev/qk-dag.mdx b/docs/api/qiskit-c/dev/qk-dag.mdx index 99451f08d69..06085190f23 100644 --- a/docs/api/qiskit-c/dev/qk-dag.mdx +++ b/docs/api/qiskit-c/dev/qk-dag.mdx @@ -18,182 +18,170 @@ The C API currently only supports building DAGs that contain operations defined ## Functions -### qk\_dag\_new +**QkDag \*qk\_dag\_new(void)** - - Construct a new empty DAG. +Construct a new empty DAG. - You must free the returned DAG with qk\_dag\_free when done with it. +You must free the returned DAG with qk\_dag\_free when done with it. - + - #### Example +### Example - ```c - QkDag *empty = qk_dag_new(); - ``` +```c +QkDag *empty = qk_dag_new(); +``` - **Returns** +**Returns** - A pointer to the created DAG. - +A pointer to the created DAG. -### qk\_dag\_add\_quantum\_register +**void qk\_dag\_add\_quantum\_register(QkDag \*dag, const QkQuantumRegister \*reg)** - - Add a quantum register to the DAG. +Add a quantum register to the DAG. - + - #### Example +### Example - ```c - QkDag *dag = qk_dag_new(); - QkQuantumRegister *qr = qk_quantum_register_new(1024, "my_register"); - qk_dag_add_quantum_register(dag, qr); - qk_quantum_register_free(qr); - qk_dag_free(dag); - ``` +```c +QkDag *dag = qk_dag_new(); +QkQuantumRegister *qr = qk_quantum_register_new(1024, "my_register"); +qk_dag_add_quantum_register(dag, qr); +qk_quantum_register_free(qr); +qk_dag_free(dag); +``` - + - #### Safety +### Safety - + - Behavior is undefined if `dag` is not a valid, non-null pointer to a `QkDag` and if `reg` is not a valid, non-null pointer to a `QkQuantumRegister`. +Behavior is undefined if `dag` is not a valid, non-null pointer to a `QkDag` and if `reg` is not a valid, non-null pointer to a `QkQuantumRegister`. - **Parameters** +**Parameters** - * **dag** – A pointer to the DAG. - * **reg** – A pointer to the quantum register. - +* **dag** – A pointer to the DAG. +* **reg** – A pointer to the quantum register. -### qk\_dag\_add\_classical\_register +**void qk\_dag\_add\_classical\_register(QkDag \*dag, const QkClassicalRegister \*reg)** - - Add a classical register to the DAG. +Add a classical register to the DAG. - + - #### Example +### Example - ```c - QkDag *dag = qk_dag_new(); - QkClassicalRegister *cr = qk_classical_register_new(24, "my_register"); - qk_dag_add_classical_register(dag, cr); - qk_classical_register_free(cr); - qk_dag_free(dag); - ``` +```c +QkDag *dag = qk_dag_new(); +QkClassicalRegister *cr = qk_classical_register_new(24, "my_register"); +qk_dag_add_classical_register(dag, cr); +qk_classical_register_free(cr); +qk_dag_free(dag); +``` - + - #### Safety +### Safety - + - Behavior is undefined if `dag` is not a valid, non-null pointer to a `QkDag` and if `reg` is not a valid, non-null pointer to a `QkClassicalRegister`. +Behavior is undefined if `dag` is not a valid, non-null pointer to a `QkDag` and if `reg` is not a valid, non-null pointer to a `QkClassicalRegister`. - **Parameters** +**Parameters** - * **dag** – A pointer to the DAG. - * **reg** – A pointer to the classical register. - +* **dag** – A pointer to the DAG. +* **reg** – A pointer to the classical register. -### qk\_dag\_num\_qubits +**uint32\_t qk\_dag\_num\_qubits(const QkDag \*dag)** - - Get the number of qubits the DAG contains. +Get the number of qubits the DAG contains. - + - #### Example +### Example - ```c - QkDag *dag = qk_dag_new(); - QkQuantumRegister *qr = qk_quantum_register_new(24, "my_register"); - qk_dag_add_quantum_register(dag, qr); - uint32_t num_qubits = qk_dag_num_qubits(dag); // num_qubits==24 - qk_quantum_register_free(qr); - qk_dag_free(dag); - ``` +```c +QkDag *dag = qk_dag_new(); +QkQuantumRegister *qr = qk_quantum_register_new(24, "my_register"); +qk_dag_add_quantum_register(dag, qr); +uint32_t num_qubits = qk_dag_num_qubits(dag); // num_qubits==24 +qk_quantum_register_free(qr); +qk_dag_free(dag); +``` - + - #### Safety +### Safety - + - Behavior is undefined if `dag` is not a valid, non-null pointer to a `QkDag`. +Behavior is undefined if `dag` is not a valid, non-null pointer to a `QkDag`. - **Parameters** +**Parameters** - **dag** – A pointer to the DAG. +* **dag** – A pointer to the DAG. - **Returns** +**Returns** - The number of qubits the DAG is defined on. - +The number of qubits the DAG is defined on. -### qk\_dag\_num\_clbits +**uint32\_t qk\_dag\_num\_clbits(const QkDag \*dag)** - - Get the number of clbits the DAG contains. +Get the number of clbits the DAG contains. - + - #### Example +### Example - ```c - QkDag *dag = qk_dag_new(); - QkClassicalRegister *cr = qk_classical_register_new(24, "my_register"); - qk_dag_add_classical_register(dag, cr); - uint32_t num_clbits = qk_dag_num_clbits(dag); // num_clbits==24 - qk_classical_register_free(cr); - qk_dag_free(dag); - ``` +```c +QkDag *dag = qk_dag_new(); +QkClassicalRegister *cr = qk_classical_register_new(24, "my_register"); +qk_dag_add_classical_register(dag, cr); +uint32_t num_clbits = qk_dag_num_clbits(dag); // num_clbits==24 +qk_classical_register_free(cr); +qk_dag_free(dag); +``` - + - #### Safety +### Safety - + - Behavior is undefined if `dag` is not a valid, non-null pointer to a `QkDag`. +Behavior is undefined if `dag` is not a valid, non-null pointer to a `QkDag`. - **Parameters** +**Parameters** - **dag** – A pointer to the DAG. +* **dag** – A pointer to the DAG. - **Returns** +**Returns** - The number of clbits the DAG is defined on. - +The number of clbits the DAG is defined on. -### qk\_dag\_free +**void qk\_dag\_free(QkDag \*dag)** - - Free the DAG. +Free the DAG. - + - #### Example +### Example - ```c - QkDag *dag = qk_dag_new(); - qk_dag_free(dag); - ``` +```c +QkDag *dag = qk_dag_new(); +qk_dag_free(dag); +``` - + - #### Safety +### Safety - + - Behavior is undefined if `dag` is not either null or a valid pointer to a `QkDag`. +Behavior is undefined if `dag` is not either null or a valid pointer to a `QkDag`. - **Parameters** +**Parameters** - **dag** – A pointer to the DAG to free. - +* **dag** – A pointer to the DAG to free. diff --git a/docs/api/qiskit-c/dev/qk-neighbors.mdx b/docs/api/qiskit-c/dev/qk-neighbors.mdx new file mode 100644 index 00000000000..366ae81e4b5 --- /dev/null +++ b/docs/api/qiskit-c/dev/qk-neighbors.mdx @@ -0,0 +1,132 @@ +--- +title: QkNeighbors (dev version) +description: API reference for QkNeighbors in the dev version of qiskit-c +in_page_toc_min_heading_level: 2 +python_api_type: module +python_api_name: QkNeighbors +--- + +# QkNeighbors + +**struct QkNeighbors** + +An adjacency-list representation of a coupling graph. + +This is initialized by `qk_neighbors_from_target`. + +This object is read-only from C. To satisfy the safety guarantees of `qk_neighbors_clear`, you must not overwrite any data initialized by `qk_neighbors_from_target`, including any pointed-to data. + + + +## Representation + + + +After initialization by `qk_neighbors_from_target`, the structure will be in one of two modes: + +* all-to-all connectivity +* limited two-qubit connectivity + +In the all-to-all case, the `neighbors` and `partition` pointers will both be the null pointer, and `num_qubits` will be the number of qubits in the `QkTarget`. These objects do not have backing allocations, and do not need to be given to `qk_neighbors_clear` (though this function is a safe no-op in this case). + +In the limited two-qubit case (which is by far the more common for real hardware), see the documentation of the structure members for their interpretation. + +**const uint32\_t \*neighbors** + +A partitioned adjacency-list representation of the neighbors of each qubit. This pointer is valid for exactly `partition[num_qubits + 1]` reads. + +For qubit number `i`, its neighbors are the values between offsets `partition[i]` (inclusive) and `partition[i + 1]` (exclusive). The values between these two offsets are sorted in ascending order and contain no duplicates. + +**const size\_t \*partition** + +How the `neighbors` field is partitioned into slices. This pointer is valid for exactly `num_qubits + 1` reads. The first value is always 0, and values increase monotonically. + +**uint32\_t num\_qubits** + +The number of qubits. + +## Functions + +**bool qk\_neighbors\_is\_all\_to\_all(const [QkNeighbors](#c.QkNeighbors "QkNeighbors") \*neighbors)** + +Does this coupling graph represent all-to-all connectivity? + +This is represented by `neighbors` and `partition` being null pointers, so they are not valid for any reads. + + + +### Safety + + + +`neighbors` must point to a valid, initialized `QkNeighbors` object. + +**Parameters** + +* **neighbors** – The coupling graph. + +**Returns** + +Whether the graph represents all to all connectivity. + +**bool qk\_neighbors\_from\_target(const QkTarget \*target, [QkNeighbors](#c.QkNeighbors "QkNeighbors") \*neighbors)** + +Initialize a `QkNeighbors` object from a `QkTarget`. + +If the target contains multi-qubit gates, they will be ignored and the connectivity will only represent the two-qubit coupling constraints. If the target represents all-to-all connectivity, the function returns `true`, and the output pointers will be initialized to be null pointers, in keeping with the representation of all-to-all connectivity. + + + +### Examples + +```c +QkTarget *target = build_target_from_somewhere(); +QkNeighbors neighbors; +if (qk_neighbors_from_target(target, &neighbors)) { + printf("All-to-all connectivity on &lu qubits.\n", neighbors.num_qubits); + return; +} +printf("Qubit 3 has %zu neighbors.\n", neighbors.partition[4] - neighbors.partition[3]); +printf("Those neighbors are: ["); +for (size_t offset = neighbors.partition[3]; offset < neighbors.partition[4]; offset++) { + printf("%u%s", + neighbors.neighbors[offset], + offset + 1 == neighbors.partition[4] ? "" : ", "); +} +printf("]\n"); +qk_neighbors_clear(&neighbors); +``` + + + +### Safety + + + +`target` must point to a valid `QkTarget` object. `neighbors` must be aligned and safe to write to, but need not be initialized. + +**Parameters** + +* **target** – The target to read the connectivity from. +* **neighbors** – The `QkNeighbors` object to initialize. + +**Returns** + +Whether the `QkTarget` represented all-to-all connectivity (`true`) or has regular connectivity (`false`). + +**void qk\_neighbors\_clear([QkNeighbors](#c.QkNeighbors "QkNeighbors") \*neighbors)** + +Free all the allocations within the object. + +After calling this function, the `QkNeighbors` object will contain null pointers in all its allocations and present as if it represents all-to-all connectivity. + +This should only be called on `QkNeighbors` objects that were initialized by `qk_neighbors_from_target`. + + + +### Safety + + + +`neighbors` must point to a valid, initialized `QkNeighbors` object, which must have been initialized by a call to `qk_neighbors_from_target` and unaltered since then. + diff --git a/docs/api/qiskit-c/dev/qk-obs-term.mdx b/docs/api/qiskit-c/dev/qk-obs-term.mdx index 87e3debed31..edac8378099 100644 --- a/docs/api/qiskit-c/dev/qk-obs-term.mdx +++ b/docs/api/qiskit-c/dev/qk-obs-term.mdx @@ -12,90 +12,76 @@ This is a group of functions for interacting with an opaque (Rust-space) SparseT ## Data types -### QkObsTerm +**struct QkObsTerm** - - A term in a `QkObs`. +A term in a `QkObs`. - This contains the coefficient (`coeff`), the number of qubits of the observable (`num_qubits`) and pointers to the `bit_terms` and `indices` arrays, which have length `len`. It’s the responsibility of the user that the data is coherent, see also the below section on safety. +This contains the coefficient (`coeff`), the number of qubits of the observable (`num_qubits`) and pointers to the `bit_terms` and `indices` arrays, which have length `len`. It’s the responsibility of the user that the data is coherent, see also the below section on safety. - + - #### Safety +### Safety - + - * `bit_terms` must be a non-null, aligned pointer to `len` elements of type `QkBitTerm`. - * `indices` must be a non-null, aligned pointer to `len` elements of type `uint32_t`. +* `bit_terms` must be a non-null, aligned pointer to `len` elements of type `QkBitTerm`. +* `indices` must be a non-null, aligned pointer to `len` elements of type `uint32_t`. - #### QkComplex64 coeff +**[QkComplex64](qk-complex-64#c.QkComplex64 "QkComplex64") coeff** - - The coefficient of the observable term. - +The coefficient of the observable term. - #### size\_t len +**size\_t len** - - Length of the `bit_terms` and `indices` arrays. - +Length of the `bit_terms` and `indices` arrays. - #### QkBitTerm \*bit\_terms +**QkBitTerm \*bit\_terms** - - A non-null, aligned pointer to `len` elements of type `QkBitTerm`. - +A non-null, aligned pointer to `len` elements of type `QkBitTerm`. - #### uint32\_t \*indices +**uint32\_t \*indices** - - A non-null, aligned pointer to `len` elements of type `uint32_t`. - +A non-null, aligned pointer to `len` elements of type `uint32_t`. - #### uint32\_t num\_qubits +**uint32\_t num\_qubits** - - The number of qubits the observable term is defined on. - - +The number of qubits the observable term is defined on. ## Functions -### qk\_obsterm\_str +**char \*qk\_obsterm\_str(const [QkObsTerm](#c.QkObsTerm "QkObsTerm") \*term)** - - Return a string representation of the sparse term. +Return a string representation of the sparse term. - + - #### Example +### Example - ```c - QkObs *obs = qk_obs_identity(100); - QkObsTerm term; - qk_obs_term(obs, 0, &term); - char *string = qk_obsterm_str(&term); - qk_str_free(string); - ``` +```c +QkObs *obs = qk_obs_identity(100); +QkObsTerm term; +qk_obs_term(obs, 0, &term); +char *string = qk_obsterm_str(&term); +qk_str_free(string); +``` - + - #### Safety +### Safety - + - Behavior is undefined `term` is not a valid, non-null pointer to a `QkObsTerm`. +Behavior is undefined `term` is not a valid, non-null pointer to a `QkObsTerm`. - The string must not be freed with the normal C free, you must use `qk_str_free` to free the memory consumed by the String. Not calling `qk_str_free` will lead to a memory leak. +The string must not be freed with the normal C free, you must use `qk_str_free` to free the memory consumed by the String. Not calling `qk_str_free` will lead to a memory leak. - Do not change the length of the string after it’s returned, although values can be mutated. +Do not change the length of the string after it’s returned, although values can be mutated. - **Parameters** +**Parameters** - **term** – A pointer to the term. +* **term** – A pointer to the term. - **Returns** +**Returns** - The function exit code. This is `>0` if reading the term failed. - +The function exit code. This is `>0` if reading the term failed. diff --git a/docs/api/qiskit-c/dev/qk-obs.mdx b/docs/api/qiskit-c/dev/qk-obs.mdx index 3c0e24cbad6..2c8ff7f3745 100644 --- a/docs/api/qiskit-c/dev/qk-obs.mdx +++ b/docs/api/qiskit-c/dev/qk-obs.mdx @@ -139,873 +139,825 @@ for (size_t i = 0; i < num_terms; i++) { ## Functions -### qk\_obs\_zero +**QkObs \*qk\_obs\_zero(uint32\_t num\_qubits)** - - Construct the zero observable (without any terms). +Construct the zero observable (without any terms). - + - #### Example +### Example - ```c - QkObs *zero = qk_obs_zero(100); - ``` +```c +QkObs *zero = qk_obs_zero(100); +``` - **Parameters** +**Parameters** - **num\_qubits** – The number of qubits the observable is defined on. +* **num\_qubits** – The number of qubits the observable is defined on. - **Returns** +**Returns** - A pointer to the created observable. - +A pointer to the created observable. -### qk\_obs\_identity +**QkObs \*qk\_obs\_identity(uint32\_t num\_qubits)** - - Construct the identity observable. +Construct the identity observable. - + - #### Example +### Example - ```c - QkObs *identity = qk_obs_identity(100); - ``` +```c +QkObs *identity = qk_obs_identity(100); +``` - **Parameters** +**Parameters** - **num\_qubits** – The number of qubits the observable is defined on. +* **num\_qubits** – The number of qubits the observable is defined on. - **Returns** +**Returns** - A pointer to the created observable. - +A pointer to the created observable. -### qk\_obs\_new +**QkObs \*qk\_obs\_new(uint32\_t num\_qubits, uint64\_t num\_terms, uint64\_t num\_bits, [QkComplex64](qk-complex-64#c.QkComplex64 "QkComplex64") \*coeffs, QkBitTerm \*bit\_terms, uint32\_t \*indices, size\_t \*boundaries)** - - Construct a new observable from raw data. +Construct a new observable from raw data. - + - #### Example +### Example - ```c - // define the raw data for the 100-qubit observable |01><01|_{0, 1} - |+-><+-|_{98, 99} - uint32_t num_qubits = 100; - uint64_t num_terms = 2; // we have 2 terms: |01><01|, -1 * |+-><+-| - uint64_t num_bits = 4; // we have 4 non-identity bits: 0, 1, +, - - QkComplex64 coeffs = {1, -1}; - QkBitTerm bits[4] = {QkBitTerm_Zero, QkBitTerm_One, QkBitTerm_Plus, QkBitTerm_Minus}; - - uint32_t indices[4] = {0, 1, 98, 99}; // <-- e.g. {1, 0, 99, 98} would be invalid - size_t boundaries[3] = {0, 2, 4}; - QkObs *obs = qk_obs_new( - num_qubits, num_terms, num_bits, &coeffs, bits, indices, boundaries - ); - ``` +```c +// define the raw data for the 100-qubit observable |01><01|_{0, 1} - |+-><+-|_{98, 99} +uint32_t num_qubits = 100; +uint64_t num_terms = 2; // we have 2 terms: |01><01|, -1 * |+-><+-| +uint64_t num_bits = 4; // we have 4 non-identity bits: 0, 1, +, - +QkComplex64 coeffs = {1, -1}; +QkBitTerm bits[4] = {QkBitTerm_Zero, QkBitTerm_One, QkBitTerm_Plus, QkBitTerm_Minus}; + +uint32_t indices[4] = {0, 1, 98, 99}; // <-- e.g. {1, 0, 99, 98} would be invalid +size_t boundaries[3] = {0, 2, 4}; +QkObs *obs = qk_obs_new( + num_qubits, num_terms, num_bits, &coeffs, bits, indices, boundaries +); +``` - + - #### Safety +### Safety - + - Behavior is undefined if any of the following conditions are violated: +Behavior is undefined if any of the following conditions are violated: - * `coeffs` is a pointer to a `QkComplex64` array of length `num_terms` - * `bit_terms` is a pointer to an array of valid `QkBitTerm` elements of length `num_bits` - * `indices` is a pointer to a `uint32_t` array of length `num_bits`, which is term-wise sorted in strict ascending order, and every element is smaller than `num_qubits` - * `boundaries` is a pointer to a `size_t` array of length `num_terms + 1`, which is sorted in ascending order, the first element is 0 and the last element is smaller than `num_terms` +* `coeffs` is a pointer to a `QkComplex64` array of length `num_terms` +* `bit_terms` is a pointer to an array of valid `QkBitTerm` elements of length `num_bits` +* `indices` is a pointer to a `uint32_t` array of length `num_bits`, which is term-wise sorted in strict ascending order, and every element is smaller than `num_qubits` +* `boundaries` is a pointer to a `size_t` array of length `num_terms + 1`, which is sorted in ascending order, the first element is 0 and the last element is smaller than `num_terms` - **Parameters** +**Parameters** - * **num\_qubits** – The number of qubits the observable is defined on. - * **num\_terms** – The number of terms. - * **num\_bits** – The total number of non-identity bit terms. - * **coeffs** – A pointer to the first element of the coefficients array, which has length `num_terms`. - * **bit\_terms** – A pointer to the first element of the bit terms array, which has length `num_bits`. - * **indices** – A pointer to the first element of the indices array, which has length `num_bits`. Note that, per term, these *must* be sorted incrementally. - * **boundaries** – A pointer to the first element of the boundaries array, which has length `num_terms + 1`. +* **num\_qubits** – The number of qubits the observable is defined on. +* **num\_terms** – The number of terms. +* **num\_bits** – The total number of non-identity bit terms. +* **coeffs** – A pointer to the first element of the coefficients array, which has length `num_terms`. +* **bit\_terms** – A pointer to the first element of the bit terms array, which has length `num_bits`. +* **indices** – A pointer to the first element of the indices array, which has length `num_bits`. Note that, per term, these *must* be sorted incrementally. +* **boundaries** – A pointer to the first element of the boundaries array, which has length `num_terms + 1`. - **Returns** +**Returns** - If the input data was coherent and the construction successful, the result is a pointer to the observable. Otherwise a null pointer is returned. - +If the input data was coherent and the construction successful, the result is a pointer to the observable. Otherwise a null pointer is returned. -### qk\_obs\_free +**void qk\_obs\_free(QkObs \*obs)** - - Free the observable. +Free the observable. - + - #### Example +### Example - ```c - QkObs *obs = qk_obs_zero(100); - qk_obs_free(obs); - ``` +```c +QkObs *obs = qk_obs_zero(100); +qk_obs_free(obs); +``` - + - #### Safety +### Safety - + - Behavior is undefined if `obs` is not either null or a valid pointer to a `QkObs`. +Behavior is undefined if `obs` is not either null or a valid pointer to a `QkObs`. - **Parameters** +**Parameters** - **obs** – A pointer to the observable to free. - +* **obs** – A pointer to the observable to free. -### qk\_obs\_add\_term +**QkExitCode qk\_obs\_add\_term(QkObs \*obs, const [QkObsTerm](qk-obs-term#c.QkObsTerm "QkObsTerm") \*cterm)** - - Add a term to the observable. +Add a term to the observable. - + - #### Example +### Example - ```c - uint32_t num_qubits = 100; - QkObs *obs = qk_obs_zero(num_qubits); +```c +uint32_t num_qubits = 100; +QkObs *obs = qk_obs_zero(num_qubits); - QkComplex64 coeff = {1, 0}; - QkBitTerm bit_terms[3] = {QkBitTerm_X, QkBitTerm_Y, QkBitTerm_Z}; - uint32_t indices[3] = {0, 1, 2}; - QkObsTerm term = {coeff, 3, bit_terms, indices, num_qubits}; +QkComplex64 coeff = {1, 0}; +QkBitTerm bit_terms[3] = {QkBitTerm_X, QkBitTerm_Y, QkBitTerm_Z}; +uint32_t indices[3] = {0, 1, 2}; +QkObsTerm term = {coeff, 3, bit_terms, indices, num_qubits}; - int exit_code = qk_obs_add_term(obs, &term); - ``` +int exit_code = qk_obs_add_term(obs, &term); +``` - + - #### Safety +### Safety - + - Behavior is undefined if any of the following is violated: +Behavior is undefined if any of the following is violated: - * `obs` is a valid, non-null pointer to a `QkObs` - * `cterm` is a valid, non-null pointer to a `QkObsTerm` +* `obs` is a valid, non-null pointer to a `QkObs` +* `cterm` is a valid, non-null pointer to a `QkObsTerm` - **Parameters** +**Parameters** - * **obs** – A pointer to the observable. - * **cterm** – A pointer to the term to add. +* **obs** – A pointer to the observable. +* **cterm** – A pointer to the term to add. - **Returns** +**Returns** - An exit code. This is `>0` if the term is incoherent or adding the term fails. - +An exit code. This is `>0` if the term is incoherent or adding the term fails. -### qk\_obs\_term +**QkExitCode qk\_obs\_term(QkObs \*obs, uint64\_t index, [QkObsTerm](qk-obs-term#c.QkObsTerm "QkObsTerm") \*out)** - - Get an observable term by reference. +Get an observable term by reference. - A `QkObsTerm` contains pointers to the indices and bit terms in the term, which can be used to modify the internal data of the observable. This can leave the observable in an incoherent state and should be avoided, unless great care is taken. It is generally safer to construct a new observable instead of attempting in-place modifications. +A `QkObsTerm` contains pointers to the indices and bit terms in the term, which can be used to modify the internal data of the observable. This can leave the observable in an incoherent state and should be avoided, unless great care is taken. It is generally safer to construct a new observable instead of attempting in-place modifications. - + - #### Example +### Example - ```c - QkObs *obs = qk_obs_identity(100); - QkObsTerm term; - int exit_code = qk_obs_term(obs, 0, &term); - // out-of-bounds indices return an error code - // int error = qk_obs_term(obs, 12, &term); - ``` +```c +QkObs *obs = qk_obs_identity(100); +QkObsTerm term; +int exit_code = qk_obs_term(obs, 0, &term); +// out-of-bounds indices return an error code +// int error = qk_obs_term(obs, 12, &term); +``` - + - #### Safety +### Safety - + - Behavior is undefined if any of the following is violated +Behavior is undefined if any of the following is violated - * `obs` is a valid, non-null pointer to a `QkObs` - * `out` is a valid, non-null pointer to a `QkObsTerm` +* `obs` is a valid, non-null pointer to a `QkObs` +* `out` is a valid, non-null pointer to a `QkObsTerm` - **Parameters** +**Parameters** - * **obs** – A pointer to the observable. - * **index** – The index of the term to get. - * **out** – A pointer to a `QkObsTerm` used to return the observable term. +* **obs** – A pointer to the observable. +* **index** – The index of the term to get. +* **out** – A pointer to a `QkObsTerm` used to return the observable term. - **Returns** +**Returns** - An exit code. - +An exit code. -### qk\_obs\_num\_terms +**size\_t qk\_obs\_num\_terms(const QkObs \*obs)** - - Get the number of terms in the observable. +Get the number of terms in the observable. - + - #### Example +### Example - ```c - QkObs *obs = qk_obs_identity(100); - size_t num_terms = qk_obs_num_terms(obs); // num_terms==1 - ``` +```c +QkObs *obs = qk_obs_identity(100); +size_t num_terms = qk_obs_num_terms(obs); // num_terms==1 +``` - + - #### Safety +### Safety - + - Behavior is undefined `obs` is not a valid, non-null pointer to a `QkObs`. +Behavior is undefined `obs` is not a valid, non-null pointer to a `QkObs`. - **Parameters** +**Parameters** - **obs** – A pointer to the observable. +* **obs** – A pointer to the observable. - **Returns** +**Returns** - The number of terms in the observable. - +The number of terms in the observable. -### qk\_obs\_num\_qubits +**uint32\_t qk\_obs\_num\_qubits(const QkObs \*obs)** - - Get the number of qubits the observable is defined on. +Get the number of qubits the observable is defined on. - + - #### Example +### Example - ```c - QkObs *obs = qk_obs_identity(100); - uint32_t num_qubits = qk_obs_num_qubits(obs); // num_qubits==100 - ``` +```c +QkObs *obs = qk_obs_identity(100); +uint32_t num_qubits = qk_obs_num_qubits(obs); // num_qubits==100 +``` - + - #### Safety +### Safety - + - Behavior is undefined `obs` is not a valid, non-null pointer to a `QkObs`. +Behavior is undefined `obs` is not a valid, non-null pointer to a `QkObs`. - **Parameters** +**Parameters** - **obs** – A pointer to the observable. +* **obs** – A pointer to the observable. - **Returns** +**Returns** - The number of qubits the observable is defined on. - +The number of qubits the observable is defined on. -### qk\_obs\_len +**size\_t qk\_obs\_len(const QkObs \*obs)** - - Get the number of bit terms/indices in the observable. +Get the number of bit terms/indices in the observable. - + - #### Example +### Example - ```c - QkObs *obs = qk_obs_identity(100); - size_t len = qk_obs_len(obs); // len==0, as there are no non-trivial bit terms - ``` +```c +QkObs *obs = qk_obs_identity(100); +size_t len = qk_obs_len(obs); // len==0, as there are no non-trivial bit terms +``` - + - #### Safety +### Safety - + - Behavior is undefined `obs` is not a valid, non-null pointer to a `QkObs`. +Behavior is undefined `obs` is not a valid, non-null pointer to a `QkObs`. - **Parameters** +**Parameters** - **obs** – A pointer to the observable. +* **obs** – A pointer to the observable. - **Returns** +**Returns** - The number of terms in the observable. - +The number of terms in the observable. -### qk\_obs\_coeffs +**[QkComplex64](qk-complex-64#c.QkComplex64 "QkComplex64") \*qk\_obs\_coeffs(QkObs \*obs)** - - Get a pointer to the coefficients. +Get a pointer to the coefficients. - This can be used to read and modify the observable’s coefficients. The resulting pointer is valid to read for `qk_obs_num_terms(obs)` elements of `QkComplex64`. +This can be used to read and modify the observable’s coefficients. The resulting pointer is valid to read for `qk_obs_num_terms(obs)` elements of `QkComplex64`. - + - #### Example +### Example - ```c - QkObs *obs = qk_obs_identity(100); - size_t num_terms = qk_obs_num_terms(obs); - QkComplex64 *coeffs = qk_obs_coeffs(obs); +```c +QkObs *obs = qk_obs_identity(100); +size_t num_terms = qk_obs_num_terms(obs); +QkComplex64 *coeffs = qk_obs_coeffs(obs); - for (size_t i = 0; i < num_terms; i++) { - printf("%f + i%f\n", coeffs[i].re, coeffs[i].im); - } - ``` +for (size_t i = 0; i < num_terms; i++) { + printf("%f + i%f\n", coeffs[i].re, coeffs[i].im); +} +``` - + - #### Safety +### Safety - + - Behavior is undefined `obs` is not a valid, non-null pointer to a `QkObs`. +Behavior is undefined `obs` is not a valid, non-null pointer to a `QkObs`. - **Parameters** +**Parameters** - **obs** – A pointer to the observable. +* **obs** – A pointer to the observable. - **Returns** +**Returns** - A pointer to the coefficients. - +A pointer to the coefficients. -### qk\_obs\_indices +**uint32\_t \*qk\_obs\_indices(QkObs \*obs)** - - Get a pointer to the indices. +Get a pointer to the indices. - This can be used to read and modify the observable’s indices. The resulting pointer is valid to read for `qk_obs_len(obs)` elements of size `uint32_t`. +This can be used to read and modify the observable’s indices. The resulting pointer is valid to read for `qk_obs_len(obs)` elements of size `uint32_t`. - + - #### Example +### Example - + - ```c - uint32_t num_qubits = 100; - QkObs *obs = qk_obs_zero(num_qubits); +```c +uint32_t num_qubits = 100; +QkObs *obs = qk_obs_zero(num_qubits); - QkComplex64 coeff = {1, 0}; - QkBitTerm bit_terms[3] = {QkBitTerm_X, QkBitTerm_Y, QkBitTerm_Z}; - uint32_t term_indices[3] = {0, 1, 2}; - QkObsTerm term = {coeff, 3, bit_terms, term_indices, num_qubits}; - qk_obs_add_term(obs, &term); +QkComplex64 coeff = {1, 0}; +QkBitTerm bit_terms[3] = {QkBitTerm_X, QkBitTerm_Y, QkBitTerm_Z}; +uint32_t term_indices[3] = {0, 1, 2}; +QkObsTerm term = {coeff, 3, bit_terms, term_indices, num_qubits}; +qk_obs_add_term(obs, &term); - size_t len = qk_obs_len(obs); - uint32_t *indices = qk_obs_indices(obs); +size_t len = qk_obs_len(obs); +uint32_t *indices = qk_obs_indices(obs); - for (size_t i = 0; i < len; i++) { - printf("index %i: %i\n", i, indices[i]); - } - ``` +for (size_t i = 0; i < len; i++) { + printf("index %i: %i\n", i, indices[i]); +} +``` - ```c - qk_obs_free(obs); - ``` +```c +qk_obs_free(obs); +``` - + - #### Safety +### Safety - + - Behavior is undefined `obs` is not a valid, non-null pointer to a `QkObs`. +Behavior is undefined `obs` is not a valid, non-null pointer to a `QkObs`. - **Parameters** +**Parameters** - **obs** – A pointer to the observable. +* **obs** – A pointer to the observable. - **Returns** +**Returns** - A pointer to the indices. - +A pointer to the indices. -### qk\_obs\_boundaries +**size\_t \*qk\_obs\_boundaries(QkObs \*obs)** - - Get a pointer to the term boundaries. +Get a pointer to the term boundaries. - This can be used to read and modify the observable’s term boundaries. The resulting pointer is valid to read for `qk_obs_num_terms(obs) + 1` elements of size `size_t`. +This can be used to read and modify the observable’s term boundaries. The resulting pointer is valid to read for `qk_obs_num_terms(obs) + 1` elements of size `size_t`. - + - #### Example +### Example - ```c - uint32_t num_qubits = 100; - QkObs *obs = qk_obs_zero(num_qubits); +```c +uint32_t num_qubits = 100; +QkObs *obs = qk_obs_zero(num_qubits); - QkComplex64 coeff = {1, 0}; - QkBitTerm bit_terms[3] = {QkBitTerm_X, QkBitTerm_Y, QkBitTerm_Z}; - uint32_t indices[3] = {0, 1, 2}; - QkObsTerm term = {coeff, 3, bit_terms, indices, num_qubits}; - qk_obs_add_term(obs, &term); +QkComplex64 coeff = {1, 0}; +QkBitTerm bit_terms[3] = {QkBitTerm_X, QkBitTerm_Y, QkBitTerm_Z}; +uint32_t indices[3] = {0, 1, 2}; +QkObsTerm term = {coeff, 3, bit_terms, indices, num_qubits}; +qk_obs_add_term(obs, &term); - size_t num_terms = qk_obs_num_terms(obs); - size_t *boundaries = qk_obs_boundaries(obs); +size_t num_terms = qk_obs_num_terms(obs); +size_t *boundaries = qk_obs_boundaries(obs); - for (size_t i = 0; i < num_terms + 1; i++) { - printf("boundary %i: %i\n", i, boundaries[i]); - } - ``` +for (size_t i = 0; i < num_terms + 1; i++) { + printf("boundary %i: %i\n", i, boundaries[i]); +} +``` - + - #### Safety +### Safety - + - Behavior is undefined `obs` is not a valid, non-null pointer to a `QkObs`. +Behavior is undefined `obs` is not a valid, non-null pointer to a `QkObs`. - **Parameters** +**Parameters** - **obs** – A pointer to the observable. +* **obs** – A pointer to the observable. - **Returns** +**Returns** - A pointer to the boundaries. - +A pointer to the boundaries. -### qk\_obs\_bit\_terms +**QkBitTerm \*qk\_obs\_bit\_terms(QkObs \*obs)** - - Get a pointer to the bit terms. +Get a pointer to the bit terms. - This can be used to read and modify the observable’s bit terms. The resulting pointer is valid to read for `qk_obs_len(obs)` elements of size `uint8_t`. +This can be used to read and modify the observable’s bit terms. The resulting pointer is valid to read for `qk_obs_len(obs)` elements of size `uint8_t`. - + - #### Example +### Example - ```c - uint32_t num_qubits = 100; - QkObs *obs = qk_obs_zero(num_qubits); +```c +uint32_t num_qubits = 100; +QkObs *obs = qk_obs_zero(num_qubits); - QkComplex64 coeff = {1, 0}; - QkBitTerm bit_terms[3] = {QkBitTerm_X, QkBitTerm_Y, QkBitTerm_Z}; - uint32_t indices[3] = {0, 1, 2}; - QkObsTerm term = {coeff, 3, bit_terms, indices, num_qubits}; - qk_obs_add_term(obs, &term); +QkComplex64 coeff = {1, 0}; +QkBitTerm bit_terms[3] = {QkBitTerm_X, QkBitTerm_Y, QkBitTerm_Z}; +uint32_t indices[3] = {0, 1, 2}; +QkObsTerm term = {coeff, 3, bit_terms, indices, num_qubits}; +qk_obs_add_term(obs, &term); - size_t len = qk_obs_len(obs); - QkBitTerm *bits = qk_obs_bit_terms(obs); +size_t len = qk_obs_len(obs); +QkBitTerm *bits = qk_obs_bit_terms(obs); - for (size_t i = 0; i < len; i++) { - printf("bit term %i: %i\n", i, bits[i]); - } +for (size_t i = 0; i < len; i++) { + printf("bit term %i: %i\n", i, bits[i]); +} - qk_obs_free(obs); - ``` +qk_obs_free(obs); +``` - + - #### Safety +### Safety - + - Behavior is undefined `obs` is not a valid, non-null pointer to a `QkObs`, or if invalid valus are written into the resulting `QkBitTerm` pointer. +Behavior is undefined `obs` is not a valid, non-null pointer to a `QkObs`, or if invalid valus are written into the resulting `QkBitTerm` pointer. - **Parameters** +**Parameters** - **obs** – A pointer to the observable. +* **obs** – A pointer to the observable. - **Returns** +**Returns** - A pointer to the bit terms. - +A pointer to the bit terms. -### qk\_obs\_multiply +**QkObs \*qk\_obs\_multiply(const QkObs \*obs, const [QkComplex64](qk-complex-64#c.QkComplex64 "QkComplex64") \*coeff)** - - Multiply the observable by a complex coefficient. +Multiply the observable by a complex coefficient. - + - #### Example +### Example - ```c - QkObs *obs = qk_obs_identity(100); - QkComplex64 coeff = {2, 0}; - QkObs *result = qk_obs_multiply(obs, &coeff); - ``` +```c +QkObs *obs = qk_obs_identity(100); +QkComplex64 coeff = {2, 0}; +QkObs *result = qk_obs_multiply(obs, &coeff); +``` - + - #### Safety +### Safety - + - Behavior is undefined if any of the following is violated +Behavior is undefined if any of the following is violated - * `obs` is a valid, non-null pointer to a `QkObs` - * `coeff` is a valid, non-null pointer to a `QkComplex64` +* `obs` is a valid, non-null pointer to a `QkObs` +* `coeff` is a valid, non-null pointer to a `QkComplex64` - **Parameters** +**Parameters** - * **obs** – A pointer to the observable. - * **coeff** – The coefficient to multiply the observable with. - +* **obs** – A pointer to the observable. +* **coeff** – The coefficient to multiply the observable with. -### qk\_obs\_add +**QkObs \*qk\_obs\_add(const QkObs \*left, const QkObs \*right)** - - Add two observables. +Add two observables. - + - #### Example +### Example - ```c - QkObs *left = qk_obs_identity(100); - QkObs *right = qk_obs_zero(100); - QkObs *result = qk_obs_add(left, right); - ``` +```c +QkObs *left = qk_obs_identity(100); +QkObs *right = qk_obs_zero(100); +QkObs *result = qk_obs_add(left, right); +``` - + - #### Safety +### Safety - + - Behavior is undefined if `left` or `right` are not valid, non-null pointers to `QkObs`\ s. +Behavior is undefined if `left` or `right` are not valid, non-null pointers to `QkObs`\ s. - **Parameters** +**Parameters** - * **left** – A pointer to the left observable. - * **right** – A pointer to the right observable. +* **left** – A pointer to the left observable. +* **right** – A pointer to the right observable. - **Returns** +**Returns** - A pointer to the result `left + right`. - +A pointer to the result `left + right`. -### qk\_obs\_compose +**QkObs \*qk\_obs\_compose(const QkObs \*first, const QkObs \*second)** - - Compose (multiply) two observables. +Compose (multiply) two observables. - + - #### Example +### Example - ```c - QkObs *first = qk_obs_zero(100); - QkObs *second = qk_obs_identity(100); - QkObs *result = qk_obs_compose(first, second); - ``` +```c +QkObs *first = qk_obs_zero(100); +QkObs *second = qk_obs_identity(100); +QkObs *result = qk_obs_compose(first, second); +``` - + - #### Safety +### Safety - + - Behavior is undefined if `first` or `second` are not valid, non-null pointers to `QkObs`\ s. +Behavior is undefined if `first` or `second` are not valid, non-null pointers to `QkObs`\ s. - **Parameters** +**Parameters** - * **first** – One observable. - * **second** – The other observable. +* **first** – One observable. +* **second** – The other observable. - **Returns** +**Returns** - `first.compose(second)` which equals the observable `result = second @ first`, in terms of the matrix multiplication `@`. - +`first.compose(second)` which equals the observable `result = second @ first`, in terms of the matrix multiplication `@`. -### qk\_obs\_compose\_map +**QkObs \*qk\_obs\_compose\_map(const QkObs \*first, const QkObs \*second, const uint32\_t \*qargs)** - - Compose (multiply) two observables according to a custom qubit order. +Compose (multiply) two observables according to a custom qubit order. - Notably, this allows composing two observables of different size. +Notably, this allows composing two observables of different size. - + - #### Example +### Example - ```c - QkObs *first = qk_obs_zero(100); - QkObs *second = qk_obs_identity(100); - QkObs *result = qk_obs_compose(first, second); - ``` +```c +QkObs *first = qk_obs_zero(100); +QkObs *second = qk_obs_identity(100); +QkObs *result = qk_obs_compose(first, second); +``` - + - #### Safety +### Safety - + - To call this function safely +To call this function safely - * `first` and `second` must be valid, non-null pointers to `QkObs`\ s - * `qargs` must point to an array of `uint32_t`, readable for `qk_obs_num_qubits(second)` elements (meaning the number of qubits in `second`) +* `first` and `second` must be valid, non-null pointers to `QkObs`\ s +* `qargs` must point to an array of `uint32_t`, readable for `qk_obs_num_qubits(second)` elements (meaning the number of qubits in `second`) - **Parameters** +**Parameters** - * **first** – One observable. - * **second** – The other observable. The number of qubits must match the length of `qargs`. - * **qargs** – The qubit arguments specified which indices in `first` to associate with the ones in `second`. +* **first** – One observable. +* **second** – The other observable. The number of qubits must match the length of `qargs`. +* **qargs** – The qubit arguments specified which indices in `first` to associate with the ones in `second`. - **Returns** +**Returns** - `first.compose(second)` which equals the observable `result = second @ first`, in terms of the matrix multiplication `@`. - +`first.compose(second)` which equals the observable `result = second @ first`, in terms of the matrix multiplication `@`. -### qk\_obs\_apply\_layout +**QkExitCode qk\_obs\_apply\_layout(QkObs \*obs, const uint32\_t \*layout, uint32\_t num\_qubits)** - - Apply a new qubit layout to the observable. +Apply a new qubit layout to the observable. - The layout is set by an array `layout` of new indices, specifying that qubit at current index `i` is relabelled to index `layout[i]`. The number of qubits the observable acts on can be extended by setting a larger `num_qubits` than the current observable has. +The layout is set by an array `layout` of new indices, specifying that qubit at current index `i` is relabelled to index `layout[i]`. The number of qubits the observable acts on can be extended by setting a larger `num_qubits` than the current observable has. - + - #### Example +### Example - + - This interface allows to relabel and extend the qubit indices: +This interface allows to relabel and extend the qubit indices: - ```c - QkObs *obs = qk_obs_zero(4); - - // add a term to the observable - QkBitTerm bit_terms[3] = {QkBitTerm_X, QkBitTerm_Y, QkBitTerm_Z}; - uint32_t qubits[3] = {1, 2, 3}; - complex double coeff = 1; - QkObsTerm term = {coeff, 3, bit_terms, qubits, 4}; - qk_obs_add_term(obs, &term); - - uint32_t layout[3] = {0, 10, 9}; // qubit mapping is: 0->0, 1->10, 2->9 - uint32_t num_output_qubits = 11; - int exit = qk_obs_apply_layout(obs, layout, num_output_qubits); - ``` +```c +QkObs *obs = qk_obs_zero(4); + +// add a term to the observable +QkBitTerm bit_terms[3] = {QkBitTerm_X, QkBitTerm_Y, QkBitTerm_Z}; +uint32_t qubits[3] = {1, 2, 3}; +complex double coeff = 1; +QkObsTerm term = {coeff, 3, bit_terms, qubits, 4}; +qk_obs_add_term(obs, &term); + +uint32_t layout[3] = {0, 10, 9}; // qubit mapping is: 0->0, 1->10, 2->9 +uint32_t num_output_qubits = 11; +int exit = qk_obs_apply_layout(obs, layout, num_output_qubits); +``` - In a compiler workflow, this function can conveniently be used to apply a `QkTranspileLayout*` obtained from a transpiler pass, called `transpile_layout` in the following example: +In a compiler workflow, this function can conveniently be used to apply a `QkTranspileLayout*` obtained from a transpiler pass, called `transpile_layout` in the following example: - ```c - // get the number of output qubits - uint32_t num_output_qubits = qk_transpile_layout_num_output_qubits(transpile_layout); +```c +// get the number of output qubits +uint32_t num_output_qubits = qk_transpile_layout_num_output_qubits(transpile_layout); - // get the layout including the ancillas (hence the ``false`` in the function call) - uint32_t *layout = malloc(sizeof(uint32_t) * num_output_qubits); - qk_transpile_layout_final_layout(transpile_layout, false, layout); +// get the layout including the ancillas (hence the ``false`` in the function call) +uint32_t *layout = malloc(sizeof(uint32_t) * num_output_qubits); +qk_transpile_layout_final_layout(transpile_layout, false, layout); - // apply the layout - int exit = qk_obs_apply_layout(obs, layout, num_output_qubits); +// apply the layout +int exit = qk_obs_apply_layout(obs, layout, num_output_qubits); - // free the layout array - free(layout); - ``` +// free the layout array +free(layout); +``` - + - #### Safety +### Safety - + - Behavior is undefined if `obs` is not a valid, non-null pointer to `QkObs` or if `layout` is not a valid, non-null pointer to a sequence of `qk_obs_num_qubits(obs)` consecutive elements of `uint32_t`. +Behavior is undefined if `obs` is not a valid, non-null pointer to `QkObs` or if `layout` is not a valid, non-null pointer to a sequence of `qk_obs_num_qubits(obs)` consecutive elements of `uint32_t`. - **Parameters** +**Parameters** - * **obs** – A pointer to the observable, this observable will be modified in place upon success. Check the exit code to ensure the layout was correctly applied. - * **layout** – A pointer to the layout. The pointer must point to an array to `qk_obs_num_qubits(obs)` elements of type `uint32_t`. Each element must have values in `[0, num_qubits)`. - * **num\_qubits** – The number of output qubits. +* **obs** – A pointer to the observable, this observable will be modified in place upon success. Check the exit code to ensure the layout was correctly applied. +* **layout** – A pointer to the layout. The pointer must point to an array to `qk_obs_num_qubits(obs)` elements of type `uint32_t`. Each element must have values in `[0, num_qubits)`. +* **num\_qubits** – The number of output qubits. - **Returns** +**Returns** - An exit code. +An exit code. - * `QkExitCode_Success` upon success - * `QkExitCode_DuplicteIndexError` if duplicate qubit indices were found - * `QkExitCode_MismatchedQubits` if `num_qubits` is smaller than the number of qubits in the observable - * `QkExitCode_IndexError` for any other index errors, such as invalid values in `layout`. - +* `QkExitCode_Success` upon success +* `QkExitCode_DuplicteIndexError` if duplicate qubit indices were found +* `QkExitCode_MismatchedQubits` if `num_qubits` is smaller than the number of qubits in the observable +* `QkExitCode_IndexError` for any other index errors, such as invalid values in `layout`. -### qk\_obs\_canonicalize +**QkObs \*qk\_obs\_canonicalize(const QkObs \*obs, double tol)** - - Calculate the canonical representation of the observable. +Calculate the canonical representation of the observable. - + - #### Example +### Example - ```c - QkObs *iden = qk_obs_identity(100); - QkObs *two = qk_obs_add(iden, iden); +```c +QkObs *iden = qk_obs_identity(100); +QkObs *two = qk_obs_add(iden, iden); - double tol = 1e-6; - QkObs *canonical = qk_obs_canonicalize(two, tol); - ``` +double tol = 1e-6; +QkObs *canonical = qk_obs_canonicalize(two, tol); +``` - + - #### Safety +### Safety - + - Behavior is undefined `obs` is not a valid, non-null pointer to a `QkObs`. +Behavior is undefined `obs` is not a valid, non-null pointer to a `QkObs`. - **Parameters** +**Parameters** - * **obs** – A pointer to the observable. - * **tol** – The tolerance below which coefficients are considered to be zero. +* **obs** – A pointer to the observable. +* **tol** – The tolerance below which coefficients are considered to be zero. - **Returns** +**Returns** - The canonical representation of the observable. - +The canonical representation of the observable. -### qk\_obs\_copy +**QkObs \*qk\_obs\_copy(const QkObs \*obs)** - - Copy the observable. +Copy the observable. - + - #### Example +### Example - ```c - QkObs *original = qk_obs_identity(100); - QkObs *copied = qk_obs_copy(original); - ``` +```c +QkObs *original = qk_obs_identity(100); +QkObs *copied = qk_obs_copy(original); +``` - + - #### Safety +### Safety - + - Behavior is undefined `obs` is not a valid, non-null pointer to a `QkObs`. +Behavior is undefined `obs` is not a valid, non-null pointer to a `QkObs`. - **Parameters** +**Parameters** - **obs** – A pointer to the observable. +* **obs** – A pointer to the observable. - **Returns** +**Returns** - A pointer to a copy of the observable. - +A pointer to a copy of the observable. -### qk\_obs\_equal +**bool qk\_obs\_equal(const QkObs \*obs, const QkObs \*other)** - - Compare two observables for equality. +Compare two observables for equality. - Note that this does not compare mathematical equality, but data equality. This means that two observables might represent the same observable but not compare as equal. +Note that this does not compare mathematical equality, but data equality. This means that two observables might represent the same observable but not compare as equal. - + - #### Example +### Example - ```c - QkObs *observable = qk_obs_identity(100); - QkObs *other = qk_obs_identity(100); - bool are_equal = qk_obs_equal(observable, other); - ``` +```c +QkObs *observable = qk_obs_identity(100); +QkObs *other = qk_obs_identity(100); +bool are_equal = qk_obs_equal(observable, other); +``` - + - #### Safety +### Safety - + - Behavior is undefined if `obs` or `other` are not valid, non-null pointers to `QkObs`\ s. +Behavior is undefined if `obs` or `other` are not valid, non-null pointers to `QkObs`\ s. - **Parameters** +**Parameters** - * **obs** – A pointer to one observable. - * **other** – A pointer to another observable. +* **obs** – A pointer to one observable. +* **other** – A pointer to another observable. - **Returns** +**Returns** - `true` if the observables are equal, `false` otherwise. - +`true` if the observables are equal, `false` otherwise. -### qk\_obs\_str +**char \*qk\_obs\_str(const QkObs \*obs)** - - Return a string representation of a `QkObs`. +Return a string representation of a `QkObs`. - + - #### Example +### Example - ```c - QkObs *obs = qk_obs_identity(100); - char *string = qk_obs_str(obs); - qk_str_free(string); - ``` +```c +QkObs *obs = qk_obs_identity(100); +char *string = qk_obs_str(obs); +qk_str_free(string); +``` - + - #### Safety +### Safety - + - Behavior is undefined `obs` is not a valid, non-null pointer to a `QkObs`. +Behavior is undefined `obs` is not a valid, non-null pointer to a `QkObs`. - The string must not be freed with the normal C free, you must use `qk_str_free` to free the memory consumed by the String. Not calling `qk_str_free` will lead to a memory leak. +The string must not be freed with the normal C free, you must use `qk_str_free` to free the memory consumed by the String. Not calling `qk_str_free` will lead to a memory leak. - Do not change the length of the string after it’s returned (by writing a nul byte somewhere inside the string or removing the final one), although values can be mutated. +Do not change the length of the string after it’s returned (by writing a nul byte somewhere inside the string or removing the final one), although values can be mutated. - **Parameters** +**Parameters** - **obs** – A pointer to the `QkObs` to get the string for. +* **obs** – A pointer to the `QkObs` to get the string for. - **Returns** +**Returns** - A pointer to a nul-terminated char array of the string representation for `obs` - +A pointer to a nul-terminated char array of the string representation for `obs` -### qk\_str\_free +**void qk\_str\_free(char \*string)** - - Free a string representation. +Free a string representation. - + - #### Safety +### Safety - + - Behavior is undefined if `str` is not a pointer returned by `qk_obs_str` or `qk_obsterm_str`. +Behavior is undefined if `str` is not a pointer returned by `qk_obs_str` or `qk_obsterm_str`. - **Parameters** +**Parameters** - **string** – A pointer to the returned string representation from `qk_obs_str` or `qk_obsterm_str`. - +* **string** – A pointer to the returned string representation from `qk_obs_str` or `qk_obsterm_str`. -### qk\_obs\_to\_python +**[PyObject](https://docs.python.org/3/c-api/structures.html#c.PyObject "(in Python v3.14)") \*qk\_obs\_to\_python(const QkObs \*obs)** - - Convert to a Python-space `SparseObservable`. +Convert to a Python-space `SparseObservable`. - + - #### Safety +### Safety - + - Behavior is undefined if `obs` is not a valid, non-null pointer to a `QkObs`. +Behavior is undefined if `obs` is not a valid, non-null pointer to a `QkObs`. - It is assumed that the thread currently executing this function holds the Python GIL this is required to create the Python object returned by this function. +It is assumed that the thread currently executing this function holds the Python GIL this is required to create the Python object returned by this function. - **Parameters** +**Parameters** - **obs** – The C-space `QkObs` pointer. +* **obs** – The C-space `QkObs` pointer. - **Returns** +**Returns** - A Python object representing the `SparseObservable`. - +A Python object representing the `SparseObservable`. diff --git a/docs/api/qiskit-c/dev/qk-quantum-register.mdx b/docs/api/qiskit-c/dev/qk-quantum-register.mdx index 29d24ba39e2..6088e3007c5 100644 --- a/docs/api/qiskit-c/dev/qk-quantum-register.mdx +++ b/docs/api/qiskit-c/dev/qk-quantum-register.mdx @@ -36,61 +36,57 @@ While circuits track registers, the registers themselves impart almost no behavi ## Functions -### qk\_quantum\_register\_new +**QkQuantumRegister \*qk\_quantum\_register\_new(uint32\_t num\_qubits, const char \*name)** - - Construct a new owning quantum register with a given number of qubits and name +Construct a new owning quantum register with a given number of qubits and name - + - #### Example +### Example - ```c - QkQuantumRegister *qr = qk_quantum_register_new(5, "five_qubits"); - ``` +```c +QkQuantumRegister *qr = qk_quantum_register_new(5, "five_qubits"); +``` - + - #### Safety +### Safety - + - The `name` parameter must be a pointer to memory that contains a valid nul terminator at the end of the string. It also must be valid for reads of bytes up to and including the nul terminator. +The `name` parameter must be a pointer to memory that contains a valid nul terminator at the end of the string. It also must be valid for reads of bytes up to and including the nul terminator. - **Parameters** +**Parameters** - * **num\_qubits** – The number of qubits to create the register for - * **name** – The name string for the created register. The name must be comprised of valid UTF-8 characters. +* **num\_qubits** – The number of qubits to create the register for +* **name** – The name string for the created register. The name must be comprised of valid UTF-8 characters. - **Returns** +**Returns** - A pointer to the created register - +A pointer to the created register -### qk\_quantum\_register\_free +**void qk\_quantum\_register\_free(QkQuantumRegister \*reg)** - - Free a quantum register. +Free a quantum register. - + - #### Example +### Example - ```c - QkQuantumRegister *qr = qk_quantum_register_new(1024, "qreg"); - qk_quantum_register_free(qr); - ``` +```c +QkQuantumRegister *qr = qk_quantum_register_new(1024, "qreg"); +qk_quantum_register_free(qr); +``` - + - #### Safety +### Safety - + - Behavior is undefined if `reg` is not either null or a valid pointer to a `QkQuantumRegister`. +Behavior is undefined if `reg` is not either null or a valid pointer to a `QkQuantumRegister`. - **Parameters** +**Parameters** - **reg** – A pointer to the register to free. - +* **reg** – A pointer to the register to free. diff --git a/docs/api/qiskit-c/dev/qk-sabre-layout-options.mdx b/docs/api/qiskit-c/dev/qk-sabre-layout-options.mdx index 111b2c3e6a8..d367d0b1760 100644 --- a/docs/api/qiskit-c/dev/qk-sabre-layout-options.mdx +++ b/docs/api/qiskit-c/dev/qk-sabre-layout-options.mdx @@ -12,41 +12,29 @@ When running the `qk_transpiler_pass_standalone_sabre_layout` function this type ## Data Types -### QkSabreLayoutOptions +**struct QkSabreLayoutOptions** - - The options for running `qk_transpiler_pass_standalone_sabre_layout`. This struct is used as an input to control the behavior of the layout and routing algorithms. +The options for running `qk_transpiler_pass_standalone_sabre_layout`. This struct is used as an input to control the behavior of the layout and routing algorithms. - #### size\_t max\_iterations +**size\_t max\_iterations** - - The number of forward-backward iterations in the sabre routing algorithm - +The number of forward-backward iterations in the sabre routing algorithm - #### size\_t num\_swap\_trials +**size\_t num\_swap\_trials** - - The number of trials to run of the sabre routing algorithm for each iteration. When > 1 the trial that routing trial that results in the output with the fewest swap gates will be selected. - +The number of trials to run of the sabre routing algorithm for each iteration. When > 1 the trial that routing trial that results in the output with the fewest swap gates will be selected. - #### size\_t num\_random\_trials +**size\_t num\_random\_trials** - - The number of random layout trials to run. The trial that results in the output with the fewest swap gates will be selected. - +The number of random layout trials to run. The trial that results in the output with the fewest swap gates will be selected. - #### uint64\_t seed +**uint64\_t seed** - - A seed value for the pRNG used internally. - - +A seed value for the pRNG used internally. ## Functions -### qk\_sabre\_layout\_options\_default +**[QkSabreLayoutOptions](#c.QkSabreLayoutOptions "QkSabreLayoutOptions") qk\_sabre\_layout\_options\_default(void)** - - Build a default sabre layout options object. This builds a sabre layout with `max_iterations` set to 4, both `num_swap_trials` and `num_random_trials` set to 20, and the seed selected by a RNG seeded from system entropy. - +Build a default sabre layout options object. This builds a sabre layout with `max_iterations` set to 4, both `num_swap_trials` and `num_random_trials` set to 20, and the seed selected by a RNG seeded from system entropy. diff --git a/docs/api/qiskit-c/dev/qk-target-entry.mdx b/docs/api/qiskit-c/dev/qk-target-entry.mdx index aaa252966a4..d9ae3e182f9 100644 --- a/docs/api/qiskit-c/dev/qk-target-entry.mdx +++ b/docs/api/qiskit-c/dev/qk-target-entry.mdx @@ -33,212 +33,198 @@ 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. +Creates an entry to the `QkTarget` based on a `QkGate` instance. - + - #### Example +### Example - ```c - QkTargetEntry *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. +```c +QkTargetEntry *entry = qk_target_entry_new(QkGate_H); +``` - **Returns** +**Parameters** - A pointer to the new `QkTargetEntry`. - +* **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. -### qk\_target\_entry\_new\_measure +**Returns** - - Creates a new entry for adding a measurement instruction to a `QkTarget`. +A pointer to the new `QkTargetEntry`. - +**QkTargetEntry \*qk\_target\_entry\_new\_measure(void)** - #### Example +Creates a new entry for adding a measurement instruction to a `QkTarget`. - ```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); - ``` +### Example - **Returns** +```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); +``` - A pointer to the new `QkTargetEntry` for a measurement instruction. - +**Returns** -### qk\_target\_entry\_new\_reset +A pointer to the new `QkTargetEntry` for a measurement instruction. - - Creates a new entry for adding a reset instruction to a `QkTarget`. +**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); - } +### Example - // Add the entry to a target with 3 qubits - QkTarget *reset_target = qk_target_new(3); - qk_target_add_instruction(reset_target, entry); - ``` +```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** +**Returns** - A pointer to the new `QkTargetEntry` for a reset instruction. - +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)** - - Creates an entry in the `QkTarget` based on a `QkGate` instance with no parameters. +Creates an entry in the `QkTarget` based on a `QkGate` instance with no parameters. - + - #### Example +### Example - ```c - double crx_params[1] = {3.14}; - QkTargetEntry *entry = qk_target_entry_new_fixed(QkGate_CRX, crx_params); - ``` +```c +double crx_params[1] = {3.14}; +QkTargetEntry *entry = qk_target_entry_new_fixed(QkGate_CRX, crx_params); +``` - + - #### Safety +### 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 `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. - - Adding a `QkGate` with regular parameters is not currently supported. - + + Adding a `QkGate` with regular parameters is not currently supported. + - **Parameters** +**Parameters** - * **operation** – The `QkGate` whose properties this target entry defines. - * **params** – A pointer to the parameters that the instruction is calibrated for. +* **operation** – The `QkGate` whose properties this target entry defines. +* **params** – A pointer to the parameters that the instruction is calibrated for. - **Returns** +**Returns** - A pointer to the new `QkTargetEntry`. - +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. +Retrieves the number of properties stored in the target entry. - + - #### Example +### 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); - ``` +```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 +### Safety - + - The behavior is undefined if `entry` is not a valid, non-null pointer to a `QkTargetEntry` object. +The behavior is undefined if `entry` is not a valid, non-null pointer to a `QkTargetEntry` object. - **Parameters** +**Parameters** - **entry** – The pointer to the mapping object. +* **entry** – The pointer to the mapping object. - **Returns** +**Returns** - The number of properties in the `QkTargetEntry`. - +The number of properties in the `QkTargetEntry`. -### qk\_target\_entry\_free +**void qk\_target\_entry\_free(QkTargetEntry \*entry)** - - Frees the entry. +Frees the entry. - + - #### Example +### Example - ```c - QkTargetEntry *entry = qk_target_entry_new(QkGate_H); - qk_target_entry_free(entry); - ``` +```c +QkTargetEntry *entry = qk_target_entry_new(QkGate_H); +qk_target_entry_free(entry); +``` - + - #### Safety +### Safety - + - The behavior is undefined if `entry` is not a valid, non-null pointer to a `QkTargetEntry` object. +The behavior is undefined if `entry` is not a valid, non-null pointer to a `QkTargetEntry` object. - - 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. - + + 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** +**Parameters** - **entry** – The pointer to the mapping object to be freed. - +* **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. +Adds an instruction property instance based on its assigned qargs. - + - #### Example +### 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); - ``` +```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 +### Safety - + - The behavior is undefined if `entry` is not a valid, non-null pointer to a `QkTargetEntry` object. +The behavior is undefined if `entry` is not a valid, non-null pointer to a `QkTargetEntry` object. - **Parameters** +**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. - +* **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. diff --git a/docs/api/qiskit-c/dev/qk-target.mdx b/docs/api/qiskit-c/dev/qk-target.mdx index 8211e939f0f..16b9b2a4b05 100644 --- a/docs/api/qiskit-c/dev/qk-target.mdx +++ b/docs/api/qiskit-c/dev/qk-target.mdx @@ -43,558 +43,524 @@ The Target C API currently only supports additions of `QkGate` instances with ei ## 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 +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 +### Example - ```c - QkTarget *target = qk_target_new(5); - ``` +```c +QkTarget *target = qk_target_new(5); +``` - **Parameters** +**Parameters** - **num\_qubits** – The number of qubits the `QkTarget` will explicitly support. +* **num\_qubits** – The number of qubits the `QkTarget` will explicitly support. - **Returns** +**Returns** - A pointer to the new `QkTarget` - +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`. +Returns the number of qubits of this `QkTarget`. - + - #### Example +### Example - ```c - QkTarget *target = qk_target_new(5); - uint32_t num_qubits = qk_target_num_qubits(target); - ``` +```c +QkTarget *target = qk_target_new(5); +uint32_t num_qubits = qk_target_num_qubits(target); +``` - + - #### Safety +### Safety - + - Behavior is undefined if `QkTarget` is not a valid, non-null pointer to a `QkTarget`. +Behavior is undefined if `QkTarget` is not a valid, non-null pointer to a `QkTarget`. - **Parameters** +**Parameters** - **target** – A pointer to the `QkTarget`. +* **target** – A pointer to the `QkTarget`. - **Returns** +**Returns** - The number of qubits this target can use. - +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`. +Returns the dt value of this `QkTarget`. - + - #### Example +### Example - ```c - QkTarget *target = qk_target_new(5); - qk_target_set_dt(target, 10e-9); - double dt = qk_target_dt(target); - ``` +```c +QkTarget *target = qk_target_new(5); +qk_target_set_dt(target, 10e-9); +double dt = qk_target_dt(target); +``` - + - #### Safety +### Safety - + - Behavior is undefined if `QkTarget` is not a valid, non-null pointer to a `QkTarget`. +Behavior is undefined if `QkTarget` is not a valid, non-null pointer to a `QkTarget`. - **Parameters** +**Parameters** - **target** – A pointer to the `QkTarget`. +* **target** – A pointer to the `QkTarget`. - **Returns** +**Returns** - The dt value of this `QkTarget` or `NAN` if not assigned. - +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`. +Returns the granularity value of this `QkTarget`. - + - #### Example +### Example - ```c - QkTarget *target = qk_target_new(5); - // The value defaults to 1 - uint32_t granularity = qk_target_granularity(target); - ``` +```c +QkTarget *target = qk_target_new(5); +// The value defaults to 1 +uint32_t granularity = qk_target_granularity(target); +``` - + - #### Safety +### Safety - + - Behavior is undefined if `QkTarget` is not a valid, non-null pointer to a `QkTarget`. +Behavior is undefined if `QkTarget` is not a valid, non-null pointer to a `QkTarget`. - **Parameters** +**Parameters** - **target** – A pointer to the `QkTarget`. +* **target** – A pointer to the `QkTarget`. - **Returns** +**Returns** - The `granularity` value of this `QkTarget`. - +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`. +Returns the `min_length` value of this `QkTarget`. - + - #### Example +### Example - ```c - QkTarget *target = qk_target_new(5); - // The value defaults to 1 - size_t min_length = qk_target_min_length(target); - ``` +```c +QkTarget *target = qk_target_new(5); +// The value defaults to 1 +size_t min_length = qk_target_min_length(target); +``` - + - #### Safety +### Safety - + - Behavior is undefined if `QkTarget` is not a valid, non-null pointer to a `QkTarget`. +Behavior is undefined if `QkTarget` is not a valid, non-null pointer to a `QkTarget`. - **Parameters** +**Parameters** - **target** – A pointer to the `QkTarget`. +* **target** – A pointer to the `QkTarget`. - **Returns** +**Returns** - The `min_length` value of this `QkTarget`. - +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`. +Returns the `pulse_alignment` value of this `QkTarget`. - + - #### Example +### Example - ```c - QkTarget *target = qk_target_new(5); - // The value defaults to 1 - uint32_t pulse_alignment = qk_target_pulse_alignment(target); - ``` +```c +QkTarget *target = qk_target_new(5); +// The value defaults to 1 +uint32_t pulse_alignment = qk_target_pulse_alignment(target); +``` - + - #### Safety +### Safety - + - Behavior is undefined if `QkTarget` is not a valid, non-null pointer to a `QkTarget`. +Behavior is undefined if `QkTarget` is not a valid, non-null pointer to a `QkTarget`. - **Parameters** +**Parameters** - **target** – A pointer to the `QkTarget`. +* **target** – A pointer to the `QkTarget`. - **Returns** +**Returns** - The `pulse_alignment` value of this `QkTarget`. - +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`. +Returns the `acquire_alignment` value of this `QkTarget`. - + - #### Example +### Example - ```c - QkTarget *target = qk_target_new(5); - // The value defaults to 0 - uint32_t acquire_alignment = qk_target_pulse_alignment(target); - ``` +```c +QkTarget *target = qk_target_new(5); +// The value defaults to 0 +uint32_t acquire_alignment = qk_target_pulse_alignment(target); +``` - + - #### Safety +### Safety - + - Behavior is undefined if `QkTarget` is not a valid, non-null pointer to a `QkTarget`. +Behavior is undefined if `QkTarget` is not a valid, non-null pointer to a `QkTarget`. - **Parameters** +**Parameters** - **target** – A pointer to the `QkTarget`. +* **target** – A pointer to the `QkTarget`. - **Returns** +**Returns** - The `acquire_alignment` value of this `QkTarget`. - +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`. +Sets the dt value of this `QkTarget`. - + - #### Example +### Example - ```c - QkTarget *target = qk_target_new(5); - double dt = qk_target_set_dt(target, 10e-9); - ``` +```c +QkTarget *target = qk_target_new(5); +double dt = qk_target_set_dt(target, 10e-9); +``` - + - #### Safety +### Safety - + - Behavior is undefined if `QkTarget` is not a valid, non-null pointer to a `QkTarget`. +Behavior is undefined if `QkTarget` is not a valid, non-null pointer to a `QkTarget`. - **Parameters** +**Parameters** - * **target** – A pointer to the `QkTarget`. - * **dt** – The `dt` value for the system time resolution of input. +* **target** – A pointer to the `QkTarget`. +* **dt** – The `dt` value for the system time resolution of input. - **Returns** +**Returns** - `QkExitCode` specifying if the operation was successful. - +`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`. +Sets the `granularity` value of this `QkTarget`. - + - #### Example +### Example - ```c - QkTarget *target = qk_target_new(5); - // The value defaults to 1 - qk_target_set_granularity(target, 2); - ``` +```c +QkTarget *target = qk_target_new(5); +// The value defaults to 1 +qk_target_set_granularity(target, 2); +``` - + - #### Safety +### Safety - + - Behavior is undefined if `QkTarget` is not a valid, non-null pointer to a `QkTarget`. +Behavior is undefined if `QkTarget` is not a valid, non-null pointer to a `QkTarget`. - **Parameters** +**Parameters** - * **target** – A pointer to the `QkTarget`. - * **granularity** – The value for the minimum pulse gate resolution in units of `dt`. +* **target** – A pointer to the `QkTarget`. +* **granularity** – The value for the minimum pulse gate resolution in units of `dt`. - **Returns** +**Returns** - `QkExitCode` specifying if the operation was successful. - +`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`. +Sets the `min_length` value of this `QkTarget`. - + - #### Example +### Example - ```c - QkTarget *target = qk_target_new(5); - // The value defaults to 1 - qk_target_set_min_length(target, 3); - ``` +```c +QkTarget *target = qk_target_new(5); +// The value defaults to 1 +qk_target_set_min_length(target, 3); +``` - + - #### Safety +### Safety - + - Behavior is undefined if `QkTarget` is not a valid, non-null pointer to a `QkTarget`. +Behavior is undefined if `QkTarget` is not a valid, non-null pointer to a `QkTarget`. - **Parameters** +**Parameters** - * **target** – A pointer to the `QkTarget`. - * **min\_length** – The minimum pulse gate length value in units of `dt`. +* **target** – A pointer to the `QkTarget`. +* **min\_length** – The minimum pulse gate length value in units of `dt`. - **Returns** +**Returns** - `QkExitCode` specifying if the operation was successful. - +`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`. +Returns the `pulse_alignment` value of this `QkTarget`. - + - #### Example +### Example - ```c - QkTarget *target = qk_target_new(5); - // The value defaults to 1 - qk_target_set_pulse_alignment(target, 4); - ``` +```c +QkTarget *target = qk_target_new(5); +// The value defaults to 1 +qk_target_set_pulse_alignment(target, 4); +``` - + - #### Safety +### Safety - + - Behavior is undefined if `QkTarget` is not a valid, non-null pointer to a `QkTarget`. +Behavior is undefined if `QkTarget` is not a valid, non-null pointer to a `QkTarget`. - **Parameters** +**Parameters** - * **target** – A pointer to the `QkTarget`. - * **pulse\_alignment** – value representing a time resolution of gate. +* **target** – A pointer to the `QkTarget`. +* **pulse\_alignment** – value representing a time resolution of gate. - **Returns** +**Returns** - `QkExitCode` specifying if the operation was successful. - +`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`. +Sets the `acquire_alignment` value of this `QkTarget`. - + - #### Example +### Example - ```c - QkTarget *target = qk_target_new(5); - // The value defaults to 0 - qk_target_set_acquire_alignment(target, 5); - ``` +```c +QkTarget *target = qk_target_new(5); +// The value defaults to 0 +qk_target_set_acquire_alignment(target, 5); +``` - + - #### Safety +### Safety - + - Behavior is undefined if `QkTarget` is not a valid, non-null pointer to a `QkTarget`. +Behavior is undefined if `QkTarget` is not a valid, non-null pointer to a `QkTarget`. - **Parameters** +**Parameters** - * **target** – A pointer to the `QkTarget`. - * **acquire\_alignment** – value representing a time resolution of measure instruction starting time. +* **target** – A pointer to the `QkTarget`. +* **acquire\_alignment** – value representing a time resolution of measure instruction starting time. - **Returns** +**Returns** - `QkExitCode` specifying if the operation was successful. - +`QkExitCode` specifying if the operation was successful. -### qk\_target\_copy +**QkTarget \*qk\_target\_copy(QkTarget \*target)** - - Creates a copy of the `QkTarget`. +Creates a copy of the `QkTarget`. - + - #### Example +### 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); +```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); - ``` +QkTarget *copied = qk_target_copy(target); +``` - + - #### Safety +### Safety - + - Behavior is undefined if `QkTarget` is not a valid, non-null pointer to a `QkTarget`. +Behavior is undefined if `QkTarget` is not a valid, non-null pointer to a `QkTarget`. - **Parameters** +**Parameters** - **target** – A pointer to the `QkTarget` to copy. +* **target** – A pointer to the `QkTarget` to copy. - **Returns** +**Returns** - A pointer to the new copy of the `QkTarget`. - +A pointer to the new copy of the `QkTarget`. -### qk\_target\_free +**void qk\_target\_free(QkTarget \*target)** - - Free the `QkTarget`. +Free the `QkTarget`. - + - #### Example +### Example - ```c - QkTarget *target = qk_target_new(5); - qk_target_free(target); - ``` +```c +QkTarget *target = qk_target_new(5); +qk_target_free(target); +``` - + - #### Safety +### Safety - + - Behavior is undefined if `QkTarget` is not a valid, non-null pointer to a `QkTarget`. +Behavior is undefined if `QkTarget` is not a valid, non-null pointer to a `QkTarget`. - **Parameters** +**Parameters** - **target** – A pointer to the `QkTarget` to free. - +* **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`. +Adds a gate to the `QkTarget` through a `QkTargetEntry`. - + - #### Example +### 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); - ``` +```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 +### Safety - + - Behavior is undefined if `QkTarget` is not a valid, non-null pointer to a `QkTarget`. +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`. +Behavior is undefined if `entry` is not a valid, non-null pointer to a `QkTargetEntry`. - **Parameters** +**Parameters** - * **target** – A pointer to the `QkTarget`. - * **target\_entry** – A pointer to the `QkTargetEntry`. The pointer gets freed when added to the `QkTarget`. +* **target** – A pointer to the `QkTarget`. +* **target\_entry** – A pointer to the `QkTargetEntry`. The pointer gets freed when added to the `QkTarget`. - **Returns** +**Returns** - `QkExitCode` specifying if the operation was successful. - +`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`. +Modifies the properties of a gate in the `QkTarget`. - + - #### Example +### 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); +```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); - ``` +qk_target_update_property(target, QkGate_CRX, qargs, 2, 0.0012, 1.1); +``` - + - #### Safety +### Safety - + - Behavior is undefined if `QkTarget` is not a valid, non-null pointer to a `QkTarget`. +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. +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** +**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. +* **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** +**Returns** - `QkExitCode` specifying if the operation was successful. - +`QkExitCode` specifying if the operation was successful. -### qk\_target\_num\_instructions +**size\_t qk\_target\_num\_instructions(const QkTarget \*target)** - - Returns the number of instructions tracked by a `QkTarget`. +Returns the number of instructions tracked by a `QkTarget`. - + - #### Example +### Example - ```c - QkTarget *target = qk_target_new(5); - QkTargetEntry *target_entry = qk_target_entry_new(QkGate_H); - qk_target_add_instruction(target, target_entry); +```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); - ``` +size_t num_instructions = qk_target_num_instructions(target); +``` - + - #### Safety +### Safety - + - Behavior is undefined if `QkTarget` is not a valid, non-null pointer to a `QkTarget`. +Behavior is undefined if `QkTarget` is not a valid, non-null pointer to a `QkTarget`. - **Parameters** +**Parameters** - **target** – A pointer to the `QkTarget`. +* **target** – A pointer to the `QkTarget`. - **Returns** +**Returns** - The length of the target. - +The length of the target. diff --git a/docs/api/qiskit-c/dev/qk-transpile-layout.mdx b/docs/api/qiskit-c/dev/qk-transpile-layout.mdx index 05aae8d2e43..76d37bc7072 100644 --- a/docs/api/qiskit-c/dev/qk-transpile-layout.mdx +++ b/docs/api/qiskit-c/dev/qk-transpile-layout.mdx @@ -74,156 +74,144 @@ The transpiler will also allocate ancilla qubits to the circuit if the target ha ## Functions -### qk\_transpile\_layout\_num\_input\_qubits +**uint32\_t qk\_transpile\_layout\_num\_input\_qubits(const QkTranspileLayout \*layout)** - - Return the number of qubits in the input circuit to the transpiler. +Return the number of qubits in the input circuit to the transpiler. - + - #### Safety +### Safety - + - Behavior is undefined if `layout` is not a valid, non-null pointer to a `QkTranspileLayout`. +Behavior is undefined if `layout` is not a valid, non-null pointer to a `QkTranspileLayout`. - **Parameters** +**Parameters** - **layout** – A pointer to the `QkTranspileLayout`. +* **layout** – A pointer to the `QkTranspileLayout`. - **Returns** +**Returns** - The number of input qubits - +The number of input qubits -### qk\_transpile\_layout\_num\_output\_qubits +**uint32\_t qk\_transpile\_layout\_num\_output\_qubits(const QkTranspileLayout \*layout)** - - Return the number of qubits in the output circuit from the transpiler. +Return the number of qubits in the output circuit from the transpiler. - + - #### Safety +### Safety - + - Behavior is undefined if `layout` is not a valid, non-null pointer to a `QkTranspileLayout`. +Behavior is undefined if `layout` is not a valid, non-null pointer to a `QkTranspileLayout`. - **Parameters** +**Parameters** - **layout** – A pointer to the `QkTranspileLayout`. +* **layout** – A pointer to the `QkTranspileLayout`. - **Returns** +**Returns** - The number of output qubits - +The number of output qubits -### qk\_transpile\_layout\_initial\_layout +**bool qk\_transpile\_layout\_initial\_layout(const QkTranspileLayout \*layout, bool filter\_ancillas, uint32\_t \*initial\_layout)** - - Query the initial layout of a `QkTranspileLayout`. +Query the initial layout of a `QkTranspileLayout`. - The output array from this function represents the mapping from the virutal qubits in the original input circuit to the physical qubit in the output circuit. The index in the array is the virtual qubit and the value is the physical qubit. For example an output array of: +The output array from this function represents the mapping from the virutal qubits in the original input circuit to the physical qubit in the output circuit. The index in the array is the virtual qubit and the value is the physical qubit. For example an output array of: - ```c - [1, 0, 2] - ``` +```c +[1, 0, 2] +``` - indicates that the layout maps virtual qubit 0 -> physical qubit 1, virtual qubit 1 -> physical qubit -> 0, and virtual qubit 2 -> physical qubit 2. +indicates that the layout maps virtual qubit 0 -> physical qubit 1, virtual qubit 1 -> physical qubit -> 0, and virtual qubit 2 -> physical qubit 2. - + - #### Safety +### Safety - + - Behavior is undefined if `layout` is not a valid, non-null pointer to a `QkTranspileLayout`. `initial_layout` must be a valid, non-null pointer with a large enough allocation to store the size necessary for the initial layout. If `filter_ancillas` is true this will be number of input qubits (which can be checked with `qk_transpile_layout_num_input_qubits()`) or the number of output qubits if `filter_ancillas` is false (which can be queried with `qk_transpile_layout_num_output_qubits()`). +Behavior is undefined if `layout` is not a valid, non-null pointer to a `QkTranspileLayout`. `initial_layout` must be a valid, non-null pointer with a large enough allocation to store the size necessary for the initial layout. If `filter_ancillas` is true this will be number of input qubits (which can be checked with `qk_transpile_layout_num_input_qubits()`) or the number of output qubits if `filter_ancillas` is false (which can be queried with `qk_transpile_layout_num_output_qubits()`). - **Parameters** +**Parameters** - * **layout** – A pointer to the `QkTranspileLayout`. - * **filter\_ancillas** – If set to true the output array will not include any indicies for any ancillas added by the transpiler. - * **initial\_layout** – A pointer to the array where this function will write the initial layout to. This must have sufficient space for the full array which will either be `qk_transpile_layout_num_input_qubits()` or `qk_transpile_layout_num_output_qubits()` for `filter_ancillas` being true or false respectively. +* **layout** – A pointer to the `QkTranspileLayout`. +* **filter\_ancillas** – If set to true the output array will not include any indicies for any ancillas added by the transpiler. +* **initial\_layout** – A pointer to the array where this function will write the initial layout to. This must have sufficient space for the full array which will either be `qk_transpile_layout_num_input_qubits()` or `qk_transpile_layout_num_output_qubits()` for `filter_ancillas` being true or false respectively. - **Returns** +**Returns** - True if there was a initial\_layout written to `initial_layout` and false if there is no initial layout. - +True if there was a initial\_layout written to `initial_layout` and false if there is no initial layout. -### qk\_transpile\_layout\_output\_permutation +**bool qk\_transpile\_layout\_output\_permutation(const QkTranspileLayout \*layout, uint32\_t \*output\_permutation)** - - Query the output permutation of a `QkTranspileLayout` +Query the output permutation of a `QkTranspileLayout` - The output array from this function represents the permutation induced by the transpiler where the index indicates the qubit at the start of the circuit and the value is the position of the qubit at the end of the circuit. For example an output array of: +The output array from this function represents the permutation induced by the transpiler where the index indicates the qubit at the start of the circuit and the value is the position of the qubit at the end of the circuit. For example an output array of: - ```c - [1, 2, 0] - ``` +```c +[1, 2, 0] +``` - indicates that qubit 0 from the start of the circuit is at qubit 1 at the end of the circuit, 1 -> 2, and 2 -> 0. +indicates that qubit 0 from the start of the circuit is at qubit 1 at the end of the circuit, 1 -> 2, and 2 -> 0. - + - #### Safety +### Safety - + - Behavior is undefined if `layout` is not a valid, non-null pointer to a `QkTranspileLayout`. `output_permutation` must be a valid, non-null pointer with a large enough allocation to store the size necessary for the output\_permutation. This will always be the number of output qubits in the `QkTranspileLayout` which can be queried with `qk_transpile_layout_num_output_qubits()`. +Behavior is undefined if `layout` is not a valid, non-null pointer to a `QkTranspileLayout`. `output_permutation` must be a valid, non-null pointer with a large enough allocation to store the size necessary for the output\_permutation. This will always be the number of output qubits in the `QkTranspileLayout` which can be queried with `qk_transpile_layout_num_output_qubits()`. - **Parameters** +**Parameters** - * **layout** – A pointer to the `QkTranspileLayout`. - * **output\_permutation** – A pointer to the array where this function will write the output permutation to. This must have sufficient space for the output which will be the number of output qubits in the layout. This can be queried with `qk_transpile_layout_num_output_qubits`. +* **layout** – A pointer to the `QkTranspileLayout`. +* **output\_permutation** – A pointer to the array where this function will write the output permutation to. This must have sufficient space for the output which will be the number of output qubits in the layout. This can be queried with `qk_transpile_layout_num_output_qubits`. - **Returns** +**Returns** - True if there is an output permutation that was written to `output_permutation` false if the `QkTranspileLayout` does not contain an output permutation. - +True if there is an output permutation that was written to `output_permutation` false if the `QkTranspileLayout` does not contain an output permutation. -### qk\_transpile\_layout\_final\_layout +**void qk\_transpile\_layout\_final\_layout(const QkTranspileLayout \*layout, bool filter\_ancillas, uint32\_t \*final\_layout)** - - Query the final layout of a `QkTranspileLayout` +Query the final layout of a `QkTranspileLayout` - The output array represents the mapping from the virtual qubit in the original input circuit to the physical qubit at the end of the transpile circuit that has that qubit’s state. The array index represents the virtual qubit and the value represents the physical qubit at the end of the transpiled circuit which has that virtual qubit’s state. For example, an output array of: +The output array represents the mapping from the virtual qubit in the original input circuit to the physical qubit at the end of the transpile circuit that has that qubit’s state. The array index represents the virtual qubit and the value represents the physical qubit at the end of the transpiled circuit which has that virtual qubit’s state. For example, an output array of: - ```c - [2, 0, 1] - ``` +```c +[2, 0, 1] +``` - indicates that virtual qubit 0’s state in the original circuit is on physical qubit 2 at the end of the transpiled circuit, 1 -> 0, and 2 -> 1. +indicates that virtual qubit 0’s state in the original circuit is on physical qubit 2 at the end of the transpiled circuit, 1 -> 0, and 2 -> 1. - + - #### Safety +### Safety - + - Behavior is undefined if `layout` is not a valid, non-null pointer to a `QkTranspileLayout`. `final_layout` must be a valid, non-null pointer with a large enough allocation to store the size necessary for the final layout. If `filter_ancillas` is true this will be number of input qubits (which can be checked with `qk_transpile_layout_num_input_qubits()`) or the number of output qubits if `filter_ancillas` is false (which can be queried with `qk_transpile_layout_num_output_qubits()`). +Behavior is undefined if `layout` is not a valid, non-null pointer to a `QkTranspileLayout`. `final_layout` must be a valid, non-null pointer with a large enough allocation to store the size necessary for the final layout. If `filter_ancillas` is true this will be number of input qubits (which can be checked with `qk_transpile_layout_num_input_qubits()`) or the number of output qubits if `filter_ancillas` is false (which can be queried with `qk_transpile_layout_num_output_qubits()`). - **Parameters** +**Parameters** - * **layout** – A pointer to the `QkTranspileLayout`. - * **filter\_ancillas** – If set to true the output array will not include any indicies for any ancillas added by the transpiler. - * **final\_layout** – A pointer to the array where this function will write the final layout to. This must have sufficient space for the output which will either be the number of input or output qubits depending on the value of filter\_ancillas. - +* **layout** – A pointer to the `QkTranspileLayout`. +* **filter\_ancillas** – If set to true the output array will not include any indicies for any ancillas added by the transpiler. +* **final\_layout** – A pointer to the array where this function will write the final layout to. This must have sufficient space for the output which will either be the number of input or output qubits depending on the value of filter\_ancillas. -### qk\_transpile\_layout\_free +**void qk\_transpile\_layout\_free(QkTranspileLayout \*layout)** - - Free a `QkTranspileLayout` object +Free a `QkTranspileLayout` object - + - #### Safety +### Safety - + - Behavior is undefined if `layout` is not a valid, non-null pointer to a `QkTranspileLayout`. +Behavior is undefined if `layout` is not a valid, non-null pointer to a `QkTranspileLayout`. - **Parameters** +**Parameters** - **layout** – a pointer to the layout to free - +* **layout** – a pointer to the layout to free diff --git a/docs/api/qiskit-c/dev/qk-transpiler-passes.mdx b/docs/api/qiskit-c/dev/qk-transpiler-passes.mdx index 9ff6b30991d..f67603596ea 100644 --- a/docs/api/qiskit-c/dev/qk-transpiler-passes.mdx +++ b/docs/api/qiskit-c/dev/qk-transpiler-passes.mdx @@ -18,397 +18,378 @@ The Qiskit C API provides functions that execute transpiler passes in a standalo ## Functions -### qk\_transpiler\_pass\_standalone\_basis\_translator +**void qk\_transpiler\_pass\_standalone\_basis\_translator(QkCircuit \*circuit, const QkTarget \*target, size\_t min\_qubits)** - - Run the BasisTranslator transpiler pass on a circuit. +Run the BasisTranslator transpiler pass on a circuit. - The BasisTranslator transpiler pass translates gates to a target basis by searching for a set of translations from the standard EquivalenceLibrary. +The BasisTranslator transpiler pass translates gates to a target basis by searching for a set of translations from the standard EquivalenceLibrary. - + - #### Example +### Example - ```c - #include +```c +#include - QkCircuit *circuit = qk_circuit_new(3, 0); - qk_circuit_gate(circuit, QkGate_CCX, (uint32_t[3]){0, 1, 2}, NULL); +QkCircuit *circuit = qk_circuit_new(3, 0); +qk_circuit_gate(circuit, QkGate_CCX, (uint32_t[3]){0, 1, 2}, NULL); - // Create a Target with global properties. - QkTarget *target = qk_target_new(3); - qk_target_add_instruction(target, qk_target_entry_new(QkGate_H)); - qk_target_add_instruction(target, qk_target_entry_new(QkGate_T)); - qk_target_add_instruction(target, qk_target_entry_new(QkGate_Tdg)); - qk_target_add_instruction(target, qk_target_entry_new(QkGate_CX)); +// Create a Target with global properties. +QkTarget *target = qk_target_new(3); +qk_target_add_instruction(target, qk_target_entry_new(QkGate_H)); +qk_target_add_instruction(target, qk_target_entry_new(QkGate_T)); +qk_target_add_instruction(target, qk_target_entry_new(QkGate_Tdg)); +qk_target_add_instruction(target, qk_target_entry_new(QkGate_CX)); - // Run pass - qk_transpiler_pass_standalone_basis_translator(circuit, target, 0); +// Run pass +qk_transpiler_pass_standalone_basis_translator(circuit, target, 0); - // Free the circuit and target pointers once you're done - qk_circuit_free(circuit); - qk_target_free(target); - ``` +// Free the circuit and target pointers once you're done +qk_circuit_free(circuit); +qk_target_free(target); +``` - + - #### Safety +### Safety - + - Behavior is undefined if `circuit` and/or `target` are not valid, non-null pointers to a `QkCircuit` or `QkTarget`. +Behavior is undefined if `circuit` and/or `target` are not valid, non-null pointers to a `QkCircuit` or `QkTarget`. - **Parameters** +**Parameters** - * **circuit** – A pointer to the circuit to run BasisTranslator on. The circuit will be mutated in-place, unless the circuit is already in the target basis, in which case the circuit remains unchanged. - * **target** – The target where we will obtain basis gates from. - * **min\_qubits** – The minimum number of qubits for operations in the input ciruit to translate. - +* **circuit** – A pointer to the circuit to run BasisTranslator on. The circuit will be mutated in-place, unless the circuit is already in the target basis, in which case the circuit remains unchanged. +* **target** – The target where we will obtain basis gates from. +* **min\_qubits** – The minimum number of qubits for operations in the input ciruit to translate. -### qk\_transpiler\_pass\_standalone\_commutative\_cancellation +**QkExitCode qk\_transpiler\_pass\_standalone\_commutative\_cancellation(QkCircuit \*circuit, const QkTarget \*target, double approximation\_degree)** - - Run the CommutativeCancellation transpiler pass on a circuit. +Run the CommutativeCancellation transpiler pass on a circuit. - This pass cancels the redundant (self-adjoint) gates through commutation relations. +This pass cancels the redundant (self-adjoint) gates through commutation relations. - + - #### Example +### Example - ```c - QkCircuit *qc = qk_circuit_new(4, 0); - uint32_t cx_qargs[2] = {0, 1}; - qk_circuit_gate(qc, QkGate_CX, cx_qargs, NULL); - qk_circuit_gate(qc, QkGate_Z, (uint32_t[]){0}, NULL); - qk_circuit_gate(qc, QkGate_CX, cx_qargs, NULL); - qk_transpiler_pass_standalone_commutative_cancellation(qc, NULL, 1.0); - ``` +```c +QkCircuit *qc = qk_circuit_new(4, 0); +uint32_t cx_qargs[2] = {0, 1}; +qk_circuit_gate(qc, QkGate_CX, cx_qargs, NULL); +qk_circuit_gate(qc, QkGate_Z, (uint32_t[]){0}, NULL); +qk_circuit_gate(qc, QkGate_CX, cx_qargs, NULL); +qk_transpiler_pass_standalone_commutative_cancellation(qc, NULL, 1.0); +``` - + - #### Safety +### Safety - + - Behavior is undefined if `circuit` or `target` is not a valid, `QkCircuit` and `QkTarget`. `QkCircuit` is not expected to be null and behavior is undefined if it is. +Behavior is undefined if `circuit` or `target` is not a valid, `QkCircuit` and `QkTarget`. `QkCircuit` is not expected to be null and behavior is undefined if it is. - **Parameters** +**Parameters** - * **circuit** – A pointer to the circuit to run CommutativeCancellation on. This circuit pointer to will be updated with the modified circuit if the pass is able to remove any gates. - * **target** – This pass will attempt to accumulate all Z rotations into either an RZ, P or U1 gate, depending on which is already used in the circuit. If none is present in the circuit, this (optional) target argument is used as fallback to decide which gate to use. If none of RZ, P or U1 are in the circuit or the target, single-qubit Z rotations will not be optimized. - * **approximation\_degree** – The approximation degree used when analyzing commutations. Must be within `(0, 1]`. +* **circuit** – A pointer to the circuit to run CommutativeCancellation on. This circuit pointer to will be updated with the modified circuit if the pass is able to remove any gates. +* **target** – This pass will attempt to accumulate all Z rotations into either an RZ, P or U1 gate, depending on which is already used in the circuit. If none is present in the circuit, this (optional) target argument is used as fallback to decide which gate to use. If none of RZ, P or U1 are in the circuit or the target, single-qubit Z rotations will not be optimized. +* **approximation\_degree** – The approximation degree used when analyzing commutations. Must be within `(0, 1]`. - **Returns** +**Returns** - The integer return code where 0 represents no error and 1 is used to indicate an error was encountered during the execution of the pass. - +The integer return code where 0 represents no error and 1 is used to indicate an error was encountered during the execution of the pass. -### qk\_transpiler\_pass\_standalone\_consolidate\_blocks +**void qk\_transpiler\_pass\_standalone\_consolidate\_blocks(QkCircuit \*circuit, const QkTarget \*target, double approximation\_degree, bool force\_consolidate)** - - Run the ConsolidateBlocks pass on a circuit. +Run the ConsolidateBlocks pass on a circuit. - ConsolidateBlocks is a transpiler pass that consolidates consecutive blocks of gates operating on the same qubits into a Unitary gate, to later on be resynthesized, which leads to a more optimal subcircuit. +ConsolidateBlocks is a transpiler pass that consolidates consecutive blocks of gates operating on the same qubits into a Unitary gate, to later on be resynthesized, which leads to a more optimal subcircuit. - + - #### Safety +### Safety - + - Behavior is undefined if `circuit` is not a valid, non-null pointer to a `QkCircuit` and if `target` is not a valid pointer to a `QkTarget`. +Behavior is undefined if `circuit` is not a valid, non-null pointer to a `QkCircuit` and if `target` is not a valid pointer to a `QkTarget`. - **Parameters** +**Parameters** - * **circuit** – A pointer to the circuit to run ConsolidateBlocks on. - * **target** – A pointer to the target to run ConsolidateBlocks on. - * **approximation\_degree** – A float between `[0.0, 1.0]` or a `NaN` which defaults to `1.0`. Lower approximates more. - * **force\_consolidate** – Force block consolidation. - +* **circuit** – A pointer to the circuit to run ConsolidateBlocks on. +* **target** – A pointer to the target to run ConsolidateBlocks on. +* **approximation\_degree** – A float between `[0.0, 1.0]` or a `NaN` which defaults to `1.0`. Lower approximates more. +* **force\_consolidate** – Force block consolidation. -### qk\_transpiler\_pass\_standalone\_elide\_permutations +**QkTranspileLayout \*qk\_transpiler\_pass\_standalone\_elide\_permutations(QkCircuit \*circuit)** - - Run the ElidePermutations transpiler pass on a circuit. +Run the ElidePermutations transpiler pass on a circuit. - The ElidePermutations transpiler pass removes any permutation operations from a pre-layout circuit. +The ElidePermutations transpiler pass removes any permutation operations from a pre-layout circuit. - This pass is intended to be run before a layout (mapping virtual qubits to physical qubits) is set during the transpilation pipeline. This pass iterates over the circuit and when a Swap gate is encountered it permutes the virtual qubits in the circuit and removes the swap gate. This will effectively remove any swap gates in the circuit prior to running layout. This optimization is not valid after a layout has been set and should not be run in this case. +This pass is intended to be run before a layout (mapping virtual qubits to physical qubits) is set during the transpilation pipeline. This pass iterates over the circuit and when a Swap gate is encountered it permutes the virtual qubits in the circuit and removes the swap gate. This will effectively remove any swap gates in the circuit prior to running layout. This optimization is not valid after a layout has been set and should not be run in this case. - + - #### Example +### Example - ```c - QkCircuit *qc = qk_circuit_new(4, 0); - for (uint32_t i = 0; i < qk_circuit_num_qubits(qc) - 1; i++) { - uint32_t qargs[2] = {i, i + 1}; - for (uint32_t j = 0; j + - #### Safety +### Safety - + - Behavior is undefined if `circuit` is not a valid, non-null pointer to a `QkCircuit`. +Behavior is undefined if `circuit` is not a valid, non-null pointer to a `QkCircuit`. - **Parameters** +**Parameters** - **circuit** – A pointer to the circuit to run ElidePermutations on. If there are changes made the object pointed to is changed in place. In case of gates being elided the original circuit’s allocations are freed by this function. +* **circuit** – A pointer to the circuit to run ElidePermutations on. If there are changes made the object pointed to is changed in place. In case of gates being elided the original circuit’s allocations are freed by this function. - **Returns** +**Returns** - the layout object containing the output permutation induced by the elided gates in the circuit. If no elisions are performed this will be a null pointer and the input circuit is unchanged. - +the layout object containing the output permutation induced by the elided gates in the circuit. If no elisions are performed this will be a null pointer and the input circuit is unchanged. -### qk\_transpiler\_pass\_standalone\_check\_gate\_direction +**bool qk\_transpiler\_pass\_standalone\_check\_gate\_direction(const QkCircuit \*circuit, const QkTarget \*target)** - - Run the `CheckGateDirection` pass on a circuit. +Run the `CheckGateDirection` pass on a circuit. - The pass checks if the directions of two-qubit gates comply with the gate directions specified in a given target. +The pass checks if the directions of two-qubit gates comply with the gate directions specified in a given target. - + - #### Example +### Example - ```c - QkTarget *target = qk_target_new(2); - uint32_t qargs[3] = {0,1}; +```c +QkTarget *target = qk_target_new(2); +uint32_t qargs[3] = {0,1}; - QkTargetEntry *cx_entry = qk_target_entry_new(QkGate_CX); - qk_target_entry_add_property(cx_entry, qargs, 2, 0.0, 0.0); - qk_target_add_instruction(target, cx_entry); +QkTargetEntry *cx_entry = qk_target_entry_new(QkGate_CX); +qk_target_entry_add_property(cx_entry, qargs, 2, 0.0, 0.0); +qk_target_add_instruction(target, cx_entry); - QkCircuit *circuit = qk_circuit_new(2, 0); - qk_circuit_gate(circuit, QkGate_CX, (uint32_t[]){1,0}, NULL); +QkCircuit *circuit = qk_circuit_new(2, 0); +qk_circuit_gate(circuit, QkGate_CX, (uint32_t[]){1,0}, NULL); - bool direction_ok = qk_transpiler_pass_standalone_check_gate_direction(circuit, target); - ``` +bool direction_ok = qk_transpiler_pass_standalone_check_gate_direction(circuit, target); +``` - + - #### Safety +### Safety - + - Behavior is undefined if `circuit` or `target` are not valid, non-null pointers to `QkCircuit` and `QkTarget` objects, respectively. +Behavior is undefined if `circuit` or `target` are not valid, non-null pointers to `QkCircuit` and `QkTarget` objects, respectively. - **Parameters** +**Parameters** - * **circuit** – A pointer to the circuit on which to run the CheckGateDirection pass. - * **target** – A pointer to the target used for checking gate directions. +* **circuit** – A pointer to the circuit on which to run the CheckGateDirection pass. +* **target** – A pointer to the target used for checking gate directions. - **Returns** +**Returns** - bool - true iff the directions of all two-qubit gates in the circuit comply with the specified target constraints. - +bool - true iff the directions of all two-qubit gates in the circuit comply with the specified target constraints. -### qk\_transpiler\_pass\_standalone\_gate\_direction +**void qk\_transpiler\_pass\_standalone\_gate\_direction(QkCircuit \*circuit, const QkTarget \*target)** - - Run the `GateDirection` pass on a circuit. +Run the `GateDirection` pass on a circuit. - The GateDirection pass modifies asymmetric gates to match the hardware coupling directions. This pass supports replacements for the `cx`, `cz`, `ecr`, `swap`, `rzx`, `rxx`, `ryy` and `rzz` gates, using predefined identities. +The GateDirection pass modifies asymmetric gates to match the hardware coupling directions. This pass supports replacements for the `cx`, `cz`, `ecr`, `swap`, `rzx`, `rxx`, `ryy` and `rzz` gates, using predefined identities. - + - #### Example +### Example - ```c - QkTarget *target = qk_target_new(3); +```c +QkTarget *target = qk_target_new(3); - uint32_t qargs[2] = {0,1}; +uint32_t qargs[2] = {0,1}; - QkTargetEntry *cx_entry = qk_target_entry_new(QkGate_CX); - qk_target_entry_add_property(cx_entry, qargs, 2, 0.0, 0.0); - qk_target_add_instruction(target, cx_entry); +QkTargetEntry *cx_entry = qk_target_entry_new(QkGate_CX); +qk_target_entry_add_property(cx_entry, qargs, 2, 0.0, 0.0); +qk_target_add_instruction(target, cx_entry); - QkCircuit *circuit = qk_circuit_new(3, 0); - qk_circuit_gate(circuit, QkGate_CX, (uint32_t[]){1,0}, NULL); +QkCircuit *circuit = qk_circuit_new(3, 0); +qk_circuit_gate(circuit, QkGate_CX, (uint32_t[]){1,0}, NULL); - qk_transpiler_pass_standalone_gate_direction(circuit, target); - ``` +qk_transpiler_pass_standalone_gate_direction(circuit, target); +``` - + - #### Safety +### Safety - + - Behavior is undefined if `circuit` or `target` are not valid, non-null pointers to `QkCircuit` and `QkTarget` objects, respectively. +Behavior is undefined if `circuit` or `target` are not valid, non-null pointers to `QkCircuit` and `QkTarget` objects, respectively. - **Parameters** +**Parameters** - * **circuit** – A pointer to the circuit on which to run the GateDirection pass. The circuit will be modified in place by the pass. - * **target** – A pointer to the target used for checking gate directions. - +* **circuit** – A pointer to the circuit on which to run the GateDirection pass. The circuit will be modified in place by the pass. +* **target** – A pointer to the target used for checking gate directions. -### qk\_transpiler\_pass\_standalone\_inverse\_cancellation +**void qk\_transpiler\_pass\_standalone\_inverse\_cancellation(QkCircuit \*circuit)** - - Run the InverseCancellation transpiler pass on a circuit. +Run the InverseCancellation transpiler pass on a circuit. - Cancels pairs of consecutive gates that are inverses of each other. The cancelled gates consist of pairs of self-inverse gates: +Cancels pairs of consecutive gates that are inverses of each other. The cancelled gates consist of pairs of self-inverse gates: - * QkGate\_H - * QkGate\_X - * QkGate\_Y - * QkGate\_Z - * QkGate\_CH - * QkGate\_CX - * QkGate\_CY - * QkGate\_CZ - * QkGate\_ECR - * QkGate\_Swap - * QkGate\_CCX - * QkGate\_CCZ - * QkGate\_CSwap - * QkGate\_RCCX - * QkGate\_C3X +* QkGate\_H +* QkGate\_X +* QkGate\_Y +* QkGate\_Z +* QkGate\_CH +* QkGate\_CX +* QkGate\_CY +* QkGate\_CZ +* QkGate\_ECR +* QkGate\_Swap +* QkGate\_CCX +* QkGate\_CCZ +* QkGate\_CSwap +* QkGate\_RCCX +* QkGate\_C3X - and pairs of inverse gates: +and pairs of inverse gates: - * (QkGate\_T, QkGate\_Tdg) - * (QkGate\_S, QkGate\_Sdg) - * (QkGate\_SX, QkGate\_SXdg) - * (QkGate\_CS, QkGate\_CSdg) +* (QkGate\_T, QkGate\_Tdg) +* (QkGate\_S, QkGate\_Sdg) +* (QkGate\_SX, QkGate\_SXdg) +* (QkGate\_CS, QkGate\_CSdg) - + - #### Example +### Example - ```c - QkCircuit *qc = qk_circuit_new(2, 2); - uint32_t qargs[1] = {0}; - qk_circuit_gate(qc, QkGate_X, qargs, NULL); - qk_circuit_gate(qc, QkGate_H, qargs, NULL); - qk_circuit_gate(qc, QkGate_H, qargs, NULL); - qk_circuit_gate(qc, QkGate_Y, qargs, NULL); - qk_transpiler_pass_standalone_inverse_cancellation(qc); - ``` +```c +QkCircuit *qc = qk_circuit_new(2, 2); +uint32_t qargs[1] = {0}; +qk_circuit_gate(qc, QkGate_X, qargs, NULL); +qk_circuit_gate(qc, QkGate_H, qargs, NULL); +qk_circuit_gate(qc, QkGate_H, qargs, NULL); +qk_circuit_gate(qc, QkGate_Y, qargs, NULL); +qk_transpiler_pass_standalone_inverse_cancellation(qc); +``` - + - #### Safety +### Safety - + - Behavior is undefined if `circuit` is not a valid, non-null pointer to a `QkCircuit`. +Behavior is undefined if `circuit` is not a valid, non-null pointer to a `QkCircuit`. - **Parameters** +**Parameters** - **circuit** – A pointer to the circuit to run InverseCancellation on. If the pass is able to remove any gates, the original circuit will be replaced by the circuit produced by this pass. - +* **circuit** – A pointer to the circuit to run InverseCancellation on. If the pass is able to remove any gates, the original circuit will be replaced by the circuit produced by this pass. -### qk\_transpiler\_standalone\_optimize\_1q\_sequences +**void qk\_transpiler\_standalone\_optimize\_1q\_sequences(QkCircuit \*circuit, const QkTarget \*target)** - - Runs the Optimize1qGatesDecomposition pass in standalone mode on a circuit. +Runs the Optimize1qGatesDecomposition pass in standalone mode on a circuit. - Optimize1qGatesDecomposition optimizes single-qubit gate sequences by re-synthesizing the unitary under the constraints of the target’s basis gates and error rates. +Optimize1qGatesDecomposition optimizes single-qubit gate sequences by re-synthesizing the unitary under the constraints of the target’s basis gates and error rates. - The decision of whether to replace the original chain depends on: +The decision of whether to replace the original chain depends on: - * If the original chain was out of basis. - * If the original chain was in basis but the replacement has lower error rates. - * If the original chain is an identity (chain gets removed). +* If the original chain was out of basis. +* If the original chain was in basis but the replacement has lower error rates. +* If the original chain is an identity (chain gets removed). - The error is the combined multiplication of the errors of individual gates on the qubit it operates on. +The error is the combined multiplication of the errors of individual gates on the qubit it operates on. - + - #### Example +### Example - ```c - QkTarget *target = qk_target_new(1); - double u_errors[3] = {0., 1e-4, 1e-4}; - for (int idx = 0; idx < 3; idx++) { - QkTargetEntry *u_entry = qk_target_entry_new(QkGate_U); - uint32_t qargs[1] = { - 0, - }; - qk_target_entry_add_property(u_entry, qargs, 1, NAN, u_errors[idx]); - qk_target_add_instruction(target, u_entry); - } +```c +QkTarget *target = qk_target_new(1); +double u_errors[3] = {0., 1e-4, 1e-4}; +for (int idx = 0; idx < 3; idx++) { + QkTargetEntry *u_entry = qk_target_entry_new(QkGate_U); + uint32_t qargs[1] = { + 0, + }; + qk_target_entry_add_property(u_entry, qargs, 1, NAN, u_errors[idx]); + qk_target_add_instruction(target, u_entry); +} - // Build circuit - QkCircuit *circuit = qk_circuit_new(1, 0); - uint32_t qubits[1] = {0}; - for (int iter = 0; iter < 3; iter++) { - qk_circuit_gate(circuit, QkGate_H, qubits, NULL); - } +// Build circuit +QkCircuit *circuit = qk_circuit_new(1, 0); +uint32_t qubits[1] = {0}; +for (int iter = 0; iter < 3; iter++) { + qk_circuit_gate(circuit, QkGate_H, qubits, NULL); +} - // Run transpiler pass - qk_transpiler_standalone_optimize_1q_sequences(circuit, target); +// Run transpiler pass +qk_transpiler_standalone_optimize_1q_sequences(circuit, target); - // Clean up - qk_target_free(target); - qk_circuit_free(circuit); - ``` +// Clean up +qk_target_free(target); +qk_circuit_free(circuit); +``` - + - #### Safety +### Safety - + - Behavior is undefined if `circuit` is not a valid, non-null pointer to a `QkCircuit` and if `target` is not a valid pointer to a `QkTarget`. +Behavior is undefined if `circuit` is not a valid, non-null pointer to a `QkCircuit` and if `target` is not a valid pointer to a `QkTarget`. - **Parameters** +**Parameters** - * **circuit** – A pointer to the `QkCircuit` object to transform. - * **target** – A pointer to the `QkTarget` object or a null pointer. In the case a null pointer is provided and gate errors are unknown the pass will choose the sequence with the least amount of gates, and will support all basis gates on its Euler basis set. - +* **circuit** – A pointer to the `QkCircuit` object to transform. +* **target** – A pointer to the `QkTarget` object or a null pointer. In the case a null pointer is provided and gate errors are unknown the pass will choose the sequence with the least amount of gates, and will support all basis gates on its Euler basis set. -### qk\_transpiler\_pass\_standalone\_remove\_diagonal\_gates\_before\_measure +**void qk\_transpiler\_pass\_standalone\_remove\_diagonal\_gates\_before\_measure(QkCircuit \*circuit)** - - Run the `RemoveDiagonalGatesBeforeMeasure` pass on a circuit. +Run the `RemoveDiagonalGatesBeforeMeasure` pass on a circuit. - Transpiler pass to remove diagonal gates (like RZ, T, Z, etc) before a measurement. Including diagonal 2Q gates. +Transpiler pass to remove diagonal gates (like RZ, T, Z, etc) before a measurement. Including diagonal 2Q gates. - + - #### Example +### Example - ```c - QkCircuit *qc = qk_circuit_new(1, 1); - qk_circuit_gate(qc, QkGate_Z, {0}, NULL); - qk_circuit_measure(qc, 0, 0); - qk_transpiler_pass_standalone_remove_diagonal_gates_before_measure(qc); - // ... - qk_circuit_free(qc); - ``` +```c +QkCircuit *qc = qk_circuit_new(1, 1); +qk_circuit_gate(qc, QkGate_Z, {0}, NULL); +qk_circuit_measure(qc, 0, 0); +qk_transpiler_pass_standalone_remove_diagonal_gates_before_measure(qc); +// ... +qk_circuit_free(qc); +``` - + - #### Safety +### Safety - + - Behavior is undefined if `circuit` is not a valid, non-null pointer to a `QkCircuit`. +Behavior is undefined if `circuit` is not a valid, non-null pointer to a `QkCircuit`. - **Parameters** +**Parameters** - **circuit** – A pointer to the circuit to run this pass on - +* **circuit** – A pointer to the circuit to run this pass on -### qk\_transpiler\_pass\_standalone\_remove\_identity\_equivalent +**void qk\_transpiler\_pass\_standalone\_remove\_identity\_equivalent(QkCircuit \*circuit, const QkTarget \*target, double approximation\_degree)** - - Run the RemoveIdentityEquivalent transpiler pass on a circuit. +Run the RemoveIdentityEquivalent transpiler pass on a circuit. - Removes gates whose effect is close to an identity operation up to a global phase and up to the specified tolerance. Parameterized gates are not considered by this pass. +Removes gates whose effect is close to an identity operation up to a global phase and up to the specified tolerance. Parameterized gates are not considered by this pass. - For a cutoff fidelity $f$, this pass removes gates whose average gate fidelity with respect to the identity is below $f$. Concretely, a gate $G$ is removed if $\bar F < f$ where +For a cutoff fidelity $f$, this pass removes gates whose average gate fidelity with respect to the identity is below $f$. Concretely, a gate $G$ is removed if $\bar F < f$ where $$ @@ -418,245 +399,236 @@ F_{\text{process}} = \frac{|\mathrm{Tr}(G)|^2}{d^2} $$ - where $d = 2^n$ is the dimension of the gate for $n$ qubits. +where $d = 2^n$ is the dimension of the gate for $n$ qubits. - + - #### Example +### Example - ```c - QkTarget *target = qk_target_new(5); - uint32_t current_num_qubits = qk_target_num_qubits(target); - QkTargetEntry *cx_entry = qk_target_entry_new(QkGate_CX); - for (uint32_t i = 0; i < current_num_qubits - 1; i++) { - uint32_t qargs[2] = {i, i + 1}; - double inst_error = 0.0090393 * (current_num_qubits - i); - double inst_duration = 0.020039; - qk_target_entry_add_property(cx_entry, qargs, 2, inst_duration, inst_error); - } - QkExitCode result_cx = qk_target_add_instruction(target, cx_entry); - QkCircuit *qc = qk_circuit_new(4, 0); - for (uint32_t i = 0; i < qk_circuit_num_qubits(qc) - 1; i++) { - uint32_t qargs[2] = {i, i + 1}; - for (uint32_t j = 0; j + - #### Safety +### Safety - + - Behavior is undefined if `circuit` or `target` is not a valid, non-null pointer to a `QkCircuit` and `QkTarget`. +Behavior is undefined if `circuit` or `target` is not a valid, non-null pointer to a `QkCircuit` and `QkTarget`. - **Parameters** +**Parameters** - * **circuit** – A pointer to the circuit to run RemoveIdentityEquivalent on. This circuit pointed to will be updated with the modified circuit if the pass is able to remove any gates. - * **target** – The target for the RemoveIdentityEquivalent pass. If `approximation_degree` is set to `NAN` the tolerance for determining whether an operation is equivalent to identity will be set to the reported error rate in the target. Otherwise the `target` is not used as the tolerance is independent of the target. - * **approximation\_degree** – The degree to approximate for the equivalence check. This can be a floating point value between 0 and 1, or `NAN`. If the value is 1 this does not approximate above the floating point precision. For a value \< 1 this is used as a scaling factor for the cutoff fidelity. If the value is `NAN` this approximates up to the fidelity for the gate specified in `target`. - +* **circuit** – A pointer to the circuit to run RemoveIdentityEquivalent on. This circuit pointed to will be updated with the modified circuit if the pass is able to remove any gates. +* **target** – The target for the RemoveIdentityEquivalent pass. If `approximation_degree` is set to `NAN` the tolerance for determining whether an operation is equivalent to identity will be set to the reported error rate in the target. Otherwise the `target` is not used as the tolerance is independent of the target. +* **approximation\_degree** – The degree to approximate for the equivalence check. This can be a floating point value between 0 and 1, or `NAN`. If the value is 1 this does not approximate above the floating point precision. For a value \< 1 this is used as a scaling factor for the cutoff fidelity. If the value is `NAN` this approximates up to the fidelity for the gate specified in `target`. -### qk\_transpiler\_pass\_standalone\_sabre\_layout +**QkTranspileLayout \*qk\_transpiler\_pass\_standalone\_sabre\_layout(QkCircuit \*circuit, const QkTarget \*target, const [QkSabreLayoutOptions](qk-sabre-layout-options#c.QkSabreLayoutOptions "QkSabreLayoutOptions") \*options)** - - Run the SabreLayout transpiler pass on a circuit. +Run the SabreLayout transpiler pass on a circuit. - The SabreLayout pass chooses a layout via an iterative bidirectional routing of the input circuit. +The SabreLayout pass chooses a layout via an iterative bidirectional routing of the input circuit. - Starting with a random initial Layout, the algorithm does a full routing of the circuit to end up with a final\_layout. This final\_layout is then used as the initial\_layout for routing the reverse circuit. The algorithm iterates a number of times until it finds an initial\_layout that reduces full routing cost. +Starting with a random initial Layout, the algorithm does a full routing of the circuit to end up with a final\_layout. This final\_layout is then used as the initial\_layout for routing the reverse circuit. The algorithm iterates a number of times until it finds an initial\_layout that reduces full routing cost. - This method exploits the reversibility of quantum circuits, and tries to include global circuit information in the choice of initial\_layout. +This method exploits the reversibility of quantum circuits, and tries to include global circuit information in the choice of initial\_layout. - This pass will run both layout and routing and will transform the circuit so that the layout is applied to the input (meaning that the output circuit will have ancilla qubits allocated for unused qubits on the coupling map and the qubits will be reordered to match the mapped physical qubits) and then routing will be applied. This is done because the pass will run parallel seed trials with different random seeds for selecting the random initial layout and then selecting the routed output which results in the least number of swap gates needed. This final swap calculation is the same as performing a final routing, so it’s more efficient to apply it after computing it. +This pass will run both layout and routing and will transform the circuit so that the layout is applied to the input (meaning that the output circuit will have ancilla qubits allocated for unused qubits on the coupling map and the qubits will be reordered to match the mapped physical qubits) and then routing will be applied. This is done because the pass will run parallel seed trials with different random seeds for selecting the random initial layout and then selecting the routed output which results in the least number of swap gates needed. This final swap calculation is the same as performing a final routing, so it’s more efficient to apply it after computing it. - This function is multithreaded and will launch a thread pool with threads equal to the number of CPUs by default. 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. +This function is multithreaded and will launch a thread pool with threads equal to the number of CPUs by default. 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. - + - #### References +### References - + - \[1] Henry Zou and Matthew Treinish and Kevin Hartman and Alexander Ivrii and Jake Lishman. “LightSABRE: A Lightweight and Enhanced SABRE Algorithm” [arXiv:2409.08368](https://doi.org/10.48550/arXiv.2409.08368) +\[1] Henry Zou and Matthew Treinish and Kevin Hartman and Alexander Ivrii and Jake Lishman. “LightSABRE: A Lightweight and Enhanced SABRE Algorithm” [arXiv:2409.08368](https://doi.org/10.48550/arXiv.2409.08368) - \[2] Li, Gushu, Yufei Ding, and Yuan Xie. “Tackling the qubit mapping problem +\[2] Li, Gushu, Yufei Ding, and Yuan Xie. “Tackling the qubit mapping problem - for NISQ-era quantum devices.” ASPLOS 2019. +for NISQ-era quantum devices.” ASPLOS 2019. - [\`arXiv:1809.02573](https://arxiv.org/pdf/1809.02573.pdf) +[\`arXiv:1809.02573](https://arxiv.org/pdf/1809.02573.pdf) - + - #### Safety +### Safety - + - Behavior is undefined if `circuit` or `target` is not a valid, non-null pointer to a `QkCircuit` and `QkTarget`. +Behavior is undefined if `circuit` or `target` is not a valid, non-null pointer to a `QkCircuit` and `QkTarget`. - **Parameters** +**Parameters** - * **circuit** – A pointer to the circuit to run SabreLayout on. The circuit is modified in place and the original circuit’s allocations are freed by this function. - * **target** – A pointer to the target to run SabreLayout on - * **options** – A pointer to the options for SabreLayout +* **circuit** – A pointer to the circuit to run SabreLayout on. The circuit is modified in place and the original circuit’s allocations are freed by this function. +* **target** – A pointer to the target to run SabreLayout on +* **options** – A pointer to the options for SabreLayout - **Returns** +**Returns** - The transpile layout that describes the layout and output permutation caused by the pass - +The transpile layout that describes the layout and output permutation caused by the pass -### qk\_transpiler\_pass\_standalone\_split\_2q\_unitaries +**QkTranspileLayout \*qk\_transpiler\_pass\_standalone\_split\_2q\_unitaries(QkCircuit \*circuit, double requested\_fidelity, bool split\_swaps)** - - Run the Split2QUnitaries transpiler pass +Run the Split2QUnitaries transpiler pass - + - #### Example +### Example - ```c - QkCircuit *qc = qk_circuit_new(4, 0); - for (uint32_t i = 0; i < qk_circuit_num_qubits(qc) - 1; i++) { - uint32_t qargs[2] = {i, i + 1}; - for (uint32_t j = 0; j + - #### Safety +### Safety - + - Behavior is undefined if `circuit` is not a valid, non-null pointer to a `QkCircuit`. +Behavior is undefined if `circuit` is not a valid, non-null pointer to a `QkCircuit`. - **Parameters** +**Parameters** - * **circuit** – A mutable pointer to the circuit to run Split2QUnitaries on. This will be replaced with the new circuit if any gates are optimized and the original will be freed. - * **requested\_fidelity** – Allowed tolerance for splitting two-qubit unitaries and gate decompositions. - * **split\_swaps** – Whether to attempt to split swap gates, resulting in a permutation of the qubits. +* **circuit** – A mutable pointer to the circuit to run Split2QUnitaries on. This will be replaced with the new circuit if any gates are optimized and the original will be freed. +* **requested\_fidelity** – Allowed tolerance for splitting two-qubit unitaries and gate decompositions. +* **split\_swaps** – Whether to attempt to split swap gates, resulting in a permutation of the qubits. - **Returns** +**Returns** - If any swap equivalent unitaries are split this function returns a pointer to a `TranspileLayout` that contains the permutation induced by this circuit optimization. If no swap equivalent unitaries are split this will be a null pointer. - +If any swap equivalent unitaries are split this function returns a pointer to a `TranspileLayout` that contains the permutation induced by this circuit optimization. If no swap equivalent unitaries are split this will be a null pointer. -### qk\_transpiler\_pass\_standalone\_unitary\_synthesis +**void qk\_transpiler\_pass\_standalone\_unitary\_synthesis(QkCircuit \*circuit, const QkTarget \*target, size\_t min\_qubits, double approximation\_degree)** - - Run the UnitarySynthesis transpiler pass. +Run the UnitarySynthesis transpiler pass. - The UnitarySynthesis transpiler pass will synthesize any UnitaryGates in the circuit into gates available in the target. +The UnitarySynthesis transpiler pass will synthesize any UnitaryGates in the circuit into gates available in the target. - + - #### Example +### Example - ```c - QkTarget *target = qk_target_new(2); - uint32_t current_num_qubits = qk_target_num_qubits(target); - QkTargetEntry *cx_entry = qk_target_entry_new(QkGate_CX); - for (uint32_t i = 0; i < current_num_qubits - 1; i++) { - uint32_t qargs[2] = {i, i + 1}; - double inst_error = 0.0090393 * (current_num_qubits - i); - double inst_duration = 0.020039; - qk_target_entry_add_property(cx_entry, qargs, 2, inst_duration, inst_error); - } - QkExitCode result_cx = qk_target_add_instruction(target, cx_entry); - QkCircuit *qc = qk_circuit_new(2, 0); - QkComplex64 c0 = {0., 0.}; - QkComplex64 c1 = {1., 0.}; - QkComplex64 unitary[16] = {c1, c0, c0, c0, // row 0 - c0, c1, c0, c0, // row 1 - c0, c0, c1, c0, // row 2 - c0, c0, c0, c1}; // row 3 - uint32_t qargs[2] = {0, 1}; - qk_circuit_unitary(qc, unitary, qargs, 2, false); - qk_transpiler_pass_standalone_unitary_synthesis(qc, target, 0, 1.0); - ``` +```c +QkTarget *target = qk_target_new(2); +uint32_t current_num_qubits = qk_target_num_qubits(target); +QkTargetEntry *cx_entry = qk_target_entry_new(QkGate_CX); +for (uint32_t i = 0; i < current_num_qubits - 1; i++) { + uint32_t qargs[2] = {i, i + 1}; + double inst_error = 0.0090393 * (current_num_qubits - i); + double inst_duration = 0.020039; + qk_target_entry_add_property(cx_entry, qargs, 2, inst_duration, inst_error); +} +QkExitCode result_cx = qk_target_add_instruction(target, cx_entry); +QkCircuit *qc = qk_circuit_new(2, 0); +QkComplex64 c0 = {0., 0.}; +QkComplex64 c1 = {1., 0.}; +QkComplex64 unitary[16] = {c1, c0, c0, c0, // row 0 + c0, c1, c0, c0, // row 1 + c0, c0, c1, c0, // row 2 + c0, c0, c0, c1}; // row 3 +uint32_t qargs[2] = {0, 1}; +qk_circuit_unitary(qc, unitary, qargs, 2, false); +qk_transpiler_pass_standalone_unitary_synthesis(qc, target, 0, 1.0); +``` - + - #### Safety +### Safety - + - Behavior is undefined if `circuit` or `target` is not a valid, non-null pointer to a `QkCircuit` and `QkTarget`. +Behavior is undefined if `circuit` or `target` is not a valid, non-null pointer to a `QkCircuit` and `QkTarget`. - **Parameters** +**Parameters** - * **circuit** – A pointer to the circuit to run UnitarySynthesis on - * **target** – A pointer to the target to run UnitarySynthesis on - * **min\_qubits** – The minimum number of qubits in the unitary to synthesize. If the unitary is less than the specified number of qubits it will not be synthesized. - * **approximation\_degree** – heuristic dial used for circuit approximation (1.0=no approximation, 0.0=maximal approximation). Approximation can make the synthesized circuit cheaper at the cost of straying from the original unitary. If NAN, the target approximation is based on gate fidelities in the `target`. - +* **circuit** – A pointer to the circuit to run UnitarySynthesis on +* **target** – A pointer to the target to run UnitarySynthesis on +* **min\_qubits** – The minimum number of qubits in the unitary to synthesize. If the unitary is less than the specified number of qubits it will not be synthesized. +* **approximation\_degree** – heuristic dial used for circuit approximation (1.0=no approximation, 0.0=maximal approximation). Approximation can make the synthesized circuit cheaper at the cost of straying from the original unitary. If NAN, the target approximation is based on gate fidelities in the `target`. -### qk\_transpiler\_pass\_standalone\_vf2\_layout +**QkVF2LayoutResult \*qk\_transpiler\_pass\_standalone\_vf2\_layout(const QkCircuit \*circuit, const QkTarget \*target, const QkVF2LayoutConfiguration \*config, bool strict\_direction)** - - Use the VF2 algorithm to choose a layout (if possible) for the input circuit, using a noise-aware scoring heuristic based only on hardware error rates, and not the specific gates in the circuit. +Use the VF2 algorithm to choose a layout (if possible) for the input circuit, using a noise-aware scoring heuristic based only on hardware error rates, and not the specific gates in the circuit. - This function corresponds to the Python-space `VF2Layout` pass. +This function corresponds to the Python-space `VF2Layout` pass. - This function is suitable for use on circuits that have not yet been fully lowered to hardware. If your circuit has already been completely lowered to hardware and you are looking to *improve* the layout for an exact interaction graph, use `qk_transpile_pass_standalone_vf2_layout_exact` instead. +This function is suitable for use on circuits that have not yet been fully lowered to hardware. If your circuit has already been completely lowered to hardware and you are looking to *improve* the layout for an exact interaction graph, use `qk_transpile_pass_standalone_vf2_layout_exact` instead. - If this pass finds a solution that means there is a “perfect layout” and that no further swap mapping or routing is needed. However, there is not always a possible solution, or a solution might exist but it is not found within the limits specified when the pass is called. +If this pass finds a solution that means there is a “perfect layout” and that no further swap mapping or routing is needed. However, there is not always a possible solution, or a solution might exist but it is not found within the limits specified when the pass is called. - + - #### Example +### Example - ```c - QkTarget *target = qk_target_new(5); - uint32_t current_num_qubits = qk_target_num_qubits(target); - QkTargetEntry *cx_entry = qk_target_entry_new(QkGate_CX); - for (uint32_t i = 0; i < current_num_qubits - 1; i++) { - uint32_t qargs[2] = {i, i + 1}; - double inst_error = 0.0090393 * (current_num_qubits - i); - double inst_duration = 0.020039; - qk_target_entry_add_property(cx_entry, qargs, 2, inst_duration, inst_error); - } - QkExitCode result_cx = qk_target_add_instruction(target, cx_entry); - QkCircuit *qc = qk_circuit_new(4, 0); - for (uint32_t i = 0; i < qk_circuit_num_qubits(qc) - 1; i++) { - uint32_t qargs[2] = {i, i + 1}; - for (uint32_t j = 0; j + - #### Safety +### Safety - + - Behavior is undefined if `circuit` or `target` is not a valid, non-null pointer to a `QkCircuit` and `QkTarget`. Behavior is undefined if `config` is a non-null pointer that does not point to a valid `QkVF2LayoutConfiguration` object (but a null pointer is fine). +Behavior is undefined if `circuit` or `target` is not a valid, non-null pointer to a `QkCircuit` and `QkTarget`. Behavior is undefined if `config` is a non-null pointer that does not point to a valid `QkVF2LayoutConfiguration` object (but a null pointer is fine). - **Parameters** +**Parameters** - * **circuit** – A pointer to the circuit to run VF2Layout on - * **target** – A pointer to the target to run the VF2Layout pass on - * **config** – A pointer to the `QkVF2LayoutConfiguration` configuration structure. If this pointer is null, the pass defaults are used. - * **strict\_direction** – If `true`, the pass will consider the edge direction in the connectivity described in the `target`. Typically, setting this to `false` is desireable as the error heuristic is already very approximate, and two-qubit gates can almost invariably be synthesised to “flip” direction using only local one-qubit gates and the native-direction two-qubit gate. +* **circuit** – A pointer to the circuit to run VF2Layout on +* **target** – A pointer to the target to run the VF2Layout pass on +* **config** – A pointer to the `QkVF2LayoutConfiguration` configuration structure. If this pointer is null, the pass defaults are used. +* **strict\_direction** – If `true`, the pass will consider the edge direction in the connectivity described in the `target`. Typically, setting this to `false` is desireable as the error heuristic is already very approximate, and two-qubit gates can almost invariably be synthesised to “flip” direction using only local one-qubit gates and the native-direction two-qubit gate. - **Returns** +**Returns** - QkVF2LayoutResult A pointer to a result object that contains the results of the pass. This object is heap allocated and will need to be freed with the `qk_vf2_layout_result_free()` function. - +QkVF2LayoutResult A pointer to a result object that contains the results of the pass. This object is heap allocated and will need to be freed with the `qk_vf2_layout_result_free()` function. diff --git a/docs/api/qiskit-c/dev/qk-transpiler.mdx b/docs/api/qiskit-c/dev/qk-transpiler.mdx index 91b031a74ae..91f6cf06db6 100644 --- a/docs/api/qiskit-c/dev/qk-transpiler.mdx +++ b/docs/api/qiskit-c/dev/qk-transpiler.mdx @@ -8,79 +8,73 @@ python_api_name: QkTranspiler # QkTranspiler -The `qk_transpile()` function exposes Qiskit’s tranpsiler ([`qiskit.transpiler`](/docs/api/qiskit/dev/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/dev/qiskit.transpiler.generate_preset_pass_manager#qiskit.transpiler.generate_preset_pass_manager "qiskit.transpiler.generate_preset_pass_manager") or [`transpile()`](/docs/api/qiskit/dev/compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") functions for those circuits. +The [`qk_transpile()`](#c.qk_transpile "qk_transpile") function exposes Qiskit’s tranpsiler ([`qiskit.transpiler`](/docs/api/qiskit/dev/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/dev/qiskit.transpiler.generate_preset_pass_manager#qiskit.transpiler.generate_preset_pass_manager "qiskit.transpiler.generate_preset_pass_manager") or [`transpile()`](/docs/api/qiskit/dev/compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") functions for those circuits. ## Data Types -### QkTranspileResult +**struct QkTranspileResult** - - The container result object from `qk_transpile` +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. - +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 +**QkCircuit \*circuit** - - The options for running the transpiler +The compiled circuit. - #### uint8\_t optimization\_level +**QkTranspileLayout \*layout** - - The optimization level to run the transpiler with. Valid values are 0, 1, 2, or 3. - +Metadata about the initial and final virtual-to-physical layouts. - #### int64\_t seed +**struct QkTranspileOptions** - - 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. - +The options for running the transpiler - #### double approximation\_degree +**uint8\_t optimization\_level** - - 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. - - +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](#c.QkTranspileOptions "QkTranspileOptions") qk\_transpiler\_default\_options(void)** - - Generate transpiler options defaults +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. - +This function generates a [QkTranspileOptions](#structqktranspileoptions) 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](#c.QkTranspileOptions "QkTranspileOptions") \*options, [QkTranspileResult](#c.QkTranspileResult "QkTranspileResult") \*result, char \*\*error)** - - Transpile a single circuit. +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. +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. +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 +### 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\`\`. +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** +**Parameters** - * **circuit** – 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. +* **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** +**Returns** - The return code for the transpiler, `QkExitCode_Success` means success and all other values indicate an error. - +The return code for the transpiler, `QkExitCode_Success` means success and all other values indicate an error. diff --git a/docs/api/qiskit-c/dev/qk-vf-2-layout.mdx b/docs/api/qiskit-c/dev/qk-vf-2-layout.mdx index 254c5e2531a..13d7b5b5567 100644 --- a/docs/api/qiskit-c/dev/qk-vf-2-layout.mdx +++ b/docs/api/qiskit-c/dev/qk-vf-2-layout.mdx @@ -14,121 +14,109 @@ python_api_name: VF2 compiler-pass objects typedef struct QkVF2LayoutConfiguration QkVF2LayoutConfiguration ``` -The `qk_transpiler_pass_standalone_vf2_layout()` function takes this object as its configuration. +The [`qk_transpiler_pass_standalone_vf2_layout()`](qk-transpiler-passes#c.qk_transpiler_pass_standalone_vf2_layout "qk_transpiler_pass_standalone_vf2_layout") function takes this object as its configuration. -### qk\_vf2\_layout\_configuration\_new +**QkVF2LayoutConfiguration \*qk\_vf2\_layout\_configuration\_new(void)** - - Create a new configuration for the VF2 passes that runs everything completely unbounded. +Create a new configuration for the VF2 passes that runs everything completely unbounded. - Call `qk_vf2_layout_configuration_free` with the return value to free the memory when done. +Call `qk_vf2_layout_configuration_free` with the return value to free the memory when done. - **Returns** +**Returns** - A pointer to the configuration. - +A pointer to the configuration. -### qk\_vf2\_layout\_configuration\_free +**void qk\_vf2\_layout\_configuration\_free(QkVF2LayoutConfiguration \*config)** - - Free a `QkVf2LayoutConfiguration` object. +Free a `QkVf2LayoutConfiguration` object. - + - #### Safety +### Safety - + - Behavior is undefined if `config` is a non-null pointer, but does not point to a valid, aligned `QkVF2LayoutConfiguration` object. +Behavior is undefined if `config` is a non-null pointer, but does not point to a valid, aligned `QkVF2LayoutConfiguration` object. - **Parameters** +**Parameters** - **config** – A pointer to the configuration. - +* **config** – A pointer to the configuration. -### qk\_vf2\_layout\_configuration\_set\_call\_limit +**void qk\_vf2\_layout\_configuration\_set\_call\_limit(QkVF2LayoutConfiguration \*config, int64\_t limit)** - - Limit the numbers of times that the VF2 algorithm will attempt to extend its mapping. +Limit the numbers of times that the VF2 algorithm will attempt to extend its mapping. - + - #### Safety +### Safety - + - Behavior is undefined if `config` is not a valid, aligned, non-null pointer to a `QkVF2LayoutConfiguration`. +Behavior is undefined if `config` is not a valid, aligned, non-null pointer to a `QkVF2LayoutConfiguration`. - **Parameters** +**Parameters** - * **config** – The configuration to update. - * **limit** – The number of attempts to allow. Set to a negative number to have no bound. - +* **config** – The configuration to update. +* **limit** – The number of attempts to allow. Set to a negative number to have no bound. -### qk\_vf2\_layout\_configuration\_set\_time\_limit +**void qk\_vf2\_layout\_configuration\_set\_time\_limit(QkVF2LayoutConfiguration \*config, double limit)** - - Limit the runtime of the VF2 search. +Limit the runtime of the VF2 search. - This is not a hard limit; it is only checked when an improved layout is encountered. Using this option also makes the pass non-deterministic. It is generally recommended to use `qk_vf2_layout_configuration_set_call_limit` instead. +This is not a hard limit; it is only checked when an improved layout is encountered. Using this option also makes the pass non-deterministic. It is generally recommended to use `qk_vf2_layout_configuration_set_call_limit` instead. - + - #### Safety +### Safety - + - Behavior is undefined if `config` is not a valid, aligned, non-null pointer to a `QkVF2LayoutConfiguration`. +Behavior is undefined if `config` is not a valid, aligned, non-null pointer to a `QkVF2LayoutConfiguration`. - **Parameters** +**Parameters** - * **config** – The configuration to update. - * **limit** – The time in seconds to allow. Set to a non-positive value to run with no limit. - +* **config** – The configuration to update. +* **limit** – The time in seconds to allow. Set to a non-positive value to run with no limit. -### qk\_vf2\_layout\_configuration\_set\_max\_trials +**void qk\_vf2\_layout\_configuration\_set\_max\_trials(QkVF2LayoutConfiguration \*config, uint64\_t limit)** - - Limit the total number of complete improvements found. +Limit the total number of complete improvements found. - Since the VF2 search tree is pruned on-the-fly based on scoring in the `QkTarget`, this limit is not especially powerful. See `qk_vf2_layout_configuration_set_call_limit` for a tighter bound. +Since the VF2 search tree is pruned on-the-fly based on scoring in the `QkTarget`, this limit is not especially powerful. See `qk_vf2_layout_configuration_set_call_limit` for a tighter bound. - + - #### Safety +### Safety - + - Behavior is undefined if `config` is not a valid, aligned, non-null pointer to a `QkVF2LayoutConfiguration`. +Behavior is undefined if `config` is not a valid, aligned, non-null pointer to a `QkVF2LayoutConfiguration`. - **Parameters** +**Parameters** - * **config** – The configuration to update. - * **limit** – The number of complete layouts to allow before terminating. Set to 0 to run unbounded. - +* **config** – The configuration to update. +* **limit** – The number of complete layouts to allow before terminating. Set to 0 to run unbounded. -### qk\_vf2\_layout\_configuration\_set\_shuffle\_seed +**void qk\_vf2\_layout\_configuration\_set\_shuffle\_seed(QkVF2LayoutConfiguration \*config, uint64\_t seed)** - - Activate node shuffling of the input graphs with a given seed. +Activate node shuffling of the input graphs with a given seed. - This effectively drives a modification of the matching order of VF2, which in theory means that the space of a bounded search is not biased based on the node indices. In practice, Qiskit uses the VF2++ ordering improvements when running in “average” mode (corresponding to initial layout search), and starts from the identity mapping in “exact” made. Both of these ordering heuristics are typically far more likely to find results for the given problem than randomization. +This effectively drives a modification of the matching order of VF2, which in theory means that the space of a bounded search is not biased based on the node indices. In practice, Qiskit uses the VF2++ ordering improvements when running in “average” mode (corresponding to initial layout search), and starts from the identity mapping in “exact” made. Both of these ordering heuristics are typically far more likely to find results for the given problem than randomization. - If this function was not called, no node shuffling takes place. +If this function was not called, no node shuffling takes place. - + - #### Safety +### Safety - + - Behavior is undefined if `config` is not a valid, aligned, non-null pointer to a `QkVF2LayoutConfiguration`. +Behavior is undefined if `config` is not a valid, aligned, non-null pointer to a `QkVF2LayoutConfiguration`. - **Parameters** +**Parameters** - * **config** – The configuration to update. - * **seed** – The seed to use for the activated shuffling. - +* **config** – The configuration to update. +* **seed** – The seed to use for the activated shuffling. ## QkVF2LayoutResult @@ -140,98 +128,90 @@ When running the `qk_transpiler_pass_standalone_vf2_layout` function it returns ### Functions -#### qk\_vf2\_layout\_result\_has\_match +**bool qk\_vf2\_layout\_result\_has\_match(const QkVF2LayoutResult \*layout)** - - Check whether a result was found. +Check whether a result was found. - A `true` value includes the situation where the configuration specified to try the “trivial” layout and it was found to be the best (and consequently no qubit relabelling is necessary, other than ancilla expansion if appropriate). See `qk_vf2_layout_result_has_improvement` to distinguish whether an explicit remapping is stored. +A `true` value includes the situation where the configuration specified to try the “trivial” layout and it was found to be the best (and consequently no qubit relabelling is necessary, other than ancilla expansion if appropriate). See `qk_vf2_layout_result_has_improvement` to distinguish whether an explicit remapping is stored. - + - ##### Safety +#### Safety - + - Behavior is undefined if `layout` is not a valid, non-null pointer to a `QkVF2LayoutResult`. +Behavior is undefined if `layout` is not a valid, non-null pointer to a `QkVF2LayoutResult`. - **Parameters** +**Parameters** - **layout** – a pointer to the layout +* **layout** – a pointer to the layout - **Returns** +**Returns** - `true` if the VF2-based layout pass found any match. - +`true` if the VF2-based layout pass found any match. -#### qk\_vf2\_layout\_result\_has\_improvement +**bool qk\_vf2\_layout\_result\_has\_improvement(const QkVF2LayoutResult \*layout)** - - Check whether the result is an improvement to the trivial layout. +Check whether the result is an improvement to the trivial layout. - + - ##### Safety +#### Safety - + - Behavior is undefined if `layout` is not a valid, non-null pointer to a `QkVF2LayoutResult`. +Behavior is undefined if `layout` is not a valid, non-null pointer to a `QkVF2LayoutResult`. - **Parameters** +**Parameters** - **layout** – a pointer to the layout +* **layout** – a pointer to the layout - **Returns** +**Returns** - `true` if the VF2-based layout pass found an improved match. - +`true` if the VF2-based layout pass found an improved match. -#### qk\_vf2\_layout\_result\_map\_virtual\_qubit +**uint32\_t qk\_vf2\_layout\_result\_map\_virtual\_qubit(const QkVF2LayoutResult \*layout, uint32\_t qubit)** - - Get the physical qubit for a given virtual qubit +Get the physical qubit for a given virtual qubit - + - ##### Safety +#### Safety - + - Behavior is undefined if `layout` is not a valid, non-null pointer to a `QkVF2LayoutResult` containing a result, or if the qubit is out of range for the initial circuit. +Behavior is undefined if `layout` is not a valid, non-null pointer to a `QkVF2LayoutResult` containing a result, or if the qubit is out of range for the initial circuit. - **Parameters** +**Parameters** - * **layout** – a pointer to the layout - * **qubit** – the virtual qubit to get the physical qubit of +* **layout** – a pointer to the layout +* **qubit** – the virtual qubit to get the physical qubit of - **Returns** +**Returns** - The physical qubit mapped to by the specified virtual qubit - +The physical qubit mapped to by the specified virtual qubit -#### qk\_vf2\_layout\_result\_free +**void qk\_vf2\_layout\_result\_free(QkVF2LayoutResult \*layout)** - - Free a `QkVF2LayoutResult` object +Free a `QkVF2LayoutResult` object - + - ##### Example +#### Example - ```c - QkCircuit *qc = qk_circuit_new(1, 0); - ``` +```c +QkCircuit *qc = qk_circuit_new(1, 0); +``` - + - ##### Safety +#### Safety - + - Behavior is undefined if `layout` is not a valid, non-null pointer to a `QkVF2Layout`. +Behavior is undefined if `layout` is not a valid, non-null pointer to a `QkVF2Layout`. - **Parameters** +**Parameters** - **layout** – a pointer to the layout to free - +* **layout** – a pointer to the layout to free diff --git a/docs/api/qiskit-ibm-runtime/dev/estimator-v2.mdx b/docs/api/qiskit-ibm-runtime/dev/estimator-v2.mdx index b3db4630236..b37c807f423 100644 --- a/docs/api/qiskit-ibm-runtime/dev/estimator-v2.mdx +++ b/docs/api/qiskit-ibm-runtime/dev/estimator-v2.mdx @@ -63,7 +63,7 @@ python_api_name: qiskit_ibm_runtime.EstimatorV2 * A [`Session`](session "qiskit_ibm_runtime.Session") if you are using session execution mode. * A [`Batch`](batch "qiskit_ibm_runtime.Batch") if you are using batch execution mode. - Refer to the [Qiskit Runtime documentation](/docs/guides/execution-modes). for more information about the `Execution modes`. + Refer to the [Qiskit Runtime documentation](/docs/guides/execution-modes) for more information about the `Execution modes`. * **options** (*Optional\[Union\[Dict,* [*EstimatorOptions*](options-estimator-options "qiskit_ibm_runtime.options.EstimatorOptions")*]]*) – Estimator options, see `EstimatorOptions` for detailed description. diff --git a/docs/api/qiskit-ibm-runtime/dev/sampler-v2.mdx b/docs/api/qiskit-ibm-runtime/dev/sampler-v2.mdx index cc3846f4e42..a56b22adbf1 100644 --- a/docs/api/qiskit-ibm-runtime/dev/sampler-v2.mdx +++ b/docs/api/qiskit-ibm-runtime/dev/sampler-v2.mdx @@ -31,7 +31,7 @@ python_api_name: qiskit_ibm_runtime.SamplerV2 * A [`Session`](session "qiskit_ibm_runtime.Session") if you are using session execution mode. * A [`Batch`](batch "qiskit_ibm_runtime.Batch") if you are using batch execution mode. - Refer to the [Qiskit Runtime documentation](/docs/guides/execution-modes). for more information about the `Execution modes`. + Refer to the [Qiskit Runtime documentation](/docs/guides/execution-modes) for more information about the `Execution modes`. * **options** (*Optional\[Union\[Dict,* [*SamplerOptions*](options-sampler-options "qiskit_ibm_runtime.options.SamplerOptions")*]]*) – Sampler options, see `SamplerOptions` for detailed description. diff --git a/docs/api/qiskit-ibm-runtime/dev/visualization-draw-circuit-schedule-timing.mdx b/docs/api/qiskit-ibm-runtime/dev/visualization-draw-circuit-schedule-timing.mdx index 44bec17ba1d..45b28027c55 100644 --- a/docs/api/qiskit-ibm-runtime/dev/visualization-draw-circuit-schedule-timing.mdx +++ b/docs/api/qiskit-ibm-runtime/dev/visualization-draw-circuit-schedule-timing.mdx @@ -10,13 +10,13 @@ python_api_name: qiskit_ibm_runtime.visualization.draw_circuit_schedule_timing # qiskit\_ibm\_runtime.visualization.draw\_circuit\_schedule\_timing - + Draw a circuit schedule timing for `CircuitSchedule`. **Parameters** - * **circuit\_schedule** (*str*) – The circuit schedule as a string as returned - * **compiler.** (*from the*) + * **circuit\_schedule** (*str | CircuitSchedule*) – The circuit schedule as a string as returned + * **object.** (*from the compiler or a CircuitSchedule*) * **included\_channels** (*list*) – A list of channels to include in the plot. * **filter\_readout\_channels** (*bool*) – If `True`, remove all readout channels. * **filter\_barriers** (*bool*) – If `True`, remove all barriers. diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.ConsolidateBlocks.mdx b/docs/api/qiskit/dev/qiskit.transpiler.passes.ConsolidateBlocks.mdx index 52b61e5acca..2411b7fef0a 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.ConsolidateBlocks.mdx +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.ConsolidateBlocks.mdx @@ -8,13 +8,15 @@ python_api_name: qiskit.transpiler.passes.ConsolidateBlocks # ConsolidateBlocks - + Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") Replace each block of consecutive gates by a single Unitary node. Pass to consolidate sequences of uninterrupted gates acting on the same qubits into a Unitary node, to be resynthesized later, to a potentially more optimal subcircuit. + This pass reads the [`PropertySet`](qiskit.passmanager.PropertySet "qiskit.passmanager.PropertySet") key `ConsolidateBlocks_qubit_map` which it uses to communicate with recursive worker instances of itself for control-flow operations. The key should never be observable in a user-facing [`PassManager`](qiskit.transpiler.PassManager "qiskit.transpiler.PassManager") pipeline (it is only set in internal [`PassManager`](qiskit.transpiler.PassManager "qiskit.transpiler.PassManager") instances), but the pass may return incorrect results or error if another pass sets this key. + **Notes** This pass assumes that the ‘blocks\_list’ property that it reads is given such that blocks are in topological order. The blocks are collected by a previous pass, such as Collect2qBlocks. @@ -83,7 +85,7 @@ python_api_name: qiskit.transpiler.passes.ConsolidateBlocks ### run - + Run the ConsolidateBlocks pass on dag. Iterate over each block and replace it with an equivalent Unitary on the same wires. diff --git a/docs/api/qiskit/dev/qiskit.transpiler.passes.OptimizeCliffordT.mdx b/docs/api/qiskit/dev/qiskit.transpiler.passes.OptimizeCliffordT.mdx index d9d2261179f..61357b5bd42 100644 --- a/docs/api/qiskit/dev/qiskit.transpiler.passes.OptimizeCliffordT.mdx +++ b/docs/api/qiskit/dev/qiskit.transpiler.passes.OptimizeCliffordT.mdx @@ -8,7 +8,7 @@ python_api_name: qiskit.transpiler.passes.OptimizeCliffordT # OptimizeCliffordT - + Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass") An optimization pass for Clifford+T circuits. @@ -67,9 +67,11 @@ python_api_name: qiskit.transpiler.passes.OptimizeCliffordT ### run - + Run the OptimizeCliffordT pass on dag. + The pass applies to a Clifford + T/Tdg circuit, and outputs an optimized Clifford + T/Tdg circuit. + **Parameters** **dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit._accelerate.circuit.DAGCircuit")) – The directed acyclic graph to run on. diff --git a/public/docs/api/qiskit-c/dev/objects.inv b/public/docs/api/qiskit-c/dev/objects.inv index 5b328bbb695..2845353bd54 100644 Binary files a/public/docs/api/qiskit-c/dev/objects.inv and b/public/docs/api/qiskit-c/dev/objects.inv differ diff --git a/public/docs/images/api/qiskit-ibm-runtime/dev/fake_provider-3.avif b/public/docs/images/api/qiskit-ibm-runtime/dev/fake_provider-3.avif index 75877d85b51..5c260f381a8 100644 Binary files a/public/docs/images/api/qiskit-ibm-runtime/dev/fake_provider-3.avif and b/public/docs/images/api/qiskit-ibm-runtime/dev/fake_provider-3.avif differ diff --git a/public/docs/images/api/qiskit-ibm-runtime/dev/twirling_strategy_options.avif b/public/docs/images/api/qiskit-ibm-runtime/dev/twirling_strategy_options.avif index 6e639ffda0c..71baf0caa46 100644 Binary files a/public/docs/images/api/qiskit-ibm-runtime/dev/twirling_strategy_options.avif and b/public/docs/images/api/qiskit-ibm-runtime/dev/twirling_strategy_options.avif differ diff --git a/public/docs/images/api/qiskit/dev/circuit_random-1.avif b/public/docs/images/api/qiskit/dev/circuit_random-1.avif index 0e42e8a7208..8798d99cdc2 100644 Binary files a/public/docs/images/api/qiskit/dev/circuit_random-1.avif and b/public/docs/images/api/qiskit/dev/circuit_random-1.avif differ diff --git a/public/docs/images/api/qiskit/dev/circuit_random-3.avif b/public/docs/images/api/qiskit/dev/circuit_random-3.avif index 452783b5b4f..f72630bbd8f 100644 Binary files a/public/docs/images/api/qiskit/dev/circuit_random-3.avif and b/public/docs/images/api/qiskit/dev/circuit_random-3.avif differ diff --git a/public/docs/images/api/qiskit/dev/providers_fake_provider-1_01.avif b/public/docs/images/api/qiskit/dev/providers_fake_provider-1_01.avif index 9106769cabf..bda74f73059 100644 Binary files a/public/docs/images/api/qiskit/dev/providers_fake_provider-1_01.avif and b/public/docs/images/api/qiskit/dev/providers_fake_provider-1_01.avif differ diff --git a/public/docs/images/api/qiskit/dev/providers_fake_provider-1_02.avif b/public/docs/images/api/qiskit/dev/providers_fake_provider-1_02.avif index 79d203ff070..40901ccfe8f 100644 Binary files a/public/docs/images/api/qiskit/dev/providers_fake_provider-1_02.avif and b/public/docs/images/api/qiskit/dev/providers_fake_provider-1_02.avif differ diff --git a/public/docs/images/api/qiskit/dev/qiskit-circuit-ControlledGate-1.avif b/public/docs/images/api/qiskit/dev/qiskit-circuit-ControlledGate-1.avif index 15dd31188f6..fa9073eb481 100644 Binary files a/public/docs/images/api/qiskit/dev/qiskit-circuit-ControlledGate-1.avif and b/public/docs/images/api/qiskit/dev/qiskit-circuit-ControlledGate-1.avif differ diff --git a/public/docs/images/api/qiskit/dev/qiskit-circuit-ControlledGate-2.avif b/public/docs/images/api/qiskit/dev/qiskit-circuit-ControlledGate-2.avif index 01e55de6b8c..76ed805a86f 100644 Binary files a/public/docs/images/api/qiskit/dev/qiskit-circuit-ControlledGate-2.avif and b/public/docs/images/api/qiskit/dev/qiskit-circuit-ControlledGate-2.avif differ diff --git a/public/docs/images/api/qiskit/dev/qiskit-circuit-Parameter-1_00.avif b/public/docs/images/api/qiskit/dev/qiskit-circuit-Parameter-1_00.avif index 9399cb592d5..67e6999fdd4 100644 Binary files a/public/docs/images/api/qiskit/dev/qiskit-circuit-Parameter-1_00.avif and b/public/docs/images/api/qiskit/dev/qiskit-circuit-Parameter-1_00.avif differ diff --git a/public/docs/images/api/qiskit/dev/qiskit-circuit-QuantumCircuit-15_00.avif b/public/docs/images/api/qiskit/dev/qiskit-circuit-QuantumCircuit-15_00.avif index 590f7499d7c..2221a613159 100644 Binary files a/public/docs/images/api/qiskit/dev/qiskit-circuit-QuantumCircuit-15_00.avif and b/public/docs/images/api/qiskit/dev/qiskit-circuit-QuantumCircuit-15_00.avif differ diff --git a/public/docs/images/api/qiskit/dev/qiskit-circuit-QuantumCircuit-15_01.avif b/public/docs/images/api/qiskit/dev/qiskit-circuit-QuantumCircuit-15_01.avif index 494516ad56f..ae644c24354 100644 Binary files a/public/docs/images/api/qiskit/dev/qiskit-circuit-QuantumCircuit-15_01.avif and b/public/docs/images/api/qiskit/dev/qiskit-circuit-QuantumCircuit-15_01.avif differ diff --git a/public/docs/images/api/qiskit/dev/qiskit-circuit-QuantumCircuit-16_00.avif b/public/docs/images/api/qiskit/dev/qiskit-circuit-QuantumCircuit-16_00.avif index e82a48976ea..93ab791058f 100644 Binary files a/public/docs/images/api/qiskit/dev/qiskit-circuit-QuantumCircuit-16_00.avif and b/public/docs/images/api/qiskit/dev/qiskit-circuit-QuantumCircuit-16_00.avif differ diff --git a/public/docs/images/api/qiskit/dev/qiskit-circuit-QuantumCircuit-16_01.avif b/public/docs/images/api/qiskit/dev/qiskit-circuit-QuantumCircuit-16_01.avif index 0428c16bbf8..9ee8c9f266a 100644 Binary files a/public/docs/images/api/qiskit/dev/qiskit-circuit-QuantumCircuit-16_01.avif and b/public/docs/images/api/qiskit/dev/qiskit-circuit-QuantumCircuit-16_01.avif differ diff --git a/public/docs/images/api/qiskit/dev/qiskit-circuit-QuantumCircuit-31.avif b/public/docs/images/api/qiskit/dev/qiskit-circuit-QuantumCircuit-31.avif index 02069dbc3eb..b1b1bf38880 100644 Binary files a/public/docs/images/api/qiskit/dev/qiskit-circuit-QuantumCircuit-31.avif and b/public/docs/images/api/qiskit/dev/qiskit-circuit-QuantumCircuit-31.avif differ diff --git a/public/docs/images/api/qiskit/dev/qiskit-circuit-library-AndGate-1.avif b/public/docs/images/api/qiskit/dev/qiskit-circuit-library-AndGate-1.avif index 4b8ff54a209..ba78b881401 100644 Binary files a/public/docs/images/api/qiskit/dev/qiskit-circuit-library-AndGate-1.avif and b/public/docs/images/api/qiskit/dev/qiskit-circuit-library-AndGate-1.avif differ diff --git a/public/docs/images/api/qiskit/dev/qiskit-circuit-library-AndGate-2.avif b/public/docs/images/api/qiskit/dev/qiskit-circuit-library-AndGate-2.avif index 997ee16415b..199204a32b3 100644 Binary files a/public/docs/images/api/qiskit/dev/qiskit-circuit-library-AndGate-2.avif and b/public/docs/images/api/qiskit/dev/qiskit-circuit-library-AndGate-2.avif differ diff --git a/public/docs/images/api/qiskit/dev/qiskit-circuit-library-BitwiseXorGate-1.avif b/public/docs/images/api/qiskit/dev/qiskit-circuit-library-BitwiseXorGate-1.avif index ad77acf5a76..5e9a64ab35a 100644 Binary files a/public/docs/images/api/qiskit/dev/qiskit-circuit-library-BitwiseXorGate-1.avif and b/public/docs/images/api/qiskit/dev/qiskit-circuit-library-BitwiseXorGate-1.avif differ diff --git a/public/docs/images/api/qiskit/dev/qiskit-circuit-library-InnerProductGate-1.avif b/public/docs/images/api/qiskit/dev/qiskit-circuit-library-InnerProductGate-1.avif index 753d4b7e442..6c87ac2f163 100644 Binary files a/public/docs/images/api/qiskit/dev/qiskit-circuit-library-InnerProductGate-1.avif and b/public/docs/images/api/qiskit/dev/qiskit-circuit-library-InnerProductGate-1.avif differ diff --git a/public/docs/images/api/qiskit/dev/qiskit-circuit-library-OrGate-1.avif b/public/docs/images/api/qiskit/dev/qiskit-circuit-library-OrGate-1.avif index 209ada5d380..f6dcd47b61f 100644 Binary files a/public/docs/images/api/qiskit/dev/qiskit-circuit-library-OrGate-1.avif and b/public/docs/images/api/qiskit/dev/qiskit-circuit-library-OrGate-1.avif differ diff --git a/public/docs/images/api/qiskit/dev/qiskit-circuit-library-OrGate-2.avif b/public/docs/images/api/qiskit/dev/qiskit-circuit-library-OrGate-2.avif index c244ffee50c..91025dd99ad 100644 Binary files a/public/docs/images/api/qiskit/dev/qiskit-circuit-library-OrGate-2.avif and b/public/docs/images/api/qiskit/dev/qiskit-circuit-library-OrGate-2.avif differ diff --git a/public/docs/images/api/qiskit/dev/qiskit-circuit-library-PermutationGate-2.avif b/public/docs/images/api/qiskit/dev/qiskit-circuit-library-PermutationGate-2.avif index adb933e8378..5ad742bf527 100644 Binary files a/public/docs/images/api/qiskit/dev/qiskit-circuit-library-PermutationGate-2.avif and b/public/docs/images/api/qiskit/dev/qiskit-circuit-library-PermutationGate-2.avif differ diff --git a/public/docs/images/api/qiskit/dev/qiskit-circuit-library-PhaseEstimation-1.avif b/public/docs/images/api/qiskit/dev/qiskit-circuit-library-PhaseEstimation-1.avif index 14dbebaf94c..df7e3c42507 100644 Binary files a/public/docs/images/api/qiskit/dev/qiskit-circuit-library-PhaseEstimation-1.avif and b/public/docs/images/api/qiskit/dev/qiskit-circuit-library-PhaseEstimation-1.avif differ diff --git a/public/docs/images/api/qiskit/dev/qiskit-circuit-library-random_iqp-1.avif b/public/docs/images/api/qiskit/dev/qiskit-circuit-library-random_iqp-1.avif index 2da96f5f59a..ada2ddff110 100644 Binary files a/public/docs/images/api/qiskit/dev/qiskit-circuit-library-random_iqp-1.avif and b/public/docs/images/api/qiskit/dev/qiskit-circuit-library-random_iqp-1.avif differ diff --git a/public/docs/images/api/qiskit/dev/qiskit-circuit-library-unitary_overlap-1.avif b/public/docs/images/api/qiskit/dev/qiskit-circuit-library-unitary_overlap-1.avif index 7812ab85ab4..19c6fa97f93 100644 Binary files a/public/docs/images/api/qiskit/dev/qiskit-circuit-library-unitary_overlap-1.avif and b/public/docs/images/api/qiskit/dev/qiskit-circuit-library-unitary_overlap-1.avif differ diff --git a/public/docs/images/api/qiskit/dev/qiskit-quantum_info-Statevector-1.avif b/public/docs/images/api/qiskit/dev/qiskit-quantum_info-Statevector-1.avif index d011e035687..5123546c0e7 100644 Binary files a/public/docs/images/api/qiskit/dev/qiskit-quantum_info-Statevector-1.avif and b/public/docs/images/api/qiskit/dev/qiskit-quantum_info-Statevector-1.avif differ diff --git a/public/docs/images/api/qiskit/dev/qiskit-transpiler-passes-FilterOpNodes-1.avif b/public/docs/images/api/qiskit/dev/qiskit-transpiler-passes-FilterOpNodes-1.avif index 4c4b40634b7..d3be70d4897 100644 Binary files a/public/docs/images/api/qiskit/dev/qiskit-transpiler-passes-FilterOpNodes-1.avif and b/public/docs/images/api/qiskit/dev/qiskit-transpiler-passes-FilterOpNodes-1.avif differ diff --git a/public/docs/images/api/qiskit/dev/qiskit-transpiler-passes-RemoveBarriers-1.avif b/public/docs/images/api/qiskit/dev/qiskit-transpiler-passes-RemoveBarriers-1.avif index 067d63a9667..cd902109ae5 100644 Binary files a/public/docs/images/api/qiskit/dev/qiskit-transpiler-passes-RemoveBarriers-1.avif and b/public/docs/images/api/qiskit/dev/qiskit-transpiler-passes-RemoveBarriers-1.avif differ diff --git a/public/docs/images/api/qiskit/dev/qiskit-transpiler-passes-WrapAngles-1.avif b/public/docs/images/api/qiskit/dev/qiskit-transpiler-passes-WrapAngles-1.avif index 41cd59085e1..897b318a860 100644 Binary files a/public/docs/images/api/qiskit/dev/qiskit-transpiler-passes-WrapAngles-1.avif and b/public/docs/images/api/qiskit/dev/qiskit-transpiler-passes-WrapAngles-1.avif differ diff --git a/public/docs/images/api/qiskit/dev/qiskit-visualization-circuit_drawer-1.avif b/public/docs/images/api/qiskit/dev/qiskit-visualization-circuit_drawer-1.avif index 02069dbc3eb..29fbcee70bb 100644 Binary files a/public/docs/images/api/qiskit/dev/qiskit-visualization-circuit_drawer-1.avif and b/public/docs/images/api/qiskit/dev/qiskit-visualization-circuit_drawer-1.avif differ diff --git a/public/docs/images/api/qiskit/dev/qiskit-visualization-plot_circuit_layout-1.avif b/public/docs/images/api/qiskit/dev/qiskit-visualization-plot_circuit_layout-1.avif index 7588b82fa42..84c2b068594 100644 Binary files a/public/docs/images/api/qiskit/dev/qiskit-visualization-plot_circuit_layout-1.avif and b/public/docs/images/api/qiskit/dev/qiskit-visualization-plot_circuit_layout-1.avif differ diff --git a/public/docs/images/api/qiskit/dev/qiskit-visualization-plot_error_map-1.avif b/public/docs/images/api/qiskit/dev/qiskit-visualization-plot_error_map-1.avif index 32fa07b91f7..d22ef0cd4cb 100644 Binary files a/public/docs/images/api/qiskit/dev/qiskit-visualization-plot_error_map-1.avif and b/public/docs/images/api/qiskit/dev/qiskit-visualization-plot_error_map-1.avif differ diff --git a/public/docs/images/api/qiskit/dev/qiskit-visualization-plot_histogram-1_01.avif b/public/docs/images/api/qiskit/dev/qiskit-visualization-plot_histogram-1_01.avif index 4ff45b6a87f..8817a2c7a53 100644 Binary files a/public/docs/images/api/qiskit/dev/qiskit-visualization-plot_histogram-1_01.avif and b/public/docs/images/api/qiskit/dev/qiskit-visualization-plot_histogram-1_01.avif differ diff --git a/public/docs/images/api/qiskit/dev/qiskit-visualization-plot_histogram-1_02.avif b/public/docs/images/api/qiskit/dev/qiskit-visualization-plot_histogram-1_02.avif index b0cc49f9775..951d6ffe35b 100644 Binary files a/public/docs/images/api/qiskit/dev/qiskit-visualization-plot_histogram-1_02.avif and b/public/docs/images/api/qiskit/dev/qiskit-visualization-plot_histogram-1_02.avif differ diff --git a/public/docs/images/api/qiskit/dev/qiskit-visualization-plot_state_hinton-1.avif b/public/docs/images/api/qiskit/dev/qiskit-visualization-plot_state_hinton-1.avif index 0a5e9783304..54f79172cf7 100644 Binary files a/public/docs/images/api/qiskit/dev/qiskit-visualization-plot_state_hinton-1.avif and b/public/docs/images/api/qiskit/dev/qiskit-visualization-plot_state_hinton-1.avif differ diff --git a/public/docs/images/api/qiskit/dev/qiskit-visualization-plot_state_paulivec-1.avif b/public/docs/images/api/qiskit/dev/qiskit-visualization-plot_state_paulivec-1.avif index da6f59a4cdf..0865c1297ee 100644 Binary files a/public/docs/images/api/qiskit/dev/qiskit-visualization-plot_state_paulivec-1.avif and b/public/docs/images/api/qiskit/dev/qiskit-visualization-plot_state_paulivec-1.avif differ diff --git a/public/docs/images/api/qiskit/dev/qiskit-visualization-timeline_drawer-1.avif b/public/docs/images/api/qiskit/dev/qiskit-visualization-timeline_drawer-1.avif index 100437004e3..6a0308edd87 100644 Binary files a/public/docs/images/api/qiskit/dev/qiskit-visualization-timeline_drawer-1.avif and b/public/docs/images/api/qiskit/dev/qiskit-visualization-timeline_drawer-1.avif differ diff --git a/public/docs/images/api/qiskit/dev/qiskit-visualization-timeline_drawer-2.avif b/public/docs/images/api/qiskit/dev/qiskit-visualization-timeline_drawer-2.avif index c26612cab44..17f985806c1 100644 Binary files a/public/docs/images/api/qiskit/dev/qiskit-visualization-timeline_drawer-2.avif and b/public/docs/images/api/qiskit/dev/qiskit-visualization-timeline_drawer-2.avif differ diff --git a/public/docs/images/api/qiskit/dev/qiskit-visualization-timeline_drawer-3.avif b/public/docs/images/api/qiskit/dev/qiskit-visualization-timeline_drawer-3.avif index a55c2c81264..ca15e946655 100644 Binary files a/public/docs/images/api/qiskit/dev/qiskit-visualization-timeline_drawer-3.avif and b/public/docs/images/api/qiskit/dev/qiskit-visualization-timeline_drawer-3.avif differ diff --git a/public/docs/images/api/qiskit/dev/transpiler-10.avif b/public/docs/images/api/qiskit/dev/transpiler-10.avif index 8ea8460837d..b352c4b1793 100644 Binary files a/public/docs/images/api/qiskit/dev/transpiler-10.avif and b/public/docs/images/api/qiskit/dev/transpiler-10.avif differ diff --git a/public/docs/images/api/qiskit/dev/transpiler-9.avif b/public/docs/images/api/qiskit/dev/transpiler-9.avif index aa05001d701..095be2df437 100644 Binary files a/public/docs/images/api/qiskit/dev/transpiler-9.avif and b/public/docs/images/api/qiskit/dev/transpiler-9.avif differ diff --git a/public/docs/images/api/qiskit/dev/visualization-1.avif b/public/docs/images/api/qiskit/dev/visualization-1.avif index dbd3791abe1..fd0445ce9a8 100644 Binary files a/public/docs/images/api/qiskit/dev/visualization-1.avif and b/public/docs/images/api/qiskit/dev/visualization-1.avif differ diff --git a/public/docs/images/api/qiskit/dev/visualization-3.avif b/public/docs/images/api/qiskit/dev/visualization-3.avif index 6c5e34e40dd..995f4841ae6 100644 Binary files a/public/docs/images/api/qiskit/dev/visualization-3.avif and b/public/docs/images/api/qiskit/dev/visualization-3.avif differ diff --git a/scripts/config/api-html-artifacts.json b/scripts/config/api-html-artifacts.json index b03ca4ab018..fcd7a57e264 100644 --- a/scripts/config/api-html-artifacts.json +++ b/scripts/config/api-html-artifacts.json @@ -1,6 +1,6 @@ { "qiskit": { - "dev": "https://api.github.com/repos/Qiskit/qiskit/actions/artifacts/4374903218/zip", + "dev": "https://api.github.com/repos/Qiskit/qiskit/actions/artifacts/4432131164/zip", "2.2": "https://ibm.box.com/shared/static/c1lktwwwo9zu4z5wxqg1xs9fj57oeoco.zip", "2.1": "https://ibm.box.com/shared/static/mplc0lvu7mi2xwri9z3y0u0lr6z9ivwv.zip", "2.0": "https://ibm.box.com/shared/static/r3qdbe7yznpi300y12tvksrts9l0xavw.zip", @@ -34,7 +34,7 @@ "0.19": "https://ibm.box.com/shared/static/wjoea4x5tnxd0l4lgo2v3kxnx6btxvvl.zip" }, "qiskit-ibm-runtime": { - "dev": "https://api.github.com/repos/Qiskit/qiskit-ibm-runtime/actions/artifacts/4362300820/zip", + "dev": "https://api.github.com/repos/Qiskit/qiskit-ibm-runtime/actions/artifacts/4437147438/zip", "0.43": "https://ibm.box.com/shared/static/nlpyvweh4n0xhuvl08p8zpykkkchgi2a.zip", "0.42": "https://ibm.box.com/shared/static/rrpqiqv9ijbkt0v4hs0usvr0gcgizr3v.zip", "0.41": "https://ibm.box.com/shared/static/eu5nc0ro07kogyki718oanyx56kkzlab.zip", diff --git a/scripts/config/historical-pages-to-latest.json b/scripts/config/historical-pages-to-latest.json index c8628c7337c..82b4739f722 100644 --- a/scripts/config/historical-pages-to-latest.json +++ b/scripts/config/historical-pages-to-latest.json @@ -1497,6 +1497,7 @@ "dev": { "qk-circuit-library": "/", "qk-dag": "/", + "qk-neighbors": "/", "qk-vf-2-layout": "/" } }