# wassimtenachi/physo architecture

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

- Interactive diagram: https://gitdiagram.com/wassimtenachi/physo
- Repository: https://github.com/wassimtenachi/physo

## Overview

Based on our analysis of the provided file tree and README, the PhySO project is a Python package for “Physical Symbolic Optimization” – essentially a symbolic regression engine aimed at discovering analytical physical laws from data using deep reinforcement learning and dimensional analysis. In this ecosystem, several key modules and layers interact to facilitate the entire workflow, from configuration, benchmarking, and demos, to core learning and symbolic manipulation.

##### Major System Components

- Core Symbolic Regression Engine:
– This is the heart of the package where the symbolic regression is performed.
– It includes the learning modules (located in physo/learn), the symbolic manipulation routines (in physo/physym), and the task-specific functions (in physo/task) that tie the workflow together (e.g., class_sr.py, sr.py).
– Emphasize the interplay between search (via reinforcement learning) and the evaluation of candidate symbolic expressions.

- Benchmarking and Dataset Modules:
– The benchmarking directory (with ClassBenchmark and FeynmanBenchmark subdirectories) and the contents of physo/benchmark organize datasets, testing routines, and performance evaluation.
– They provide the means to assess the robustness (even against noise) of the symbolic regression output.

- Configuration Layer:
– The physo/config folder holds multiple configuration files (config0, config1, config2, etc.) that define hyperparameters and preset use cases.
– These files tune the behavior of the SR process (speed vs. effectiveness) and control aspects like dimensional analysis options.

- Demo / Example Workflows:
– The demos directory contains Jupyter notebooks (e.g., sr_quick_start.ipynb, class_sr demos) and Python scripts that exemplify how to invoke PhySO’s functionality.
– It helps users understand how to set up synthetic datasets, call the SR function, and interpret/log output.

- Documentation & Testing Infrastructure:
– The docs directory (with Sphinx configuration, markdown, and assets) and separate testing files in physo/*/tests show that documentation and unit tests are integral parts of the project.
– Although not part of the runtime, these components are key when considering system maintenance and reproducibility.

##### Component Relationships & Data Flow

- User/Demo Entry Point:

- Core Engine Interactions:
– The main SR function (e.g., physo.SR) orchestrates calls into the learning module (for neural network training and reinforcement learning), the physics/symbolic manipulation module (for evaluating expressions and free constant optimization), and the task layer (for handling specific regression tasks).

- Configuration Injection:
– Show that across the board the configuration layer (physo/config) feeds hyperparameter settings into the core engine and learning modules.

- Benchmarking & Evaluation:
– The benchmarking component (both from physo/benchmark and the benchmarking folder) is used to run comprehensive evaluations (e.g., on the Feynman benchmark).

- Logging & Visualization:
– Incorporate a component for logging and visualizing training statistics and performance curves (as seen in the README).
– Show data flows from the core engine to “RunLogger” and “RunVisualiser” modules.

##### Architectural Patterns and Design Principles

- Modular Organization:
– The project is organized into clearly separated modules (learning, physics/symbolic math, benchmarking, configuration) that interact through well-defined function calls.

- Layered and Extensible Design:
– Consider the system as having a core engine layer (where the main physics and symbolic regression happens) that is extended and tested by demos, benchmarking, and configuration modules.
– This separation encourages both extensibility (ability to plug in new configurations or benchmarks) and maintainability.

- Integration of External Technologies:
– Identify key external libraries like NumPy, PyTorch, Matplotlib, and Sympy as underlying technologies.
– Optionally incorporate a small “External Dependencies” component that supplies these libraries to the core engine.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Demo / Client Interface
    subgraph "Demo / Client Interface"
        Demo["Demo Workflows"]:::demo
    end

    %% Core Symbolic Regression Engine and its Modules
    subgraph "Core Symbolic Regression Engine"
        CoreEngine["SR Engine (API)"]:::core
        Learning["Learning Module"]:::core
        Physym["Symbolic Manipulation Module"]:::core
        Task["Task-Specific Functions"]:::core
    end

    %% Configuration Layer
    subgraph "Configuration Layer"
        Config["Configuration Files"]:::config
    end

    %% Benchmarking and Dataset Modules
    subgraph "Benchmarking & Dataset Modules"
        BenchDir["Benchmarking Directory"]:::benchmark
        InPackageBench["In-Package Benchmarking"]:::benchmark
    end

    %% Logging & Visualization
    subgraph "Logging & Visualization"
        Logger["RunLogger/Visualiser"]:::logvis
    end

    %% Documentation & Testing Infrastructure
    subgraph "Documentation & Testing"
        Docs["Documentation"]:::docs
        Tests["Unit Tests"]:::docs
    end

    %% External Dependencies
    subgraph "External Dependencies"
        Ext["External Libraries"]:::external
    end

    %% Connections
    %% Demo calls the Core Engine
    Demo -->|"calls"| CoreEngine

    %% Configuration injection to Core Engine
    Config -->|"injects"| CoreEngine

    %% Core Engine invoking its modules
    CoreEngine -->|"triggers"| Learning
    CoreEngine -->|"triggers"| Physym
    CoreEngine -->|"triggers"| Task

    %% Inter-module collaboration (bidirectional interactions)
    Learning <-->|"collaborates"| Physym
    Learning <-->|"collaborates"| Task
    Physym <-->|"collaborates"| Task

    %% Core Engine communicates with Benchmarking modules
    CoreEngine -->|"evaluated by"| BenchDir
    CoreEngine -->|"evaluated by"| InPackageBench
    BenchDir -->|"feeds results"| CoreEngine
    InPackageBench -->|"feeds results"| CoreEngine

    %% Core Engine outputs to Logger/Visualiser
    CoreEngine -->|"logs/output"| Logger

    %% External libraries support the Core Engine
    Ext -->|"provides tech to"| CoreEngine

    %% Documentation & Testing are separate support layers
    Docs -->|"documents"| CoreEngine
    Tests -->|"validates"| CoreEngine

    %% Click Events
    click Demo "https://github.com/wassimtenachi/physo/tree/main/demos"
    click Learning "https://github.com/wassimtenachi/physo/tree/main/physo/learn"
    click Physym "https://github.com/wassimtenachi/physo/tree/main/physo/physym"
    click Task "https://github.com/wassimtenachi/physo/blob/main/physo/task/class_sr.py"
    click BenchDir "https://github.com/wassimtenachi/physo/tree/main/benchmarking"
    click InPackageBench "https://github.com/wassimtenachi/physo/tree/main/physo/benchmark"
    click Config "https://github.com/wassimtenachi/physo/tree/main/physo/config"
    click Docs "https://github.com/wassimtenachi/physo/tree/main/docs"
    click Tests "https://github.com/wassimtenachi/physo/tree/main/physo/learn/tests"

    %% Styles
    classDef core fill:#FAD7A0,stroke:#C0392B,stroke-width:2px;
    classDef config fill:#D6EAF8,stroke:#2874A6,stroke-width:2px;
    classDef demo fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef benchmark fill:#FADBD8,stroke:#CB4335,stroke-width:2px;
    classDef logvis fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef docs fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
    classDef external fill:#D6DBDF,stroke:#566573,stroke-width:2px;
```
