Skip to main contentIBM Quantum Documentation


class qiskit.transpiler.passes.HLSConfig(use_default_on_unspecified=True, plugin_selection='sequential', plugin_evaluation_fn=None, **kwargs)

GitHub(opens in a new tab)

Bases: object(opens in a new tab)

The high-level-synthesis config allows to specify a list of “methods” used by HighLevelSynthesis transformation pass to synthesize different types of higher-level objects.

A higher-level object is an object of type Operation (e.g., Clifford or LinearFunction). Each object is referred to by its name field (e.g., "clifford" for Clifford objects), and the applicable synthesis methods are tied to this name.

In the config, each method is specified in one of several ways:

  1. a tuple consisting of the name of a known synthesis plugin and a dictionary providing additional arguments for the algorithm.
  2. a tuple consisting of an instance of HighLevelSynthesisPlugin and additional arguments for the algorithm.
  3. a single string of a known synthesis plugin
  4. a single instance of HighLevelSynthesisPlugin.

The following example illustrates different ways how a config file can be created:

from qiskit.transpiler.passes.synthesis.high_level_synthesis import HLSConfig
from qiskit.transpiler.passes.synthesis.high_level_synthesis import ACGSynthesisPermutation
# All the ways to specify hls_config are equivalent
hls_config = HLSConfig(permutation=[("acg", {})])
hls_config = HLSConfig(permutation=["acg"])
hls_config = HLSConfig(permutation=[(ACGSynthesisPermutation(), {})])
hls_config = HLSConfig(permutation=[ACGSynthesisPermutation()])

The names of the synthesis plugins should be declared in entry-points table for qiskit.synthesis in pyproject.toml, in the form <higher-level-object-name>.<synthesis-method-name>.

The standard higher-level-objects are recommended to have a synthesis method called “default”, which would be called automatically when synthesizing these objects, without having to explicitly set these methods in the config.

To avoid synthesizing a given higher-level-object, one can give it an empty list of methods.

For an explicit example of using such config files, refer to the documentation for HighLevelSynthesis.

For an overview of the complete process of using high-level synthesis, see High-level Synthesis Plugins.

Creates a high-level-synthesis config.


  • use_default_on_unspecified (bool(opens in a new tab)) – if True, every higher-level-object without an explicitly specified list of methods will be synthesized using the “default” algorithm if it exists.
  • plugin_selection (str(opens in a new tab)) – if set to "sequential" (default), for every higher-level-object the synthesis pass will consider the specified methods sequentially, stopping at the first method that is able to synthesize the object. If set to "all", all the specified methods will be considered, and the best synthesized circuit, according to plugin_evaluation_fn will be chosen.
  • plugin_evaluation_fn (Callable(opens in a new tab)[[QuantumCircuit], int(opens in a new tab)] | None) – a callable that evaluates the quality of the synthesized quantum circuit; a smaller value means a better circuit. If None, the quality of the circuit its size (i.e. the number of gates that it contains).
  • kwargs – a dictionary mapping higher-level-objects to lists of synthesis methods.



set_methods(hls_name, hls_methods)

GitHub(opens in a new tab)

Sets the list of synthesis methods for a given higher-level-object. This overwrites the lists of methods if also set previously.

Was this page helpful?
Report a bug or request content on GitHub.