Increasing pyMBE interoperability (part I)

AUTHORS.md

@@ -12,6 +12,7 @@ The following people have contributed to pyMBE (Github username, Name, current a
 - paobtorres, Paola B. Torres (Universidad Tecnológica Nacional, Argentina)
 - pinedaps, Sebastian P. Pineda (University of Lund, Sweden)
 - 1234somesh, Somesh Kurahatti (University of Stuttgart, Germany)
+- jorch28, Jordi Sans-Duñó  (Freelance,Figaró, Spain)
 
 ## Tier-1 Contributors
 - TommyTraan, Duy Tommy Tran (Norwegian University of Science and Technology, Norway)
@@ -28,4 +29,4 @@ The following people have contributed to pyMBE (Github username, Name, current a
 - Magdaléna Nejedlá (Charles University, Czech Republic)
 - Raju Lunkad (University of Goettingen, Germany)
 - Rita S. Dias (Norwegian University of Science and Technology, Norway)
-- Sergio Madurga (University of Barcelona, Spain)
+- Sergio Madurga (University of Barcelona, Spain)

CHANGELOG.md

@@ -8,6 +8,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ## Added
+- Simulation-engine abstraction layer to decouple pyMBE molecular-building logic from simulation-engine-specific implementation details. (#151)
+- Added `EspressoEngine` to delegate ESPResSo-specific operations, including reaction methods, setup utilities, and particle/bond/angle insertion. (#151)
+- Added `add_instances_to_engine()` to transfer pyMBE particles, bonds, and angles to the selected simulation engine. (#151)
+- Added protocol classes to validate supported simulation-engine interfaces, including ESPResSo-system compatibility checks. (#151)
+- Added preliminary LAMMPS engine scaffolding to prepare pyMBE for future interoperability with additional simulation backends. (#151)
 - Support to setup angular potentials with pyMBE. All flexible pyMBE templates now support angula potentials: hydrogels, molecules, peptides and residues (including residues with nested residues). (#150)
 - Sample scripts and tests for the new functionality. (#150)
 - Template and instance `Angle` to store information about angular potentials in the pyMBE database. (#150)
@@ -22,6 +27,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added utility functions in `lib/handy_functions` to define residue and particle templates for aminoacids en peptides and residues: `define_protein_AA_particles`, `define_protein_AA_residues` and `define_peptide_AA_residues`. (#147)
 
 ## Changed
+- Moved engine-dependent functionality from pyMBE-level methods and helper functions to the selected simulation engine. (#151)
 - Create methods (`create_particle`, `create_residue`, `create_molecule`, `create_protein`, `create_hydrogel`) now raise a ValueError if no template is found for an input `name` instead than a warning. (#147)
 - Refactored core modules to use the new database schema based on templates and instances  for particles, residues, molecules, hydrogels, proteins and peptides. (#147)
 - Particle states now are independent templates and are now disentangled from particle templates. (#147)
@@ -35,6 +41,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 
 ### Removed
+- Deprecated legacy ESPResSo-specific helper functions in favor of the corresponding pmb.simulation_engine.* methods, including reaction execution, particle counting, system relaxation, Langevin dynamics setup, and electrostatic-interaction setup.
 - Methods that interact directly with the pyMBE dataframe. These methods have been replaced by private methods that instead interact with the new canonical pyMBE database in (`pyMBE/storage/manager`). This includes the methods: `add_bond_in_df`, `add_value_to_df`, `assign_molecule_id`, `check_if_df_cell_has_a_value`, `check_if_name_is_defined_in_df`, `check_if_multiple_pmb_types_for_name`, `clean_df_row`, `clean_ids_in_df_row`, `copy_df_entry`, `create_variable_with_units`, `convert_columns_to_original_format`, `convert_str_to_bond_object`, `delete_entries_in_df`, `find_bond_key`, `setup_df`, `define_particle_entry_in_df`, custom `NumpyEncoder`. (#145,#147)
 - Method `add_bonds_to_espresso` has been removed from the API. pyMBE now adds bonds internally to ESPResSo when molecule instances are created into ESPResSo. (#147)
 - Tutorial `lattice_builder.ipynb` has been removed because its content is redundant with sample script `build_hydrogel.py`. (#147)

pyMBE/exceptions/pmb_warnings.py

@@ -0,0 +1,35 @@
+#
+# Copyright (C) 2023-2026 pyMBE-dev team
+#
+# This file is part of pyMBE.
+#
+# pyMBE is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# pyMBE is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+import warnings
+from functools import wraps
+
+def deprecated(new_function):
+    """Wrapper function to display a warning deprecation message to all functions that are going to be removed in a future
+    """
+    def decorator(func):
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            warnings.warn(
+                f"{func.__name__} is deprecated and it will be removed in the future. Please use"+ new_function +"instead.",
+                DeprecationWarning,
+                stacklevel=2
+            )
+            return func(*args, **kwargs)
+        return wrapper
+    return decorator

pyMBE/lib/handy_functions.py

@@ -20,6 +20,7 @@
 import re
 import numpy as np
 import scipy
+from pyMBE.exceptions.pmb_warnings import deprecated
 
 def calculate_initial_bond_length(bond_parameters, bond_type, lj_parameters):
     """
@@ -281,7 +282,7 @@ def define_peptide_AA_residues(sequence,model, pmb):
             pmb.define_residue(name = residue_name, 
                                     central_bead = central_bead,
                                     side_chains = side_chains)
-
+@deprecated('pmb.simulation_engine.do_reaction')
 def do_reaction(algorithm, steps):
     """
     Executes reaction steps using an ESPResSo reaction algorithm with
@@ -311,6 +312,7 @@ def do_reaction(algorithm, steps):
     else:
         algorithm.reaction(steps=steps)
 
+@deprecated('pmb.simulation_engine.get_number_of_particles')
 def get_number_of_particles(espresso_system, ptype):
     """
     Returns the number of particles of a given ESPResSo particle type.
@@ -508,7 +510,7 @@ def protein_sequence_parser(sequence):
             clean_sequence.append(residue_ok)
     return clean_sequence
 
-
+@deprecated('pmb.simulation_engine.relax_system')
 def relax_espresso_system(espresso_system, seed, gamma=1e-3, Nsteps_steepest_descent=5000, max_displacement=0.01, Nsteps_iter_relax=500):
     """
     Relaxes the energy of the given ESPResSo system by performing the following steps:
@@ -571,7 +573,7 @@ def relax_espresso_system(espresso_system, seed, gamma=1e-3, Nsteps_steepest_des
     logging.info(f"*** Minimum particle distance after relaxation: {espresso_system.analysis.min_dist()} ***")
     logging.debug("*** Relaxation finished ***")
     return espresso_system.analysis.min_dist()
-
+@deprecated('pmb.simulation_engine.setup_langevin_dynamics')
 def setup_langevin_dynamics(espresso_system, kT, seed,time_step=1e-2, gamma=1, tune_skin=True, min_skin=1, max_skin=None, tolerance=1e-3, int_steps=200, adjust_max_skin=True):
     """
     Sets up Langevin Dynamics for an ESPResSo simulation system.
@@ -634,7 +636,7 @@ def setup_langevin_dynamics(espresso_system, kT, seed,time_step=1e-2, gamma=1, t
                                               int_steps=int_steps, 
                                               adjust_max_skin=adjust_max_skin)
         logging.info(f"Optimized skin value: {espresso_system.cell_system.skin}")
-
+@deprecated('pmb.simulation_engine.setup_electrostatic_interactions')
 def setup_electrostatic_interactions(units, espresso_system, kT, c_salt=None, solvent_permittivity=78.5, method='p3m', tune_p3m=True, accuracy=1e-3, params=None, verbose=False):
     """
     Sets up electrostatic interactions in an ESPResSo system.

pyMBE/lib/lattice.py

@@ -333,5 +333,5 @@ def __init__(self,mpc,bond_l):
             raise ValueError("mpc must be a non-zero positive integer.")
         self.mpc = mpc
         self.bond_l = bond_l
-        self.box_l = (self.mpc+2)*self.bond_l.magnitude / (np.sqrt(3)*0.25)
+        self.box_l = (self.mpc+1)*self.bond_l.magnitude / (np.sqrt(3)*0.25)