---
title: EquivalenceLibrary (latest version)
description: API reference for qiskit.circuit.EquivalenceLibrary in the latest version of qiskit
source: https://quantum.cloud.ibm.com/docs/en/api/qiskit/qiskit.circuit.EquivalenceLibrary
---

# EquivalenceLibrary

*class* `qiskit.circuit.EquivalenceLibrary(base=None)`

[GitHub](https://github.com/Qiskit/qiskit/tree/stable/2.5/qiskit/circuit/equivalence.py#L40-L109)

Bases: `BaseEquivalenceLibrary`

A library providing a one-way mapping of Gates to their equivalent implementations as QuantumCircuits.

## Attributes

### graph

Return graph representing the equivalence library data.

This property should be treated as read-only as it provides a reference to the internal state of the [`EquivalenceLibrary`](#qiskit.circuit.EquivalenceLibrary "qiskit.circuit.EquivalenceLibrary") object. If the graph returned by this property is mutated it could corrupt the the contents of the object. If you need to modify the output `PyDiGraph` be sure to make a copy prior to any modification.

**Returns**

A graph object with equivalence data in each node.

**Return type**

PyDiGraph

## Methods

### add\_equivalence

`add_equivalence(gate, equivalent_circuit)`

Add a new equivalence to the library. Future queries for the Gate will include the given circuit, in addition to all existing equivalences (including those from base).

Parameterized Gates (those including qiskit.circuit.Parameters in their Gate.params) can be marked equivalent to parameterized circuits, provided the parameters match.

**Parameters**

- **gate** ([*Gate*](/docs/api/qiskit/qiskit.circuit.Gate "qiskit.circuit.Gate")) – A Gate instance.
- **equivalent\_circuit** ([*QuantumCircuit*](/docs/api/qiskit/qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – A circuit equivalently implementing the given Gate.

### draw

`draw(filename=None)`

[GitHub](https://github.com/Qiskit/qiskit/tree/stable/2.5/qiskit/circuit/equivalence.py#L44-L73)

Draws the equivalence relations available in the library.

> **Warning**
>
> This function will call the system Graphviz tool on a file involving user-controllable strings (such as gate names). It is recommended to only call this function on trusted input.

**Parameters**

**filename** ([*str*](https://docs.python.org/3/library/stdtypes.html#str)) – An optional path to write the output image to. If unspecified, the image will instead be returned.

**Returns**

If `filename` is `None`, then the rendered image.

**Return type**

PIL.Image

**Raises**

[**InvalidFileError**](/docs/api/qiskit/exceptions#qiskit.exceptions.InvalidFileError "qiskit.exceptions.InvalidFileError") – if filename is not valid.

### get\_entry

`get_entry(gate)`

Gets the set of [`QuantumCircuit`](/docs/api/qiskit/qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") instances circuits from the library which equivalently implement the given [`Gate`](/docs/api/qiskit/qiskit.circuit.Gate "qiskit.circuit.Gate").

Parameterized circuits will have their parameters replaced with the corresponding entries from Gate.params.

**Parameters**

**gate** ([*Gate*](/docs/api/qiskit/qiskit.circuit.Gate "qiskit.circuit.Gate")) – A Gate instance.

**Returns**

**A list of equivalent [`QuantumCircuit`](/docs/api/qiskit/qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") instances.**

If empty, library contains no known decompositions of Gate.

Returned circuits will be ordered according to their insertion in the library, from earliest to latest, from top to base. The ordering of the StandardEquivalenceLibrary will not generally be consistent across Qiskit versions.

**Return type**

List\[[QuantumCircuit](/docs/api/qiskit/qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")]

### has\_entry

`has_entry(gate)`

Check if a library contains any decompositions for gate.

**Parameters**

**gate** ([*Gate*](/docs/api/qiskit/qiskit.circuit.Gate "qiskit.circuit.Gate")) – A Gate instance.

**Returns**

**True if gate has a known decomposition in the library.**

False otherwise.

**Return type**

[Bool](/docs/api/qiskit/circuit_classical#qiskit.circuit.classical.types.Bool "qiskit.circuit.classical.types.Bool")

### keys

`keys()`

Return list of keys to key to node index map.

**Returns**

Keys to the key to node index map.

**Return type**

List

### node\_index

`node_index(key)`

Return node index for a given key.

**Parameters**

**key** (*Key*) – Key to an equivalence.

**Returns**

Index to the node in the graph for the given key.

**Return type**

Int

### set\_entry

`set_entry(gate, entry)`

Set the equivalence record for a Gate. Future queries for the Gate will return only the circuits provided.

Parameterized Gates (those including qiskit.circuit.Parameters in their Gate.params) can be marked equivalent to parameterized circuits, provided the parameters match.

**Parameters**

- **gate** ([*Gate*](/docs/api/qiskit/qiskit.circuit.Gate "qiskit.circuit.Gate")) – A Gate instance.
- **entry** (*List\['QuantumCircuit']*) – A list of [`QuantumCircuit`](/docs/api/qiskit/qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") instances, each equivalently implementing the given Gate.