# EZGA Examples & Workflows

A comprehensive collection of scripts demonstrating the capabilities of the Evolutionary Structure Explorer, from simple numeric optimization to complex electrochemical phase diagrams.

---

## 🏛️ Chemical & Material Discovery
These scripts represent full research-grade workflows for periodic and cluster systems.

| Script | System | Description |
| :--- | :--- | :--- |
| `hise_cuo_phase_diagram.py` | **Cu-O Phase Diagram** | Full Grand-Canonical simulation of CuO/Cu₂O using HiSE and variable composition. |
| `hise_diversity_nio.py` | **Ni-O Diversity** | Exploration of Ni-O structural motifs using hierarchical supercell escalation. |
| `hise_diversity_cu_o_dimer.py` | **Cu-O Clusters** | Targeting diverse bonding environments in small copper oxide clusters. |
| `example_dimer_emt.py` | **EMT Dimer** | A "Hello World" for chemistry: simple bond length optimization for a dimer. |

---

## 🧬 Evolutionary & Adaptive Logic
Benchmarks for the core GA engine and its adaptive/guided variation mechanisms.

| Script | Focus | Description |
| :--- | :--- | :--- |
| `test_adaptive_mutation.py` | **Multi-Armed Bandit** | Tests the Thompson Sampling / MAB logic for dynamic mutation weight control. |
| `test_guided_variation.py` | **Guided Search** | Verifies the "Closest Parent" selection logic for directed crossovers. |
| `test_robust_variation.py` | **Error Handling** | Ensures the engine recovers gracefully from illegal mutations or unphysical structures. |

---

## 🤖 Bayesian Optimization (Generative)
Scripts focused on AI-guided structural proposals and surrogate model fitting.

| Script | Complexity | Description |
| :--- | :--- | :--- |
| `compare_bo.py` | **Benchmarking** | Head-to-head comparison of Pure GA vs. BO-Augmented searches. |
| `example_2d_gaussian.py` | **Visualization** | 2D surrogate model plotting and acquisition function diagnostics. |
| `test_bo_ndim.py` | **Scaling** | Verifies BO performance and memory usage in high-dimensional feature spaces. |
| `test_bo_scaling.py` | **Warm-Starting** | Checks the efficiency of the BO kernel when restarts/warm-starts are enabled. |
| `debug_bo.py` | **Diagnostics** | Minimal script for troubleshooting BO kernel collapse or fitting errors. |

---

## 🧮 Symbolic Logic & Rule Discovery
Examples of evolving mathematical expressions or logic rules instead of coordinates.

| Script | Focus | Description |
| :--- | :--- | :--- |
| `example_soft_logic.py` | **Soft Rules** | Evolves logical conditions (IF/THEN) for feature-based classification. |
| `pruning_utils.py` | **Simplification** | Utility script used to simplify and prune symbolic expression trees. |

---

## ⚡ Quickstart & Tooling
Minimal templates to get you running in minutes.

| Script | Interface | Description |
| :--- | :--- | :--- |
| `minimal_example.py` | **Python API** | A concise, single-file template to start any Python-based GA project. |
| `minimal_example.yaml` | **CLI / YAML** | The standard starting point for users who prefer configuration files. |
| `min.yaml` | **Ultra-Minimal** | Absolute bare-bones configuration for smoke testing. |
| `run_yaml.py` | **Utility** | A simple wrapper to launch any `.yaml` configuration from Python. |

---

## 🚀 Running Examples

Most examples can be executed directly with `python`:
```bash
python hise_diversity_nio.py
```

For YAML-based examples:
```bash
ezga run minimal_example.yaml
```
