pyMBE
pyMBE provides tools to facilitate building up molecules with complex architectures in the Molecular Dynamics software ESPResSo. Some examples of molecules that can be set up with pyMBE are polyelectrolytes, hydrogels, peptides and globular proteins. pyMBE bookkeeps all the information about the molecule topology, permitting to link each particle to its corresponding residue and molecule. pyMBE uses the Pint library to enable input parameters in any arbitrary unit system, which is later transformed in the reduced unit system used in ESPResSo.
See pyMBE.pyMBE
for the pyMBE main API.
Usage
Set up the pyMBE virtual environment
To use pyMBE in your simulations, first clone this repository locally:
git clone git@github.com:pyMBE-dev/pyMBE.git
Please, be aware that pyMBE is intended to be a supporting tool to setup simulations with ESPResSo. Thus, for most of its functionalities ESPResSo must also be available. pyMBE supports ESPResSo 4.2 and ESPResSo 4.3-dev. Following the NEP29 guidelines, we recommend using Python3.10+. Both NumPy 1 and NumPy 2 are supported.
The pyMBE module needs a Python virtual environment to avoid compatibility issues with its dependencies.
Any virtual environment manager should work, but this readme will use venv
, which can be installed on Ubuntu as follows:
sudo apt install python3-venv
To set up pyMBE, users need to configure a virtual environment. This is achieved by installing the Python dependencies and setting the path to the ESPResSo build folder, as follows:
python3 -m venv pymbe # create a local folder named pymbe containing the environment files
source pymbe/bin/activate # activate the virtual environment
python3 -m pip install -r requirements.txt "numpy<2.0" "pandas<2.0"
python3 maintainer/configure_venv.py --espresso_path=/home/user/espresso/build # please adapt the espresso path accordingly
python3 simulation_script.py # run a simulation script
deactivate # deactivate the virtual environment
NumPy 2 users should adapt the pip command as follows:
python3 -m pip install -r requirements.txt "numpy>=2.1" "pandas>=2.0"
We highlight that the path /home/user/espresso/build
is just an example of a possible path to the ESPResSo build folder.
The user should change this path to match the local absolute path where ESPResSo was built.
Also, ESPResSo must be built with the same NumPy version as the one installed in the environment to avoid API version mismatch.
For more details on how to install ESPResSo, please consult the ESPResSo installation guide.
The pyMBE virtual environment can be deactivated at any moment as follows:
deactivate
Cluster users who rely on module files to load dependencies should opt for the following alternative:
module load ESPResSo/4.2.2-foss-2023a # adapt release if needed
python3 -m venv --system-site-packages pymbe
source pymbe/bin/activate
python3 maintainer/configure_venv.py
python3 -m pip install -r requirements.txt
deactivate
module purge
Please note the module files need to be loaded before every activation of the virtual environment.
Now you can use pyMBE and ESPResSo by activating the virtual environment:
$ source pymbe/bin/activate
(pymbe) $ python3 -c "import espressomd.version; print(espressomd.version.friendly())"
4.2
(pymbe) $ python3 -c "import pyMBE; print(pyMBE.__file__)"
/home/user/Documents/pyMBE/pyMBE/__init__.py
$ deactivate
To use pyMBE in JupyterLab, install extra dependencies and register the virtual environment in a new kernel:
source pymbe/bin/activate
python3 -m pip install ipykernel "jupyterlab>=4.0.8" "PyOpenGL>=3.1.5" "ipympl>=0.9.3"
python3 -m ipykernel install --user --name=pyMBE
deactivate
Please be aware the pyMBE kernel will be registered outside the environment, typically in your home folder. You can later inspect the list of registered kernels and delete unwanted ones with the following commands:
jupyter kernelspec list
jupyter kernelspec uninstall pymbe
The JupyterLab main menu will now show a new Python kernel called "pyMBE" that uses the virtual environment.
Run simulation scripts
You can run the branched polyampholyte sample with the following commands:
source pymbe/bin/activate
python3 samples/branched_polyampholyte.py --pH 6
python3 samples/analyze_time_series.py --data_folder samples/time_series/branched_polyampholyte
python3 samples/plot_branched_polyampholyte.py
deactivate
Run tutorials
You can run the interactive tutorials with the following commands:
source pymbe/bin/activate
jupyter-lab
deactivate
In the Jupyter interface, open the tutorials
folder and then the pyMBE_tutorial
file.
It will guide you through the creation of polyelectrolytes with pyMBE.
Be sure to use the pyMBE kernel instead of the default Python3 kernel.
The currently active kernel is usually displayed in the top right corner of the notebook.
Run the testsuite
To make sure your code is valid, please run the testsuite before submitting your contribution:
source pymbe/bin/activate
make tests -j4
deactivate
Here, -j4
instructs CTest to run the test cases in parallel using 4 CPU cores.
This number can be adjusted depending on your hardware specifications.
You can use make unit_tests -j4
to run the subset of fast tests, but keep in mind those
won't be able to detect more serious bugs that only manifest themselves in long simulations.
You can also run individual test cases directly, for example with python3 testsuite/parameter_test.py
.
When contributing new features, consider adding a unit test in the testsuite/
folder and a corresponding line in the testsuite/CTestTestfile.cmake
file.
Every contribution is automatically tested in CI using EESSI (https://www.eessi.io) and the EESSI GitHub Action.
References
Check out the corresponding paper to learn more about pyMBE. If you use pyMBE in your research, please cite our paper:
@article{beyer2024pymbe,
author = {Beyer, David and Torres, Paola B. and Pineda, Sebastian P. and
Narambuena, Claudio F. and Grad, Jean-No{\"e}l and Ko{\v{s}}ovan,
Peter and Blanco, Pablo M.},
title = {{pyMBE}: The {P}ython-based molecule builder for {ESPResSo}},
journal = {The Journal of Chemical Physics},
volume = {161},
number = {2},
pages = {022502},
year = {2024},
month = jul,
issn = {0021-9606},
doi = {10.1063/5.0216389},
}
When using a released version of pyMBE, we recommend citing the corresponding Zenodo record in addition to the pyMBE paper, for example: "We set up our coarse-grained models using pyMBE v0.8.0 \cite{beyer2024pymbe,zenodo2024pymbe}".
Please also make sure to properly cite the original authors if you use the resources provided in the pyMBE/parameters/
folder.
The relevant references are provided as metadata in the corresponding files.
1# 2# Copyright (C) 2025 pyMBE-dev team 3# 4# This file is part of pyMBE. 5# 6# pyMBE is free software: you can redistribute it and/or modify 7# it under the terms of the GNU General Public License as published by 8# the Free Software Foundation, either version 3 of the License, or 9# (at your option) any later version. 10# 11# pyMBE is distributed in the hope that it will be useful, 12# but WITHOUT ANY WARRANTY; without even the implied warranty of 13# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 14# GNU General Public License for more details. 15# 16# You should have received a copy of the GNU General Public License 17# along with this program. If not, see <http://www.gnu.org/licenses/>. 18# 19 20""" 21.. include:: ../README.md 22 :start-after: [comment]: # (introduction start) 23 :end-before: [comment]: # (introduction stop) 24 :parser: markdown 25 26See `pyMBE.pyMBE` for the pyMBE main API. 27 28.. include:: ../README.md 29 :start-after: [comment]: # (usage start) 30 :end-before: [comment]: # (usage stop) 31 :parser: markdown 32 33.. include:: ../README.md 34 :start-after: [comment]: # (references start) 35 :end-before: [comment]: # (references stop) 36 :parser: markdown 37 38""" 39 40from .pyMBE import pymbe_library