Installation

MolClusters needs Python 3.12 or newer, and is published on PyPI from v0.7.0.

Don't use cluster properties from MolClusters 0.6.0 or earlier

Versions up to 0.6.0 computed several cluster properties wrongly. Use a later version, and recompute any results obtained with those versions:

• Dipole moments were 1.89 times too small: they were converted to debye with the factor for e·a₀ instead of e·Å.
• Volumes were 2.15 times too small (a sphere whose radius is the radius of gyration, not the uniform sphere with that radius of gyration).
• Densities used that volume and an inverted unit factor (amu/ų to g/cm³, off by 2.76 times).
• Clusters wider than half the box could be split apart when made whole, which distorted all their geometric properties.

The radius and diameter also changed meaning: they were the radius of gyration and twice it, and are now the equivalent sphere's, so they can't be compared across versions.

Which molecules form a cluster could differ too: cm rules used the plain center of mass of molecules split across the periodic boundaries, which could connect molecules that weren't close, or miss ones that were.

Known issues in earlier versions lists every error, the outputs it affects and how to correct old results.

uv (recommended)pipxpip

uv installs the molclusters command in an isolated environment of its own:

uv tool install molclusters
molclusters --version

Upgrade it later with uv tool upgrade molclusters.

pipx install molclusters
molclusters --version

Into an environment you manage yourself (a virtual environment or a conda environment), for instance to use MolClusters from Python as well:

python -m pip install molclusters
molclusters --version

To install a given release, pin its version, e.g. molclusters==0.7.0; the releases and what changed in each are listed in the changelog. The latest development version, not yet released, installs from the repository's dev branch: git+https://github.com/EmanuelMancio/MolClusters@dev in place of molclusters.

Dependencies

They are installed automatically:

Package	Used for
MDAnalysis	reading topologies and trajectories, distances, hydrogen bonds
NetworkX	the graph of connections between molecules
NumPy, pandas	numbers and tables
Pydantic, PyYAML	reading and checking the configuration file
orjson, zstandard	writing the JSON report
loguru, tqdm	logging and the progress bar

From a clone, for development

To work on MolClusters itself, see the development setup.