Metadata-Version: 2.4
Name: MolClusters
Version: 0.7.0
Summary: Tool to analyze cluster formation in molecular dynamics simulations
Keywords: molecular dynamics,clusters,nucleation,MDAnalysis
Author: Emanuel Mancio
Author-email: Emanuel Mancio <emanuelmancio@usp.br>
License-Expression: LGPL-3.0-or-later
License-File: COPYING
License-File: LICENSE
License-File: LICENSES/CC0-1.0.txt
License-File: LICENSES/LGPL-3.0-or-later.txt
License-File: LICENSES/OFL-1.1.txt
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Dist: numpy>=2.2.4,<3.0.0
Requires-Dist: networkx>=3.4.2,<4.0.0
Requires-Dist: mdanalysis[analysis]>=2.10.0,<3.0.0
Requires-Dist: pyyaml>=6.0.2,<7.0.0
Requires-Dist: tqdm>=4.67.1,<5.0.0
Requires-Dist: pandas>=2.2.3,<4.0.0
Requires-Dist: pydantic-settings>=2.14.2,<3.0.0
Requires-Dist: pydantic>=2.12.5,<3.0.0
Requires-Dist: loguru>=0.7.3,<0.8.0
Requires-Dist: biopython>1.86
Requires-Dist: orjson>=3.11.0,<4.0.0
Requires-Dist: zstandard>=0.25.0,<1.0.0
Requires-Python: >=3.12, <4.0
Project-URL: homepage, https://emanuelmancio.github.io/MolClusters/
Project-URL: documentation, https://emanuelmancio.github.io/MolClusters/
Project-URL: repository, https://github.com/EmanuelMancio/MolClusters
Project-URL: issues, https://github.com/EmanuelMancio/MolClusters/issues
Project-URL: changelog, https://github.com/EmanuelMancio/MolClusters/blob/main/CHANGELOG.md
Description-Content-Type: text/markdown

<!--
SPDX-FileCopyrightText: © 2024 Emanuel Mancio <emanuelmancio@usp.br>

SPDX-License-Identifier: LGPL-3.0-or-later
-->

# MolClusters

[![PyPI](https://img.shields.io/pypi/v/molclusters.svg)](https://pypi.org/project/molclusters/)
[![Python versions](https://img.shields.io/pypi/pyversions/molclusters.svg)](https://pypi.org/project/molclusters/)
[![Tests](https://github.com/EmanuelMancio/MolClusters/actions/workflows/tests.yml/badge.svg?branch=dev)](https://github.com/EmanuelMancio/MolClusters/actions/workflows/tests.yml)
[![Docs](https://github.com/EmanuelMancio/MolClusters/actions/workflows/docs.yml/badge.svg)](https://emanuelmancio.github.io/MolClusters/)
[![License: LGPL v3+](https://img.shields.io/badge/license-LGPL--3.0--or--later-blue.svg)](https://github.com/EmanuelMancio/MolClusters/blob/main/LICENSE)
[![REUSE compliant](https://img.shields.io/badge/REUSE-compliant-green.svg)](https://reuse.software/)

Track the formation, growth, splitting, merging and lifetime of molecular clusters in
molecular dynamics trajectories (GROMACS, LAMMPS and any other format
[MDAnalysis](https://www.mdanalysis.org/) 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](https://emanuelmancio.github.io/MolClusters/user-guide/known-issues/)
> for which results are affected and how to correct them.

## Installation

MolClusters needs Python 3.12 or newer, and is published on
[PyPI](https://pypi.org/project/molclusters/):

```bash
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](https://www.mdanalysis.org/), [NetworkX](https://networkx.org/),
[NumPy](https://numpy.org/), [pandas](https://pandas.pydata.org/),
[Pydantic](https://docs.pydantic.dev/) and a few others, installed automatically.

## Usage

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

The [user guide](https://emanuelmancio.github.io/MolClusters/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](https://github.com/EmanuelMancio/MolClusters/blob/main/CONTRIBUTING.md) and the
[developer guide](https://emanuelmancio.github.io/MolClusters/developer-guide/) for the
development setup and conventions.

## Citing

If you use MolClusters in your research, please cite it:
[CITATION.cff](https://github.com/EmanuelMancio/MolClusters/blob/main/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](https://choosealicense.com/licenses/lgpl-3.0/) or any later version; see
[LICENSE](https://github.com/EmanuelMancio/MolClusters/blob/main/LICENSE) and, for the GNU
GPL v3 it builds on, [COPYING](https://github.com/EmanuelMancio/MolClusters/blob/main/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](https://reuse.software/) specification.

## Authorship

This package was written by Emanuel Fernandes Dias Mancio ([ORCID](https://orcid.org/0000-0002-0262-711X), [Lattes](http://lattes.cnpq.br/3118069372734394)), with the important contribution of Prof. Kaline Coutinho ([ORCID](https://orcid.org/0000-0002-7586-3324), [Web of Science](https://www.webofscience.com/wos/author/record/C-2104-2012), [Lattes](http://lattes.cnpq.br/9205662588542783)) 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](https://bv.fapesp.br/pt/pesquisador/709594/emanuel-fernandes-dias-mancio).
