EZGA — Evolutionary Structure Exploration Framework

ChemRxiv License: MIT Python 3.10+ Tests Passing Coverage

image

image

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

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (1.2.31)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for JuanManuel from gravatar.com JuanManuel

Credits

Author: Juan Manuel Lombardi

License

MIT License (MIT)

Requires

Python >=3.10

Provides Extra

accel dev examples symmetry tests viz

Tags

DFT MLIP genetic algorithm materials multi-objective

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ezga_lib-1.2.28.tar.gz (1.2 MB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

ezga_lib-1.2.28-py3-none-any.whl (1.3 MB view details)

Uploaded Python 3

File details

Details for the file ezga_lib-1.2.28.tar.gz.

File metadata

  • Download URL: ezga_lib-1.2.28.tar.gz
  • Upload date:
  • Size: 1.2 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.2.0 CPython/3.12.3

File hashes

Hashes for ezga_lib-1.2.28.tar.gz
Algorithm Hash digest
SHA256 0322e061184cc138af6d0b8dd9076d936c9d093e0c0cb79597999b78f94d269f
MD5 61d0579b7b6884a5c95613b213e8dbd3
BLAKE2b-256 2faca3fbc1334fdfb1c0add299c02999474487a1484ccde0e9dfb3e093364cb8

See more details on using hashes here.

File details

Details for the file ezga_lib-1.2.28-py3-none-any.whl.

File metadata

  • Download URL: ezga_lib-1.2.28-py3-none-any.whl
  • Upload date:
  • Size: 1.3 MB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.2.0 CPython/3.12.3

File hashes

Hashes for ezga_lib-1.2.28-py3-none-any.whl
Algorithm Hash digest
SHA256 32de4ab958ebb33707ffb4def244642c66762ded3cb284c5476eb4983c746ebb
MD5 32baf04168ffab4da89cb6fca26353c3
BLAKE2b-256 88bde512599d492df21818ed1ccff014c32313907c96f69433d4c360f546ed82

See more details on using hashes here.

Release history Release notifications | RSS feed

1.2.31

2 files

1.2.30

2 files

1.2.29

2 files

This release

1.2.28 This release

2 files

1.2.27

2 files

1.2.26

2 files

1.2.25

2 files

1.2.24

2 files

1.2.23

2 files

1.2.22

2 files

1.2.21

2 files

1.2.20

2 files

1.2.19

2 files

1.2.18

2 files

1.2.17

2 files

1.2.16

2 files

1.2.15

2 files

1.2.14

2 files

1.2.13

2 files

1.2.12

2 files

1.2.11

2 files

1.2.10

2 files

1.2.9

2 files

1.2.8

2 files

1.2.7

2 files

1.2.6

2 files

1.2.5

2 files

1.2.4

2 files

1.2.3

2 files

1.2.2

2 files

1.2.1

2 files

1.2.0

2 files

1.1.0

2 files

1.0.8

2 files

1.0.7

2 files

1.0.6

2 files

1.0.5

2 files

1.0.4

2 files

1.0.3

2 files

1.0.2

2 files

1.0.1

2 files

1.0.0

2 files

0.0.59

2 files

0.0.57

2 files

0.0.56

2 files

0.0.55

2 files

0.0.54

2 files

0.0.52

2 files

0.0.51

2 files

0.0.50

2 files

0.0.49

2 files

0.0.48

2 files

0.0.47

2 files

0.0.46

2 files

0.0.45

2 files

0.0.44

2 files

0.0.43

2 files

0.0.42

2 files

0.0.41

2 files

0.0.40

2 files

0.0.39

2 files

0.0.38

2 files

0.0.37

2 files

0.0.36

2 files

0.0.35

2 files

0.0.34

2 files

0.0.33

2 files

0.0.32

2 files

0.0.31

2 files

0.0.30

2 files

0.0.29

2 files

0.0.28

2 files

0.0.27

2 files

0.0.26

2 files

0.0.25

2 files

0.0.23

2 files

0.0.21

2 files

0.0.20

2 files

0.0.19

2 files

0.0.18

2 files

0.0.17

2 files

0.0.16

2 files

0.0.15

2 files

0.0.14

2 files

0.0.13

2 files

0.0.12

2 files

0.0.11

2 files

0.0.10

2 files

0.0.9

2 files

0.0.8

2 files

0.0.7

2 files

0.0.6

2 files

0.0.5

2 files

0.0.4

2 files

0.0.3

2 files

0.0.2

2 files

0.0.1

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page