# enthusiasticteslim/separationml architecture

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

- Interactive diagram: https://gitdiagram.com/enthusiasticteslim/separationml
- Repository: https://github.com/enthusiasticteslim/separationml

## Overview

##### Project Type & Purpose
- The project is a research and development prototype focused on integrating physics-based models with RL controllers. It aims to guide control strategies for electrochemical separation processes.
- The repository’s README and file tree indicate that it provides modules for simulation (physics), environment modelling (RL), and post-analysis (plotting, notebooks, images, and model outputs).

##### Key Components
a. Core Modules:
- Physics Module: Found under the "OptiDial/physics" directory. It includes files like device.py and utils.py. This module encapsulates the simulation of the physical system (electrochemical separation).
- RL Module: Found under "OptiDial/rl". It has environment.py and associated utilities. This module sets up the RL environment and controller which interact with the physics simulation.
- Configuration & Parameters: The "OptiDial/params.yaml" file contains key configuration parameters for simulations and training. Show this as a configuration source that feeds into other system parts.
- Plotting/Visualization: The "OptiDial/plotter.py" is responsible for visualizing simulation outcomes, performance metrics, and training results.

b. Supportive/Ancillary Components:
- Notebooks: Under the "notebooks" directory are interactive Jupyter notebooks used for training RL controllers and analyzing results. These illustrate the experiment workflow.
- Trained Models: The "models" directory contains directories for different reward scenarios (reward-one, reward-two, reward-three), with different RL algorithms (A2C, PPO, SAC) stored as zip files along with test CSV logs. These represent the outputs/results of the training process.
- Environment Setup Scripts: Files like "env.sh" and "setup.sh" (mentioned in the README) are used to prepare the runtime environment but can be abstracted as part of the deployment initial setup.

##### Relationships and Data Flow
- The Physics Module simulates the electrochemical processes (OptiDial/physics) and communicates with the RL Module (OptiDial/rl) that manages the controller’s learning environment.
- The RL Module interacts bi-directionally with the Physics Module; sensor and state feedback from the physics simulation inform the RL decision-making process while control signals from the RL agent may adjust simulation parameters.
- Outputs from both modules (for example, simulation results and RL training logs) are processed by the Plotting Module (OptiDial/plotter.py) and further analyzed in the Jupyter notebooks.
- The final trained models are persisted in the "models" directory and are subsequently analyzed using test CSVs and images for reward distributions and sensitivity analyses.

##### Architectural Patterns & Technologies
- The project loosely follows a modular pattern where each aspect of the overall system (simulation, control (RL), visualization) is encapsulated in its own component for clarity and separation of concerns.
- Key technologies include Python (with version 3.9 as outlined by the badge), YAML for configuration, Jupyter notebooks for interactive experimentation, and standard Python libraries likely used for RL and simulation tasks.
- The design principles reflect a separation between the physics simulation (knowledge-based computations) and the data-driven RL methods, which is central to the paper’s methodology.

## Diagram (Mermaid)

```mermaid
graph TD
    A["Environment Setup Scripts"]:::setup
    B["Configuration (params.yaml)"]:::config
    C["Physics Simulation (OptiDial/physics)"]:::physics
    D["RL Environment (OptiDial/rl)"]:::rl
    E["Plotting/Visualization (OptiDial/plotter.py)"]:::plot
    F["Trained Models & Outputs (models)"]:::output
    G["Images (images)"]:::output
    H["Notebooks (notebooks)"]:::notebook

    A -->|"initializes"| B
    B -->|"feeds"| C
    B -->|"feeds"| D
    C <-->|"feedback_loop"| D
    C -->|"outputs"| E
    D -->|"outputs"| E
    E -->|"generates"| F
    E -->|"generates"| G
    H -->|"triggers_experiments"| D
    F -->|"analyzed_by"| H

    click A "https://github.com/enthusiasticteslim/separationml/blob/main/env.sh"
    click B "https://github.com/enthusiasticteslim/separationml/blob/main/OptiDial/params.yaml"
    click C "https://github.com/enthusiasticteslim/separationml/tree/main/OptiDial/physics"
    click D "https://github.com/enthusiasticteslim/separationml/tree/main/OptiDial/rl"
    click E "https://github.com/enthusiasticteslim/separationml/blob/main/OptiDial/plotter.py"
    click F "https://github.com/enthusiasticteslim/separationml/tree/main/models"
    click G "https://github.com/enthusiasticteslim/separationml/tree/main/images"
    click H "https://github.com/enthusiasticteslim/separationml/tree/main/notebooks"

    classDef setup fill:#d5f5e3,stroke:#27ae60,stroke-width:2px,color:#333;
    classDef config fill:#a2d9ce,stroke:#34495e,stroke-width:2px,color:#333;
    classDef physics fill:#f9e79f,stroke:#b7950b,stroke-width:2px,color:#333;
    classDef rl fill:#aed6f1,stroke:#2471a3,stroke-width:2px,color:#333;
    classDef plot fill:#d2b4de,stroke:#7d3c98,stroke-width:2px,color:#333;
    classDef output fill:#f5cba7,stroke:#d35400,stroke-width:2px,color:#333;
    classDef notebook fill:#fad7a0,stroke:#e67e22,stroke-width:2px,color:#333;
```
