Merge branch 'main' into 30-improve-read-write-functions

.github/workflows/testsuite.yml

@@ -0,0 +1,34 @@
+name: run tests
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read # to fetch code (actions/checkout)
+
+jobs:
+  ubuntu:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Setup EESSI
+        uses: eessi/github-action-eessi@v3
+        with:
+          eessi_stack_version: "2023.06"
+      - name: Checkout repository
+        uses: actions/checkout@main
+      - name: Install dependencies
+        run: |
+          module load ESPResSo/4.2.1-foss-2023a
+          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
+          source pymbe/bin/activate
+          make testsuite
+          deactivate
+        shell: bash

CONTRIBUTING.md

@@ -1,16 +1,16 @@
 # Please contribute to pyMBE!
 
 ## Bug reporting
-If you discover any strange feature or unexpected behaviour of the library, please report it by opening an issue in this Gitlab repository or contacting Dr. Pablo M. Blanco (pablb@ntnu.no) or any other member of the pyMBE development team.
-Once a ticket is open in Gitlab, we will work to fix the issue as soon as possible.
+If you discover any strange feature or unexpected behaviour of the library, please report it by opening an issue in this GitHub repository or contacting Dr. Pablo M. Blanco (pablb@ntnu.no) or any other member of the pyMBE development team.
+Once a ticket is open in GitHub, we will work to fix the issue as soon as possible.
 
 ## New contributors
 New developers are welcomed to contribute to extend the functionalities of the pyMBE library. 
-To contribute to the pyMBE library, first one needs to be added as a member of this Gitlab repository.
+To contribute to the pyMBE library, first one needs to be added as a member of this GitHub repository.
 If you want to contribute to the development of the pyMBE library, please contact Dr. Pablo M. Blanco (pablb@ntnu.no)
 
 ## Rules to contribute to pyMBE
-All new features of pyMBE must be developed in a branch of this Gitlab repository and must be reported to a member of the pyMBE development team.
 Any new version of the code must reproduce all the data stored in `reference_data/`. 
 The scripts provided in `tests/` can be used to quickly set-up  simulations with pyMBE to reproduce such data sets.
 All new code will be reviewed by at least one member of the pyMBE development team before being merged into the stable version of the library to ensure that a functional version of the code is always available.
+Class methods are sorted in alphabetical order.

Makefile

@@ -3,31 +3,30 @@
 .PHONY: visual 
 .PHONY: clean
 .PHONY: tests
+.PHONY: testsuite
 .PHONY: docs
 
-ESPResSo_build_path=~/software/espresso_v4.2/build/
-
 docs:
 	pdoc ./pyMBE.py -o ./docs --docformat google 
 
+testsuite:
+	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,11 +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/)
+- [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
@@ -21,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.
@@ -34,45 +37,126 @@ 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
+```
+
+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:
+
+```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
+```
+
+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
+deactivate
 ```
 
-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
+Cluster users who rely on module files to load dependencies should opt for the
+following alternative:
 
-```py
-import espressomd
+```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
 ```
 
-and your simulations should be runned using ESPResSo
+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
-${ESPResSo_build_path}/pypresso your_simulation_script.py
+$ 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
+```
+
+To use pyMBE in JupyterLab, register the virtual environment in a new kernel:
+
+```sh
+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
+```
+
+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
+You can run the interactive tutorial of pyMBE with the command:
 
 ```sh
-${ESPResSo_build_path}/ipypresso notebook pyMBE_tutorial.ipynb
+source pymbe/bin/activate
+jupyter-lab tutorials/pyMBE_tutorial.ipynb
+deactivate
 ```
 
-or alternatively you can run the command
+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
-make tutorial
+source pymbe/bin/activate
+make testsuite
+deactivate
 ```
 
-provided that you have modified the `$ESPResSo_build_path` variable in `Makefile` to match the path where you have built ESPResSo.
+When contributing new features, consider adding a unit test in the `testsuite/`
+folder and a corresponding line in the `testsuite` target of the Makefile.
 
+Every contribution is automatically tested in CI using EESSI (https://www.eessi.io)
+and the [EESSI GitHub Action](https://github.com/marketplace/actions/eessi).