Initial `Target` C API #14248

raynelfss · 2025-04-25T13:34:30Z

Summary

The following commits enable a C FFI for creation of a Rust Target.

Details and comments

As we work into expanding Qiskit into working in C, it is important to bring parts of the transpiler into this domain. One such part is the Target, which contains a lot of information about the hardware a circuit will be executed in. The following commits expose a C FFI that allows us to create and interact with a Target directly from C.

In order to achieve this we have 3 types of pointers being exposed to C:

QkTarget - which points to a Target in Rust.
QkPropsMap - which represents a mapping between Qargs : InstructionProperties, or, in C terms, this would be a mapping of uint32_t[] : QkInstructionProps.

The C FFI should allow us to:

Fully build a Target based on standard gates QkGate, a list of parameters double[], and an optional QkPropsMap containing the instruction properties.
Update any of the QkTarget instruction's properties after being added.

coveralls · 2025-04-25T14:00:26Z

Pull Request Test Coverage Report for Build 15447438495

Warning: This coverage report may be inaccurate.

This pull request's base commit is no longer the HEAD commit of its target branch. This means it includes changes from outside the original pull request, including, potentially, unrelated coverage changes.

For more information on this, see Tracking coverage changes with pull request builds.
To avoid this issue with future PRs, see these Recommended CI Configurations.
For a quick fix, rebase this PR at GitHub. Your next report should be accurate.

Details

276 of 316 (87.34%) changed or added relevant lines in 5 files are covered.
18 unchanged lines in 4 files lost coverage.
Overall coverage increased (+0.003%) to 87.906%

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
crates/cext/src/exit_codes.rs	6	8	75.0%
crates/transpiler/src/target/mod.rs	34	40	85.0%
crates/cext/src/transpiler/target.rs	233	265	87.92%

Files with Coverage Reduction	New Missed Lines	%
crates/transpiler/src/passes/unitary_synthesis.rs	1	94.57%
crates/qasm2/src/lex.rs	2	92.23%
qiskit/transpiler/passes/layout/vf2_utils.py	3	93.33%
crates/qasm2/src/parse.rs	12	96.68%

Totals
Change from base Build 15440870635:	0.003%
Covered Lines:	81653
Relevant Lines:	92887

💛 - Coveralls

- Add provisional `PropertyMap` to represent the mapping of `qargs : InstructionProperties` before adding it to the `Target`. - `InstructionProperties`: - free. - `Target`: - `update_instruction_prop` - `operation_names` - `physical_qubits` - `non_global_operation_names`. - `operation_names_for_qargs`. - `qargs_for_operation_names`. - `qargs`. - `instruction_supported`. - `contains_key`.

- Add getter methods for `InstructionProperties`. - Add `length` method for `PropertyMap`. - Add name maping for `PropertyMap`.

- Add `get` method to `Target`. - Add missing methods to `PropertyMap`. - Fix methods returning arrays to C by adding a a forget statement to prevent pointer from being destroyed. - Add getter methods to the `C` api of target. - Add helper function to parse qargs.

- Move `print_qargs` helper to top of module.

- Add helper method to compare arrays. - Fix print method for qargs.

- Use correct type of pointers for outputs,

- Use IndexSet to preserve insertion order to avoid sorting in the C API.

- Sort the string arrays obtained from the target in C during tests. - Remove `Copy` from `InstructionProperties`. - Add helper method to sort string array outputs, coming from the Target.

- Add getters for `description`, `dt` `min_length` `granularity`, `acquire_alignment`, and `pulse_alignment`. - Add Target construction test.

mtreinish

I know this isn't ready for review yet, and I haven't done a full review. But I opened this up and got triggered on the first c function so left a comment there.