# EZGA Unit Tests

This directory contains the comprehensive unit test suite for the Evolutionary Structure Explorer (EZGA). The tests ensure the reliability of the genetic algorithm pipeline, thermodynamic sampling accuracy, and integration with the SAGE geometry engine.

---

## 1. Core Genetic Operators & Logic
These tests focus on the fundamental building blocks of the evolutionary search.

*   **[test_mutations.py](./test_mutations.py)**  
    *   **Focus**: Verifies the internal consistency of atomic-level and lattice-level transformation primitives.
    *   **Details**: Validates specific operators like `rattle` (random coordinate displacement), `change_atom_type` (species transmutation), and lattice shears/strains. It ensures that constraints (e.g., fixed atoms) are respected and that the resulting structures remain mathematically valid.
*   **[test_selector.py](./test_selector.py)** / **[test_selector_methods.py](./test_selector_methods.py)**  
    *   **Focus**: Benchmarking the statistical distributions of selection policies.
    *   **Details**: Specifically validates that **Boltzmann selection** correctly reproduces the expected Boltzmann distribution at given temperatures. It also tests multidimensional **Pareto sorting** and the impact of repulsion weights on population diversity.
*   **[test_selector_plot.py](./test_selector_plot.py)**  
    *   **Focus**: Visual verification of selection behavior.
    *   **Details**: Generates plots showing the probability of selection for different individuals based on their objective values, helping debug weight and temperature settings.
*   **[test_scaling_selector.py](./test_scaling_selector.py)**  
    *   **Focus**: Robustness across magnitude differences.
    *   **Details**: Ensures that selectors maintain their efficacy even when objectives (e.g., Energy vs Diversity) differ by several orders of magnitude.
*   **[test_adaptive_mutation.py](./test_adaptive_mutation.py)**  
    *   **Focus**: Validates the self-learning mechanism for operator weights.
    *   **Details**: Tests how the engine dynamically adjusts the probabilities of different mutations based on their historical success in finding improved structures.
*   **[test_adaptive_parsimony.py](./test_adaptive_parsimony.py)**  
    *   **Focus**: Multi-objective complexity control.
    *   **Details**: Ensures that the GA favors simpler structures (parsimony pressure) when they achieve similar fitness to complex ones, preventing "bloat."

## 2. Thermodynamics & MCMC
Essential for any simulation intended to sample physical ensembles (NVT, GCMC, etc.).

*   **[test_detailed_balance.py](./test_detailed_balance.py)**  
    *   **Focus**: Verifies the mathematical reversibility of all Monte Carlo moves.
    *   **Details**: This is a critical test that calculates the forward and reverse proposal probabilities ($q_{fwd}$ and $q_{rev}$). It ensures that moves like adding or removing atoms are perfectly reversible.
*   **[test_trajectory_survival.py](./test_trajectory_survival.py)**  
    *   **Focus**: Acceptance/Rejection logic within the MCMC loops.
    *   **Details**: Directly tests the `Selector.survive()` logic, simulating different $\Delta U$ scenarios and verifying that the Metropolis-Hastings criteria are applied correctly.
*   **[test_exchange.py](./test_exchange.py)**  
    *   **Focus**: Multi-walker and Multi-phase exchange logic.
    *   **Details**: Validates **Replica Exchange** (temperature swaps) and **Gibbs Ensemble** (volume/particle transfer) moves, ensuring joint acceptance ratios are correctly computed.
*   **[test_linear_trajectory.py](./test_linear_trajectory.py)**  
    *   **Focus**: Sampling performance on 1D landscapes.
    *   **Details**: Verifies that MCMC walkers correctly explore a 1D potential well and converge to the expected probability density.

## 3. Machine Learning & Bayesian Optimization
Testing the "smart" search and regression components.

*   **[test_bo_ndim.py](./test_bo_ndim.py)** / **[test_bo_scaling.py](./test_bo_scaling.py)**  
    *   **Focus**: Numerical stability and scalability of Gaussian Process surrogate models.
    *   **Details**: Verifies that input features are correctly normalized and that BO can efficiently suggest high-fitness candidates in high-dimensional spaces.
*   **[test_symbolic_regression.py](./test_symbolic_regression.py)**  
    *   **Focus**: Correctness of expression trees and mathematical evaluations.
    *   **Details**: Tests the generation, mutation, and evaluation of symbolic trees against target data.
*   **[test_grammar_simplification.py](./test_grammar_simplification.py)**  
    *   **Focus**: Algebraic reduction of expressions.
    *   **Details**: Ensures that symbolic expressions like `x + x` are simplified to `2*x` to improve readability and evaluation speed.

## 4. System & Infrastructure
Backend robustness and data integrity.

*   **[test_file_system.py](./test_file_system.py)**  
    *   **Focus**: Persistence and data recovery.
    *   **Details**: Mocking the file system to verify that generation snapshots are written correctly and that the `resume` functionality works.
*   **[test_cli_dispatch.py](./test_cli_dispatch.py)**  
    *   **Focus**: Command-line interface integrity.
    *   **Details**: Verifies that CLI arguments are correctly parsed and routed to the appropriate GA engine configurations.
*   **[test_hash_benchmark.py](./test_hash_benchmark.py)**  
    *   **Focus**: Structural uniqueness and performance.
    *   **Details**: Benchmarks the speed of structural fingerprinting to ensure efficient duplicate detection.

## 5. Material Science & Physics
Physics-specific calculators and transformations.

*   **[test_dimer_calculator.py](./test_dimer_calculator.py)**  
    *   **Focus**: Energy evaluation for simple systems.
    *   **Details**: Validates energy and force calculations for diatomic systems using various potentials.
*   **[test_objective_pourbaix.py](./test_objective_pourbaix.py)**  
    *   **Focus**: Specialized fitness functions for stability.
    *   **Details**: Tests the calculation of Pourbaix diagram coordinates to optimize material stability under varying pH and potential conditions.
*   **[test_hise_materialization.py](./test_hise_materialization.py)**  
    *   **Focus**: Hierarchical Supercell transformations.
    *   **Details**: Ensures that structures are correctly mapped and materialized when transitioning between different supercell sizes.

---

## Running the Test Suite
To execute all tests with detailed output, use:
```bash
PYTHONPATH=src pytest -v tests/
```
To run only the core physics tests:
```bash
PYTHONPATH=src pytest tests/test_mutations.py tests/test_detailed_balance.py
```
