Configure the pyMBE virtual environment

.github/workflows/testsuite.yml

@@ -20,13 +20,15 @@ jobs:
       - name: Install dependencies
         run: |
           module load ESPResSo/4.2.1-foss-2023a
-          python3 -m pip install --user -r requirements.txt
+          python3 -m venv --system-site-packages pymbe
+          source pymbe/bin/activate
+          python3 maintainer/configure_venv.py
+          python3 -m pip install -r requirements.txt
+          deactivate
       - name: Run testsuite
         run: |
           module load ESPResSo/4.2.1-foss-2023a
-          export OLD_PYTHONPATH="${PYTHONPATH}"
-          export PYTHONPATH="$(realpath .)${PYTHONPATH:+:$PYTHONPATH}"
-          sed -i "s/\${ESPResSo_build_path}\///" Makefile
+          source pymbe/bin/activate
           make testsuite
-          export PYTHONPATH="${OLD_PYTHONPATH}"
+          deactivate
         shell: bash

Makefile

@@ -6,32 +6,27 @@
 .PHONY: testsuite
 .PHONY: docs
 
-ESPResSo_build_path=~/software/espresso_v4.2/build/
-
 docs:
 	pdoc ./pyMBE.py -o ./docs --docformat google 
 
 testsuite:
-	${ESPResSo_build_path}/pypresso testsuite/LYS_ASP_peptide.py
+	python3 testsuite/LYS_ASP_peptide.py
 
 sample:
-	${ESPResSo_build_path}/pypresso sample_scripts/peptide_simulation_example.py
+	python3 sample_scripts/peptide_simulation_example.py
 
 visual:
 	python3 handy_scripts/vmd-traj.py
 	vmd -e visualization.tcl
 
-tutorial:
-	${ESPResSo_build_path}/ipypresso notebook sugar_tutorial.ipynb
-
 tests_peptide:
-	 ${ESPResSo_build_path}/pypresso tests/LYS_ASP_peptide.py
-	 ${ESPResSo_build_path}/pypresso tests/GLU_HIS_peptide.py
-	 ${ESPResSo_build_path}/pypresso tests/histatin5_peptide.py
-	 
+	python3 tests/LYS_ASP_peptide.py
+	python3 tests/GLU_HIS_peptide.py
+	python3 tests/histatin5_peptide.py
+
 tests_globular_protein:
-	python3 tests/run_test_protein.py --pdb_code 1beb --run_command "${ESPResSo_build_path}/pypresso sample_scripts/globular_protein.py  --pdb 1beb --path_to_cg reference_parameters/coarse_grained_structures/1beb.vtf"
-	python3 tests/run_test_protein.py --pdb_code 1f6s --run_command "${ESPResSo_build_path}/pypresso  sample_scripts/globular_protein.py  --pdb 1f6s --metal_ion_name Ca --metal_ion_charge 2 --path_to_cg reference_parameters/coarse_grained_structures/1f6s.vtf"
+	python3 tests/run_test_protein.py --pdb_code 1beb --run_command "python3 sample_scripts/globular_protein.py  --pdb 1beb --path_to_cg reference_parameters/coarse_grained_structures/1beb.vtf"
+	python3 tests/run_test_protein.py --pdb_code 1f6s --run_command "python3 sample_scripts/globular_protein.py  --pdb 1f6s --metal_ion_name Ca --metal_ion_charge 2 --path_to_cg reference_parameters/coarse_grained_structures/1f6s.vtf"
 
 tests:
 	make tests_peptide

README.md

@@ -4,12 +4,12 @@ pyMBE provides tools to facilitate building up molecules with complex architectu
 
 ## Dependencies
 
-- [ESPResSo](https://espressomd.org/wordpress/) v4.2.1 
-- [Pint](https://pint.readthedocs.io/en/stable/) v0.20.01 
-- [Pandas](https://pandas.pydata.org/) v1.5.3
-- [Pint-Pandas](https://pypi.org/project/Pint-Pandas/) v0.5
-- [Numpy](https://numpy.org/)
-- [SciPy](https://scipy.org/)
+- [ESPResSo](https://espressomd.org/wordpress/) =4.2.1 
+- [Pint](https://pint.readthedocs.io/en/stable/) >=0.20.01
+- [Pandas](https://pandas.pydata.org/) >=1.5.3
+- [Pint-Pandas](https://pypi.org/project/Pint-Pandas/) >=0.3
+- [Numpy](https://numpy.org/) >=1.23
+- [SciPy](https://scipy.org/) 
 - [pdoc](https://pdoc.dev/) (for building the docs)
 
 ## Branches
@@ -22,10 +22,12 @@ A deprecated version of pyMBE compatible with ESPResSo v4.1.4 (under the histori
 - `figs/`: folder with various images used in the tutorials of pyMBE.
 - `handy_scripts/`: folder with various handy scripts and libraries.
 - `logo/`: folder with the logo of pyMBE.
+- `mantainer/`: folder with various scripts used by the mantainers.
 - `reference_data/`: folder with various reference data set used to validate pyMBE.
 - `reference_parameters/`: folder with various sets of parameters from previous works.
 - `sample_scripts/`: folder with various sample scripts showcasing how to use pyMBE to setup different systems.
 - `tests/`: folder with several test scripts to check that new developments do not break pyMBE.
+- `testsuite/`: folder with several test scripts and data for continous integration of the library.
 - `tutorials/`: folder with the available tutorials on pyMBE.
 - `visualization/`: folder with helper scripts to aid the visualization of vtf trajectories from constant pH and Grand reaction simulations with [VMD](https://www.ks.uiuc.edu/Research/vmd/).
 - `AUTHORS.md`: list of authors and contributors of pyMBE.
@@ -35,54 +37,122 @@ A deprecated version of pyMBE compatible with ESPResSo v4.1.4 (under the histori
 
 ## Usage
 
-### Use pyMBE in your simulation scripts 
+### Set up the pyMBE virtual environment
 
-To use pyMBE in your simulations, first clone this repository into your source folder
+To use pyMBE in your simulations, first clone this repository locally:
 
 ```sh
-git clone git@gitlab.com:blancoapa/pyMBE.git
+git clone git@github.com:pm-blanco/pyMBE.git
 ```
 
-then you can load pyMBE into your script with the command
+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. Following the NEP29 guidelines, we recommend the users of pyMBE to use Python3.10+ when using our module.
 
-```py
-from pyMBE import pyMBE
+The pyMBE module uses its own Python virtual enviroment to avoid incompatibility issues when loading its requierements from other libraries. 
+The Python module (`venv`)[https://docs.python.org/3/library/venv.html#module-venv] from the Python Standard Library (starting with Python 3.3)  is needed to set up pyMBE. 
+If `venv` is not in the Python distribution of the user, the user will need to first install 'venv' before setting up pyMBE.
+For Ubuntu users, this can be done as follows:
+
+```sh
+sudo apt install python3-venv
 ```
 
-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 be also loaded to your script
+To set up pyMBE, the users need to install its virtual environment, install its Python dependencies and configure the path to the ESPResSo build folder as follows:
 
-```py
-import espressomd
+```sh
+python3 -m venv pymbe
+source pymbe/bin/activate
+python3 maintainer/configure_venv.py --espresso_path=/home/user/espresso/build # adapt path
+python3 -m pip install -r requirements.txt
+deactivate
 ```
 
-and your simulations should be runned using ESPResSo
+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 were ESPResSo was installed. 
 
+The pyMBE virtual enviroment can be deactivated at any moment:
 ```sh
-${ESPResSo_build_path}/pypresso your_simulation_script.py
+deactivate
 ```
 
-### Run the tutorial of pyMBE
+Cluster users who rely on module files to load dependencies should opt for the
+following alternative:
+
+```sh
+module load ESPResSo/4.2.1-foss-2022a # adapt module name
+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
+```
+
+We highlight that 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:
+
+```sh
+$ 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.py
+$ deactivate
+```
 
-You can run the interactive tutorial of pyMBE with the command
+To use pyMBE in JupyterLab, register the virtual environment in a new kernel:
 
 ```sh
-${ESPResSo_build_path}/ipypresso notebook pyMBE_tutorial.ipynb
+source pymbe/bin/activate
+python3 -m pip install ipykernel "jupyterlab>=4.0.8" "PyOpenGL>=3.1.5"
+python3 -m ipykernel install --user --name=pyMBE
+deactivate
 ```
 
-or alternatively you can run the command
+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:
+
+```sh
+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.
+
+### Use pyMBE in your simulation scripts
+
+```sh
+source pymbe/bin/activate
+python3 sample_scripts/peptide.py
+deactivate
+```
+
+### Run the tutorial of pyMBE
+
+You can run the interactive tutorial of pyMBE with the command:
 
 ```sh
-make tutorial
+source pymbe/bin/activate
+jupyter-lab tutorials/pyMBE_tutorial.ipynb
+deactivate
 ```
 
-provided that you have modified the `$ESPResSo_build_path` variable in `Makefile` to match the path where you have built ESPResSo.
+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:
 
 ```sh
-PYTHONPATH=$(realpath .) make testsuite
+source pymbe/bin/activate
+make testsuite
+deactivate
 ```
 
 When contributing new features, consider adding a unit test in the `testsuite/`

maintainer/configure_venv.py

@@ -0,0 +1,29 @@
+import os
+import argparse
+import sysconfig
+try:
+    import espressomd
+    espressomd_found = True
+except ModuleNotFoundError:
+    espressomd_found = False
+
+
+def make_pth(name, path):
+    if not os.path.isdir(path):
+        raise ValueError(f"Folder '{path}' doesn't exist")
+    site_packages = sysconfig.get_path("platlib")
+    with open(os.path.join(site_packages, f"{name}.pth"), "w") as f:
+        f.write(os.path.realpath(path))
+
+
+parser = argparse.ArgumentParser(description="Configure pyBME and ESPResSo module paths")
+parser.add_argument("--espresso_path", type=str, required=not espressomd_found,
+                    help="Path to the ESPResSo build folder")
+args = parser.parse_args()
+
+if not os.environ.get("VIRTUAL_ENV"):
+    raise RuntimeError("This script should be run in a virtual environment")
+
+if not espressomd_found:
+    make_pth("espresso", os.path.join(args.espresso_path, "src", "python"))
+make_pth("pymbe", os.path.dirname(os.path.dirname(os.path.abspath(__file__))))

requirements.txt

@@ -1,7 +1,7 @@
 numpy>=1.23
 pandas>=1.5.3
 pint>=0.20.01
-pint-pandas==0.5
+pint-pandas>=0.3
 biopandas==0.5.1.dev0
 scipy
 matplotlib

sample_scripts/branched_polyampholyte.py

@@ -11,13 +11,6 @@
 from espressomd import interactions
 
 
-# Find path to pyMBE
-current_dir= os.path.dirname(os.path.abspath(inspect.getfile(inspect.currentframe())))
-path_end_index=current_dir.find("pyMBE")
-pyMBE_path=current_dir[0:path_end_index]+"pyMBE"
-sys.path.insert(0, pyMBE_path)
-
-
 # Create an instance of pyMBE library
 import pyMBE
 pmb = pyMBE.pymbe_library()

sample_scripts/globular_protein.py

@@ -9,12 +9,6 @@
 from espressomd.io.writer import vtf
 from espressomd import electrostatics 
 
-# Find path to pyMBE
-current_dir= os.path.dirname(os.path.abspath(inspect.getfile(inspect.currentframe())))
-path_end_index=current_dir.find("pyMBE")
-pyMBE_path=current_dir[0:path_end_index]+"pyMBE"
-sys.path.insert(0, pyMBE_path)
-
 # Create an instance of pyMBE library
 import pyMBE
 pmb = pyMBE.pymbe_library()
@@ -74,11 +68,9 @@
 espresso_system = espressomd.System(box_l=[Box_L.to('reduced_length').magnitude] * 3)
 espresso_system.virtual_sites = espressomd.virtual_sites.VirtualSitesRelative()
 
-#Directory of the protein model 
-protein_filename = pyMBE_path+"/"+args.path_to_cg
-
 #Reads the VTF file of the protein model
-topology_dict = pmb.read_protein_vtf_in_df (filename=protein_filename)
+path_to_cg=pmb.get_resource(args.path_to_cg)
+topology_dict = pmb.read_protein_vtf_in_df (filename=path_to_cg)
 #Defines the protein in the pmb.df
 pmb.define_protein (name=protein_name, topology_dict=topology_dict, model = '2beadAA')
 
@@ -116,8 +108,9 @@
 pmb.define_particle(name = cation_name, q = 1, diameter=0.2*pmb.units.nm, epsilon=epsilon)
 pmb.define_particle(name = anion_name,  q =-1, diameter=0.2*pmb.units.nm, epsilon=epsilon)
 
-# Here we upload the pka set from the reference_parameters folder 
-pmb.load_pka_set (filename=pyMBE_path+'/reference_parameters/pka_sets/Nozaki1967.txt')
+# Here we upload the pka set from the reference_parameters folder
+path_to_pka=pmb.get_resource('reference_parameters/pka_sets/Nozaki1967.txt') 
+pmb.load_pka_set (filename=path_to_pka)
 
 #We create the protein in espresso 
 pmb.create_protein(name=protein_name,

sample_scripts/peptide.py

@@ -11,14 +11,6 @@
 from espressomd import interactions
 from espressomd import electrostatics
 
-
-# Find path to pyMBE
-current_dir= os.path.dirname(os.path.abspath(inspect.getfile(inspect.currentframe())))
-path_end_index=current_dir.find("pyMBE")
-pyMBE_path=current_dir[0:path_end_index]+"pyMBE"
-sys.path.insert(0, pyMBE_path)
-
-
 # Create an instance of pyMBE library
 import pyMBE
 pmb = pyMBE.pymbe_library()
@@ -53,8 +45,11 @@
 N_peptide_chains = 4
 
 # Load peptide parametrization from Lunkad, R. et al.  Molecular Systems Design & Engineering (2021), 6(2), 122-131.
-pmb.load_interaction_parameters (filename=pyMBE_path+'/reference_parameters/interaction_parameters/Lunkad2021.txt') 
-pmb.load_pka_set (filename=pyMBE_path+'/reference_parameters/pka_sets/Hass2015.txt')
+
+path_to_interactions=pmb.get_resource("reference_parameters/interaction_parameters/Lunkad2021.txt")
+path_to_pka=pmb.get_resource("reference_parameters/pka_sets/Hass2015.txt")
+pmb.load_interaction_parameters (filename=path_to_interactions) 
+pmb.load_pka_set (path_to_pka)
 
 # Use a generic parametrization for the aminoacids not parametrized
 

sample_scripts/peptide_mixture_grxmc_ideal.py

@@ -11,12 +11,6 @@
 from espressomd import interactions
 from espressomd import electrostatics
 
-# Find path to pyMBE
-current_dir= os.path.dirname(os.path.abspath(inspect.getfile(inspect.currentframe())))
-path_end_index=current_dir.find("pyMBE")
-pyMBE_path=current_dir[0:path_end_index]+"pyMBE"
-sys.path.insert(0, pyMBE_path)
-
 # Create an instance of pyMBE library
 import pyMBE
 pmb = pyMBE.pymbe_library()
@@ -52,8 +46,10 @@
 N_peptide2_chains = 10
 
 # Load peptide parametrization from Lunkad, R. et al.  Molecular Systems Design & Engineering (2021), 6(2), 122-131.
-pmb.load_interaction_parameters (filename=pyMBE_path+'/reference_parameters/interaction_parameters/Lunkad2021.txt') 
-pmb.load_pka_set (filename=pyMBE_path+'/reference_parameters/pka_sets/Hass2015.txt')
+path_to_interactions=pmb.get_resource("reference_parameters/interaction_parameters/Lunkad2021.txt")
+path_to_pka=pmb.get_resource("reference_parameters/pka_sets/Hass2015.txt")
+pmb.load_interaction_parameters (filename=path_to_interactions) 
+pmb.load_pka_set (path_to_pka)
 
 # Use a generic parametrization for the aminoacids not parametrized
 not_parametrized_neutral_aminoacids = ['A','N','Q','G','I','L','M','F','P','O','S','U','T','W','V','J']