ezga-lib 1.2.25

A modular multi-objective genetic algorithm framework for atomistic structure exploration

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

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:

• Home
• Installation
• Quickstart
• Recipes
• Configuration (GAConfig)

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 Agent, load_config
config = load_config("config.yaml")
agent = Agent(config)
agent.run()

---

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.

• 🐞 Report a bug
• ✨ Request a feature
• ❓ Ask a question
• 📝 Improve documentation

Issue templates are available here: Issue templates

---

Authors

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