Metadata-Version: 2.4
Name: growpal
Version: 0.1.0
Summary: Growth Pattern Algorithm
Author-email: Isaac Rafael Gutierrez Campos <isaac.gutierrezcam@gmail.com>, Gabriel Merino <gabriel.merino2@gmail.com>, Filiberto Ortiz Chi <fortiz666@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/fortizchi/growpal
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aegon==1.3.5
Requires-Dist: dscribe
Dynamic: license-file

# GrowPAL

**Growth Pattern Algorithm with diversity-preserving selection for global optimization of atomic clusters.**

GrowPAL implements a progressive-growth strategy for exploring potential energy surfaces (PESs) of atomic clusters. Its key innovation is incorporating unsupervised structural classification into the selection stage, preserving morphological diversity across growth steps rather than selecting exclusively by energy.

## Background

Global optimization algorithms based on progressive growth are widely used to explore PESs of atomic clusters. However, selection schemes based exclusively on energy may reduce structural diversity when multiple competing funnels are present.

GrowPAL addresses this by combining **Many-Body Tensor Representation (MBTR)** descriptors with **hierarchical Ward clustering**, preserving representatives from distinct morphological families throughout the growth process. This ensures that alternative growth pathways remain available even when their intermediate configurations are not the most stable structures at a given size.

## Key results

- Benchmark calculations on Lennard-Jones clusters (10–130 atoms) recover all reported global minima, including the challenging LJ75–LJ78, LJ98, and LJ102–LJ104 cases.
- Sutton-Chen potential benchmarks for nine parameter sets (clusters up to 90 atoms) reproduce known global minima and identify new putative global minima:
  - Palladium (n–m = 12-7): N = 26 and 29
  - Aluminum (n–m = 7–6): N = 12 and 20

## Installation

```bash
pip install growpal
```

Requires Python >= 3.13.

## Dependencies

- [aegon](https://pypi.org/project/aegon/) — utilities for cluster manipulation and energy sorting
- [dscribe](https://singroup.github.io/dscribe/) — MBTR descriptors for multi-species systems
- [numba](https://numba.pydata.org/) — JIT-compiled MBTR kernels for monoatomic systems
- [scikit-learn](https://scikit-learn.org/) — agglomerative clustering
- [scipy](https://scipy.org/) — sparse graph connectivity
- [ASE](https://wiki.fysik.dtu.dk/ase/) — atomic structure representation
- [joblib](https://joblib.readthedocs.io/) — parallel intra-cluster selection

## Module overview

| Module | Description |
|---|---|
| `libgrowpal.py` | Core growth engine: adjacency detection, interstitial atom placement at triangle centroids, focused radial expansion, and parallel processing via `multiprocessing.Pool` |
| `libdescriptors.py` | MBTR descriptor computation: fast numba-parallelized path for monoatomic systems (`mbtr_comb_fast`), and dscribe-based path for multi-species systems (`mbtr_comb_dscribe`) |
| `libclustering.py` | Agglomerative Ward clustering with optional k-NN connectivity constraint for scalability to large structure pools |
| `libselect_clustering.py` | Main selection interface: computes descriptors, clusters, and returns the lowest-energy representatives from each morphological family |

## Basic usage

```python
from growpal.libgrowpal import growpal_parallel
from growpal.libselect_clustering import select_by_clustering

# Grow a list of N-atom clusters to N+1
candidates = growpal_parallel(poscarlist, specie='Ar', dtol=1.2)

# Select preserving morphological diversity
selected = select_by_clustering(
    candidates,
    selection_count=160,
    n_clusters=8,
)
```

## Citation

If you use GrowPAL in your research, please cite:

> Gutiérrez-Campos I., Merino G., Ortiz-Chi F.
> *Morphological Diversity as a Selection Principle in Growth-Based Global Optimization.*

## Authors

- Isaac Gutiérrez-Campos — Departamento de Física Aplicada, Cinvestav-IPN, Mérida, México
- Gabriel Merino — Departamento de Física Aplicada, Cinvestav-IPN, Mérida, México
- Filiberto Ortiz-Chi — Secihti-Departamento de Física Aplicada, Cinvestav-IPN, Mérida, México

## License

MIT
