# bbradz/cloned_analysis architecture

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

- Interactive diagram: https://gitdiagram.com/bbradz/cloned_analysis
- Repository: https://github.com/bbradz/cloned_analysis

## Overview

##### Main Components
- Entry & Orchestration Layer:
– Main scripts such as run.py, run.sh, evaluate.py, default_pi.py that “glue” the system together.
– The instructions file and the README (though minimal here) suggest that users invoke one of these scripts to start experiments.

- Reinforcement Learning / Dyna Gym:
– The dyna_gym directory contains agents (asynchronous_dp.py, mcts.py, oluct.py, uct.py, my_random_agent.py) and utilities (benchmark.py, distribution.py, utils.py).
– This module is likely responsible for simulating environments or decision processes with multiple RL agents.

- Symbolic Regression Core:
– The symbolicregression folder houses modules for defining environments (envs), models (model subdirectory with embedders, sklearn_wrapper, transformer, etc.), trainers, metrics, logging, and optimization.
– It encapsulates the logic for generating and refining symbolic expressions, integrating core algorithms and evaluation metrics.

- Benchmarking & Experimentation (Nesymres):
– The nesymres folder includes configuration files (config.yaml, equation config files), benchmarking scripts (in scripts/benchmark), data creation utilities, as well as a src submodule containing architectures and dataset handling utilities.
– This component appears to set up benchmarks, run batch experiments (with subdirectories using Hydra for configuration management), and collect results (e.g., fitting functions, genetic programming scripts).

- Utility & Infrastructure Modules:
– Standalone utilities like parsers.py, reward.py, timeout.py, and the various config/Makefiles serve as infrastructure pieces.
– They handle cross-cutting concerns such as parsing input data files, managing experiment timeout conditions, and configuring experiment runs.

##### Relationships and Data Flow
- The Entry Layer (scripts run.py, run.sh, evaluate.py) initiates execution.
- Depending on the experiment mode, the system may invoke the symbolic regression module (for modeling, training, and evaluation) or the RL module (dyna_gym) with its various agents for environment interaction.
- The nesymres benchmarking component interacts with both symbolic regression and data creation modules to generate datasets, run experiments, and collect evaluation metrics.
- Configuration and experiment metadata (e.g., Hydra configurations in the “scripts/run” directories) underlie many processes, influencing behavior in the regression/training pipelines.
- Utility modules (e.g., utils, distribution functions, CSV handling) support data transformation across the system.

##### Architectural Patterns and Design Principles
- Modular Design: The project cleanly separates experimental benchmarks (nesymres), reinforcement learning (dyna_gym), and core symbolic regression (symbolicregression).
- Extensibility: The availability of multiple agents in dyna_gym and diverse models in symbolicregression emphasizes a plug-and-play style—each module can be iterated or replaced without affecting the rest of the system.
- Configuration-Driven Execution: Hydra configuration and YAML files for experiments indicate that behavior is highly customizable via external configuration files.

##### Key Technologies & Frameworks
- Python as the primary implementation language.
- Hydra (as indicated by the .hydra directories and config files) for experiment configuration.
- YAML/JSON configurations used for experiment setup and benchmarking.
- Likely use of numerical libraries and machine learning frameworks (inferred by the presence of “sklearn_wrapper.py”, “gaussian_proc.yaml”, etc.) for model building and evaluation.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Entry & Orchestration Layer
    subgraph "Entry & Orchestration Layer"
        E1["run.py"]:::entry
        E2["run.sh"]:::entry
        E3["evaluate.py"]:::entry
        E4["default_pi.py"]:::entry
    end

    %% Reinforcement Learning / Dyna Gym
    subgraph "Reinforcement Learning Module (dyna_gym)"
        RL["dyna_gym (Agents & Utils)"]:::rl
    end

    %% Symbolic Regression Core
    subgraph "Symbolic Regression Core"
        SR["symbolicregression (envs, model, trainer, metrics, logger)"]:::sr
    end

    %% Benchmarking & Experimentation (Nesymres)
    subgraph "Benchmarking & Experimentation (Nesymres)"
        BM["nesymres (Configs, Scripts, Data, src)"]:::bm
    end

    %% Utilities & Infrastructure Modules
    subgraph "Utilities & Infrastructure"
        UT1["parsers.py"]:::util
        UT2["reward.py"]:::util
        UT3["timeout.py"]:::util
        UT4["rl_env.py"]:::util
        UT1 --> UT2
        UT1 --> UT3
        UT1 --> UT4
    end

    %% Connections from Entry Layer (using run.py as the representative entry)
    E1 -->|"initiates"| RL
    E1 -->|"initiates"| SR
    E1 -->|"initiates"| BM

    %% Benchmarking feeds evaluation into Symbolic Regression Core
    BM -->|"feeds_eval"| SR

    %% Modules utilizing utilities (pointing to parsers.py as representative)
    RL -->|"uses"| UT1
    SR -->|"logs_support"| UT1
    BM -->|"utilizes"| UT1

    %% Class definitions for colours
    classDef entry fill:#f9e79f,stroke:#000,stroke-width:1px;
    classDef rl fill:#aed6f1,stroke:#000,stroke-width:1px;
    classDef sr fill:#a9dfbf,stroke:#000,stroke-width:1px;
    classDef bm fill:#f5b7b1,stroke:#000,stroke-width:1px;
    classDef util fill:#d7bde2,stroke:#000,stroke-width:1px;

    %% Click Events
    click E1 "https://github.com/bbradz/cloned_analysis/blob/main/TPSR/run.py"
    click E2 "https://github.com/bbradz/cloned_analysis/blob/main/TPSR/run.sh"
    click E3 "https://github.com/bbradz/cloned_analysis/blob/main/TPSR/evaluate.py"
    click E4 "https://github.com/bbradz/cloned_analysis/blob/main/TPSR/default_pi.py"
    click RL "https://github.com/bbradz/cloned_analysis/tree/main/TPSR/dyna_gym"
    click SR "https://github.com/bbradz/cloned_analysis/tree/main/TPSR/symbolicregression"
    click BM "https://github.com/bbradz/cloned_analysis/tree/main/TPSR/nesymres"
    click UT1 "https://github.com/bbradz/cloned_analysis/blob/main/TPSR/parsers.py"
    click UT2 "https://github.com/bbradz/cloned_analysis/blob/main/TPSR/reward.py"
    click UT3 "https://github.com/bbradz/cloned_analysis/blob/main/TPSR/timeout.py"
    click UT4 "https://github.com/bbradz/cloned_analysis/blob/main/TPSR/rl_env.py"
```
