---
title: MapperFnEvolutionSynthesis (latest version)
description: API reference for qiskit_fermions.transpiler.passes.synthesis.MapperFnEvolutionSynthesis in the latest version of qiskit-fermions
source: https://quantum.cloud.ibm.com/docs/en/api/qiskit-fermions/transpiler-passes-synthesis-mapper-fn-evolution-synthesis
---

# MapperFnEvolutionSynthesis

*class* `MapperFnEvolutionSynthesis(mapper_fn, product_formula=None)`

Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object)

A [`F2QSynthesisPlugin`](/docs/api/qiskit-fermions/transpiler-passes-synthesis-f-2-q-synthesis-plugin "qiskit_fermions.transpiler.passes.synthesis.F2QSynthesisPlugin") for transpiling [`Evolution`](/docs/api/qiskit-fermions/circuit-library-evolution "qiskit_fermions.circuit.library.Evolution") under a custom mapping.

This plugin maps the fermionic Hamiltonian $H$ of the incoming [`Evolution`](/docs/api/qiskit-fermions/circuit-library-evolution "qiskit_fermions.circuit.library.Evolution") gate to a qubit operator using [`mapper_fn`](#qiskit_fermions.transpiler.passes.synthesis.MapperFnEvolutionSynthesis.mapper_fn "qiskit_fermions.transpiler.passes.synthesis.MapperFnEvolutionSynthesis.mapper_fn") and emits a [`PauliEvolutionGate`](/docs/api/qiskit/qiskit.circuit.library.PauliEvolutionGate). It thereby preserves the $e^{-i t H}$ convention of the [`Evolution`](/docs/api/qiskit-fermions/circuit-library-evolution "qiskit_fermions.circuit.library.Evolution") gate, with the same evolution time $t$.

How that [`PauliEvolutionGate`](/docs/api/qiskit/qiskit.circuit.library.PauliEvolutionGate) is subsequently decomposed into basis gates is governed by the product formula passed as [`product_formula`](#qiskit_fermions.transpiler.passes.synthesis.MapperFnEvolutionSynthesis.product_formula "qiskit_fermions.transpiler.passes.synthesis.MapperFnEvolutionSynthesis.product_formula"). Leaving it at its default (`None`) defers to the [`PauliEvolutionGate`](/docs/api/qiskit/qiskit.circuit.library.PauliEvolutionGate)’s own default synthesis (a first-order [`LieTrotter`](/docs/api/qiskit/qiskit.synthesis.LieTrotter) decomposition with a single repetition). Supplying an explicit [`EvolutionSynthesis`](/docs/api/qiskit/qiskit.synthesis.EvolutionSynthesis) (for example a higher-order [`SuzukiTrotter`](/docs/api/qiskit/qiskit.synthesis.SuzukiTrotter) or one with several repetitions) selects a different Trotter-Suzuki product formula, trading circuit depth for a smaller Trotter error.

> **Note**
>
> The operator returned by [`mapper_fn`](#qiskit_fermions.transpiler.passes.synthesis.MapperFnEvolutionSynthesis.mapper_fn "qiskit_fermions.transpiler.passes.synthesis.MapperFnEvolutionSynthesis.mapper_fn") is passed on as-is, in particular **without** being simplified. A product formula synthesizes the Pauli terms in the order it receives them, so the term order that [`mapper_fn`](#qiskit_fermions.transpiler.passes.synthesis.MapperFnEvolutionSynthesis.mapper_fn "qiskit_fermions.transpiler.passes.synthesis.MapperFnEvolutionSynthesis.mapper_fn") produces is part of its output and is preserved here. A [`mapper_fn`](#qiskit_fermions.transpiler.passes.synthesis.MapperFnEvolutionSynthesis.mapper_fn "qiskit_fermions.transpiler.passes.synthesis.MapperFnEvolutionSynthesis.mapper_fn") that maps an operator group by group, for instance, emits the terms of each group together, which lets the terms of one group be scheduled in parallel where their supports are disjoint. See [`group_wise()`](/docs/api/qiskit-fermions/transpiler-passes-synthesis-group-wise "qiskit_fermions.transpiler.passes.synthesis.group_wise"), which wraps any mapper to do exactly that.

> **Caution**
>
> A consequence of preserving that order is that the synthesized circuit is only as reproducible as [`mapper_fn`](#qiskit_fermions.transpiler.passes.synthesis.MapperFnEvolutionSynthesis.mapper_fn "qiskit_fermions.transpiler.passes.synthesis.MapperFnEvolutionSynthesis.mapper_fn") is. The operators of the Rust core do **not** preserve the order in which their terms were added, so a mapper that walks an operator’s terms can emit them in a different order from one run to the next. The circuits that result are all equally valid (they approximate the same evolution of the same operator) but they need not be identical, and metrics such as depth or gate count can vary between them.
>
> Wrap the mapper in [`simplify()`](/docs/api/qiskit-fermions/transpiler-passes-synthesis-simplify "qiskit_fermions.transpiler.passes.synthesis.simplify") to pin a canonical order where that matters:
>
> ```python
> MapperFnEvolutionSynthesis(simplify(jordan_wigner))
> ```

Initializing this transpiler pass plugin can be done with the arguments listed below.

**Parameters**

- **mapper\_fn** (*MapperFunction*) – the fermion-to-qubit operator mapping function.
- **product\_formula** (*EvolutionSynthesis | None*) – the product formula with which to synthesize the emitted [`PauliEvolutionGate`](/docs/api/qiskit/qiskit.circuit.library.PauliEvolutionGate). If `None` (the default), the gate’s own default synthesis is used (a first-order [`LieTrotter`](/docs/api/qiskit/qiskit.synthesis.LieTrotter) decomposition with a single repetition).

## Attributes

### mapper\_fn

Type: `MapperFunction`

The fermion-to-qubit operator mapping function.

The two input arguments should be the following:

1. the operator to be mapped.
2. the number of qubits that the resulting operator should be defined on.

> **Note**
>
> It is the user’s responsibility to ensure that this function is in-sync with the global transpilation [`F2QLayout`](/docs/api/qiskit-fermions/transpiler-f-2-q-layout "qiskit_fermions.transpiler.F2QLayout") setting.

### product\_formula

Type: `EvolutionSynthesis` | [`None`](https://docs.python.org/3/builtins/constants.html#None)

The product formula used to synthesize the emitted [`PauliEvolutionGate`](/docs/api/qiskit/qiskit.circuit.library.PauliEvolutionGate), or `None` to defer to that gate’s own default synthesis.

## Methods

### run

`run(in_node, out_dag, *, f2q_layout)`

Runs this transpilation plugin.

The fermionic Hamiltonian of the incoming [`Evolution`](/docs/api/qiskit-fermions/circuit-library-evolution "qiskit_fermions.circuit.library.Evolution") gate is mapped to a qubit operator via [`mapper_fn`](#qiskit_fermions.transpiler.passes.synthesis.MapperFnEvolutionSynthesis.mapper_fn "qiskit_fermions.transpiler.passes.synthesis.MapperFnEvolutionSynthesis.mapper_fn") and appended to `out_dag` as a [`PauliEvolutionGate`](/docs/api/qiskit/qiskit.circuit.library.PauliEvolutionGate) implementing $e^{-i t H}$ with the original evolution time $t$ and the [`product_formula`](#qiskit_fermions.transpiler.passes.synthesis.MapperFnEvolutionSynthesis.product_formula "qiskit_fermions.transpiler.passes.synthesis.MapperFnEvolutionSynthesis.product_formula") synthesis.

**Parameters**

- **in\_node** ([*DAGOpNode*](/docs/api/qiskit/qiskit.dagcircuit.DAGOpNode)) – the input fermion-based circuit instruction. When this plugin gets called, the `in_node.op` attribute must be of type [`Evolution`](/docs/api/qiskit-fermions/circuit-library-evolution "qiskit_fermions.circuit.library.Evolution").
- **out\_dag** ([*DAGCircuit*](/docs/api/qiskit/qiskit.dagcircuit.DAGCircuit)) – the output qubit-based circuit.
- **f2q\_layout** ([*dict*](https://docs.python.org/3/builtins/stdtypes.html#dict)*\[*[*QuantumRegister*](/docs/api/qiskit/circuit#qiskit.circuit.QuantumRegister)*,* [*QuantumRegister*](/docs/api/qiskit/circuit#qiskit.circuit.QuantumRegister)*]*) – the global transpilation [`F2QLayout`](/docs/api/qiskit-fermions/transpiler-f-2-q-layout "qiskit_fermions.transpiler.F2QLayout") setting.

**Return type**

None

> **See also**
>
> The documentation of [`F2QSynthesisPlugin`](/docs/api/qiskit-fermions/transpiler-passes-synthesis-f-2-q-synthesis-plugin "qiskit_fermions.transpiler.passes.synthesis.F2QSynthesisPlugin") for more detailed explanations of the arguments.

**Raises**

[**NotImplementedError**](https://docs.python.org/3/builtins/exceptions.html#NotImplementedError) – when `in_node` acts on fermionic modes that are spread across multiple [`FermionicRegister`](/docs/api/qiskit-fermions/circuit-fermionic-register "qiskit_fermions.circuit.FermionicRegister") instances.

**Parameters**

- **in\_node** ([*DAGOpNode*](/docs/api/qiskit/qiskit.dagcircuit.DAGOpNode))
- **out\_dag** ([*DAGCircuit*](/docs/api/qiskit/qiskit.dagcircuit.DAGCircuit))
- **f2q\_layout** ([*dict*](https://docs.python.org/3/builtins/stdtypes.html#dict)*\[*[*QuantumRegister*](/docs/api/qiskit/circuit#qiskit.circuit.QuantumRegister)*,* [*QuantumRegister*](/docs/api/qiskit/circuit#qiskit.circuit.QuantumRegister)*]*)

**Return type**

None