Add support for all bonded potentials

[pm-blanco]

Currently only harmonic and FENE bond interactions are supported in pyMBE. That limits our capabilities as a tool to setup advanced force fields in ESPResSo. Tasks to be done to make progress in this project:

• Implement define_angular_potential and define_dihedral_potential functions in analogy to our current setup for bonds, done with define_bond.
• Implement bookkeeping tool (map) of the connectivity between pairs, triplets and quadriplets of particles within molecules either using the pyMBE dataframe (one would need to create two more columns for particle ids) or with a dedicated data structure.
• When creating a molecule, pyMBE should check for the conectivity of the particle and add bending and dihedral potentials (if defined).

[pm-blanco]

Draft of define_angular_potential , after online discussion with @1234somesh

• We add support for "Harmonic angle", "Cosine angle" and "Harmonic cosine" potentials, given by the angle_potential_type
• particle_triplets = [ [name0, name1, name2 ], ], where we hard-code that the name in the center of the inner list is always the central particle. This should be clearly documented.
• We also define a create_angular_potential_in_espresso(self, angle_potential_type, angle_parameters) that checks the parameters and creates the espresso angular potential object (cf. create_bond_in_espresso)
• the angle_key of a particle triplet ["A", "B", "C"] should be "A-B-C"

 def define_angular_potential(self, angle_potential_type, angle_parameters, particle_triplets):
        # Add docs here
        angular_potential_object=self.create_angular_potential_in_espresso(angle_potential_type, angle_parameters)
        for side_particle0, central_particle, side_particle1 in particle_triplets :
            index = len(self.df)
            # Adapt this to the label for angular potential A-B-C
            for label in [f'{particle_name1}-{particle_name2}', f'{particle_name2}-{particle_name1}']:
                self._check_if_multiple_pmb_types_for_name(name=label, pmb_type_to_be_defined="angle_potential")
            name=f'{particle_name1}-{particle_name2}'
            self._check_if_multiple_pmb_types_for_name(name=name, pmb_type_to_be_defined="angle_potential")    
            self.df.at [index,'name']= name
            self.df.at [index,'bond_object'] = bond_object      
            self.add_value_to_df(index=index,
                                    key=('pmb_type',''),
                                    new_value='angle_potential')
            self.add_value_to_df(index=index,
                                    key=('parameters_of_the_potential',''),
                                    new_value=bond_object.get_params(),
                                    non_standard_value=True)
        self.df.fillna(pd.NA, inplace=True)
        return

[rajkumarrb]

Hi @pm-blanco,

I'd like to contribute the dihedral-potentials part of this issue. I attended the ESPResSo summer school in 2025 and have been working on Martini CG simulations; this felt like a good first contribution.

Angles were merged in #150, so dihedrals are the remaining bonded-potential scope here. You'll have seen the automatic commit cross-references above from my fork — I've implemented them there.

Branch: https://github.com/rajkumarrb/pyMBE/tree/dihedral-potentials
The current branch head is ddc05b5 (c3b10a2 adds a follow-up test fix).

What it adds:

• DihedralTemplate / DihedralInstance in pyMBE/storage, mirroring the angle types. The template holds a list of terms, so GROMACS-style stacked multiplicities on the same quadruplet register as one Dihedral object per term.
• define_dihedral_potential / define_default_dihedral_potential / create_dihedral_potential / get_dihedral_template.
• _generate_dihedrals_for_entity and a gen_dihedral kwarg on create_residue / create_molecule / create_hydrogel, following the gen_angle pattern.
• espresso_engine _add_dihedral / _get_dihedral_instance / _create_dihedral_instance, wired into add_instances_to_engine.
• storage manager + io register/update/delete/save/load branches for the new type.
• testsuite/dihedral_tests.py, samples/setup_dihedral_potential.py, and the database_unit_tests / test_io_database / simulation_builder_tests updates.

The motivating case is Martini 2.1 peptide backbone dihedrals. The "periodic" type maps onto the ESPResSo Dihedral bond V(phi) = k·[1 − cos(n·phi − phi_0)]; "tabulated" is reserved but raises NotImplementedError.

Testing: full make tests, make pylint and make docs all pass (built against ESPResSo 5.0.1). Nothing in testsuite/data changes.

Two things I'd like your steer on before I open the PR:

1. GROMACS proper dihedral type 1, V(phi) = k·[1 + cos(n·phi − phi_s)], is recovered with phi_0 = phi_s + π. I've documented this in the docstrings and the sample rather than applying it implicitly. Is that the convention you want, or would you prefer pyMBE to absorb the shift?
2. Related — do you want a GROMACS .itp energy-validation test (reproducing dihedral energies from a martinize type-1 .itp) in this same PR, or as a follow-up?

Happy to open the PR against main once I'm added to the repo, as the contributing guide describes.

Thanks,
Raj

[pm-blanco]

Hi @rajkumarrb,

First of all: Thank you for the iniciative to contribute to pyMBE, you are more than welcomed :) The changes you describe sound exactly like what was pending to do, but I need some time to go through the code in detail.

I would like to invite you to our next meeting of the pyMBE community of users and developers on Mon 9/14/2026 5:00 PM - 6:00 PM, where we can more confortably discuss the two points you want our feedback on. Please send me an email to pablomiguel.blanco@udl.cat so I can invite you to the event. If you prefer to discuss it on a private meeting or are unavailable on the date please let me know and we can arrange another time.

@jngrad @1234somesh you may also want to take a look on this.