# jonfanlab/glonet architecture

> Architecture diagram of the GitHub repository jonfanlab/glonet, 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/jonfanlab/glonet
- Repository: https://github.com/jonfanlab/glonet

## Overview

##### Main Components
- Entry Point & Control Flow: The project starts with main.py, which acts as the entry point. It reads parameters (from results/Params.json) and may trigger training or evaluation routines.
- Neural Network Components: There are key modules like net.py (defining the network architecture of the generative model) and metalayers.py (likely containing custom layers or operations specific to the application).
- Training and Evaluation: The script train_and_evaluate.py implies a component responsible for the training loop and performance evaluation.
- Utility Functions: utils.py handles supporting functionalities that are shared among modules.
- Simulation & Solver Integration: The “solvers” directory contains MATLAB scripts (e.g., Eval_Eff_1D.m, GradientFromSolver_1D.m, and their parallel counterparts) and a material properties file (p_Si.mat). These represent a dedicated simulation component accessed via the MATLAB engine in Python.
- Results Management: The results/ directory holds the configuration file (Params.json) and is used to store output data like figures, generated devices (in .mat format), loss curves, model weights, and logs.

##### Relationships and Data Flow
- Parameter Loading: main.py first reads configuration parameters (from results/Params.json).
- Model Building: The parameters determine how the generative model (defined in net.py and supplemented by metalayers.py) is configured.
- Training Loop: The training (possibly orchestrated by main.py or train_and_evaluate.py) involves iteratively generating candidate designs with the network and then evaluating them.
- Simulation Interaction: During training, MATLAB solvers (located in the “solvers” folder) are called via the MATLAB engine. These solvers perform electromagnetic simulations and compute gradients or evaluations required for optimization.
- Data Persistence: Outputs are stored in the results directory structure (including figures, model weights, and logs).

##### Architectural Patterns and Design Principles
- Modular Design: The code is laid out in separate Python modules, each with a clear role (e.g., model architecture, training routines, utilities) to keep functionalities decoupled.
- Pipeline Integration: The design follows a sequential pipeline process – define configuration, build model, compute simulation gradients via external MATLAB scripts, update network parameters, and finally save results.

##### Including Technology Stack and Frameworks
- Python (for the main implementation, training, model building).
- MATLAB engine for Python integration (to run the solvers in MATLAB).
- External dependencies (as listed in requirements.txt).

##### Capturing the Essential Details
- Don’t shy away from showing even the minor points, like the dependency on the MATLAB engine for simulation or the requirement to add the RETICOLO path (as noted in main.py).
- Feedback loop in the training process – generated designs are evaluated via simulation, and the gradients are used to optimize the generative network.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Python Components"
        config["Configuration (results/Params.json)"]
        main["Main Script (main.py)"]
        subgraph "Neural Network Module"
            net["net.py"]
            metalayers["metalayers.py"]
        end
        training["Training & Evaluation (train_and_evaluate.py)"]
        utils["Utility Functions (utils.py)"]
    end

    subgraph "MATLAB Simulation"
        matlab["MATLAB Simulation & Solvers (solvers/)"]
    end

    results["Results & Logging (results/)"]

    config -->|"parameters"| main
    main -->|"initialize_model"| net
    net -->|"apply_custom_layers"| metalayers
    metalayers -->|"generate_candidates"| training
    main -->|"calls_utilities"| utils
    training -->|"calls_utilities"| utils
    training -->|"call_simulation"| matlab
    matlab -->|"simulation_results"| training
    training -->|"save_outputs"| results

    click config "https://github.com/jonfanlab/glonet/blob/master/results/Params.json"
    click main "https://github.com/jonfanlab/glonet/blob/master/main.py"
    click net "https://github.com/jonfanlab/glonet/blob/master/net.py"
    click metalayers "https://github.com/jonfanlab/glonet/blob/master/metalayers.py"
    click training "https://github.com/jonfanlab/glonet/blob/master/train_and_evaluate.py"
    click utils "https://github.com/jonfanlab/glonet/blob/master/utils.py"
    click matlab "https://github.com/jonfanlab/glonet/tree/master/solvers/"
    click results "https://github.com/jonfanlab/glonet/tree/master/results/"

    class config,main,net,metalayers,training,utils python
    class matlab matlab
    class results results

    classDef python fill:#ffcccc,stroke:#660000,stroke-width:2px;
    classDef matlab fill:#ccffcc,stroke:#006600,stroke-width:2px;
    classDef results fill:#ccccff,stroke:#000066,stroke-width:2px;
```
