PUCHIK 1.3.0

Python Utility for Characterizing Heterogeneous Interfaces and Kinetics creates a grid from an molecular dynamics structure file. The system in question can have an arbitrary structure. Volume and species densities can then calculated.

PUCHIK

Overview

Python Utility for Characterizing Heterogeneous Interfaces and Kinetics (PUCHIK), is a tool for analyzing molecular dynamics trajectories. It allows constructing an interface between two phases, enabling to calculate intrinsic density profiles, volumes, etc.

The interface construction works for spherical and rod-like nanoparticles equally well, making it a great tool to work with nanoparticles of almost every shape.

This package is built on top of MDAnalysis, SciPy, NumPy and PyGEL3D libraries.

Functionality to use alpha shapes (with an optimal or user provided alpha value) instead of a convex hull is now added to main branch. This is done with the help of AlphaShaper executable which was compiled using the CGAL library. For now this only works on Windows. C++ source code is provided as well in case you would like to compile it for other platforms. Help on how to compile it and use it will be given below.

Installation

You can install the PUCHIK package using pip:

pip install PUCHIK

Usage

The main class in this package is the "Interface" class. To set up a mesh, import it from PUCHIK:

from PUCHIK import Interface

You should provide it with a topology and optionally a trajectory files. PUCHIK uses MDAnalysis Readers to open a trajectory. You can find the supported formats here.

trj = '<path_to_trajectory>'
top = '<path_to_topology>'
m = Interface(trj, top)

Optionally, if you want to use the alpha shape functionality, change the use_alpha_shape property to True:

m.use_alpha_shape = True

Lastly, select the atom groups you want to consider, atom groups that comprise the interface, and run the calculate_density method:

m.select_atoms('all')  # Consider every atom in the system
m.select_structure('<selection>')  # resname of the nanoparticle

density_selection = 'resname TIP3'
m.calculate_density(density_selection)

Note that calculate_density uses every CPU core. You can specify the number of cores you want to use with the keyword argument cpu_count.

A more customized usage of the calculate_density method can be:

distances, densities = m.calculate_density(density_selection, start=10, end=1000, skip=2, norm_bin_count=12)

This version will start the calculation at the 10th frame and finish it at frame 1000 considering every 2nd frame. norm_bin_count specifies the number of divisions of the simulation box in each dimension to create a grid.

An example figure which shows the number density of different residues relative to the distance to the interface of a sodium oleate micelle:

Solubilized molecule count

PUCHIK also offers functionality for calculating the number of solubilized small molecules within a nanoparticle. This can be accomplished using the mol_count method. The signature of this method is identical to that of the calculate_density method. Here is an example usage:

sol = m.mol_count('resname TIP3 and type O', start=0, end=500)

Volume and area

As a direct consequence of using a convex hull, the volume of the hull can be easily extracted. The calculate_volume method does just that:

v = m.calculate_volume(start=500, end=1000, skip=2)

area keyword argument can be set to True to return the area of the hull as well:

v, a = m.calculate_volume(area=True, start=500, end=1000, skip=2)

Compiling the executable for alpha shapes

For MacOS it's pretty straightforward. You will need the CGAL library installed on your system. You can use brew for it:

brew install cgal

On a Linux machine (Debian, Ubuntu, etc.), you can install the CGAL library with apt-get:

sudo apt-get install libcgal-dev

On a different Linux distribution, use the according package manager or build CGAL manually.

Then navigate to PUCHIK/grid_project/alpha_shaper/src and create a dir called build

# From root of PUCHIK repo
cd PUCHIK/grid_project/alpha_shaper/src
mkdir build
cd build
cmake ..
make

# Move the executable into the alpha_shaper folder for PUCHIK to find it
mv AlphaShaper PUCHIK/grid_project/alpha_shaper

Cite

If you've used this package in your project please cite the following paper:

Ishkhanyan, H., Santana-Bonilla, A., & Lorenz, C. D. (2025). PUCHIK: A Python Package To Analyze Molecular Dynamics Simulations of Aspherical Nanoparticles. Journal of Chemical Information and Modeling. https://doi.org/10.1021/ACS.JCIM.4C02128