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.29.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.29-py3-none-any.whl (1.3 MB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: ezga_lib-1.2.29.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.29.tar.gz
Algorithm Hash digest
SHA256 230c250cea441ea87b6ca78011c8c3715b66296b4fc460c1c1ea33c832bf91b9
MD5 4300d8ef5999a1f7c26870b1852875d9
BLAKE2b-256 1f1dba76a4852a9c5bc3edcf63331c83e53e1a2ae03e3f2a9478333e4d67e804

See more details on using hashes here.

File details

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

File metadata

  • Download URL: ezga_lib-1.2.29-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.29-py3-none-any.whl
Algorithm Hash digest
SHA256 513acd09ca9d6242862ac295c11b7e153cce21977ebfd7934b9c2cc3e5b3f4ab
MD5 97d71fa9048e206e88fadb57ee244f15
BLAKE2b-256 8cee46f5543165948d7b810db67fe949699c98b370dc461be7242662019068fa

See more details on using hashes here.

Release history Release notifications | RSS feed

1.2.31

2 files

1.2.30

2 files

This release

1.2.29 This release

2 files

1.2.28

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