# EZGA

EZGA is an independently developed framework for exploring candidate
structures through agents, populations, and generations. These tutorials
cover running EZGA through SODA's parallel execution and data-collection
infrastructure.

Start with [installation](../install.md) and
[SODA basics](concepts.md) if you need a build or an introduction to the runtime.

## Examples

Start with a small lattice relaxation to learn how EZGA's population settings,
calculator, and starting structures fit together.

| Example | What you will do | Requirements |
| --- | --- | --- |
| [FCC argon with Lennard–Jones](ezga-fcc.md) | Relax an FCC supercell, run one evolutionary generation with cell-strain mutations, and inspect the best lattice. | EZGA-enabled build, ASE, and CPU cores. No external model file or GPU. |

Inputs live in the repository's `examples/ezga/` directories. Copy the files
specified in the walkthrough into a separate run directory and edit those
copies for your calculation.

:::{admonition} Native settings and integration limits
:class: tip

Some native EZGA parameters are not supported by the SODA integration.
For example, descriptor-based hashing is unavailable, and native snapshot
restart and filesystem population storage are replaced by SODA's HDF5
persistence. Use SODA's `--loadrun` for restarts. The
[settings page](ezga-settings.md#unsupported-and-redirected-settings) lists
specific parameters and their alternatives; these limits concern running
EZGA through SODA, not EZGA's standalone capabilities.
:::

More tutorials on multiple agents, population design, and advanced search
settings are coming soon.

## Settings, custom factories, and analysis

- [EZGA settings](ezga-settings.md): where to set native scientific options,
  starting structures, and SODA runtime controls.
- [Preparing custom factories for SODA–EZGA](ezga-factories.md): follow the
  generation flow and supply functions with the required inputs and outputs.
- [Analyzing EZGA output](ezga-analysis.md): inspect generations and populations,
  export structures, and check rejected candidates.

```{toctree}
:maxdepth: 1
:hidden:

ezga-fcc
ezga-settings
ezga-factories
ezga-analysis
```

## References and project links

Lombardi, J. M., et al. *Computer Physics Communications* **328**, 110354
(2026). [doi:10.1016/j.cpc.2026.110354](https://doi.org/10.1016/j.cpc.2026.110354).

Upstream project and source code: [EZGA on GitLab](https://gitlab.mpcdf.mpg.de/fhi-theory/EZGA).

Cite EZGA for its scientific methods and software, and SODA for the supporting
infrastructure used in the calculation. See [Citing SODA](../citations.md)
for the corresponding references and those for the potential or model used.