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) and operates directly on ase.Atoms objects. It provides a self-contained toolkit covering every stage of a global optimization workflow, organized into three subpackages that mirror the three stages of the search: generation (random and symmetry-constrained structure creation), optimization (local relaxation — built-in potentials and external QM/FF codes behind one plugin registry), and discrimination (structure deduplication). Performance-critical routines are accelerated through Numba just-in-time compilation.

Table of Contents

• Features
• Installation
• Dependencies
• Module Overview
• Usage
• Reference Databases
• Sutton-Chen Parameters
• Known Dead Code
• Citation
• Authors
• License

Features

• Random structure generation — ten structural templates (compact 3D, diffuse 3D, planar 2D, spherical shell, wire, ring, two-ring, helix, eye, and a symmetry-constrained template drawn from a randomly chosen compatible point group) 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.
• Rotamer/conformer generation — dihedral rotation along bridge bonds identified from the molecular graph (rattle-based random sampling), for single-molecule conformer search.
• 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; a Numba-accelerated periodic empirical engine (LJ + Buckingham + Ewald, cell+positions relaxed via UnitCellFilter) for TiO2, MgAl2O4, MgSiO3, and SrTiO3; ANI machine-learned potentials (ANI1x/ANI1ccx/ANI2x, optional [ani] extra).
• Calculator registry — a plugin-style registry (aegon.optimization.build(calc_type, **kwargs)) that drives full parallel local optimizations for LJ, SC, TIO2, EMT, PERIODIC, ANI, GAUSSIAN, ORCA, MOPAC, GULP, and VASP behind one interface. A generic 'ASE' entry dynamically wraps any ase.calculators.Calculator by module + class name (optionally relaxing cell and positions together via an ase.filters cell filter for periodic structures), so new ASE-compatible potentials work without new registry code.
• Periodic-aware GULP/VASP — GulpEngine/VaspEngine auto-detect already-periodic input (any(atoms.pbc)) and preserve the real cell instead of vacuum-boxing it via molecule2poscar (which stays the default for non-periodic clusters), so the same registry entries serve both cluster codes (growpal) and crystal structure prediction (solids).
• External quantum chemistry interfaces — per-code parsers under aegon.parsing (libcode_gaussian/libcode_orca/libcode_mopac/libcode_gulp/libcode_vasp: geometry, trajectory, termination status), plus a unified convenience parser (aegon.parsing.read_out) for output files from Gaussian, ORCA, VASP, GULP, and MOPAC; input generation and batch execution with parallel queuing (libengine_gaussian/libengine_orca/libengine_mopac/libengine_gulp/libengine_vasp).
• Multi-node dispatch (aegon.optimization.launchers) — all 5 external-code engines accept an optional Launcher (launcher=), a strategy for turning one job into an actually-running subprocess. LocalLauncher (the default) is exactly today's single-node subprocess.run() behavior — nothing changes unless a caller opts in. SlurmLauncher packs each job as its own srun step inside a multi-node Slurm allocation (job-step packing, not MPI — each job still only uses the cores of the one node it lands on), so optimize_parallel() can spread jobs round-robin across nodes= (e.g. SlurmLauncher.nodes_from_allocation()). No other aegon module besides launchers/slurm.py imports anything Slurm-specific.
• Layered site configuration — aegon.config resolves installation-specific settings (binary paths, scratch folders) from an environment variable, an XDG user config file, or packaged defaults, validated with Pydantic — kept separate from per-run parameters.
• Consistent unit system — aegon.units ties energy and force units together as one choice (eV/eV·Å⁻¹, atomic/Eh·bohr⁻¹, or kcal/kcal·mol⁻¹·Å⁻¹), applied uniformly by every calculator.
• Structure discrimination — USR (Ultrafast Shape Recognition) descriptors for fast deduplication/filtering of cluster pools, and MBTR descriptor-based comparison for periodic crystal 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

pip install aegon

Requires Python >= 3.10. To use the ANI machine-learned potentials (torch/torchani, a heavy optional dependency not needed for anything else in AEGON):

pip install aegon[ani]

Google Colab

!pip install aegon

Dependencies

ASE is capped at <3.27 because dscribe 2.1.2 (the latest release on PyPI — no fix is available) builds its internal System wrapper by calling ase.Atoms.__init__ with positional arguments in the pre-3.27 parameter order. ASE 3.27.0 removed calculator and inserted velocities into that positional sequence, so dscribe's call now lands info in the velocities slot — colliding with ASE's own "Use only one of momenta and velocities" check and raising a TypeError on every MBTR call (aegon.discrimination.crystal_mbtr, and growpal's multi-species mbtr_comb_dscribe). Confirmed broken on ASE 3.27.0/3.28.0/3.29.0 + dscribe 2.1.2, confirmed working on ASE 3.26.0 + dscribe 2.1.2. crystal_mbtr.py and growpal/libdescriptors.py both also carry an in-process compatibility patch as defense in depth, in case this ceiling is ever loosened or overridden.

MatterSim (pip install mattersim) is not a dependency or extra of AEGON — AEGON's own source never imports it, it's only used in examples/example_opt_crystal_mattersim.py through the generic 'ASE' strategy (optimization/potentials/ase_generic.py), which can wrap any ASE-compatible calculator without AEGON code changes. Adding it as a formal extra was deliberately rejected: MatterSim pulls in a large, unrelated dependency tree (pymatgen, torch_geometric, phonopy/phono3py, wandb, the Azure SDK, ...) that has nothing to do with AEGON's minimal core.

Known conflict if you install both aegon[ani] and mattersim in the same environment: MatterSim requires torch>=2.2.0 with no upper bound, while TorchANI 2.7.9 declares torch<=2.8,>=2.0. pip install mattersim will happily upgrade torch past 2.8 to satisfy its own constraint, which pip check then reports as a broken requirement for torchani. In practice ANI has been verified to still run correctly against torch==2.13.0 (installed by MatterSim) — this is a stale declared ceiling in TorchANI's metadata, not an observed runtime failure — but the two packages are not a clean, warning-free combination, and there's no way to prevent this from aegon's pyproject.toml since neither package is one of its extras.

Module Overview

AEGON's own code is organized into three subpackages that mirror the three stages of a global optimization search, plus shared infrastructure used across all three.

1. generation — creating structures

Three structure types (cluster, crystal, rotamer), each with its own _random module for stochastic generation. AEGON only builds the initial population — running a genetic algorithm on top of it (crossover, mutation, fitness-proportional selection) is the job of whichever driver package actually searches with that structure type, not AEGON itself: glomos.generation for clusters and rotamers, solids.generation for crystals. Both build directly on AEGON's population/geometry/ discrimination primitives below, so a GA driver never needs AEGON to know a GA exists.

2. optimization — relaxing structures

3. discrimination — filtering redundant structures

Shared infrastructure

Usage

Three complete examples below, one per subpackage from Module Overview — this is the same generate → optimize → discriminate sequence a GA driver (glomos, solids) repeats every generation, shown here as three standalone steps.

1. Generating structures

generation/cluster_random.py covers both unconstrained and symmetry-constrained cluster generation; generation/crystal_random.py and generation/rotamer_random.py cover the other two structure types (periodic crystals, single-molecule conformers — see Module Overview).

from aegon.generation.cluster_random import make_molecules_random, make_clusters_symmetric, make_cluster_symmetric

composition = ['Au'] * 13

# Unconstrained random generation, covalent-radii distance constraints + BFS
# connectivity check, generated in parallel
random_pop = make_molecules_random(composition, count=100, n_cores=4)

# Symmetry-constrained generation: each structure gets an automatically
# compatible point group
symmetric_pop = make_clusters_symmetric(composition, count=100, n_cores=4)

# Or fix a specific point group
mol_ih = make_cluster_symmetric(composition, point_group='Ih')

2. Optimizing structures

Every calculator — built-in potentials, ANI, or an external code — is driven through the same registry entry point, aegon.optimization.build:

from aegon.optimization import build, available

print(available())
# ['ANI', 'ASE', 'EMT', 'GAUSSIAN', 'GULP', 'LJ', 'MOPAC', 'ORCA', 'PERIODIC', 'SC', 'TIO2', 'VASP']

calc = build('SC', metal_symbol='Au', units='eV')
optimized = calc.optimize_parallel(random_pop, n_jobs=4)

# Periodic empirical potentials (no external binary) work the same way
calc_periodic = build('PERIODIC', spec='TIO2', units='eV')
optimized_crystal = calc_periodic.optimize_parallel(crystal_population, n_jobs=4)

units ('eV'/'atomic'/'kcal') fixes energy and force together, applied uniformly by every calculator via aegon.units.energy_factor/force_factor. The potential-specific functions (opt_LJ_parallel, opt_sc/opt_SC_parallel, ...) underneath each 'LJ'/'SC'/... strategy are also directly importable from optimization/potentials/*.py if you don't need the registry indirection.

External codes need binary paths and scratch folders, resolved from a layered site configuration (env var → XDG user config → packaged defaults, Pydantic-validated):

python -m aegon.config show

Every external-code calculator (GAUSSIAN/ORCA/MOPAC/GULP/VASP) also accepts an optional launcher, to spread jobs across more than one node of a multi-node job (e.g. under Slurm) instead of running everything on the current host — the default (launcher=None → LocalLauncher) is exactly the single-node behavior above, unchanged:

from aegon.optimization.launchers.slurm import SlurmLauncher

calc = build('GAUSSIAN', input_block=..., g16root=..., scratch_folder=...,
              output_folder=..., launcher=SlurmLauncher(mem_mb=13500),
              nodes=SlurmLauncher.nodes_from_allocation(), ncores_per_job=4)
calc.optimize_parallel(pool, n_jobs=26)   # 26 = 2 nodes x 13 concurrent jobs

To read an already-finished calculation instead of running a new one:

from aegon.parsing import read_out

reader = read_out()
mol  = reader.geo('gaussian', 'output.log')    # final geometry
traj = reader.traj('orca', 'calculation.out')  # full optimization trajectory

3. Discriminating structures

from aegon.population import sort_by_energy
from aegon.discrimination.cluster_usr import deduplicate_by_usr

ranked = sort_by_energy(optimized, abs_energy=True)
unique = deduplicate_by_usr(ranked, tols=0.99, tole=0.1, mono=True)
print(f"{len(optimized)} → {len(unique)} unique structures")
for mol in unique[:5]:
    print(mol.info['i'], mol.info['e'])

deduplicate_by_usr ranks by USR (Ultrafast Shape Recognition) descriptor similarity within tole (eV) of each other; mono=True skips the descriptor's moment-of-inertia component (irrelevant for single-element clusters). For periodic crystal pools, discrimination/crystal_mbtr.py provides the same deduplication via MBTR descriptors (requires the optional dscribe dependency).

Writing structures back out is a property of the ase.Atoms object itself (periodic or not, with or without forces), not of which code produced it: aegon.io.xyz.writexyzs (plain or, with extended=True, ASE's extended XYZ format) or aegon.io.poscar.writeposcars.

Crossover, mutation, and fitness-proportional roulette selection — the operators a genetic algorithm needs on top of these three steps — are not part of AEGON; see glomos's and solids's own READMEs.

Visualize in Jupyter / Colab

from aegon.io.gcolab 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.

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

from aegon.data.lj import get_lj_cluster
from aegon.data.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 aegondb

from aegon.data.clusterdb import aegondb

# LJ cluster: info keys are 'i' (ID string) and 'e' (energy in eV) — same
# convention as the direct functions above, since aegondb delegates to them
lj38 = aegondb.get(N=38, model='LJ')
print(lj38.info['i'], lj38.info['e'])

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

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

Compare Sutton-Chen energies between two metals

import numpy as np
from aegon.optimization.potentials.sc import SUTTON_CHEN_PARAMS
from aegon.data.sc import get_sc_cluster

metal_type1, metal_type2 = 'Pt', 'Au'
epsilon1 = SUTTON_CHEN_PARAMS[metal_type1]['epsilon']
epsilon2 = SUTTON_CHEN_PARAMS[metal_type2]['epsilon']

for i in range(4, 90 + 1):
    atoms1 = get_sc_cluster(i, symbol=metal_type1)
    atoms2 = get_sc_cluster(i, symbol=metal_type2)
    e1     = atoms1.info['e'] / epsilon1
    e2     = atoms2.info['e'] / epsilon2
    deltae = np.abs(e1 - e2)
    print("%9s vs. %9s  dE=%f" % (atoms1.info['i'], atoms2.info['i'], deltae))

Sutton-Chen Parameters

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

from aegon.optimization.potentials.sc import SUTTON_CHEN_PARAMS

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

Known Dead Code

Functions currently unreferenced anywhere in the codebase, flagged here so they are easy to find:

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.