# hugodovs/gl2o architecture

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

- Interactive diagram: https://gitdiagram.com/hugodovs/gl2o
- Repository: https://github.com/hugodovs/gl2o

## Overview

1. **What this repository is**
   - GL2O is a Python library for “learning to optimize”: it runs optimization algorithms, trains meta-optimizers over those runs, and then evaluates and visualizes the results.
   - The codebase is organized around an experiment pipeline rather than a single application.

2. **Top-level orchestration**
   - The main control flow lives under `mlo/application/`.
   - These modules split the experiment lifecycle into distinct phases: building an experiment, preprocessing for meta-optimization, preprocessing for optimization, and postprocessing/analysis.
   - `main.py` is the likely entry point that wires a chosen YAML config into this pipeline.

3. **Configuration-driven experiments**
   - `cfg/exp1/` contains the concrete experiment definitions.
   - The `train`, `pre_opt`, and `post_opt` folders indicate a staged workflow: train/meta-learn first, then run optimization, then generate outputs such as plots.
   - This configuration layer is the main boundary between experiment setup and algorithm code.

4. **Experiment assembly and shared state**
   - `mlo/application/builder.py` and `mlo/application/experiment.py` appear to assemble the components for a run and hold the experiment-level coordination logic.
   - `mlo/components/infoset.py` likely acts as a shared data container for metrics, observations, or run-state passed between stages.

5. **Task model and benchmark domain**
   - Optimization problems are represented in `mlo/components/tasks/`.
   - `task.py` defines the task abstraction, while `bbob.py` ties the project to the BBOB benchmark family.
   - `mlo/components/task_distributions/` adds a layer for sampling or managing collections of tasks, so experiments can train/evaluate over distributions rather than a single objective.

6. **Optimization algorithms**
   - `mlo/components/optimizers/` contains the concrete optimizers being compared or learned over.
   - The set includes CMA-ES variants, DE, PSO, random search, one-plus-one, and specialized methods like LIOH and SHIWA.
   - `optimizer.py` is the common interface boundary that the rest of the system uses, which lets the application treat all optimizers uniformly.

7. **Meta-optimization layer**
   - `mlo/components/metaoptimizers/` contains the learning-to-optimize machinery.
   - The `deepga_table/` subtree is the main meta-optimizer implementation, organized into population members, selection, mutation, slicing, and core algorithm logic.
   - `mpi_extensions.py` suggests distributed or parallel execution support for scaling meta-optimization runs.

8. **Factory-based dependency creation**
   - `mlo/factories/` is the indirection layer that maps config names to concrete tasks, optimizers, meta-optimizers, and visualizers.
   - This keeps the application layer from importing algorithm classes directly and makes the system extensible via configuration.

9. **Postprocessing and visualization**
   - `mlo/components/visualizers/` contains the output-generation layer.
   - `ecdf.py` and `heatmap.py` indicate the main analysis products: benchmark-performance curves and performance landscapes.
   - `postprocessing_optimization.py` likely turns raw experiment outputs into these visual artifacts.

10. **Utility and experiment support**
   - `mlo/utils/generator.py` provides helper generation logic, likely for tasks, samples, or parameter sets.
   - `logexample.py` and `plot_metaloss.py` are standalone analysis/demo scripts rather than core runtime components.
   - The `data/` directory is just a workspace placeholder, implying the repo expects experiment artifacts or datasets to be generated locally.

11. **Architecture in one sentence**
   - The system flows from YAML experiment definitions into factory-built tasks and optimizers, runs them through a staged application pipeline, optionally meta-trains an optimizer with distributed support, and finally emits benchmark visualizations and summaries.

Main entry points: [`mlo/application/builder.py`](https://github.com/hugodovs/gl2o/blob/main/mlo/application/builder.py) (Builder), [`mlo/application/experiment.py`](https://github.com/hugodovs/gl2o/blob/main/mlo/application/experiment.py) (Experiment), [`mlo/components/optimizers/optimizer.py`](https://github.com/hugodovs/gl2o/blob/main/mlo/components/optimizers/optimizer.py) (Optimizer), [`mlo/application/preprocessing_optimization.py`](https://github.com/hugodovs/gl2o/blob/main/mlo/application/preprocessing_optimization.py) (Opt prep)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cfg["Config"]
  node_cfg_train["Train cfg<br/>yaml config"]
  node_cfg_preopt["Opt cfgs<br/>yaml config"]
  node_cfg_postopt["Post cfgs<br/>yaml config"]
end

subgraph group_app["Application"]
  node_builder["Builder<br/>orchestrator<br/>[builder.py]"]
  node_experiment["Experiment<br/>run state<br/>[experiment.py]"]
  node_pre_meta["Meta prep<br/>stage"]
  node_pre_opt["Opt prep<br/>stage"]
  node_post_opt["Postprocess<br/>stage"]
end

subgraph group_components["Components"]
  node_infoset[("Info set<br/>shared state<br/>[infoset.py]")]
  node_task["Task<br/>problem api<br/>[task.py]"]
  node_bbob_task["BBOB task<br/>benchmark task<br/>[bbob.py]"]
  node_task_dist["Task dist"]
  node_optimizer["Optimizer<br/>[optimizer.py]"]
  node_cmaes["CMA-ES<br/>optimizer<br/>[cmaes.py]"]
  node_de["DE<br/>optimizer<br/>[de.py]"]
  node_pso["PSO<br/>optimizer<br/>[pso.py]"]
  node_deepga["DeepGA<br/>meta-optimizer<br/>[deepga.py]"]
  node_member_ops["GA ops<br/>evolution ops<br/>[member.py]"]
  node_visualizer["Visualizer<br/>output api<br/>[visualizer.py]"]
  node_ecdf["ECDF<br/>visualizer<br/>[ecdf.py]"]
  node_heatmap["Heatmap<br/>visualizer<br/>[heatmap.py]"]
end

subgraph group_factories["Factories"]
  node_opt_factory["Opt factory<br/>[optimizer.py]"]
  node_meta_factory["Meta factory<br/>[meta_optimizer.py]"]
  node_viz_factory["Viz factory<br/>[visualizer.py]"]
end

node_main["Main<br/>entrypoint<br/>[main.py]"]

node_main -->|"loads"| node_cfg_train
node_main -->|"starts"| node_builder
node_builder -->|"creates"| node_experiment
node_builder -->|"binds"| node_opt_factory
node_builder -->|"binds"| node_meta_factory
node_builder -->|"binds"| node_viz_factory
node_experiment -->|"phase"| node_pre_meta
node_experiment -->|"phase"| node_pre_opt
node_experiment -->|"phase"| node_post_opt
node_pre_meta -->|"writes"| node_infoset
node_pre_opt -->|"uses"| node_task_dist
node_pre_opt -->|"runs"| node_optimizer
node_task_dist -->|"provides"| node_task
node_task -->|"implements"| node_bbob_task
node_optimizer -->|"concrete"| node_cmaes
node_optimizer -->|"concrete"| node_de
node_optimizer -->|"concrete"| node_pso
node_meta_factory -->|"creates"| node_deepga
node_deepga -->|"uses"| node_member_ops
node_post_opt -->|"uses"| node_visualizer
node_visualizer -->|"concrete"| node_ecdf
node_visualizer -->|"concrete"| node_heatmap
node_cfg_train -.->|"configures"| node_builder
node_cfg_preopt -.->|"configures"| node_pre_opt
node_cfg_postopt -.->|"configures"| node_post_opt
node_infoset -.->|"feeds"| node_deepga

click node_main "https://github.com/hugodovs/gl2o/blob/main/main.py"
click node_cfg_train "https://github.com/hugodovs/gl2o/blob/main/cfg/exp1/train/LIOH_2D_20I_5R.yaml"
click node_cfg_preopt "https://github.com/hugodovs/gl2o/blob/main/cfg/exp1/pre_opt/CMAES_2D_20I_5R.yaml"
click node_cfg_postopt "https://github.com/hugodovs/gl2o/blob/main/cfg/exp1/post_opt/ECDF_2D_20I_5R.yaml"
click node_builder "https://github.com/hugodovs/gl2o/blob/main/mlo/application/builder.py"
click node_experiment "https://github.com/hugodovs/gl2o/blob/main/mlo/application/experiment.py"
click node_pre_meta "https://github.com/hugodovs/gl2o/blob/main/mlo/application/preprocessing_metaoptimization.py"
click node_pre_opt "https://github.com/hugodovs/gl2o/blob/main/mlo/application/preprocessing_optimization.py"
click node_post_opt "https://github.com/hugodovs/gl2o/blob/main/mlo/application/postprocessing_optimization.py"
click node_infoset "https://github.com/hugodovs/gl2o/blob/main/mlo/components/infoset.py"
click node_task "https://github.com/hugodovs/gl2o/blob/main/mlo/components/tasks/task.py"
click node_bbob_task "https://github.com/hugodovs/gl2o/blob/main/mlo/components/tasks/bbob.py"
click node_task_dist "https://github.com/hugodovs/gl2o/blob/main/mlo/components/task_distributions/task_distribution.py"
click node_optimizer "https://github.com/hugodovs/gl2o/blob/main/mlo/components/optimizers/optimizer.py"
click node_cmaes "https://github.com/hugodovs/gl2o/blob/main/mlo/components/optimizers/cmaes.py"
click node_de "https://github.com/hugodovs/gl2o/blob/main/mlo/components/optimizers/de.py"
click node_pso "https://github.com/hugodovs/gl2o/blob/main/mlo/components/optimizers/pso.py"
click node_deepga "https://github.com/hugodovs/gl2o/blob/main/mlo/components/metaoptimizers/deepga_table/deepga.py"
click node_member_ops "https://github.com/hugodovs/gl2o/blob/main/mlo/components/metaoptimizers/deepga_table/member.py"
click node_visualizer "https://github.com/hugodovs/gl2o/blob/main/mlo/components/visualizers/visualizer.py"
click node_ecdf "https://github.com/hugodovs/gl2o/blob/main/mlo/components/visualizers/ecdf.py"
click node_heatmap "https://github.com/hugodovs/gl2o/blob/main/mlo/components/visualizers/heatmap.py"
click node_opt_factory "https://github.com/hugodovs/gl2o/blob/main/mlo/factories/optimizer.py"
click node_meta_factory "https://github.com/hugodovs/gl2o/blob/main/mlo/factories/meta_optimizer.py"
click node_viz_factory "https://github.com/hugodovs/gl2o/blob/main/mlo/factories/visualizer.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_cfg_train,node_cfg_preopt,node_cfg_postopt toneBlue
class node_builder,node_experiment,node_pre_meta,node_pre_opt,node_post_opt toneAmber
class node_infoset,node_task,node_bbob_task,node_task_dist,node_optimizer,node_cmaes,node_de,node_pso,node_deepga,node_member_ops,node_visualizer,node_ecdf,node_heatmap toneMint
class node_opt_factory,node_meta_factory,node_viz_factory toneRose
class node_main toneNeutral
```

## Components

### Config

YAML experiment definitions for staged runs

- [Train cfg](https://github.com/hugodovs/gl2o/blob/main/cfg/exp1/train/LIOH_2D_20I_5R.yaml): yaml config · Training/meta-learning experiment definitions · `cfg/exp1/train/LIOH_2D_20I_5R.yaml`
- [Opt cfgs](https://github.com/hugodovs/gl2o/blob/main/cfg/exp1/pre_opt/CMAES_2D_20I_5R.yaml): yaml config · Pre-optimization run definitions · `cfg/exp1/pre_opt/CMAES_2D_20I_5R.yaml`
- [Post cfgs](https://github.com/hugodovs/gl2o/blob/main/cfg/exp1/post_opt/ECDF_2D_20I_5R.yaml): yaml config · Postprocessing and visualization definitions · `cfg/exp1/post_opt/ECDF_2D_20I_5R.yaml`

### Application

Experiment lifecycle orchestration

- [Builder](https://github.com/hugodovs/gl2o/blob/main/mlo/application/builder.py): orchestrator · Assembles an experiment from config and factories · `mlo/application/builder.py`
- [Experiment](https://github.com/hugodovs/gl2o/blob/main/mlo/application/experiment.py): run state · Coordinates the staged experiment lifecycle · `mlo/application/experiment.py`
- [Meta prep](https://github.com/hugodovs/gl2o/blob/main/mlo/application/preprocessing_metaoptimization.py): stage · Preprocessing for meta-optimization · `mlo/application/preprocessing_metaoptimization.py`
- [Opt prep](https://github.com/hugodovs/gl2o/blob/main/mlo/application/preprocessing_optimization.py): stage · Preprocessing for optimization runs · `mlo/application/preprocessing_optimization.py`
- [Postprocess](https://github.com/hugodovs/gl2o/blob/main/mlo/application/postprocessing_optimization.py): stage · Aggregates results and prepares analysis outputs · `mlo/application/postprocessing_optimization.py`

### Components

Core optimization, meta-optimization, tasks, and output modules

- [Info set](https://github.com/hugodovs/gl2o/blob/main/mlo/components/infoset.py): shared state · Shared run metrics and observations passed between stages · `mlo/components/infoset.py`
- [Task](https://github.com/hugodovs/gl2o/blob/main/mlo/components/tasks/task.py): problem api · Abstract optimization problem interface · `mlo/components/tasks/task.py`
- [BBOB task](https://github.com/hugodovs/gl2o/blob/main/mlo/components/tasks/bbob.py): benchmark task · Concrete benchmark task family · `mlo/components/tasks/bbob.py`
- [Task dist](https://github.com/hugodovs/gl2o/blob/main/mlo/components/task_distributions/task_distribution.py): task distribution · Samples or manages collections of tasks · `mlo/components/task_distributions/task_distribution.py`
- [Optimizer](https://github.com/hugodovs/gl2o/blob/main/mlo/components/optimizers/optimizer.py): optimizer api · Common optimizer interface used by the application · `mlo/components/optimizers/optimizer.py`
- [CMA-ES](https://github.com/hugodovs/gl2o/blob/main/mlo/components/optimizers/cmaes.py): optimizer · Evolution strategy baseline and variants · `mlo/components/optimizers/cmaes.py`
- [DE](https://github.com/hugodovs/gl2o/blob/main/mlo/components/optimizers/de.py): optimizer · Differential evolution baseline · `mlo/components/optimizers/de.py`
- [PSO](https://github.com/hugodovs/gl2o/blob/main/mlo/components/optimizers/pso.py): optimizer · Particle swarm optimizer · `mlo/components/optimizers/pso.py`
- [DeepGA](https://github.com/hugodovs/gl2o/blob/main/mlo/components/metaoptimizers/deepga_table/deepga.py): meta-optimizer · Main learning-to-optimize algorithm · `mlo/components/metaoptimizers/deepga_table/deepga.py`
- [GA ops](https://github.com/hugodovs/gl2o/blob/main/mlo/components/metaoptimizers/deepga_table/member.py): evolution ops · Population member, selection, mutation, and slicing logic · `mlo/components/metaoptimizers/deepga_table/member.py`
- [Visualizer](https://github.com/hugodovs/gl2o/blob/main/mlo/components/visualizers/visualizer.py): output api · Common visualization interface · `mlo/components/visualizers/visualizer.py`
- [ECDF](https://github.com/hugodovs/gl2o/blob/main/mlo/components/visualizers/ecdf.py): visualizer · Performance curve output · `mlo/components/visualizers/ecdf.py`
- [Heatmap](https://github.com/hugodovs/gl2o/blob/main/mlo/components/visualizers/heatmap.py): visualizer · Performance landscape output · `mlo/components/visualizers/heatmap.py`

### Factories

Config-to-implementation binding layer

- [Opt factory](https://github.com/hugodovs/gl2o/blob/main/mlo/factories/optimizer.py): factory · Resolves optimizer names from config · `mlo/factories/optimizer.py`
- [Meta factory](https://github.com/hugodovs/gl2o/blob/main/mlo/factories/meta_optimizer.py): factory · Resolves meta-optimizer implementations · `mlo/factories/meta_optimizer.py`
- [Viz factory](https://github.com/hugodovs/gl2o/blob/main/mlo/factories/visualizer.py): factory · Resolves visualization backends · `mlo/factories/visualizer.py`

### Other components

- [Main](https://github.com/hugodovs/gl2o/blob/main/main.py): entrypoint · CLI entry that loads a config and starts the pipeline · `main.py`

## Connections

- Main → Train cfg: loads · Entry point selects a staged experiment config
- Main → Builder: starts · Bootstraps the experiment assembly
- Builder → Experiment: creates · Builds the run coordinator
- Builder → Opt factory: binds · Maps optimizer names to concrete classes
- Builder → Meta factory: binds · Maps meta-optimizer names to concrete classes
- Builder → Viz factory: binds · Maps analysis names to visualizers
- Experiment → Meta prep: phase · Runs meta-optimization preprocessing
- Experiment → Opt prep: phase · Runs optimization preprocessing
- Experiment → Postprocess: phase · Runs postprocessing and analysis
- Meta prep → Info set: writes · Stores shared state for later stages
- Opt prep → Task dist: uses · Prepares task sampling for optimization
- Opt prep → Optimizer: runs · Executes optimizers through the common API
- Task dist → Task: provides · Supplies tasks to training or evaluation
- Task → BBOB task: implements · BBOB benchmark specialization
- Optimizer → CMA-ES: concrete · One of the main optimizer implementations
- Optimizer → DE: concrete · One of the main optimizer implementations
- Optimizer → PSO: concrete · One of the main optimizer implementations
- Meta factory → DeepGA: creates · Instantiates the learning-to-optimize algorithm
- DeepGA → GA ops: uses · Population dynamics and genetic operators
- Postprocess → Visualizer: uses · Formats outputs via the visualizer API
- Visualizer → ECDF: concrete · Benchmark curve visualization
- Visualizer → Heatmap: concrete · Benchmark surface visualization
- Train cfg → Builder: configures · Training config drives assembly choices
- Opt cfgs → Opt prep: configures · Optimization config selects runtime parameters
- Post cfgs → Postprocess: configures · Postprocessing config selects analysis outputs
- Info set → DeepGA: feeds · Shared state can inform meta-optimization