# roberttlange/evosax architecture

> Architecture diagram of the GitHub repository roberttlange/evosax, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/roberttlange/evosax
- Repository: https://github.com/roberttlange/evosax

## Overview

##### Main Components
- Library Core: This is contained in the "evosax" package.
– The "algorithms" directory is split into two major parts:
▪ distribution_based – Contains implementations for strategies like CMA-ES, SNES, OpenAI-ES, xNES, and many more.
▪ population_based – Implements genetic algorithms and other population-based methods like Differential Evolution, PSO, and more.
– The "core" subpackage includes modules for shared functionalities such as fitness shaping, kernel operations, optimizers, and restart strategies. This forms the base layer that many algorithms build upon.
– The "learned_evolution" subpackage provides advanced modules like EvoTF and LES/DES tools that support using learned representations via attention and transformer modules.
– The "problems" subpackage defines benchmark problems (e.g., bbob, reinforcement learning environments, vision tasks) against which the evolution strategies are tested.
– A separate "types.py" module likely defines shared types and data structures across the library.

##### Surrounding Infrastructure
- Examples: The "examples" directory contains Jupyter notebooks illustrating API usage for various tasks. This component demonstrates how users interact with the library.
- Tests: The "tests" directory holds unit tests to verify the functionality of algorithms and core modules.
- Documentation & Community Files: The "docs" folder, along with files like README.md, CONTRIBUTING.md, CHANGELOG.md, and configuration files for GitHub workflows, show the project’s practices for continuous integration testing, publishing, and contributing.

##### Relationships and Interactions
- The central “ask – eval – tell” cycle is implemented across the algorithm modules. All evolution strategies (from distribution-based to population-based) interact with the shared core components for operations like fitness shaping and optimizers.
- The “core” modules provide baseline functionalities used in nearly every algorithm, making them a central utility service.
- The problem definitions are decoupled from the algorithm implementations; however, they are used during the testing and example phases.
- The learned evolution modules integrate with both the algorithm implementations and additional transformer tools (e.g., in evotf_tools), indicating modularity and extensibility.
- On the integration side, the use of JAX (with dependencies on jax transformations such as jit and vmap) is a significant architectural choice that promotes vectorization and hardware acceleration across the library.

##### Architectural Patterns and Design Principles
- Modular Design: The division of the project into subpackages (algorithms, core, learned_evolution, problems) reflects a modular approach that simplifies testing and extension.
- Unified API: All evolution strategies implement a uniform interface (ask, eval, tell) which is central to the library's design.
- Separation of Concerns: Clear separation exists between algorithm implementations, core functionalities, problem definitions, and user examples.
- Extensibility: With a wide range of strategies (each in its own module, including checkpoint versions) the pattern encourages adding more strategies or benchmarking tasks.
- Testing & CI Integration: The presence of GitHub workflows and a comprehensive test suite underscores a design process that values continuous integration and code quality.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Evosax Library"
        A["Core Utilities"]:::core
        B["Distribution-Based Algorithms"]:::algorithm
        C["Population-Based Algorithms"]:::algorithm
        D["Learned Evolution Modules"]:::learned
        E["Shared Types & Data Structures"]:::shared
        F(("Ask-Eval-Tell Cycle")):::cycle
    end

    subgraph "Infrastructure"
        G["Benchmark/Problems Definitions"]:::problems
        H["Examples (Jupyter Notebooks)"]:::example
        I["Tests (Unit/Integration)"]:::test
        J["Documentation & CI"]:::docs
    end

    K["JAX:jit,vmap (Hardware Acceleration)"]:::jax

    %% Connections within Evosax Library
    A -->|"supports"| B
    A -->|"supports"| C
    B -->|"implements"| F
    C -->|"implements"| F
    F -->|"evaluates"| G
    D -->|"enhances"| A
    D -->|"integrates"| B
    D -->|"integrates"| C

    %% Connections with Infrastructure
    H -->|"demonstrates"| A
    H -->|"showcases"| G
    I -->|"validates"| A
    I -->|"tests"| G
    J -->|"documents"| A

    %% JAX Note connection
    K ---|"accelerates"| A

    %% Class definitions for styling
    classDef core fill:#f4cccc,stroke:#b45f06,stroke-width:2px;
    classDef algorithm fill:#c9daf8,stroke:#073763,stroke-width:2px;
    classDef learned fill:#d9ead3,stroke:#38761d,stroke-width:2px;
    classDef shared fill:#ead1dc,stroke:#843c6b,stroke-width:2px;
    classDef cycle fill:#fff2cc,stroke:#bf9000,stroke-width:2px,stroke-dasharray: 4 2;
    classDef problems fill:#d0e0e3,stroke:#4a708b,stroke-width:2px;
    classDef example fill:#fce5cd,stroke:#d79b00,stroke-width:2px;
    classDef test fill:#d9d2e9,stroke:#674ea7,stroke-width:2px;
    classDef docs fill:#cfe2f3,stroke:#1c4587,stroke-width:2px;
    classDef jax fill:#ead1dc,stroke:#843c6b,stroke-width:2px,stroke-dasharray:5,5;

    %% Click Events for components
    click A "https://github.com/roberttlange/evosax/tree/main/evosax/core/"
    click B "https://github.com/roberttlange/evosax/tree/main/evosax/algorithms/distribution_based/"
    click C "https://github.com/roberttlange/evosax/tree/main/evosax/algorithms/population_based/"
    click D "https://github.com/roberttlange/evosax/tree/main/evosax/learned_evolution/"
    click E "https://github.com/roberttlange/evosax/blob/main/evosax/types.py"
    click G "https://github.com/roberttlange/evosax/tree/main/evosax/problems/"
    click H "https://github.com/roberttlange/evosax/tree/main/examples/"
    click I "https://github.com/roberttlange/evosax/tree/main/tests/"
    click J "https://github.com/roberttlange/evosax/blob/main/README.md"
```
