---
title: build_excitation_span_minimization_model (latest version)
description: API reference for qiskit_fermions.mappers.optimization.build_excitation_span_minimization_model in the latest version of qiskit-fermions
source: https://eu-de.quantum.cloud.ibm.com/docs/en/api/qiskit-fermions/mappers-optimization-build-excitation-span-minimization-model
---

# build\_excitation\_span\_minimization\_model

`build_excitation_span_minimization_model(excitations, num_modes, *, objective='multi', mix_delta=0.1)`

Build a Pyomo model for ordering fermionic modes to minimize excitation spans.

The model constructs a permutation where each original mode index is assigned to exactly one position in a linear ordering. For every 2-mode and 4-mode excitation tuple, the span of occupied positions is minimized according to the chosen objective.

> **Note**
>
> The `excitations` list is pre-processed as follows:
>
> - indices that occur twice within the same tuple get cancelled
> - resulting tuples of length 0 or 1 are ignored, therefore not imposing a distance constraint in the resulting minimization model
> - consequently, only post-processed tuples of length 2 or 4 are expected

> **See also**
>
> For a more detailed discussion and explanation of the reasoning behind this pre-processing, refer to section III.B of [this paper](https://arxiv.org/abs/2508.02578v2).

**Parameters**

- **excitations** (*Sequence\[*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple)*\[*[*int*](https://docs.python.org/3/library/functions.html#int)*,* [*int*](https://docs.python.org/3/library/functions.html#int)*] |* [*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple)*\[*[*int*](https://docs.python.org/3/library/functions.html#int)*,* [*int*](https://docs.python.org/3/library/functions.html#int)*,* [*int*](https://docs.python.org/3/library/functions.html#int)*,* [*int*](https://docs.python.org/3/library/functions.html#int)*]]*) – a sequence of excitation index tuples over fermionic mode indices.

- **num\_modes** ([*int*](https://docs.python.org/3/library/functions.html#int)) – the total number of fermionic modes to be ordered.

- **objective** (*Literal\['minmax', 'multi', 'avg']*) –

  the chosen objective mode. This may be one of the following literals:

  - `minmax`: minimizes the maximum excitation span.
  - `avg`: minimizes the average excitation span.
  - `multi`: minimizes `max_span + mix_delta * average_span`.

- **mix\_delta** ([*float*](https://docs.python.org/3/library/functions.html#float)) – the mixing weight used in the case of `objective="multi"`.

**Returns**

A Pyomo optimization model encoding the permutation variables, span variables, constraints, and objective. Solve this model with a Pyomo solver to obtain an optimized ordering.

**Raises**

- [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError) – if a post-processed excitation tuple has length unequal to 2 or 4.
- [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError) – if an unknown `objective` is chosen.

**Return type**

[pyomo.core.base.PyomoModel.ConcreteModel](https://pyomo.readthedocs.io/en/stable/api/pyomo.core.base.PyomoModel.ConcreteModel.html#pyomo.core.base.PyomoModel.ConcreteModel "(in Pyomo v6.10.1)")