Metadata-Version: 2.4
Name: solids
Version: 0.4.1
Summary: Solids: A tool for crystal structure prediction
Author-email: Carlos Lopez-Castro <carlosdrakko@gmail.com>, Gabriel Merino <gabriel.merino2@gmail.com>, Filiberto Ortiz-Chi <fortiz666@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/Carloast0790/SolidASE_0.0
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aegon>=1.3.12
Requires-Dist: dscribe
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file

# SOLIDS

**Crystal structure prediction — a genetic algorithm / stochastic search for periodic solids, built on top of [AEGON](https://pypi.org/project/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](#features)
- [Installation](#installation)
- [Dependencies](#dependencies)
- [The INPUT file](#the-input-file)
- [Supported calculators](#supported-calculators)
- [Usage](#usage)
- [Command-line tool](#command-line-tool)
- [Citation](#citation)
- [Authors](#authors)
- [License](#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

```bash
pip install solids
```

Requires Python >= 3.9.

---

## Dependencies

| Package | Role |
|---|---|
| [aegon](https://pypi.org/project/aegon/) | Structure generation (space-group-aware crystals), unit conversion, and the calculator registry |
| [dscribe](https://singroup.github.io/dscribe/) | MBTR descriptors for periodic structure discrimination |

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

| `calculator` | Backend | Notes |
|---|---|---|
| `GULP` | GULP | External binary; periodic-aware (`GulpEngine` keeps the real cell, no vacuum-boxing) |
| `VASP` | VASP | External binary, periodic DFT; requires a licensed POTCAR |
| `EMT` | ASE EMT, via the generic `ASE` strategy | Cell relaxation enabled (AEGON's own `'EMT'` entry is position-only, insufficient for crystals) |
| `ASE` | any `ase.calculators.Calculator` | Generic, by `ase_module`/`ase_class` — how MatterSim and other ML potentials are used |
| `TIO2_PERIODIC` | `solids.calc`, Matsui-Akaogi Buckingham+Ewald | No external binary; verified against GULP's own `matsui-akaogi.lib` |
| `MGAL2O4_PERIODIC` | `solids.calc`, LJ+Buckingham+Ewald | No external binary; constant-pressure cell relaxation |
| `MGSIO3_PERIODIC` | `solids.calc`, LJ+Buckingham+Ewald | No external binary; zero-pressure cell relaxation |
| `SRTIO3_PERIODIC` | `solids.calc`, LJ+Buckingham+Ewald | No external binary; zero-pressure cell relaxation |

---

## Usage

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

```bash
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

```bash
x-solids INPUT_SOLIDS.txt
```

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

```bash
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](LICENSE).
