---
title: group_terms_by_electronic_structure (latest version)
description: API reference for qiskit_fermions.operators.terms.group_terms_by_electronic_structure in the latest version of qiskit-fermions
source: https://eu-de.quantum.cloud.ibm.com/docs/en/api/qiskit-fermions/operators-terms-group-terms-by-electronic-structure
---

# group\_terms\_by\_electronic\_structure

`group_terms_by_electronic_structure(op, num_modes, *, two_body_physicist_order=False)`

Groups the terms of an operator by their electronic structure.

This function automatically populates the [`groups`](/docs/api/qiskit-fermions/operators-fermion-operator#groups "qiskit_fermions.operators.FermionOperator.groups") attribute of the provided [`FermionOperator`](/docs/api/qiskit-fermions/operators-fermion-operator "qiskit_fermions.operators.FermionOperator") such that terms satisfying a symmetric perturbation present in electronic-structure Hamiltonians are grouped.

> **Caution**
>
> The provided operator *must* be normal-ordered! This is an underlying assumption of the implementation that is *not* being verified! See [`normal_ordered()`](/docs/api/qiskit-fermions/operators-fermion-operator#normal_ordered "qiskit_fermions.operators.FermionOperator.normal_ordered") for how to get an operator of that form.

More concretely, given an electronic-structure Hamiltonian of the form

$$
\mathcal{H} = \sum_{ij} c_{ij} a^\dagger_i a_j
+ \sum_{ijkl} c_{ijkl} a^\dagger_i a^\dagger_j a_k a_l \, ,
$$

this function will group 1-body terms with permutational symmetry of `(i, j)` as well as the 2-body terms with permutational symmetry of `(i, j, k, l)`. For the 2-body terms, not all permutations will be grouped. Instead, the `two_body_physicist_order` determines how the four indices get grouped into pairs of two within which permutational symmetries exist:

- `two_body_physicist_order=False` (default): `(i, l)` and `(j, k)`
- `two_body_physicist_order=True`: `(i, k)` and `(j, l)`

```python
from qiskit_fermions.operators import FermionOperator
from qiskit_fermions.operators.library import FCIDump

fcidump = FCIDump.from_file("molecule.fcidump")
operator = FermionOperator.from_fcidump(fcidump)

normal = op.normal_ordered().simplify(atol=0.0)

group_terms_by_electronic_structure(normal, 2 * fcidump.norb, two_body_physicist_order=False)

assert normal.has_groups()
```

**Parameters**

- **op** – the normal-ordered operator whose terms to group.
- **num\_modes** – the number of spin-less fermionic modes in the system.
- **two\_body\_physicist\_order** – whether the 2-body terms are stored in physicists order.

**Raises**

[**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError) – if an unexpected term is encountered.