Define Custom Operations via the C API

[raynelfss]

Summary

Fix #16621
The following commits introduce Custom Operations to the C API by doing the following:

• Introduce an interface to define custom operations through the C API.
• Introduce the ability to insert custom operations to QkCircuit and QkDAG via the new methods.

Detailed breakdown

Since #15573 closed, we now have the ability of defining custom operations without needing to interact with Python. Having the ability to use dynamic dispatching to define operations while also allowing them to have the minimal amount of functionality needed for them to work inside a circuit.

The following commits add the ability to do the same using the C API in a more explicit way.

Custom Operations in C

A custom operation defined in C is currently represented by the struct QkCustomOperation (representing BoxedCustomOperation), which essentially wraps a struct with two fields.

• orig: A pointer to the operation struct instance to be added to the circuit.
• v_table: A pointer to the QkCustomOpVtable to be used for accessing the methods that establish minimal functionality for an operation.

QkCustomOpVtable

This v_table contains the slots referring the required/optional methods for an Operation to work. This includes the following methods:

Slot	Arg(s) type	Return type	Index	Required
name	const void *	char *	0	Yes
num_qubits	const void *	uint32_t	1	Yes
num_clbits	const void *	uint32_t	2	Yes
num_params	const void *	uint32_t	3	Yes
directive	const void *	bool	4	Yes
is_unitary	const void *	bool	5	Yes
num_ctrl_qubits	const void *	uint32_t	6	No
label	const void *	char *	7	No
definition	const void *, QkParam *	QkCircuit *	8	No
eq	const void *, const void *	bool	9	No

Refer the included documentation to further understand how it works.

Circuit methods

Two functions to add custom operations to a circuit have been included in this PR:

• qk_circuit_add_custom_operation: To add to any QkCircuit instance.
• qk_dag_apply_custom_operation: To add to any QkDAG instance.

AI/LLM disclosure

• I didn't use LLM tooling, or only used it privately.
• I used the following tool to help write this PR description:
• I used the following tool to generate or modify code:

[qiskit-bot]

One or more of the following people are relevant to this code:

• @Qiskit/terra-core

[coveralls]

Coverage Report for CI Build 33197765241

Warning

Build has drifted: This PR's base is out of sync with its target branch, so coverage data may include unrelated changes.
Quick fix: rebase this PR. Learn more →

Coverage increased (+0.09%) to 87.681%

Details

• Coverage increased (+0.09%) from the base build.
• Patch coverage: 107 uncovered changes across 3 files (172 of 279 lines covered, 61.65%).
• 2378 coverage regressions across 36 files.

Uncovered Changes

File	Changed	Covered	%
crates/cext/src/operations.rs	195	104	53.33%
crates/cext/src/dag.rs	48	35	72.92%
crates/cext/src/circuit.rs	29	26	89.66%
Total (4 files)	279	172	61.65%

Coverage Regressions

2378 previously-covered lines in 36 files lost coverage.

Top 10 Files by Coverage Loss	Lines Losing Coverage	Coverage
crates/circuit/src/dag_circuit.rs	535	86.0%
crates/circuit/src/parameter/symbol_expr.rs	456	77.96%
qiskit/qpy/binary_io/circuits.py	245	63.72%
crates/qpy/src/circuit_reader.rs	230	74.53%
crates/qpy/src/value.rs	139	73.54%
crates/cext/src/circuit.rs	91	82.77%
crates/circuit/src/operations.rs	86	83.78%
qiskit/transpiler/passes/synthesis/hls_plugins.py	84	85.94%
crates/synthesis/src/multi_controlled/mcx.rs	64	90.5%
crates/qpy/src/circuit_writer.rs	62	92.99%

---

Coverage Stats

Relevant Lines:	131377
Covered Lines:	115193
Line Coverage:	87.68%
Coverage Strength:	978514.95 hits per line

---

💛 - Coveralls