# 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`](qiskit_fermions.operators.FermionOperator.html.md#qiskit_fermions.operators.FermionOperator.groups) attribute of the provided
[`FermionOperator`](qiskit_fermions.operators.FermionOperator.html.md#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()`](qiskit_fermions.operators.FermionOperator.html.md#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/builtins/exceptions.html#ValueError) – if an unexpected term is encountered.