ionicluster

A Python package for high-throughput structural and graph-based cluster analysis of molecular simulation data.

ionicluster provides algorithms and reusable analysis workflows for identifying and characterising atomic clusters in molecular dynamics trajectories. The package combines graph-based analysis, numerical computing, and trajectory processing to extract quantitative structural features from large simulation datasets.

The package was developed as part of research on ionic clustering in molecular simulations and provides the computational analysis used in an associated research publication.

ionicluster also provides specialized utilities for the post-processing of infRETIS (Replica Exchange Transition Interface Sampling) simulation paths.

Key technologies: Python · NumPy · SciPy · MDAnalysis · graph algorithms · molecular dynamics

Features

• Structural Analysis:
  • Radius of Gyration ($R_g$)
  • Coordination Numbers (CN)
  • Radial Distribution Function (RDF)* Note that this implementation specifically calculates the RDF within identified clusters, rather than bulk systems; see the supporting literature for the modified mathematical framework.
  • Xth-minimum distance
• Cluster Analysis: Graph-based algorithms utilizing scipy.sparse.csgraph to identify, quantify, and analyze the distribution of simulation entities (atoms, ions).
• Analysis Classes: ClusterAnalyser and StructuralAnalyser are designed to process atomic coordinates under periodic boundary conditions.
• InfRETIS Post-processing: Dedicated workflows to work with the pathways generated by InfRETIS simulations.
• Ecosystem Integration: Built on top of MDAnalysis to handle simulation trajectories generated with different software; NumPy and SciPy enable high-performance numerical and graph-based operations.

This package was used to obtain analysis presented in the paper in development. This paper also contains the detailed description of the math of the listed structural parameters.

Usage & Examples

For a quick start, please refer to the scripts provided in the paper_examples/OPES and paper_examples/infRETIS directories. These scripts demonstrate how to apply the ClusterAnalyser and StructuralAnalyser classes to simulation data.

The paper_examples/OPES and paper_examples/infRETIS directories contain folders with the input files and atomic configurations required to reproduce the results presented in our paper using the infRETIS and OPES methods, respectively. The OPES scripts were tested on the MD trajectories generated with LAMMPS and PLUMMED. However, they are also applicable to any ordered set of the simulation trajectories.

Installation

Via pip:

git clone https://github.com/lizasidler/ionicluster.git
cd ionicluster
pip install -e .

Citation

This package was used to obtain the analysis presented in the following paper. Please cite this work if you use ionicluster in your research:

In development.

The paper contains the detailed mathematical descriptions of the structural parameters used in this package.

Contributing

Contributions are welcome! Please fork the repository and submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

License

This project is licensed under the MIT License. See the LICENSE file for details.