Lift restrictions on ESPResSo/NumPy/Pandas version requirements (#106)

* Modernize samples and documentation

* Add support for ESPResSo 4.2.2 and 4.3-dev

.github/workflows/samples.yml

@@ -26,7 +26,7 @@ jobs:
         uses: ./.github/actions/dependencies
         with:
           modules: |-
-            ESPResSo/4.2.1-foss-2023a
+            ESPResSo/4.2.2-foss-2023a
       - name: Run testsuite
         run: |
           module restore pymbe

.github/workflows/testsuite.yml

@@ -27,7 +27,7 @@ jobs:
         uses: ./.github/actions/dependencies
         with:
           modules: |-
-            ESPResSo/4.2.1-foss-2023a
+            ESPResSo/4.2.2-foss-2023a
           extra-python-packages: |-
             pdoc==14.3
             pylint==3.0.3

CHANGELOG.md

@@ -35,6 +35,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `lib.analysis.get_dt` now raises a ValueError if the two first two rows of the dataframe have the same values for the time, which break the subsequent code. (#95)
 - Removed global state variables, instead they are now created by the constructor of `pyMBE.pymbe_library`. This prevents two instances of the pyMBE library to share the same memory address for their attributes. (#89)
 - Required Python dependency versions compatible with ESPResSo 4.2 (#84)
+- NumPy 2, Pandas 2 and the development version of ESPResSo are now fully supported. (#106)
 - Fixed several deprecated paths and function names in `tutorials/pyMBE_tutorial.ipynb`. (#77, #78, #79, #80, #81)
 
 ## [0.8.0] - 2024-06-18

README.md

@@ -14,14 +14,22 @@ pyMBE provides tools to facilitate building up molecules with complex architectu
 
 ## Dependencies
 
-- [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/) 
+- [ESPResSo](https://espressomd.org/wordpress/)
+- [Pint](https://pint.readthedocs.io/en/stable/)
+- [Pandas](https://pandas.pydata.org/)
+- [Pint-Pandas](https://pypi.org/project/Pint-Pandas/)
+- [Numpy](https://numpy.org/)
+- [SciPy](https://scipy.org/)
 - [pdoc](https://pdoc.dev/) (for building the docs)
 - [CMake](https://cmake.org/) (for running the testsuite)
+- any virtual environment manager: [venv](https://docs.python.org/3/library/venv.html),
+  [virtualenv](https://virtualenv.pypa.io/en/latest/),
+  [conda](https://docs.conda.io/projects/conda/en/latest/user-guide/getting-started.html#managing-python),
+  [miniconda](https://docs.anaconda.com/free/miniconda),
+  [micromamba](https://mamba.readthedocs.io/en/latest/user_guide/micromamba.html),
+  etc.
+
+Version requirements are documented in [`requirements.txt`](requirements.txt).
 
 ## Contents
 
@@ -50,33 +58,42 @@ git clone [email protected]: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. Following the NEP29 guidelines, we recommend the users of pyMBE to use Python3.10+ when using our module.
+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 uses its own Python virtual enviroment to avoid incompatibility issues when loading its requirements from other libraries.
-The Python module [`venv`](https://docs.python.org/3/library/venv.html) 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:
+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:
 
 ```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:
+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:
 
 ```sh
-python3 -m venv pymbe  # creates a local folder named pymbe, which contains the virtual environment
-source pymbe/bin/activate  # activates the pymbe venv
-python3 maintainer/configure_venv.py --espresso_path=/home/user/espresso/build # please, adapt the espresso path accordingly
-python3 -m pip install -r requirements.txt
-python3 simulation_script.py # run the espresso simulation script
+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:
+
+```sh
+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 were ESPResSo was installed.
+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](https://espressomd.github.io/doc4.2.2/installation.html).
 
-The pyMBE virtual enviroment can be deactivated at any moment:
+The pyMBE virtual environment can be deactivated at any moment as follows:
+
 ```sh
 deactivate
 ```
@@ -85,7 +102,7 @@ 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
+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
@@ -94,7 +111,7 @@ deactivate
 module purge
 ```
 
-We highlight that the module files need to be loaded before every activation
+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:
@@ -108,11 +125,11 @@ $ source pymbe/bin/activate
 $ deactivate
 ```
 
-To use pyMBE in JupyterLab, register the virtual environment in a new kernel:
+To use pyMBE in JupyterLab, install extra dependencies and 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 pip install ipykernel "jupyterlab>=4.0.8" "PyOpenGL>=3.1.5" "ipympl>=0.9.3"
 python3 -m ipykernel install --user --name=pyMBE
 deactivate
 ```
@@ -129,24 +146,30 @@ 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
+### Run simulation scripts
+
+You can run the branched polyampholyte sample with the following commands:
 
 ```sh
 source pymbe/bin/activate
-python3 samples/peptide.py
+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 the tutorial of pyMBE
+### Run tutorials
 
-You can run the interactive tutorial of pyMBE with the command:
+You can run the interactive tutorials with the following commands:
 
 ```sh
 source pymbe/bin/activate
-jupyter-lab tutorials/pyMBE_tutorial.ipynb
+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.
 

lib/analysis.py

@@ -50,7 +50,7 @@ def analyze_time_series(path_to_datafolder, filename_extension= ".csv", minus_se
         path_to_datafolder(`str`): path to the folder with the files with the time series
         filename_extension(`str`): extension of the file. Defaults to ".csv"
         minus_separator(`bool`): switch to enable the minus as a separator. Defaults to False.
-        ignore_files(`lst`): list of filenames to be ignored for the bining analysis.
+        ignore_files(`lst`): list of filenames to be ignored for the binning analysis.
 
     Returns:
         data(`Pandas.Dataframe`): Dataframe with the time averages of all the time series in the datafolder.
@@ -113,7 +113,7 @@ def block_analyze(full_data, n_blocks=16, time_col = "time", equil=0.1,  columns
             print(f"Warning: looks like a repeated time value was encountered {n_warnings} times")
 
     drop_rows = int(full_data.shape[0]*equil) # calculate how many rows should be dropped as equilibration
-    # drop the rows that will be discarded as equlibration
+    # drop the rows that will be discarded as equilibration
     data = full_data.drop(range(0,drop_rows))
     # drop the columns step, time and MC sweep
     if time_col in data.columns :

lib/handy_functions.py

@@ -32,6 +32,7 @@ def setup_electrostatic_interactions (units, espresso_system, kT, c_salt=None, s
         verbose (`bool`): switch to activate/deactivate verbose. Defaults to True.
     """
     import espressomd.electrostatics
+    import espressomd.version
     import numpy as np
     import scipy.constants
 
@@ -71,12 +72,18 @@ def setup_electrostatic_interactions (units, espresso_system, kT, c_salt=None, s
 
         if tune_p3m:
             espresso_system.time_step=0.01
-            espresso_system.actors.add(coulomb)
+            if espressomd.version.friendly() == "4.2":
+                espresso_system.actors.add(coulomb)
+            else:
+                espresso_system.electrostatics.solver = coulomb
 
             # save the optimal parameters and add them by hand
 
             p3m_params = coulomb.get_params()
-            espresso_system.actors.remove(coulomb)
+            if espressomd.version.friendly() == "4.2":
+                espresso_system.actors.remove(coulomb)
+            else:
+                espresso_system.electrostatics.solver = None
             coulomb = espressomd.electrostatics.P3M(
                                         prefactor = COULOMB_PREFACTOR.magnitude,
                                         accuracy = accuracy,
@@ -94,7 +101,10 @@ def setup_electrostatic_interactions (units, espresso_system, kT, c_salt=None, s
                                             r_cut = KAPPA.to('reduced_length').magnitude)
 
 
-    espresso_system.actors.add(coulomb)
+    if espressomd.version.friendly() == "4.2":
+        espresso_system.actors.add(coulomb)
+    else:
+        espresso_system.electrostatics.solver = coulomb
     if verbose:
         print("\n Electrostatics successfully added to the system \n")
 
@@ -211,3 +221,20 @@ def do_snapshot_espresso_system(espresso_system, filename):
     visualizer.screenshot(filename)
 
     return
+
+def get_number_of_particles(espresso_system, ptype):
+    import espressomd.version
+    if espressomd.version.friendly() == "4.2":
+        args = (ptype,)
+        kwargs = {}
+    else:
+        args = ()
+        kwargs = {"type": ptype}
+    return espresso_system.number_of_particles(*args, **kwargs)
+
+def do_reaction(algorithm, steps):
+    import espressomd.version
+    if espressomd.version.friendly() == '4.2':
+        algorithm.reaction(reaction_steps=steps)
+    else:
+        algorithm.reaction(steps=steps)

pyMBE.py

@@ -1006,7 +1006,7 @@ def create_particle(self, name, espresso_system, number_of_particles, position=N
             created_pid_list(`list` of `float`): List with the ids of the particles created into `espresso_system`.
         """       
         if number_of_particles <=0:
-            return 0
+            return []
         self.check_if_name_is_defined_in_df(name=name,
                                        pmb_type_to_be_defined='particle')
         # Copy the data of the particle `number_of_particles` times in the `df`
@@ -1015,6 +1015,7 @@ def create_particle(self, name, espresso_system, number_of_particles, position=N
                           number_of_copies=number_of_particles)
         # Get information from the particle type `name` from the df     
         z = self.df.loc[self.df['name']==name].state_one.z.values[0]
+        z = 0. if z is None else z
         es_type = self.df.loc[self.df['name']==name].state_one.es_type.values[0]
         # Get a list of the index in `df` corresponding to the new particles to be created
         index = np.where(self.df['name']==name)
@@ -1033,11 +1034,10 @@ def create_particle(self, name, espresso_system, number_of_particles, position=N
             else:
                 bead_id = max (espresso_system.part.all().id) + 1
             created_pid_list.append(bead_id)
-
+            kwargs = dict(id=bead_id, pos=particle_position, type=es_type, q=z)
             if fix:
-                espresso_system.part.add (id=bead_id, pos = particle_position, type = es_type, q = z,fix =[fix,fix,fix])        
-            else:
-                espresso_system.part.add (id=bead_id, pos = particle_position, type = es_type, q = z)        
+                kwargs["fix"] = 3 * [fix]
+            espresso_system.part.add(**kwargs)
             self.add_value_to_df(key=('particle_id',''),index=df_index,new_value=bead_id, verbose=False)                  
         return created_pid_list
 

requirements.txt

@@ -1,4 +1,4 @@
-numpy>=1.23,<2.0
+numpy>=1.23
 pandas>=1.5.3
 pint>=0.20.01
 pint-pandas>=0.3

samples/Beyer2024/README.md

@@ -9,6 +9,6 @@ where the previous line will run the script to produce Fig. 7a in Ref.[^1] The u
 - globular_protein.py: for the globular protein benchmarks
 - weak_polyelectrolyte_dialysis.py: for the weak polyelectrolyte dialysis benchmarks
 
-The optional argparse argument `--plot` controls if these scripts generate the corresponding plot or if the data is simply stored to file. We note that the format of the plots can differ from that of our publication [^1]. Theses scripts are part of the continous integration (CI) scheme of the pyMBE library and they are used to ensure that any stable version of the library reproduces the benchmarks.
+The optional argparse argument `--plot` controls if these scripts generate the corresponding plot or if the data is simply stored to file. We note that the format of the plots can differ from that of our publication [^1]. Theses scripts are part of the continous integration (CI) pipeline to ensure that future pyMBE releases still reproduce the benchmarks.
 
-[^1]: D. Beyer, P. B. Torres, S. P. Pineda, C. F. Narambuena, J. N. Grad, P. Košovan, P. M Blanco. J. Chem. Phys.(2024), 161 (2), 022502. doi: [10.1063/5.0216389](https://doi.org/10.1063/5.0216389).
+[^1]: D. Beyer, P. B. Torres, S. P. Pineda, C. F. Narambuena, J.-N. Grad, P. Košovan, P. M. Blanco. J. Chem. Phys.(2024), 161 (2), 022502. doi: [10.1063/5.0216389](https://doi.org/10.1063/5.0216389).