SOLIDS

Crystal structure prediction — a genetic algorithm / stochastic search for periodic solids, built on top of AEGON.

SOLIDS searches 2-D (layer-group) and 3-D (space-group) periodic structures for a given composition, delegating every local optimization to AEGON's calculator registry — the same pattern glomos uses for clusters/molecules. Unlike glomos, both search modes (evolutive GA and stochastic kick) are dispatched from a single entry point, solids.heuristic.mainAlgorithm, selected by one algorithm key in the input file.

Table of Contents

• Features
• Installation
• Dependencies
• The INPUT file
• Supported calculators
• Usage
• Command-line tool
• Citation
• Authors
• License

Features

• Two search drivers, one entry point — mainAlgorithm(inputfile) dispatches on algorithm = evolutive (crossover + lattice-strain/atom-exchange mutation, generational) or algorithm = stochastic (fixed local-opt + niching stages, no evolutionary operators), reading everything else from the same INPUT format.
• Space-group-aware initial population — aegon.generation.crystal_random generates 3-D structures over all 230 space groups or 2-D slabs over all 80 layer groups, mixed with plain P1/P1-slab random structures in the same population.
• Own GA operators (solids.generation) — crystal crossover (generation/crystal_crossover.py) and lattice-strain/atom-exchange mutation (generation/crystal_mutant.py), plus fitness-proportional roulette selection (generation/selection.py), live in SOLIDS itself, not AEGON — AEGON only supplies the space-group-aware random generator, geometry utilities, and MBTR discrimination they're built on.
• Calculator-agnostic — dispatches through AEGON's registry: GULP/VASP (external binaries, periodic-aware — real cell kept intact, not vacuum-boxed like cluster search), EMT (ASE Effective Medium Theory with cell relaxation enabled), generic ASE (any ase.calculators.Calculator by module+class name — this is how MatterSim is used, without adding it as a dependency), and four of the package's own analytic periodic potentials (TIO2_PERIODIC/MGAL2O4_PERIODIC/MGSIO3_PERIODIC/SRTIO3_PERIODIC: Buckingham/LJ + Ewald + UnitCellFilter, Numba-JIT'd).
• MBTR-based discrimination — aegon.discrimination.crystal_mbtr deduplicates periodic pools by a cell-aware descriptor (unlike clusters, USR alone isn't meaningful across different unit cells).
• Unit-consistent — one units key (eV/atomic/kcal) fixes energy and force together across every calculator.
• Resumable evolutive runs — _find_latest_completed_stage picks up an interrupted GA run from its last completed generation.

Installation

pip install solids

Requires Python >= 3.9.

Dependencies

MatterSim is not a dependency — like in aegon's own examples, it's used only through the generic ASE calculator, so it never has to be declared. See examples/x_run_solids_mattersim_gega_si8.py, which pins a separate Python interpreter with MatterSim installed rather than requiring it in this environment.

The INPUT file

---COMPOSITION---
Ti   1
O    2
---COMPOSITION---

formula_units           4     #Composition above is multiplied by this
dimension               3     #2 (layer-group slabs) or 3 (space-group bulk)
volume_factor            1.0
tol_atomic_overlap       0.98 #Minimum interatomic distance, as a fraction of the covalent-radii sum

#ALGORITHM PARAMETERS:
algorithm                evolutive   #evolutive | stochastic

#INITIAL POPULATION:
nof_sg_structures        10    #Space-group (dimension=3) / layer-group (dimension=2) structures
nof_random_structures     0    #Plain P1 / P1-slab random structures

#Evolutive-only:
nof_matings              20
nof_strains               2
nof_xchange                2
strain_std                0.5

#NICHING PARAMETERS:
tol_similarity            0.98
cutoff_energy             40.0
cutoff_population          20

#HALT CRITERION:
#Stochastic: nof_stages 2
#Evolutive:
nof_generations             5
nof_repeats                10
nof_stagnant                5

#THEORY LEVEL:
calculator                GULP
nof_processes               10

The ---GULP---/---VASP---/... route block (only for the calculator actually selected) follows the same convention as glomos. Binary paths and scratch folders come from AEGON's site configuration (python -m aegon.config show), though path_exe in the INPUT file overrides it for a one-off run.

Supported calculators

Usage

from solids.heuristic import mainAlgorithm

population = mainAlgorithm('INPUT_SOLIDS_GULP_GEGA_TiO2.txt')
for mol in population[:5]:
    print(mol.info['i'], mol.info['e'])

Same function for both modes — only the input file's algorithm key (evolutive/stochastic) and its matching parameter block differ. The population is written to summary.vasp after every generation/stage, so progress is never lost if the process is interrupted; an evolutive run also resumes automatically from its last completed generation if restarted with the same working directory.

Examples cover every calculator across representative systems — TiO2, MgAl2O4, MgSiO3, SrTiO3 (GULP and the matching *_PERIODIC potential, both evolutive and stochastic), Al4 (EMT), C8 diamond (GULP and VASP), and Si8 (MatterSim, via the generic ASE strategy):

cd examples
python x_run_solids_gulp_gega_tio2.py      # one example
python run_all_examples.py                 # everything not commented out (VASP skipped -- real DFT)

Each script creates its own run_<code>_<heuristic>_<system>/ working directory and compares the result against reference structures (run_utils.py's compare_against_references) where available — see examples/run_all_examples.py's own header comment for per-example timings and examples/REF_*.vasp for the reference structures used.

Command-line tool

x-solids INPUT_SOLIDS.txt

runs mainAlgorithm directly from an input file. Without an existing input file:

x-solids input_emt    # write a template EMT input file (inputEMT), no external binary
x-solids input_gulp   # write a template GULP input file
x-solids input_vasp   # write a template VASP input file

Citation

If you use SOLIDS in your research, please cite the associated manuscript (in preparation), and the AEGON backend it builds on:

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

• Carlos Lopez-Castro — 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

See LICENSE.