EZGA — Evolutionary Structure Exploration Framework

Overview

EZGA is a modular, scalable, and chemically aware evolutionary framework for exploring and optimizing atomistic structures. It follows the GitLab Enterprise Documentation Style, emphasizing clarity, task‑orientation, operational guidance, and maintainability. This page serves as the primary landing document for new users and contributors.

EZGA enables configuration‑first evolutionary searches across molecular, cluster, crystalline, and surface systems. The engine integrates interchangeable components—initialization, features, objectives, selection, variation, convergence, and simulation—built around reproducible workflows and deterministic archival.

📄 Reference & Citation

The methodology and design principles of EZGA are described in:

Juan Manuel Lombardi et al.
EZGA: An Evolutionary Structure Exploration Framework
ChemRxiv (2025)

https://chemrxiv.org/doi/full/10.26434/chemrxiv.15000180/v1

BibTeX

@article{lombardi2025ezga,
  title   = {EZGA: An Evolutionary Structure Exploration Framework},
  author  = {Lombardi, Juan Manuel and Riccius, Felix and Paré, Charles W. P., Hendrik H. Heenen, and Reuter, Karsten and Scheurer, Christoph},
  journal = {ChemRxiv},
  year    = {2025},
  doi     = {10.26434/chemrxiv.15000180}
}

Key capabilities

Configuration‑driven GA engine for molecules and periodic crystals.
Advanced Bayesian Optimization: Integrated BO with efficient warm-starting, model persistence, ARD kernels for anisotropic features, and visualization utilities.
Composable modules: initialization, constraints, features, objectives, selection, variation, simulator, convergence.
Robust execution: deterministic seeds, deduplication, integrity checks, scalable parallelism.
Physical‑model integration with ASE/MACE or any Python‑callable evaluator.
Hierarchical Supercell Escalation (HiSE) for periodic systems.
Task‑oriented workflows: copy → modify → run.

Why use EZGA

Explore large compositional/structural spaces efficiently.
Apply human‑readable constraints (e.g., greater_than("Cu", 1)).
Start with datasets or DoE space‑filling seeds; escalate to larger supercells.
Increase robustness using integrity checks that avoid unphysical trial structures.
Scale seamlessly from a laptop to multi‑GPU clusters.

Get started fast

1. Install (Python ≥ 3.10)

pip install ezga-lib

Optional GPU/ML potential dependencies (MACE/ASE, CUDA/ROCm) depend on your environment. See Simulator in the Wiki.

2. Smoke test

import ezga

print(getattr(ezga, "__version__", "unknown"))

3. Run your first job

New here? Run python examples/00_start_here/optimize_a_structure.py — finishes in seconds, writes best.xyz + energy_vs_step.png.

Follow the minimal runnable script in Quickstart.

Tip: In GitLab Wiki, section anchors work like: ./Constraints#greater-than.

For Claude Code Users

If you want to use Claude Code with automatic skill discovery and AI-assisted development:

Option A: Install from PyPI (Easiest)

pip install ezga-lib
ezga setup-claude

The setup-claude command copies the Claude Code skills to your current directory.

Option B: Clone and develop

git clone https://gitlab.mpcdf.mpg.de/fhi-theory/EZGA
cd Evolutionary-Structure-Explorer
pip install -e .

Using Claude Code

Once set up, open in Claude Code:

Web: Go to claude.com/code and open this folder
CLI: Run claude code . in this directory
IDE: Use the Claude Code extension in VSCode or your editor

Claude will automatically discover and use the /ezga-* skills:

/ezga-setup — API, QuickGA, HiSE
/ezga-config — Configuration & parameters
/ezga-objectives — Features & objectives
/ezga-mutations — Operators & constraints
/ezga-ensemble-sampling — Ensemble methods
/ezga-debug — Troubleshooting guides
/ezga-benchmark — Performance testing

Documentation

Full documentation is available in the project's GitLab Wiki:

See ROADMAP.md for the full list of planned improvements, bug fixes, and upcoming features.

Repository structure

src/ezga/
    core/                   # GA engine configuration & parameters
    simple/                 # Simplified API (minimize, GA class)
    generative/             # Generative models (Bayesian Optimization)
    selection/              # Parent selectors
    variation/              # Mutation & crossover operators
    hise/                   # Supercell escalation
    thermostat/             # Exploration–exploitation control
    DoE/                    # Design-of-Experiments initializer
    convergence/            # Termination logic
    simulator/              # MD, relaxations, MLIPs
    evaluator/              # Feature & objective metrics
    visualization/          # Plotting & analysis tools
    sync/                   # Island-model mailbox
    io/                     # State persistence (SQL/HDF5)
    cli/                    # Command-line interface
    utils/                  # Helper utilities (including bo_plotter)

docs/                       # Sphinx documentation
tests/                      # Regression tests
dist/                       # Build artifacts
examples/                   # Example workflows

Usage

YAML workflow

ezga run config.yaml

Python API

from ezga import load_config, build_default_engine

# `load_config` accepts a YAML path *or* a plain dict matching the GAConfig schema.
config = load_config("config.yaml")  # e.g. load_config({"max_generations": 5})
engine = build_default_engine(config)
engine.run()

Prefer the one-liner facade? from ezga import QuickGA wraps the same pipeline. Agent is an internal component and is not part of the public API.

Bayesian Optimization & Generative AI

EZGA includes a powerful, configuration-driven Bayesian Optimization (BO) module designed to accelerate discovery in expensive search spaces.

Key Features

Automatic Relevance Determination (ARD): Automatically upgrades to an anisotropic Matern kernel for multi-dimensional problems, learning independent length scales for each feature (use_ard=True).
Robust Fitting: Improved kernel bounds prevent model collapse and ensure meaningful uncertainty estimates.
Model Persistence: Save trained GP models for offline analysis or warm-starting future runs (save_model=True).
Subsampling Control: Efficiently handle large datasets by subsampling training data (training_subsample=200).
Visualization: Built-in utilities to plot 2D surrogate models and diagnostics (ezga.utils.bo_plotter).

Example Usage

from ezga.simple.algorithm import GA

# Configure GA with advanced BO settings
algorithm = GA(
    pop_size=100,
    enable_bo=True,
    warm_start=True,  # Reuse previous solution for faster fitting
    use_ard=True,  # Enable anisotropic kernel
    save_model=True,  # Save GP models to disk
    training_subsample=500,  # Limit training data for speed
)

Benchmarks

EZGA is validated on:

Molecular conformational exploration (alanine dipeptide).
Lennard–Jones cluster global search.
Binary‑oxide convex‑hull reconstruction.
Autonomous CuO/Cu₂O grand‑canonical phase diagram.

Issues & Support

We use the GitLab issue tracker for bug reports, feature requests, and questions.

Issue templates are available here: Issue templates

Authors

Juan Manuel Lombardi
Felix Riccius
Charles W. P. Paré
Hendrik Hennen
Karsten Reuter
Christoph Scheurer

Metadata

Release files for ezga-lib 1.2.32

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ezga-lib 1.2.32
File	Size	Uploaded
ezga_lib-1.2.32.tar.gz	1.7 MB	Aug 28, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for ezga-lib 1.2.32
File	Interpreter	ABI	Platform	Reset
ezga_lib-1.2.32-py3-none-any.whl 1.9 MB Aug 28, 2026	Python 3	none	any	Details

Total release size: 3.7 MB

Release files / ezga_lib-1.2.32.tar.gz

Download URL	ezga_lib-1.2.32.tar.gz
Size	1.7 MB
Tags	Source
SHA-256 checksum How to use checksums	`cf5542b3d517ef41fa2c6857c0d7e4d349bb6edd945b58676f7d6b7a07eff6b9`
BLAKE2b-256 checksum How to use checksums	`9c68a5fb4427f66f25d83225bdd456ec44f8d87247d6651ff900639576a870e8`
Upload date	Aug 28, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.12.3`

Release files / ezga_lib-1.2.32-py3-none-any.whl

Download URL	ezga_lib-1.2.32-py3-none-any.whl
Size	1.9 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`442bbe07effb87cde5770a2ca10d08e9a43435e216f100a931627d138e9a8417`
BLAKE2b-256 checksum How to use checksums	`3d16eee0506cea50b0531f979655105bdf807d4b4ab704f60149ab48c9566782`
Upload date	Aug 28, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.12.3`