# donlan7524/esa-implementation architecture

> Architecture diagram of the GitHub repository donlan7524/esa-implementation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/donlan7524/esa-implementation
- Repository: https://github.com/donlan7524/esa-implementation

## Overview

ESA is a research implementation for minimizing expensive benchmark functions: an experiment run initializes evaluated samples, lets an agent choose an optimization strategy, evaluates proposed candidates, updates the sample history and agent, and records results. The main workflow is visible in `experiment.py` and documented in the README; strategies use surrogate models to guide proposals, while benchmark functions supply the objective. Alternative agents, strategies, and surrogate implementations are preserved as distinct capabilities. Some source files were not excerpted, so their internal behavior and connections are not inferred.

Main entry points: [`experiment.py`](https://github.com/donlan7524/esa-implementation/blob/main/experiment.py) (Experiment runner), [`code/RBF.py`](https://github.com/donlan7524/esa-implementation/blob/main/code/RBF.py) (Surrogate selector), [`main.py`](https://github.com/donlan7524/esa-implementation/blob/main/main.py) (Main entry), [`code/database.py`](https://github.com/donlan7524/esa-implementation/blob/main/code/database.py) (Sample database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_run["Experiment orchestration"]
  node_experiment["Experiment runner<br/>[experiment.py]"]
  node_main["Main entry<br/>[main.py]"]
end

subgraph group_learning["Agents"]
  node_qagent["Q-learning<br/>[Qagent.py]"]
  node_tsagent["Thompson sampling<br/>[TSagent.py]"]
  node_ucbagent["UCB1 agent<br/>[UCBagent.py]"]
end

subgraph group_search["Search strategies"]
  node_base["Strategy base<br/>[base_Strategy.py]"]
  node_de["Differential evolution<br/>[DE_strategy.py]"]
  node_sls["Local search<br/>[SLS_strategy.py]"]
  node_crossover["Crossover search"]
  node_trls["Trust-region search<br/>[TRLS_Strategy.py]"]
  node_lbfgs["L-BFGS search<br/>[LBFGS_Strategy.py]"]
end

subgraph group_models["Surrogate models"]
  node_selector["Surrogate selector<br/>[RBF.py]"]
  node_rbfhpo["RBF with HPO<br/>[RBF_hpo.py]"]
  node_rbfsimple["Simple RBF<br/>[RBF_simple.py]"]
  node_knn["Clustered KNN<br/>[KNN_surrogate.py]"]
  node_mlp["MLP surrogate<br/>[MLP_hpo.py]"]
  node_gp["Gaussian process<br/>[GP_surrogate.py]"]
  node_kmeans["K-means helper<br/>[kmeans.py]"]
end

subgraph group_domain["Data and objectives"]
  node_database[("Sample database<br/>[database.py]")]
  node_benchmarks["Benchmark functions<br/>[functions.py]"]
end

node_engineer(("Experiment user"))

node_engineer -->|"starts runs"| node_experiment
node_engineer -->|"starts program"| node_main
node_experiment -->|"initializes samples"| node_database
node_experiment -->|"selects objective"| node_benchmarks
node_experiment -->|"creates agent"| node_qagent
node_experiment -->|"creates agent"| node_tsagent
node_experiment -->|"creates agent"| node_ucbagent
node_experiment -->|"configures strategy"| node_de
node_experiment -->|"configures strategy"| node_sls
node_experiment -->|"configures strategy"| node_crossover
node_experiment -->|"configures strategy"| node_trls
node_experiment -->|"configures strategy"| node_lbfgs
node_experiment -->|"updates samples"| node_database
node_main -->|"initializes samples"| node_database
node_main -->|"selects objective"| node_benchmarks
node_de -->|"fits surrogate"| node_selector
node_sls -->|"fits surrogate"| node_selector
node_crossover -->|"fits surrogate"| node_selector
node_trls -->|"fits surrogate"| node_selector
node_lbfgs -->|"fits surrogate"| node_selector
node_selector -->|"selects implementation"| node_rbfhpo
node_selector -->|"selects implementation"| node_rbfsimple
node_selector -->|"selects implementation"| node_knn
node_selector -->|"selects implementation"| node_mlp
node_selector -->|"selects implementation"| node_gp
node_knn -->|"uses clustering"| node_kmeans

click node_experiment "https://github.com/donlan7524/esa-implementation/blob/main/experiment.py"
click node_main "https://github.com/donlan7524/esa-implementation/blob/main/main.py"
click node_qagent "https://github.com/donlan7524/esa-implementation/blob/main/code/Qagent.py"
click node_tsagent "https://github.com/donlan7524/esa-implementation/blob/main/code/TSagent.py"
click node_ucbagent "https://github.com/donlan7524/esa-implementation/blob/main/code/UCBagent.py"
click node_database "https://github.com/donlan7524/esa-implementation/blob/main/code/database.py"
click node_benchmarks "https://github.com/donlan7524/esa-implementation/blob/main/code/brenchmarks/functions.py"
click node_base "https://github.com/donlan7524/esa-implementation/blob/main/code/strategy/base_Strategy.py"
click node_de "https://github.com/donlan7524/esa-implementation/blob/main/code/strategy/DE_strategy.py"
click node_sls "https://github.com/donlan7524/esa-implementation/blob/main/code/strategy/SLS_strategy.py"
click node_crossover "https://github.com/donlan7524/esa-implementation/blob/main/code/strategy/crossover_strategy.py"
click node_trls "https://github.com/donlan7524/esa-implementation/blob/main/code/strategy/TRLS_Strategy.py"
click node_lbfgs "https://github.com/donlan7524/esa-implementation/blob/main/code/strategy/LBFGS_Strategy.py"
click node_selector "https://github.com/donlan7524/esa-implementation/blob/main/code/RBF.py"
click node_rbfhpo "https://github.com/donlan7524/esa-implementation/blob/main/code/RBF_hpo.py"
click node_rbfsimple "https://github.com/donlan7524/esa-implementation/blob/main/code/RBF_simple.py"
click node_knn "https://github.com/donlan7524/esa-implementation/blob/main/code/KNN_surrogate.py"
click node_mlp "https://github.com/donlan7524/esa-implementation/blob/main/code/MLP_hpo.py"
click node_gp "https://github.com/donlan7524/esa-implementation/blob/main/code/GP_surrogate.py"
click node_kmeans "https://github.com/donlan7524/esa-implementation/blob/main/code/kmeans.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_experiment,node_main,node_engineer toneBlue
class node_qagent,node_tsagent,node_ucbagent toneAmber
class node_base,node_de,node_sls,node_crossover,node_trls,node_lbfgs toneMint
class node_selector,node_rbfhpo,node_rbfsimple,node_knn,node_mlp,node_gp,node_kmeans toneRose
class node_database,node_benchmarks toneIndigo
```

## Components

### Experiment orchestration

- [Experiment runner](https://github.com/donlan7524/esa-implementation/blob/main/experiment.py): `experiment.py`
- [Main entry](https://github.com/donlan7524/esa-implementation/blob/main/main.py): `main.py`

### Agents

- [Q-learning](https://github.com/donlan7524/esa-implementation/blob/main/code/Qagent.py): `code/Qagent.py`
- [Thompson sampling](https://github.com/donlan7524/esa-implementation/blob/main/code/TSagent.py): `code/TSagent.py`
- [UCB1 agent](https://github.com/donlan7524/esa-implementation/blob/main/code/UCBagent.py): `code/UCBagent.py`

### Search strategies

- [Strategy base](https://github.com/donlan7524/esa-implementation/blob/main/code/strategy/base_Strategy.py): `code/strategy/base_Strategy.py`
- [Differential evolution](https://github.com/donlan7524/esa-implementation/blob/main/code/strategy/DE_strategy.py): `code/strategy/DE_strategy.py`
- [Local search](https://github.com/donlan7524/esa-implementation/blob/main/code/strategy/SLS_strategy.py): `code/strategy/SLS_strategy.py`
- [Crossover search](https://github.com/donlan7524/esa-implementation/blob/main/code/strategy/crossover_strategy.py): `code/strategy/crossover_strategy.py`
- [Trust-region search](https://github.com/donlan7524/esa-implementation/blob/main/code/strategy/TRLS_Strategy.py): `code/strategy/TRLS_Strategy.py`
- [L-BFGS search](https://github.com/donlan7524/esa-implementation/blob/main/code/strategy/LBFGS_Strategy.py): `code/strategy/LBFGS_Strategy.py`

### Surrogate models

- [Surrogate selector](https://github.com/donlan7524/esa-implementation/blob/main/code/RBF.py): `code/RBF.py`
- [RBF with HPO](https://github.com/donlan7524/esa-implementation/blob/main/code/RBF_hpo.py): `code/RBF_hpo.py`
- [Simple RBF](https://github.com/donlan7524/esa-implementation/blob/main/code/RBF_simple.py): `code/RBF_simple.py`
- [Clustered KNN](https://github.com/donlan7524/esa-implementation/blob/main/code/KNN_surrogate.py): `code/KNN_surrogate.py`
- [MLP surrogate](https://github.com/donlan7524/esa-implementation/blob/main/code/MLP_hpo.py): `code/MLP_hpo.py`
- [Gaussian process](https://github.com/donlan7524/esa-implementation/blob/main/code/GP_surrogate.py): `code/GP_surrogate.py`
- [K-means helper](https://github.com/donlan7524/esa-implementation/blob/main/code/kmeans.py): `code/kmeans.py`

### Data and objectives

- [Sample database](https://github.com/donlan7524/esa-implementation/blob/main/code/database.py): `code/database.py`
- [Benchmark functions](https://github.com/donlan7524/esa-implementation/blob/main/code/brenchmarks/functions.py): `code/brenchmarks/functions.py`

### Other components

- **Experiment user**

## Connections

- Experiment user → Experiment runner: starts runs (evidence: `README.md`)
- Experiment user → Main entry: starts program (evidence: `README.md`)
- Experiment runner → Sample database: initializes samples (evidence: `experiment.py`)
- Experiment runner → Benchmark functions: selects objective (evidence: `experiment.py`)
- Experiment runner → Q-learning: creates agent (evidence: `experiment.py`)
- Experiment runner → Thompson sampling: creates agent (evidence: `experiment.py`)
- Experiment runner → UCB1 agent: creates agent (evidence: `experiment.py`)
- Experiment runner → Differential evolution: configures strategy (evidence: `experiment.py`)
- Experiment runner → Local search: configures strategy (evidence: `experiment.py`)
- Experiment runner → Crossover search: configures strategy (evidence: `experiment.py`)
- Experiment runner → Trust-region search: configures strategy (evidence: `experiment.py`)
- Experiment runner → L-BFGS search: configures strategy (evidence: `experiment.py`)
- Experiment runner → Sample database: updates samples (evidence: `experiment.py`)
- Main entry → Sample database: initializes samples (evidence: `main.py`)
- Main entry → Benchmark functions: selects objective (evidence: `main.py`)
- Differential evolution → Surrogate selector: fits surrogate (evidence: `code/strategy/DE_strategy.py`)
- Local search → Surrogate selector: fits surrogate (evidence: `code/strategy/SLS_strategy.py`)
- Crossover search → Surrogate selector: fits surrogate (evidence: `code/strategy/crossover_strategy.py`)
- Trust-region search → Surrogate selector: fits surrogate (evidence: `code/strategy/TRLS_Strategy.py`)
- L-BFGS search → Surrogate selector: fits surrogate (evidence: `code/strategy/LBFGS_Strategy.py`)
- Surrogate selector → RBF with HPO: selects implementation (evidence: `code/RBF.py`)
- Surrogate selector → Simple RBF: selects implementation (evidence: `code/RBF.py`)
- Surrogate selector → Clustered KNN: selects implementation (evidence: `code/RBF.py`)
- Surrogate selector → MLP surrogate: selects implementation (evidence: `code/RBF.py`)
- Surrogate selector → Gaussian process: selects implementation (evidence: `code/RBF.py`)
- Clustered KNN → K-means helper: uses clustering (evidence: `code/KNN_surrogate.py`)
