# BasisTranslator

`qiskit.transpiler.passes.BasisTranslator(*args, **kwargs)`

GitHub(opens in a new tab)

Bases: `TransformationPass`

Translates gates to a target basis by searching for a set of translations from a given EquivalenceLibrary.

This pass operates in several steps:

- Determine the source basis from the input circuit.
- Perform a Dijkstra search over basis sets, starting from the device’s target_basis new gates are being generated using the rules from the provided EquivalenceLibrary and the search stops if all gates in the source basis have been generated.
- The found path, as a set of rules from the EquivalenceLibrary, is composed into a set of gate replacement rules.
- The composed replacement rules are applied in-place to each op node which is not already in the target_basis.

If the target keyword argument is specified and that `Target`

objects contains operations which are non-global (i.e. they are defined only for a subset of qubits), as calculated by `get_non_global_operation_names()`

, this pass will attempt to match the output translation to those constraints. For 1 qubit operations this is straightforward, the pass will perform a search using the union of the set of global operations with the set of operations defined solely on that qubit. For multi-qubit gates this is a bit more involved, while the behavior is initially similar to the single qubit case, just using all the qubits the operation is run on (where order is not significant) isn’t sufficient. We also need to consider any potential local qubits defined on subsets of the quantum arguments for the multi-qubit operation. This means the target used for the search of a non-global multi-qubit gate is the union of global operations, non-global multi-qubit gates sharing the same qubits, and any non-global gates defined on any subset of the qubits used.

In the case of non-global operations it is possible for a single execution of this pass to output an incomplete translation if any non-global gates are defined on qubits that are a subset of a larger multi-qubit gate. For example, if you have a `u`

gate only defined on qubit 0 and an `x`

gate only on qubit 1 it is possible when translating a 2 qubit operation on qubit 0 and 1 that the output might have `u`

on qubit 1 and `x`

on qubit 0. Typically running this pass a second time will correct these issues.

## Translation Errors

This pass will error if there is no path to translate an input gate to the specified basis. However, during a typical/default preset passmanager this pass gets run multiple times at different stages of the compilation pipeline. This means that potentially the input gates that are getting translated were not in the input circuit to `transpile()`

as they were generated by an intermediate transform in the circuit.

When this error occurs it typically means that either the target basis is not universal or there are additional equivalence rules needed in the :clas:~.EquivalenceLibrary` instance being used by the :class:~.BasisTranslator` pass. You can refer to Custom Basis Gates for details on adding custom equivalence rules.

Initialize a BasisTranslator instance.

**param equivalence_library**

The equivalence library which will be used by the BasisTranslator pass. (Instructions in this library will not be unrolled by this pass.)

**type equivalence_library**

EquivalenceLibrary

**param target_basis**

Target basis names to unroll to, e.g. `['u3', 'cx']`

.

**type target_basis**

list[str]

**param target**

The backend compilation target

**type target**

Target

**param min_qubits**

The minimum number of qubits for operations in the input dag to translate.

**type min_qubits**

int

## Attributes

### 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.

### 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).

## Methods

### execute

`execute(passmanager_ir, state, callback=None)`

Execute optimization task for input Qiskit IR.

**Parameters**

**passmanager_ir**(*Any*(opens in a new tab)) – Qiskit IR to optimize.**state**(*PassManagerState*) – State associated with workflow execution by the pass manager itself.**callback**(*Callable*(opens in a new tab)*| None*) – A callback function which is caller per execution of optimization task.

**Returns**

Optimized Qiskit IR and state of the workflow.

**Return type**

tuple(opens in a new tab)[*Any*(opens in a new tab), qiskit.passmanager.compilation_status.PassManagerState]

### name

`name()`

Name of the pass.

**Return type**

### run

`run(dag)`

Translate an input DAGCircuit to the target basis.

**Parameters**

**dag** (*DAGCircuit*) – input dag

**Raises**

**TranspilerError** – if the target basis cannot be reached

**Returns**

translated circuit.

**Return type**

### update_status

`update_status(state, run_state)`

Update workflow status.

**Parameters**

**state**(*PassManagerState*) – Pass manager state to update.**run_state**(*RunState*) – Completion status of current task.

**Returns**

Updated pass manager state.

**Return type**