Metadata-Version: 2.4
Name: PUCHIK
Version: 1.2.5
Summary: 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.
Home-page: https://github.com/hrachishkhanyan/grid_project
Author: H. Ishkhanyan
Author-email: Hrachya Ishkhanyan <hrachya.ishkhanyan@kcl.ac.uk>
License: MIT License
        
        Copyright (c) 2024 Hrachya Ishkhanyan
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
Project-URL: Homepage, https://github.com/hrachishkhanyan/grid_project
Project-URL: Bug Tracker, https://github.com/hrachishkhanyan/grid_project/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Provides: PUCHIK
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: MDAnalysis
Requires-Dist: scipy>=1.14.0
Requires-Dist: PyGEL3D
Requires-Dist: python-dotenv
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: provides

# 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](https://www.mdanalysis.org/), [SciPy](https://scipy.org/), [NumPy](https://numpy.org/doc/stable/index.html) and [PyGEL3D](https://pypi.org/project/PyGEL3D/) libraries.

This is an experimental branch that offers a functionality to use alpha shapes (with an optimal or user provided alpha value) instead of a convex hull. This is done with the help of AlphaShaper.exe which was compiled using the [CGAL](https://www.cgal.org/) 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. The usage will be shown below.

![image](https://drive.google.com/uc?export=view&id=1YTiM2OxzkGO0GcbC5WvFffBdZN9-e_6D)

## 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:

```python
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](https://docs.mdanalysis.org/stable/documentation_pages/coordinates/init.html).

```python
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*:
```python
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:

```python
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:

```python
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:

![image](https://drive.google.com/uc?export=view&id=1swRuoD-rs01SA-4jqPLjwxuuv9UlUGkm)


### 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:
```python
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:
 
```python
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:
```python
v, a = m.calculate_volume(area=True, start=500, end=1000, skip=2)
```

## 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
