Add TranspileLayout struct to rust #14778
Open
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This commit adds a Rust TranspileLayout object which is analgous to the Python space object. It is a self contained struct that is only for Rust and will be used by the C API for the C transpiler so that users will be able to reason about the permutations caused by the transpiler. This will also be used by Qiskit#14106 to apply a transpilation layout to the SparseObservable in C. This commit only adds the rust struct and it's associated tests, a subsequent PR will add the C API on top. This won't be used until we have a full path transpiler in C though (see Qiskit#14760).
mtreinish
added
Changelog: None
|
One or more of the following people are relevant to this code:
|
jakelishman
reviewed
Jul 22, 2025
There was a problem hiding this comment.
If we're going to do this, please can we replace the Python-space version at the same time? TranspileLayout in Python is already not well documented and hard to follow1, and I really don't want two parallel structs of the same type in the library at the same time.
Footnotes
-
as this notification popped, I was literally writing something against
TranspileLayoutand had to got to thePassManagerto figure out what one of the input fields was supposed to represent. ↩
jakelishman
reviewed
Jul 22, 2025
Comment on lines
+15
to
+29
| /// The "layout" caused by transpilation | ||
| /// | ||
| /// In general Qiskit's transpiler is unitary-preserving up to the initial layout | ||
| /// and routing permutations. The initial layout permutation is caused by | ||
| /// setting and applying the initial layout (the mapping from virtual circuit | ||
| /// qubits to physical qubits on the target) and the routing permtuations are | ||
| /// caused by swap gate insertion or permutation ellision prior to the initial | ||
| /// layout. This struct tracks these details and provide an interface to reason | ||
| /// about these permutations. | ||
| pub struct TranspileLayout { | ||
| initial_layout: NLayout, | ||
| routing_permutation: Option<Vec<PhysicalQubit>>, | ||
| input_qubit_count: u32, | ||
| output_qubit_count: u32, | ||
| } |
There was a problem hiding this comment.
This could do with more documentation, especially routing_permutation - this needs to clearly state how the permutation of routing_permutation is supposed to be interpreted.
Under what circumstances can output_qubit_count be different to the length of initial_layout?
Pull Request Test Coverage Report for Build 16481789778Details
💛 - Coveralls |
I considered doing it but I wrote this specifically using the Rust native types to work with the transpiler in rust and c. If you look at #14760 besides the output I was planning to use this as the container throughout the The problem with using it as a replacement in python is the existing class has public attributes that are all python types and the construction is in terms of the python |
mtreinish
added a commit
to mtreinish/qiskit-core
that referenced
this pull request
Jul 22, 2025
This commit adds the TranspileLayout struct added in Qiskit#14778 to the C API. It is a straightforward addition to the API as the interface is fairly simple. Given a pointer to a TranspileLayout the methods return the arrays for the various views of the layout or the number of qubits for the input and output circuits. One small change was made to the PhysicalQubit and VirtualQubit type definitions to use #[repr(transparent)] which in practice shouldn't change anything, but it makes it explicit that these can be used interchangeably with a u32. This simplifies how we can return arrays of either type to C because it is safe to cast them as pointers to u32s. Note that nothing in the C API is capable of generating a transpile layout currently. The intent is for it to be part of the full transpile() function return (see Qiskit#14778). In the meantime this is tested solely through rust tests and there aren't any tests written in C yet. A potential follow up commit can be made to update the standalone vf2 layout pass function to use a transpile layout inside it's result type which would be more ergonomic than it's current layout object in the result. But to keep this PR targeted this doesn't update that interface and only exposes the struct to the C API.
mtreinish
added a commit
to mtreinish/qiskit-core
that referenced
this pull request
Jul 22, 2025
This commit adds the TranspileLayout struct added in Qiskit#14778 to the C API. It is a straightforward addition to the API as the interface is fairly simple. Given a pointer to a TranspileLayout the methods return the arrays for the various views of the layout or the number of qubits for the input and output circuits. One small change was made to the PhysicalQubit and VirtualQubit type definitions to use #[repr(transparent)] which in practice shouldn't change anything, but it makes it explicit that these can be used interchangeably with a u32. This simplifies how we can return arrays of either type to C because it is safe to cast them as pointers to u32s. Note that nothing in the C API is capable of generating a transpile layout currently. The intent is for it to be part of the full transpile() function return (see Qiskit#14778). In the meantime this is tested solely through rust tests and there aren't any tests written in C yet. A potential follow up commit can be made to update the standalone vf2 layout pass function to use a transpile layout inside it's result type which would be more ergonomic than it's current layout object in the result. But to keep this PR targeted this doesn't update that interface and only exposes the struct to the C API.
mtreinish
added a commit
to mtreinish/qiskit-core
that referenced
this pull request
Jul 22, 2025
This commit adds the TranspileLayout struct added in Qiskit#14778 to the C API. It is a straightforward addition to the API as the interface is fairly simple. Given a pointer to a TranspileLayout the methods return the arrays for the various views of the layout or the number of qubits for the input and output circuits. One small change was made to the PhysicalQubit and VirtualQubit type definitions to use #[repr(transparent)] which in practice shouldn't change anything, but it makes it explicit that these can be used interchangeably with a u32. This simplifies how we can return arrays of either type to C because it is safe to cast them as pointers to u32s. Note that nothing in the C API is capable of generating a transpile layout currently. The intent is for it to be part of the full transpile() function return (see Qiskit#14778). In the meantime this is tested solely through rust tests and there aren't any tests written in C yet. A potential follow up commit can be made to update the standalone vf2 layout pass function to use a transpile layout inside it's result type which would be more ergonomic than it's current layout object in the result. But to keep this PR targeted this doesn't update that interface and only exposes the struct to the C API.
mtreinish
added a commit
to mtreinish/qiskit-core
that referenced
this pull request
Jul 22, 2025
This commit adds the TranspileLayout struct added in Qiskit#14778 to the C API. It is a straightforward addition to the API as the interface is fairly simple. Given a pointer to a TranspileLayout the methods return the arrays for the various views of the layout or the number of qubits for the input and output circuits. One small change was made to the PhysicalQubit and VirtualQubit type definitions to use #[repr(transparent)] which in practice shouldn't change anything, but it makes it explicit that these can be used interchangeably with a u32. This simplifies how we can return arrays of either type to C because it is safe to cast them as pointers to u32s. Note that nothing in the C API is capable of generating a transpile layout currently. The intent is for it to be part of the full transpile() function return (see Qiskit#14778). In the meantime this is tested solely through rust tests and there aren't any tests written in C yet. A potential follow up commit can be made to update the standalone vf2 layout pass function to use a transpile layout inside it's result type which would be more ergonomic than it's current layout object in the result. But to keep this PR targeted this doesn't update that interface and only exposes the struct to the C API.
This commit improves the routing permutation method to make them more rust native. It updates the return to be a slice of PhysicalQubits instead of an owned vec. To get the explicit trivial permutation in the case of None a new method explicit_routing_permutation is added that returns `Cow<[PhysicalQubits]>` and only allocates in the None case.
This commit updates the final layout method to return a NLayout and a new method final_index_layout is added to return a Vec.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
This commit adds a Rust TranspileLayout object which is analgous to the Python space object. It is a self contained struct that is only for Rust and will be used by the C API for the C transpiler so that users will be able to reason about the permutations caused by the transpiler. This will also be used by #14106 to apply a transpilation layout to the SparseObservable in C. This commit only adds the rust struct and it's associated tests, a subsequent PR will add the C API on top. This won't be used until we have a full path transpiler in C though (see #14760).
Details and comments