qiskit-documentation/docs/api/qiskit/1.2/qiskit.transpiler.passes.HighLevelSynthesis.mdx

---
title: HighLevelSynthesis (v1.2)
description: API reference for qiskit.transpiler.passes.HighLevelSynthesis in qiskit v1.2
in_page_toc_min_heading_level: 1
python_api_type: class
python_api_name: qiskit.transpiler.passes.HighLevelSynthesis
---

# HighLevelSynthesis

<Class id="qiskit.transpiler.passes.HighLevelSynthesis" isDedicatedPage={true} github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/transpiler/passes/synthesis/high_level_synthesis.py#L306-L721" signature="qiskit.transpiler.passes.HighLevelSynthesis(*args, **kwargs)" modifiers="class">
  Bases: [`TransformationPass`](qiskit.transpiler.TransformationPass "qiskit.transpiler.basepasses.TransformationPass")

  Synthesize higher-level objects and unroll custom definitions.

  The input to this pass is a DAG that may contain higher-level objects, including abstract mathematical objects (e.g., objects of type [`LinearFunction`](qiskit.circuit.library.LinearFunction "qiskit.circuit.library.LinearFunction")), annotated operations (objects of type [`AnnotatedOperation`](qiskit.circuit.AnnotatedOperation "qiskit.circuit.AnnotatedOperation")), and custom gates.

  In the most common use-case when either `basis_gates` or `target` is specified, all higher-level objects are synthesized, so the output is a [`DAGCircuit`](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") without such objects. More precisely, every gate in the output DAG is either directly supported by the target, or is in `equivalence_library`.

  The abstract mathematical objects are synthesized using synthesis plugins, applying synthesis methods specified in the high-level-synthesis config (refer to the documentation for [`HLSConfig`](qiskit.transpiler.passes.HLSConfig "qiskit.transpiler.passes.HLSConfig")).

  As an example, let us assume that `op_a` and `op_b` are names of two higher-level objects, that `op_a`-objects have two synthesis methods `default` which does require any additional parameters and `other` with two optional integer parameters `option_1` and `option_2`, that `op_b`-objects have a single synthesis method `default`, and `qc` is a quantum circuit containing `op_a` and `op_b` objects. The following code snippet:

  ```python
  hls_config = HLSConfig(op_b=[("other", {"option_1": 7, "option_2": 4})])
  pm = PassManager([HighLevelSynthesis(hls_config=hls_config)])
  transpiled_qc = pm.run(qc)
  ```

  shows how to run the alternative synthesis method `other` for `op_b`-objects, while using the `default` methods for all other high-level objects, including `op_a`-objects.

  The annotated operations (consisting of a base operation and a list of inverse, control and power modifiers) are synthesizing recursively, first synthesizing the base operation, and then applying synthesis methods for creating inverted, controlled, or powered versions of that).

  The custom gates are synthesized by recursively unrolling their definitions, until every gate is either supported by the target or is in the equivalence library.

  When neither `basis_gates` nor `target` is specified, the pass synthesizes only the top-level abstract mathematical objects and annotated operations, without descending into the gate `definitions`. This is consistent with the older behavior of the pass, allowing to synthesize some higher-level objects using plugins and leaving the other gates untouched.

  HighLevelSynthesis initializer.

  **Parameters**

  *   **hls\_config** – Optional, the high-level-synthesis config that specifies synthesis methods and parameters for various high-level-objects in the circuit. If it is not specified, the default synthesis methods and parameters will be used.
  *   **coupling\_map** – Optional, directed graph represented as a coupling map.
  *   **target** – Optional, the backend target to use for this pass. If it is specified, it will be used instead of the coupling map.
  *   **use\_qubit\_indices** – a flag indicating whether this synthesis pass is running before or after the layout is set, that is, whether the qubit indices of higher-level-objects correspond to qubit indices on the target backend.
  *   **equivalence\_library** – The equivalence library used (instructions in this library will not be unrolled by this pass).
  *   **basis\_gates** – Optional, target basis names to unroll to, e.g. \[‘u3’, ‘cx’]. Ignored if `target` is also specified.
  *   **min\_qubits** – The minimum number of qubits for operations in the input dag to translate.

  ## Attributes

  ### is\_analysis\_pass

  <Attribute id="qiskit.transpiler.passes.HighLevelSynthesis.is_analysis_pass">
    Check if the pass is an analysis pass.

    If the pass is an AnalysisPass, that means that the pass can analyze the DAG and write the results of that analysis in the property set. Modifications on the DAG are not allowed by this kind of pass.
  </Attribute>

  ### is\_transformation\_pass

  <Attribute id="qiskit.transpiler.passes.HighLevelSynthesis.is_transformation_pass">
    Check if the pass is a transformation pass.

    If the pass is a TransformationPass, that means that the pass can manipulate the DAG, but cannot modify the property set (but it can be read).
  </Attribute>

  ## Methods

  ### execute

  <Function id="qiskit.transpiler.passes.HighLevelSynthesis.execute" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/transpiler/basepasses.py#L189-L211" signature="execute(passmanager_ir, state, callback=None)">
    Execute optimization task for input Qiskit IR.

    **Parameters**

    *   **passmanager\_ir** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.13)")) – Qiskit IR to optimize.
    *   **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – State associated with workflow execution by the pass manager itself.
    *   **callback** ([*Callable*](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable "(in Python v3.13)") *| None*) – A callback function which is caller per execution of optimization task.

    **Returns**

    Optimized Qiskit IR and state of the workflow.

    **Return type**

    [tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")\[[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.13)"), [qiskit.passmanager.compilation\_status.PassManagerState](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")]
  </Function>

  ### name

  <Function id="qiskit.transpiler.passes.HighLevelSynthesis.name" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/passmanager/base_tasks.py#L68-L70" signature="name()">
    Name of the pass.

    **Return type**

    [str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)")
  </Function>

  ### run

  <Function id="qiskit.transpiler.passes.HighLevelSynthesis.run" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/transpiler/passes/synthesis/high_level_synthesis.py#L408-L457" signature="run(dag)">
    Run the HighLevelSynthesis pass on dag.

    **Parameters**

    **dag** ([*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.dagcircuit.DAGCircuit")) – input dag.

    **Returns**

    Output dag with higher-level operations synthesized.

    **Raises**

    *   [**TranspilerError**](transpiler#qiskit.transpiler.TranspilerError "qiskit.transpiler.TranspilerError") – when the transpiler is unable to synthesize the given DAG
    *   **(****for instance****, ****when the specified synthesis method is not available****)\*\*\*\*.** –

    **Return type**

    [*DAGCircuit*](qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.dagcircuit.DAGCircuit")
  </Function>

  ### update\_status

  <Function id="qiskit.transpiler.passes.HighLevelSynthesis.update_status" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/transpiler/basepasses.py#L213-L221" signature="update_status(state, run_state)">
    Update workflow status.

    **Parameters**

    *   **state** ([*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")) – Pass manager state to update.
    *   **run\_state** (*RunState*) – Completion status of current task.

    **Returns**

    Updated pass manager state.

    **Return type**

    [*PassManagerState*](qiskit.passmanager.PassManagerState "qiskit.passmanager.compilation_status.PassManagerState")
  </Function>
</Class>