Increasing pyMBE interoperability (part I)

.github/workflows/testsuite.yml

@@ -16,16 +16,16 @@ jobs:
       GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
     strategy:
       matrix:
-        espresso:
-          - version: "4.2.2"
-            eessi_modules: ESPResSo/4.2.2-foss-2023b
+        software:
+          - label: "ESPResSo 4.2.2, LAMMPS 2024"
+            eessi_modules: ESPResSo/4.2.2-foss-2023b LAMMPS/29Aug2024-foss-2023b-kokkos
             eessi_stack_version: "2023.06"
             upload_artifact: true
-          - version: "5.0.1"
+          - label: "ESPResSo 5.0.1"
             eessi_modules: ESPResSo/5.0.1-foss-2025a
             eessi_stack_version: "2025.06"
             upload_artifact: false
-    name: ubuntu - ESPResSo ${{ matrix.espresso.version }}
+    name: ubuntu - ${{ matrix.software.label }}
     steps:
       - name: Checkout repository
         uses: actions/checkout@main
@@ -36,12 +36,12 @@ jobs:
       - name: Setup EESSI
         uses: eessi/github-action-eessi@v3
         with:
-          eessi_stack_version: ${{ matrix.espresso.eessi_stack_version }}
+          eessi_stack_version: ${{ matrix.software.eessi_stack_version }}
       - name: Install dependencies
         uses: ./.github/actions/dependencies
         with:
           modules: |-
-            ${{ matrix.espresso.eessi_modules }}
+            ${{ matrix.software.eessi_modules }}
           extra-python-packages: |-
             pdoc==15.0.3
             pylint==3.0.3
@@ -58,7 +58,7 @@ jobs:
           make coverage_xml
         shell: bash
       - name: Upload artifact
-        if: ${{ matrix.espresso.upload_artifact }}
+        if: ${{ matrix.software.upload_artifact }}
         uses: actions/upload-artifact@v7
         with:
           path: "./documentation"

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)