Restructure pyMBE as a package

.github/workflows/testsuite.yml

@@ -31,7 +31,7 @@ jobs:
           modules: |-
             ESPResSo/4.2.2-foss-2023a
           extra-python-packages: |-
-            pdoc==14.3
+            pdoc==15.0.3
             pylint==3.0.3
             coverage==7.4.4
       - name: Run testsuite

.gitignore

@@ -1,6 +1,5 @@
 simulation_parameters.txt
 visualization.tcl
-frames
 .ipynb_checkpoints/
 .vscode
 __pycache__

CHANGELOG.md

@@ -8,6 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Changed
+- Parameter sets (pKa values and force field-related parameters) from previous work are now belong to the pyMBE package and are directly accesible from the root path of the package. For example, the path to the Lunkad2021 data set can be accessed as `pmb.root / "parameters" / "peptides" / "Lunkad2021.json"`. (#132)
 - Peptide molecules have now their own pyMBE type pmb_type = "peptide" instead that sharing type with custom molecules pmb_type = "molecule". (#126)
 - Unified exception handling, soft errors and internal information messages are now handled by loggins and hard errors by raise statements. (#126)
 - `lib.handy_functions.setup_langevin_dynamics` now takes `seed` as input argument instead than `SEED` for coherence with the rest of the library. (#118)
@@ -58,6 +59,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Unsupported ESPResSo features now raise a `NotImplementedError` instead of a `ValueError`. (#113)
 
 ### Removed
+- `pmb.get_resource()` is no longer needed because pyMBE has been restructured as a package and therefore all of its resources are internally accessible. (#135)
+- `lib/create_cg_from_pdb.py` because it was not covered by CI testing and it was imposing a too restrictive coarse-graning of globular proteins to be used for the general public. Future development plans include substituting this functunality for a more general parser. (#135)
 - `tutorials/solution_tutorial.ipynb` to avoid code repetition. Instead, the exercise in `pyMBE_tutorial.ipynb` has been adapted to match one of the example in `samples/branched_polyampholyte.py`. (#130)
 - `verbose` optional argument has been deprecated in most of pyMBE methods, except those where is needed to silence verbose from ESPResSo. Now the module `loggins` is used instead for handling pyMBE's logs. (#119)
 - `lib.handy_functions.minimize_espresso_system_energy` because its name was confusing (it was not only minimizing the system energy) and was changing the parameters of the integrator under the hood. (#118)

Makefile

@@ -35,7 +35,7 @@ THREADS = $(shell echo $(MAKEFLAGS) | grep -oP "\\-j *\\d+")
 
 docs:
 	mkdir -p ./documentation
-	PDOC_ALLOW_EXEC=0 ${PYTHON} -m pdoc ./pyMBE.py -o ./documentation --docformat google
+	PYTHONWARNINGS=error PDOC_ALLOW_EXEC=0 ${PYTHON} -m pdoc ./pyMBE -o ./documentation --docformat google
 
 unit_tests:
 	COVERAGE=$(COVERAGE) ctest --output-on-failure $(THREADS) --test-dir testsuite -LE long --timeout 300
@@ -66,4 +66,4 @@ tutorial:
 	jupyter-lab tutorials/pyMBE_tutorial.ipynb
 
 pylint:
-	${PYTHON} -m pylint pyMBE.py lib/ testsuite/ samples/ maintainer/ visualization/
+	${PYTHON} -m pylint pyMBE/ testsuite/ samples/ maintainer/ visualization/

README.md

@@ -12,8 +12,12 @@
 [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](LICENSE.txt)
 [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](CODE_OF_CONDUCT.md) 
 
+[comment]: # (introduction start)
+
 pyMBE provides tools to facilitate building up molecules with complex architectures in the Molecular Dynamics software [ESPResSo](https://espressomd.org/wordpress/). 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](https://pint.readthedocs.io/en/stable/) library to enable input parameters in any arbitrary unit system, which is later transformed in the reduced unit system used in ESPResSo.
 
+[comment]: # (introduction stop)
+
 An up-to-date documentation of all methods of the library can be found [here](pymbe-dev.github.io/pyMBE/pyMBE.html) and in the source code.
 
 ## Dependencies
@@ -37,20 +41,21 @@ Version requirements are documented in [`requirements.txt`](requirements.txt).
 
 ## Contents
 
+- `pyMBE/`: source code of pyMBE
+- `pyMBE/parameters/`: folder with various sets of parameters from previous works.
 - `figs/`: folder with various images used in the tutorials of pyMBE.
-- `lib/`: folder with various libraries.
 - `maintainer/`: folder with various scripts used by the maintainers.
-- `parameters/`: folder with various sets of parameters from previous works.
 - `samples/`: folder with various sample scripts showcasing how to use pyMBE to setup different systems.
 - `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.
 - `CONTRIBUTING.md`: rules on how to contribute to pyMBE.
 - `LICENSE.txt`: license of pyMBE.
-- `pyMBE.py`: source code of pyMBE
 - `requirements.txt`: list of required libraries to use pyMBE.
 
+[comment]: # (usage start)
+
 ## Usage
 
 ### Set up the pyMBE virtual environment
@@ -125,7 +130,7 @@ $ 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
+/home/user/Documents/pyMBE/pyMBE/__init__.py
 $ deactivate
 ```
 
@@ -199,6 +204,10 @@ 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](https://github.com/marketplace/actions/eessi).
 
+[comment]: # (usage stop)
+
+[comment]: # (references start)
+
 ## References
 
 Check out the corresponding [paper](https://doi.org/10.1063/5.0216389) to learn more about pyMBE.
@@ -224,11 +233,13 @@ If you use pyMBE in your research, please cite our paper:
 When using a released version of pyMBE, we recommend citing the corresponding
 [Zenodo record](https://doi.org/10.5281/zenodo.12102634) in addition to the pyMBE paper,
 for example: "We set up our coarse-grained models using pyMBE v0.8.0
-[\@beyer2024pymbe; \@zenodo2024pymbe]".
+\cite{beyer2024pymbe,zenodo2024pymbe}".
 
-Please also make sure to properly cite the original authors if you use the resources provided in the `parameters/` folder.
+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.
 
+[comment]: # (references stop)
+
 ## License
 
 Copyright (C) 2023-2025 pyMBE-dev team