[rajkumarrb]

Adds the dihedral (torsion) potentials part of #143 (bonds and angles #150 are already in).

Follows the discussion in #143 and the pyMBE-dev meeting of 14.09.2026.

What it adds

• DihedralTemplate / DihedralInstance in pyMBE/storage, mirroring the angle types. A template holds a list of terms, so GROMACS-style stacked multiplicities on the same quadruplet are supported. The template name is invariant under full reversal (A-B-C-D == D-C-B-A).
• define_dihedral_potential, define_default_dihedral_potential, create_dihedral_potential, get_dihedral_template.
• gen_dihedral argument in create_residue, create_molecule and create_hydrogel, following the gen_angle pattern. In hydrogels, only dihedrals internal to the chains are generated; dihedrals involving crosslinker nodes are not.
• ESPResSo engine support, storage manager and io (save/load) support.
• Tests (testsuite/dihedral_tests.py), sample script (samples/setup_dihedral_potential.py) and CHANGELOG entries.

Convention

As agreed in #143, the API uses the IUPAC/GROMACS convention (phi = 0 at cis). Users pass the parameters of the GROMACS proper dihedral type 1, V(phi) = k*[1 + cos(n*phi - phi_s)], as k, phi_s and mult. The ESPResSo-specific conversion is done inside the ESPResSo engine (phase = -(phi_s + pi)) and is documented in _create_dihedral_instance.

The ESPResSo Dihedral bond is attached to the second particle of the quadruplet, as in the ESPResSo documentation.

Testing

Besides checking that the right ESPResSo objects are created, the tests compare the dihedral set up in ESPResSo with independent numpy references:

• energies for several multiplicities, phases and angles, multi-term sums, and GROMACS type 1 parameters;
• forces against finite differences of the analytical energy, and net force and torque equal to zero;
• energy conservation in a short NVE run, and relaxation to the expected minimum with the right sign;
• reversed quadruplets and periodic boundaries;
• generation of dihedrals compared with a brute-force enumeration of the bond graph, and for nested residues and hydrogels.

The force tests use geometries away from the angles affected by espressomd/espresso#5401 (phi = 0 and pi).

make tests (36/36), make pylint and make docs passed locally with ESPResSo 5.0.1. The nested-residue and hydrogel generation tests were added after that run; dihedral_tests.py passes 27/27 and pylint is clean.

Not included

• Improper dihedrals and tabulated types ("tabulated" raises NotImplementedError).
• A comparison against a GROMACS .itp file, which can be a follow-up.
• Dihedrals involving hydrogel crosslinker nodes. Only dihedrals internal to the chains are generated (the angle potentials handle crosslinker junctions in _generate_hydrogel_crosslinker_angles).

Questions for reviewers

• Is phi_s an acceptable name for the parameter key (instead of phi_0 as in the angle potentials)?
• For molecules and residues, gen_dihedral=True skips quadruplets without a matching template silently, as gen_angle does. Should it log a warning instead? Should hydrogel crosslinker dihedrals follow the same all-or-nothing rule as the crosslinker angles?