# xlowz/ln-es architecture

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

- Interactive diagram: https://gitdiagram.com/xlowz/ln-es
- Repository: https://github.com/xlowz/ln-es

## Overview

##### Project Type and Purpose
- The project implements an evolutionary strategies algorithm – specifically (μ + λ) – with gene-wise log-normal mutation. Its primary purpose is optimization, using the Rastrigin function as its objective. The design hints at a modular approach by relying on a structure inspired by DEAP.

##### Main Components
a. Application Entry Point:
- src/main.py – The orchestration script that initializes parameters and invokes the evolutionary strategy routines.
b. Domain Models:
- src/classes/individual.py and src/classes/individualz.py – These modules define the data model for individuals in the population (possibly two variants of individuals).
- src/classes/parameters.py – Contains configuration and adjustable parameters for the optimization (e.g., mutation rates, population size, etc.).
c. Evolution Strategies (ES) Modules:
- src/es/es_single.py – Likely contains logic for a single instance or a variant of the evolutionary strategy.
- src/es/mu_plus_es.py – Implements the critical (μ + λ) selection method and mutation logic.
d. Utility Functions:
- src/utils/utils.py – Provides helper functions that may be used during various stages of the algorithm (e.g., logging, mathematical helpers, etc.).

##### Interactions and Data Flow
- The main module creates or populates instances of individuals using the classes in the “classes” folder.
- It then calls the evolutionary strategy in the “es” components, passing individuals and parameters, and receives feedback (fitness evaluations, updated population data).
- Utility functions (from utils) are invoked at different points to support common operations (data validation, logging, or computations).

##### Architectural Patterns and Design Principles
- Modular Design: Emphasize the clear separation of concerns. Each directory (classes, es, utils) encapsulates distinct parts of the algorithm.
- Loose Coupling: Show how the main orchestration remains decoupled from the specifics of the ES implementations.

##### Elements
- Each component should be clearly labeled:
- “Main Application” for src/main.py.
- “Domain Models” for classes/individual.py, classes/individualz.py, and classes/parameters.py.
- “Evolution Strategies” covering es_single.py and mu_plus_es.py.
- “Utilities” for supporting functions in utils/utils.py.
- Data/control flows from main application to domain models (setting up individuals/parameters).
- Invocation from the main module to ES logic.
- Feedback loops within the evolutionary strategy (e.g., mutation and selection cycles).
- This will help visually distinguish the types of components and their boundaries.

- Detail the evolutionary cycle stage:
- Initialization: “Load parameters” (from parameters.py) and “Create initial population” (individual classes).
- Evolution Loop: “Evaluate Fitness (Rastrigin)”, “Mutation (log-normal strategy)” in the ES modules, and then “Selection” (μ + λ strategy).
- Termination: Criteria check and final output.
- Optionally, include an external reference node/note indicating that the mutation logic takes inspiration from the DEAP library.
- Avoid unnecessary fragmentation; however, emphasize the interaction flows to capture the core algorithm steps.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Orchestration
    subgraph "Core Orchestration"
        MA["Main Application"]:::core
    end

    %% Domain Models (Oval shape for data models)
    subgraph "Domain Models"
        ind(("Individual")):::model
        indz(("Individualz")):::model
        param(("Parameters")):::config
    end

    %% Evolution Strategies (Rectangles for core algorithm components)
    subgraph "Evolution Strategies"
        es1["ES Single"]:::es
        mu_es["(μ+λ) Selection"]:::es
    end

    %% Utilities (Rounded boxes for utility modules)
    subgraph "Utilities"
        util["Utilities"]:::util
    end

    %% Interactions & Data Flow
    MA -->|"load_params"| param
    MA -->|"create_individual"| ind
    MA -->|"create_individual"| indz
    MA -->|"invoke_ES"| es1
    MA -->|"invoke_ES"| mu_es
    es1 -- "mutation_cycle" --> es1
    mu_es -- "mutation_cycle" --> mu_es
    es1 -->|"utilize"| util
    mu_es -->|"utilize"| util
    es1 -->|"return_results"| MA
    mu_es -->|"return_results"| MA

    %% Styles
    classDef core fill:#ffcc00,stroke:#333,stroke-width:2px;
    classDef model fill:#99ccff,stroke:#333,stroke-width:2px;
    classDef config fill:#99ff99,stroke:#333,stroke-width:2px;
    classDef es fill:#ff99cc,stroke:#333,stroke-width:2px;
    classDef util fill:#ccffff,stroke:#333,stroke-width:2px;

    %% Click Events
    click MA "https://github.com/xlowz/ln-es/blob/main/src/main.py"
    click ind "https://github.com/xlowz/ln-es/blob/main/src/classes/individual.py"
    click indz "https://github.com/xlowz/ln-es/blob/main/src/classes/individualz.py"
    click param "https://github.com/xlowz/ln-es/blob/main/src/classes/parameters.py"
    click es1 "https://github.com/xlowz/ln-es/blob/main/src/es/es_single.py"
    click mu_es "https://github.com/xlowz/ln-es/blob/main/src/es/mu_plus_es.py"
    click util "https://github.com/xlowz/ln-es/blob/main/src/utils/utils.py"
```
