Skip to content

Update API dev docs #5261

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
github-actions wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Update API dev docs #5261

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions docs/api/qiskit-c/dev/qk-bit-term.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -91,7 +91,7 @@ The numeric structure of these is that they are all four-bit values of which the
<Function id="qk_bitterm_label" signature="uint8_t qk_bitterm_label(QkBitTerm bit_term)">
Get the label for a bit term.

<span id="group__QkBitTerm_1autotoc_md252" />
<span id="group__QkBitTerm_1autotoc_md253" />

#### Example

Expand All @@ -101,11 +101,11 @@ The numeric structure of these is that they are all four-bit values of which the
char label = qk_bitterm_label(bit_term);
```

<span id="group__QkBitTerm_1autotoc_md253" />
<span id="group__QkBitTerm_1autotoc_md254" />

#### Safety

<span id="group__QkBitTerm_1autotoc_md253" />
<span id="group__QkBitTerm_1autotoc_md254" />

The behavior is undefined if `bit_term` is not a valid `uint8_t` value of a `QkBitTerm`.

Expand Down
28 changes: 14 additions & 14 deletions docs/api/qiskit-c/dev/qk-circuit-library.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -85,11 +85,11 @@ The Qiskit circuit library contains functions and higher-level building blocks f

The `interactions` matrix is interpreted as an `n × n` row-major array of 64-bit integers, where `n = num_qubits`. The diagonal entries set T-like phase powers, and the upper triangle encodes two-qubit CPhase interactions.

<span id="group__QkCircuitLibrary_1autotoc_md76" />
<span id="group__QkCircuitLibrary_1autotoc_md77" />

#### Safety

<span id="group__QkCircuitLibrary_1autotoc_md76" />
<span id="group__QkCircuitLibrary_1autotoc_md77" />

If `num_qubits > 0`, `interactions` **must** be a valid, non-null pointer to at least `num_qubits * num_qubits` contiguous `int64_t` values in row-major order. The memory pointed to by `interactions` must be properly aligned, readable for the duration of this call, and not mutably aliased. Passing an invalid pointer or a buffer that is too small results in undefined behaviour.

Expand Down Expand Up @@ -128,7 +128,7 @@ The Qiskit circuit library contains functions and higher-level building blocks f

This frees the memory of the `z` and `x` arrays and frees the `angle`. This function should only be called for `QkPauliProductRotation` objects whose data has been populated by Rust.

<span id="group__QkCircuitLibrary_1autotoc_md77" />
<span id="group__QkCircuitLibrary_1autotoc_md78" />

#### Example

Expand Down Expand Up @@ -156,11 +156,11 @@ The Qiskit circuit library contains functions and higher-level building blocks f
qk_param_free(angle);
```

<span id="group__QkCircuitLibrary_1autotoc_md78" />
<span id="group__QkCircuitLibrary_1autotoc_md79" />

#### Safety

<span id="group__QkCircuitLibrary_1autotoc_md78" />
<span id="group__QkCircuitLibrary_1autotoc_md79" />

Behavior is undefined if `inst` is not a valid, non-null pointer to a `QkPauliProductRotation`, or if the internal data of `QkPauliProductRotation` is incoherent.

Expand All @@ -176,7 +176,7 @@ The Qiskit circuit library contains functions and higher-level building blocks f

This frees the memory of the `z` and `x` arrays. This function should only be called for `QkPauliProductMeasurement` objects whose data has been populated by Rust.

<span id="group__QkCircuitLibrary_1autotoc_md79" />
<span id="group__QkCircuitLibrary_1autotoc_md80" />

#### Example

Expand All @@ -203,11 +203,11 @@ The Qiskit circuit library contains functions and higher-level building blocks f
// since this data is allocated by C, we do not call `qk_pauli_product_measurement_clear(&inst)`
```

<span id="group__QkCircuitLibrary_1autotoc_md80" />
<span id="group__QkCircuitLibrary_1autotoc_md81" />

#### Safety

<span id="group__QkCircuitLibrary_1autotoc_md80" />
<span id="group__QkCircuitLibrary_1autotoc_md81" />

Behavior is undefined if `inst` is not a valid, non-null pointer to a `QkPauliProductMeasurement`, or if the internal data of `QkPauliProductMeasurement` is incoherent.

Expand All @@ -227,7 +227,7 @@ The Qiskit circuit library contains functions and higher-level building blocks f

\[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)

<span id="group__QkCircuitLibrary_1autotoc_md81" />
<span id="group__QkCircuitLibrary_1autotoc_md82" />

#### Example

Expand All @@ -253,7 +253,7 @@ The Qiskit circuit library contains functions and higher-level building blocks f

The Suzuki-Trotter formulas improve the error of the Lie-Trotter approximation. In this implementation, the operators are provided as sum terms of a Pauli operator. Higher order decompositions are based on recursions, see Ref. \[1] for more details.

<span id="group__QkCircuitLibrary_1autotoc_md82" />
<span id="group__QkCircuitLibrary_1autotoc_md83" />

#### Example

Expand All @@ -274,19 +274,19 @@ The Qiskit circuit library contains functions and higher-level building blocks f
qk_circuit_free(qc);
```

<span id="group__QkCircuitLibrary_1autotoc_md83" />
<span id="group__QkCircuitLibrary_1autotoc_md84" />

#### Safety

<span id="group__QkCircuitLibrary_1autotoc_md83" />
<span id="group__QkCircuitLibrary_1autotoc_md84" />

Behavior is undefined `op` is not a valid, non-null pointer to a `QkObs`.

<span id="group__QkCircuitLibrary_1autotoc_md84" />
<span id="group__QkCircuitLibrary_1autotoc_md85" />

#### References

<span id="group__QkCircuitLibrary_1autotoc_md84" />
<span id="group__QkCircuitLibrary_1autotoc_md85" />

\[1]: D. Berry, G. Ahokas, R. Cleve and B. Sanders, “Efficient quantum algorithms for simulating sparse Hamiltonians” (2006). [arXiv:quant-ph/0508139](https://arxiv.org/abs/quant-ph/0508139)

Expand Down
65 changes: 45 additions & 20 deletions docs/api/qiskit-c/dev/qk-circuit.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1350,6 +1350,31 @@ The circuit C API currently only supports creating circuits that contain operati
The pointer to the copied circuit.
</Function>

### qk\_circuit\_estimate\_fidelity

<Function id="qk_circuit_estimate_fidelity" signature="double qk_circuit_estimate_fidelity(const QkCircuit *circuit, const QkTarget *target)">
Estimate the fidelity of a physical circuit.

This function will compute the product of the error rates for each gate in the circuit to estimate the fidelity of the circuit. This method is not intended to compute a realistic simulation of the fidelity of execution on real hardware. It is designed to provide an estimate of how the transpiler would work with the fidelity for various heuristics in its operation. It is typically only useful for comparing different compilation outputs against each other to estimate which one would produce a better quality execution on hardware.

<span id="group__QkCircuit_1autotoc_md66" />

#### Safety

<span id="group__QkCircuit_1autotoc_md66" />

Behavior is undefined if `circuit` and `target` are not a valid, non-null pointer to a `QkCircuit` and `QkTarget` respectively.

**Parameters**

* **circuit** – A pointer to the circuit to estimate the fidelity of.
* **target** – A pointer to the target that the circuit will be executed on. This is used to get the error rates for the instructions in the circuit.

**Returns**

The computed fidelity of the circuit. This will return NaN if the circuit is not physical, meaning there are instructions in `circuit` not supported by `target`.
</Function>

### qk\_circuit\_to\_python

<Function id="qk_circuit_to_python" signature="PyObject *qk_circuit_to_python(QkCircuit *qc)">
Expand All @@ -1359,11 +1384,11 @@ The circuit C API currently only supports creating circuits that contain operati

It is not safe to use the `QkCircuit` pointer after calling this function. In particular, you should not attempt to clear or free it. The caller must own the `QkCircuit`, not hold a borrowed reference (for example, a `QkCircuit *` retrieved from `qk_circuit_borrow_from_python` is not owned).

<span id="group__QkCircuit_1autotoc_md66" />
<span id="group__QkCircuit_1autotoc_md67" />

#### Safety

<span id="group__QkCircuit_1autotoc_md66" />
<span id="group__QkCircuit_1autotoc_md67" />

The caller must be attached to a Python interpreter. Behavior is undefined if `circuit` is not a valid non-null pointer to an initialized and owned `QkCircuit`.

Expand All @@ -1385,11 +1410,11 @@ The circuit C API currently only supports creating circuits that contain operati

It is not safe to use the `QkCircuit` pointer after calling this function. In particular, you should not attempt to clear or free it. The caller must own the `QkCircuit`, not hold a borrowed reference (for example, a `QkCircuit *` retrieved from `qk_circuit_borrow_from_python` is not owned).

<span id="group__QkCircuit_1autotoc_md67" />
<span id="group__QkCircuit_1autotoc_md68" />

#### Safety

<span id="group__QkCircuit_1autotoc_md67" />
<span id="group__QkCircuit_1autotoc_md68" />

The caller must be attached to a Python interpreter. Behavior is undefined if `circuit` is not a valid non-null pointer to an initialized and owned `QkCircuit`.

Expand All @@ -1415,11 +1440,11 @@ The circuit C API currently only supports creating circuits that contain operati

You can also use `qk_circuit_convert_from_python`, which is logically the exact same as this function, but can be directly used as a “converter” function for the `PyArg_Parse*` family of Python converter functions.

<span id="group__QkCircuit_1autotoc_md68" />
<span id="group__QkCircuit_1autotoc_md69" />

#### Safety

<span id="group__QkCircuit_1autotoc_md68" />
<span id="group__QkCircuit_1autotoc_md69" />

The caller must be attached to a Python interpreter. Behavior is undefined if `ob` is not a valid non-null pointer to a Python object.

Expand All @@ -1445,11 +1470,11 @@ The circuit C API currently only supports creating circuits that contain operati

You can also use `qk_circuit_borrow_from_python`, which is logically the exact same as this, but with a more natural signature for direct usage.

<span id="group__QkCircuit_1autotoc_md69" />
<span id="group__QkCircuit_1autotoc_md70" />

#### Safety

<span id="group__QkCircuit_1autotoc_md69" />
<span id="group__QkCircuit_1autotoc_md70" />

The caller must be attached to a Python interpreter. Behavior is undefined if `object` is not a valid non-null pointer to a Python object, or if `address` is not a pointer to writeable data of the correct type.

Expand All @@ -1470,11 +1495,11 @@ The circuit C API currently only supports creating circuits that contain operati

It is not safe to use the `QkQuantumRegister` pointer after calling this function. In particular, you should not attempt to clear or free it. The caller must own the `QkQuantumRegister`, not hold a borrowed reference (for example, a `QkQuantumRegister *` retrieved from `qk_quantum_register_borrow_from_python` is not owned).

<span id="group__QkCircuit_1autotoc_md70" />
<span id="group__QkCircuit_1autotoc_md71" />

#### Safety

<span id="group__QkCircuit_1autotoc_md70" />
<span id="group__QkCircuit_1autotoc_md71" />

The caller must be attached to a Python interpreter. Behavior is undefined if `qr` is not a valid non-null pointer to an initialized and owned `QkQuantumRegister`.

Expand All @@ -1498,11 +1523,11 @@ The circuit C API currently only supports creating circuits that contain operati

You can also use `qk_quantum_register_convert_from_python`, which is logically the exact same as this function, but can be directly used as a “converter” function for the `PyArg_Parse*` family of Python converter functions.

<span id="group__QkCircuit_1autotoc_md71" />
<span id="group__QkCircuit_1autotoc_md72" />

#### Safety

<span id="group__QkCircuit_1autotoc_md71" />
<span id="group__QkCircuit_1autotoc_md72" />

The caller must be attached to a Python interpreter. Behavior is undefined if `ob` is not a valid non-null pointer to a Python object.

Expand All @@ -1526,11 +1551,11 @@ The circuit C API currently only supports creating circuits that contain operati

You can also use `qk_quantum_register_borrow_from_python`, which is logically the exact same as this, but with a more natural signature for direct usage.

<span id="group__QkCircuit_1autotoc_md72" />
<span id="group__QkCircuit_1autotoc_md73" />

#### Safety

<span id="group__QkCircuit_1autotoc_md72" />
<span id="group__QkCircuit_1autotoc_md73" />

The caller must be attached to a Python interpreter. Behavior is undefined if `object` is not a valid non-null pointer to a Python object, or if `address` is not a pointer to writeable data of the correct type.

Expand All @@ -1551,11 +1576,11 @@ The circuit C API currently only supports creating circuits that contain operati

It is not safe to use the `QkClassicalRegister` pointer after calling this function. In particular, you should not attempt to clear or free it. The caller must own the `QkClassicalRegister`, not hold a borrowed reference (for example, a `QkClassicalRegister *` retrieved from `qk_classical_register_borrow_from_python` is not owned).

<span id="group__QkCircuit_1autotoc_md73" />
<span id="group__QkCircuit_1autotoc_md74" />

#### Safety

<span id="group__QkCircuit_1autotoc_md73" />
<span id="group__QkCircuit_1autotoc_md74" />

The caller must be attached to a Python interpreter. Behavior is undefined if `cr` is not a valid non-null pointer to an initialized and owned `QkClassicalRegister`.

Expand All @@ -1579,11 +1604,11 @@ The circuit C API currently only supports creating circuits that contain operati

You can also use `qk_classical_register_convert_from_python`, which is logically the exact same as this function, but can be directly used as a “converter” function for the `PyArg_Parse*` family of Python converter functions.

<span id="group__QkCircuit_1autotoc_md74" />
<span id="group__QkCircuit_1autotoc_md75" />

#### Safety

<span id="group__QkCircuit_1autotoc_md74" />
<span id="group__QkCircuit_1autotoc_md75" />

The caller must be attached to a Python interpreter. Behavior is undefined if `ob` is not a valid non-null pointer to a Python object.

Expand All @@ -1607,11 +1632,11 @@ The circuit C API currently only supports creating circuits that contain operati

You can also use `qk_classical_register_borrow_from_python`, which is logically the exact same as this, but with a more natural signature for direct usage.

<span id="group__QkCircuit_1autotoc_md75" />
<span id="group__QkCircuit_1autotoc_md76" />

#### Safety

<span id="group__QkCircuit_1autotoc_md75" />
<span id="group__QkCircuit_1autotoc_md76" />

The caller must be attached to a Python interpreter. Behavior is undefined if `object` is not a valid non-null pointer to a Python object, or if `address` is not a pointer to writeable data of the correct type.

Expand Down
Loading