Metadata-Version: 2.4
Name: aegon
Version: 1.3.6
Summary: Atomic Environment for Global OptimizatioN
Author-email: Filiberto Ortiz Chi <fortiz666@gmail.com>, Aileen Garcia Cano <garciacanoaileen@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/fortizchi/aegon
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: ase>=3.22
Requires-Dist: numpy>=1.24
Requires-Dist: scipy
Requires-Dist: py3Dmol
Requires-Dist: numba>=0.61.0

# AEGON

**Atomic Environment for Global OptimizatioN — an open-source Python framework for the global optimization of atomic clusters and molecules.**

AEGON is built natively on top of the [Atomic Simulation Environment (ASE)](https://wiki.fysik.dtu.dk/ase/) and operates directly on `ase.Atoms` objects. It provides a self-contained toolkit covering every stage of a global optimization workflow: random and symmetry-constrained structure generation, built-in potential energy evaluators, genetic-algorithm operators, structure deduplication, and reference databases of pre-optimized clusters. Performance-critical routines are accelerated through [Numba](https://numba.readthedocs.io/) just-in-time compilation.

---

## Table of Contents

- [Features](#features)
- [Installation](#installation)
- [Dependencies](#dependencies)
- [Module Overview](#module-overview)
- [Usage](#usage)
- [Reference Databases](#reference-databases)
- [Sutton-Chen Parameters](#sutton-chen-parameters)
- [Citation](#citation)
- [Authors](#authors)
- [License](#license)

---

## Features

- **Random structure generation** — nine structural templates (compact 3D, diffuse 3D, planar 2D, spherical shell, wire, ring, two-ring, helix, eye) with covalent-radii-based distance constraints and BFS connectivity verification.
- **Symmetry-constrained generation** — orbit-by-orbit placement for 30+ molecular point groups (C1 through Ih), with automatic fallback when the composition is incompatible with the requested symmetry.
- **Periodic crystal generation** — space-group-aware random crystal structures for all 230 space groups using ASE symmetry operations.
- **Built-in potential energy calculators** — Lennard-Jones (LJ) and Sutton-Chen (SC) potentials with Numba-accelerated energy and force evaluation; L-BFGS-B local minimization; ASE Effective Medium Theory (EMT) via BFGS.
- **External quantum chemistry interfaces** — unified parser (`read_out`) for output files from Gaussian, ORCA, VASP, and GULP; input generation and batch execution with parallel queuing.
- **Genetic algorithm operators** — mutation (atom displacement, twist), Deaven-Ho cut-and-splice crossover, and dihedral rotamer exploration along bridge bonds.
- **Fitness-proportional selection** — roulette wheel selection with a tanh-based fitness mapping.
- **Structure discrimination** — USR (Ultrafast Shape Recognition) descriptors for fast deduplication and filtering of large structure pools.
- **Reference cluster databases** — pre-optimized LJ clusters (5–130 atoms) and Sutton-Chen clusters for ten transition and main-group metals (Ag, Al, Au, Cu, Ir, Ni, Pb, Pd, Pt, Rh, up to 90 atoms), loaded lazily and cached per session.
- **Visualization** — inline Jupyter/Colab rendering with py3Dmol; support for periodic structures with unit-cell edges.

---

## Installation

```bash
pip install aegon
```

Requires Python >= 3.10.

### Google Colab

```python
!pip install aegon
```

---

## Dependencies

| Package | Role |
|---|---|
| [ASE](https://wiki.fysik.dtu.dk/ase/) | Atomic structure representation (`Atoms` objects) |
| [NumPy](https://numpy.org/) | Array operations throughout |
| [SciPy](https://scipy.org/) | L-BFGS-B optimization, k-d tree, sparse graph |
| [Numba](https://numba.pydata.org/) | JIT-compiled energy, force, and descriptor kernels |
| [py3Dmol](https://github.com/3dmol/3Dmol.js) | Inline 3D visualization in Jupyter/Colab |

---

## Module Overview

| Module | Description |
|---|---|
| `libmolgen.py` | Random cluster generators (nine structural templates, parallel batch generation) and symmetry-constrained generators for 30+ point groups |
| `libcrystalgen.py` | Space-group-aware periodic crystal generator for all 230 space groups |
| `libclusterfactory.py` | `ClusterFactory` class for retrieving pre-optimized LJ and SC reference clusters by size and element |
| `libdata_lj.py` | Direct access to LJ reference clusters via `get_lj_cluster(N)` |
| `libdata_sc.py` | Direct access to SC reference clusters via `get_sc_cluster(N, symbol)` |
| `libcalc_lj.py` | Lennard-Jones energy, forces, and L-BFGS-B local minimization (Numba-accelerated) |
| `libcalc_sc.py` | Sutton-Chen potential for 10 metals with parameters; Numba-accelerated energy/forces and `opt_sc` / `opt_SC_parallel` |
| `libcalc_emt.py` | EMT energy and BFGS local minimization via ASE |
| `libcode.py` | `read_out` unified parser for Gaussian, ORCA, VASP, and GULP output files |
| `libmutants.py` | Mutation operators: atom displacement, twist, overlap resolution |
| `libcrossover.py` | Deaven-Ho cut-and-splice crossover (`crossover_deavenho`) |
| `librotamers.py` | Dihedral rotamer search along bridge bonds using the molecular graph |
| `libsel_roulette.py` | Roulette wheel selection with tanh-based fitness proportional to energy ranking |
| `libdisc_usr.py` | USR descriptor computation, batch deduplication (`deduplicate_by_usr`), and filtering against a reference pool |
| `libutils.py` | General utilities: sorting, distance functions, rotation matrices, XYZ I/O (`readxyzs`, `writexyzs`) |
| `libqueuing.py` | Parallel bash script execution via `multiprocessing.Queue` |
| `libgcolab.py` | Inline py3Dmol visualization for Jupyter and Google Colab (`viewmol_ASE`) |
| `libposcar.py` | POSCAR/CONTCAR file writing |
| `libstdio.py` | Composition I/O: reading composition blocks from AEGON input files, cluster naming |

---

## Usage

### Generate and optimize a random cluster

```python
from aegon.libmolgen import make_molecules_random
from aegon.libcalc_lj import opt_LJ_parallel

composition = ['Au'] * 7

# Generate 100 random starting structures in parallel
population = make_molecules_random(composition, cuantas=100, n_cores=4)

# Parallel local minimization with the Lennard-Jones potential
optimized = opt_LJ_parallel(population, n_jobs=4)
```

### Generate symmetry-constrained clusters

```python
from aegon.libmolgen import make_clusters_symmetric, make_cluster_symmetric

# Generate 50 clusters with automatically compatible point groups
population = make_clusters_symmetric(['Au'] * 13, cuantas=50, n_cores=4)

# Or fix a specific point group
mol = make_cluster_symmetric(['Au'] * 13, point_group='Ih')
```

### Optimize with the Sutton-Chen potential

```python
from aegon.libmolgen import make_molecules_random
from aegon.libcalc_sc import opt_sc, opt_SC_parallel

composition = ['Au'] * 10
population = make_molecules_random(composition, cuantas=50)

# Single structure
optimized_one = opt_sc(population[0], metal_type='Au')

# Parallel batch
optimized_all = opt_SC_parallel(population, metal_type='Au', n_jobs=4)
```

### Deduplicate a structure pool with USR

```python
from aegon.libdisc_usr import deduplicate_by_usr

unique = deduplicate_by_usr(optimized, tols=0.99, tole=0.1, mono=True)
print(f"{len(optimized)} → {len(unique)} unique structures")
```

### Apply genetic algorithm operators

```python
from aegon.libmutants import atom_displacement, twist_mutation
from aegon.libcrossover import crossover_deavenho
from aegon.libsel_roulette import get_roulette_wheel_selection

# Select parents by roulette wheel (fitness-proportional)
parents = get_roulette_wheel_selection(optimized, nmating=20)

# Mutation
mutant = atom_displacement(parents[0], delta=0.4)

# Deaven-Ho cut-and-splice crossover
atomlist = parents[0].get_chemical_symbols()
children = crossover_deavenho(parents[0], parents[1], atomlist)
```

### Read output from quantum chemistry codes

```python
from aegon.libcode import read_out

reader = read_out()

# Final optimized geometry (supported: 'gaussian', 'orca', 'vasp', 'gulp')
mol = reader.geo('gaussian', 'output.log')

# Full optimization trajectory (supported: 'gaussian', 'orca', 'vasp')
traj = reader.traj('orca', 'calculation.out')
```

### Visualize in Jupyter / Colab

```python
from aegon.libgcolab import viewmol_ASE

viewmol_ASE(mol, width=500, height=500)
```

---

## Reference Databases

AEGON ships two bundled databases loaded lazily at runtime. Each entry is returned as an `ase.Atoms` object.

| Database | Potential | Available elements | Sizes |
|---|---|---|---|
| `libdata_lj.npz` | Lennard-Jones (ε = 1 eV, r₀ = 2^(1/6) σ = 3 Å) | any (Mo by default) | N = 5–130 |
| `SC_<El>_clusters_data.npz` | Sutton-Chen | Ag, Al, Au, Cu, Ir, Ni, Pb, Pd, Pt, Rh | N = 5–90 |

These datasets were generated with the GrowPAL diversity-preserving algorithm and validated against the Wales reference database (LJ) and literature results (SC).

### Access via direct functions

```python
from aegon.libdata_lj import get_lj_cluster
from aegon.libdata_sc import get_sc_cluster

# LJ cluster: info keys are 'i' (ID string) and 'e' (energy in eV)
lj38 = get_lj_cluster(38)
print(lj38.info['i'], lj38.info['e'])

# SC cluster
au20 = get_sc_cluster(20, symbol='Au')
print(au20.info['i'], au20.info['e'])
```

### Access via ClusterFactory

```python
from aegon.libclusterfactory import ClusterFactory

# LJ cluster: info keys are 'label' and 'energy'
lj38 = ClusterFactory.get(N=38, model='LJ')
print(lj38.info['label'], lj38.info['energy'])

# SC cluster
au20 = ClusterFactory.get(N=20, model='SC', element='Au')

# List available sizes
print(ClusterFactory.list_available(model='SC', element='Pt'))
```

---

## Sutton-Chen Parameters

AEGON includes the original Sutton-Chen parameters from Sutton & Chen, *Philos. Mag. Lett.* **1990**, 61, 139–146, for ten metals:

| Element | n | m | ε (eV) | a (Å) | C |
|---------|---|---|--------|--------|---|
| Ni | 9 | 6 | 1.5707×10⁻² | 3.52 | 39.432 |
| Cu | 9 | 6 | 1.2382×10⁻² | 3.61 | 39.432 |
| Rh | 12 | 6 | 4.9371×10⁻³ | 3.80 | 144.41 |
| Pd | 12 | 7 | 4.1790×10⁻³ | 3.89 | 108.27 |
| Ag | 12 | 6 | 2.5415×10⁻³ | 4.09 | 144.41 |
| Ir | 14 | 6 | 2.4489×10⁻³ | 3.84 | 334.94 |
| Pt | 10 | 8 | 1.9833×10⁻² | 3.92 | 34.408 |
| Au | 10 | 8 | 1.2793×10⁻² | 4.08 | 34.008 |
| Pb | 10 | 7 | 5.5765×10⁻³ | 4.95 | 45.778 |
| Al | 7  | 6 | 3.3147×10⁻² | 4.05 | 16.339 |

```python
from aegon.libcalc_sc import SUTTON_CHEN_PARAMS

params = SUTTON_CHEN_PARAMS['Pd']
print(params['n'], params['m'], params['epsilon'])
```

---

## Citation

If you use AEGON in your research, please cite the associated manuscript (in preparation).

AEGON is the optimization backend used in:

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

> López-Castro C., Ortiz-Chi F., Merino G.
> *An Efficient Growth Pattern Algorithm (GrowPAL) for Cluster Structure Prediction.*
> J. Chem. Theory Comput. **2024**, 20, 4939–4948.

---

## Authors

- **Filiberto Ortiz-Chi** — Secihti-Departamento de Física Aplicada, Cinvestav-IPN, Mérida, México
- **Aileen Garcia Cano** — Facultad de Ingeniería, Universidad Autónoma de Yucatán, Mérida, México

---

## License

MIT — see [LICENSE](LICENSE).
