MolClusters

Track the formation, growth, splitting, merging and lifetime of molecular clusters in molecular dynamics trajectories (GROMACS, LAMMPS and any other format MDAnalysis reads).

Documentation: https://emanuelmancio.github.io/MolClusters/

⚠️ Results from v0.6.0 or earlier? Those versions have errors in dipoles, volumes, densities and, in some cases, cluster membership, fixed in v0.7.0. See Known issues in earlier versions for which results are affected and how to correct them.

Installation

MolClusters needs Python 3.12 or newer, and is published on PyPI:

uv tool install molclusters   # the molclusters command, in an environment of its own
# or
pip install molclusters       # into your current environment, e.g. to use it from Python

The latest development version installs from this repository with pip install git+https://github.com/EmanuelMancio/MolClusters@dev.

It depends on MDAnalysis, NetworkX, NumPy, pandas, Pydantic and a few others, installed automatically.

Usage

molclusters traj.xtc topol.tpr config.yml --output-dir results

The user guide covers the configuration file, the output files and using MolClusters from Python; molclusters -h lists the command-line options.

Contributing

Bug reports and pull requests are welcome; for major changes, please open an issue first to discuss what you would like to change. See CONTRIBUTING.md and the developer guide for the development setup and conventions.

Citing

If you use MolClusters in your research, please cite it: CITATION.cff has the details, and GitHub's "Cite this repository" button formats them.

License

MolClusters is free software, licensed under the GNU LGPL v3 or any later version; see LICENSE and, for the GNU GPL v3 it builds on, COPYING. You can use it as a library from software under any license; changes to MolClusters itself that you distribute must stay under the LGPL. Every file's license is declared per the REUSE specification.

Authorship

This package was written by Emanuel Fernandes Dias Mancio (ORCID, Lattes), with the important contribution of Prof. Kaline Coutinho (ORCID, Web of Science, Lattes) who supervised the work and gave suggestions to its improvement.

Acknowledgments

We thank the Brazilian funding agencies CAPES, CNPq and FAPESP for the fellowships and approved research projects. This work was done under FAPESP fellowships for Emanuel Fernandes Dias Mancio (grants: #2022/01284-1, #2025/15166-9), listed in the FAPESP research database.