VF2 compiler-pass objects
QkVF2LayoutConfiguration
typedef struct QkVF2LayoutConfiguration QkVF2LayoutConfigurationThe configuration for the VF2 layout passes. This is an encapsulated configuration to allow for changes in the API over time; you create and mutate this using the constructor and setters below.
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.
Call qk_vf2_layout_configuration_free with the return value to free the memory when done.
Returns
A pointer to the configuration.
qk_vf2_layout_configuration_free
void qk_vf2_layout_configuration_free(QkVF2LayoutConfiguration *config)
Free a QkVf2LayoutConfiguration object.
Safety
Behavior is undefined if config is a non-null pointer, but does not point to a valid, aligned QkVF2LayoutConfiguration object.
Parameters
- 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 before, int64_t after)
Limit the numbers of times that the VF2 algorithm will attempt to extend its mapping before and after it finds the first match.
The VF2 algorithm keeps track of the number of steps it has taken, and terminates when it reaches the limit. After the first match is found, the limit swaps from the “before” limit to the “after” limit without resetting the number of steps taken.
Safety
Behavior is undefined if config is not a valid, aligned, non-null pointer to a QkVF2LayoutConfiguration.
Parameters
- config – The configuration to update.
- before – The number of attempts to allow before the first match is found. Set to a negative number to have no bound.
- after – The number of attempts to allow after the first match (if any) is found. 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.
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
Behavior is undefined if config is not a valid, aligned, non-null pointer to a QkVF2LayoutConfiguration.
Parameters
- 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.
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
Behavior is undefined if config is not a valid, aligned, non-null pointer to a QkVF2LayoutConfiguration.
Parameters
- 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.
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.
Safety
Behavior is undefined if config is not a valid, aligned, non-null pointer to a QkVF2LayoutConfiguration.
Parameters
- config – The configuration to update.
- seed – The seed to use for the activated shuffling.
qk_vf2_layout_configuration_set_score_initial
void qk_vf2_layout_configuration_set_score_initial(QkVF2LayoutConfiguration *config, bool score_initial)
Whether to eagerly score the initial “trivial” layout of the interaction graph.
You typically want to set this true if you are using the VF2 passes to improve a circuit that is already lowered to hardware, in order to set a baseline for the score-based pruning. If not, you can leave this as false (the default), to avoid a calculation that likely will not have any impact.
Safety
Behavior is undefined if config is not a valid, aligned, non-null pointer to a VF2LayoutConfiguration.
Parameters
- config – The configuration to update.
- score_initial – Whether to eagerly score the initial trivial layout.
QkVF2LayoutResult
typedef struct QkVF2LayoutResult QkVF2LayoutResultWhen running the qk_transpiler_pass_standalone_vf2_layout function it returns its analysis result as a QkVF2LayoutResult object. This object contains the outcome of the transpiler pass, whether the pass was able to find a layout or not, and what the layout selected by the pass was.
Functions
qk_vf2_layout_result_has_match
bool qk_vf2_layout_result_has_match(const QkVF2LayoutResult *layout)
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.
Safety
Behavior is undefined if layout is not a valid, non-null pointer to a QkVF2LayoutResult.
Parameters
- layout – a pointer to the layout
Returns
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.
Safety
Behavior is undefined if layout is not a valid, non-null pointer to a QkVF2LayoutResult.
Parameters
- layout – a pointer to the layout
Returns
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
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.
Parameters
- layout – a pointer to the layout
- qubit – the virtual qubit to get the physical qubit of
Returns
The physical qubit mapped to by the specified virtual qubit