# cuhk-eda/neural-ilt architecture

> Architecture diagram of the GitHub repository cuhk-eda/neural-ilt, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cuhk-eda/neural-ilt
- Repository: https://github.com/cuhk-eda/neural-ilt

## Overview

##### Project type and purpose
- This is a single‐application, research‐grade, end‐to‐end machine‐learning tool (“Neural‐ILT”) for mask optimization in photolithography. It integrates PyTorch neural networks with a CUDA‐based imaging simulator to jointly optimize masks under a partial coherent imaging model.

##### File structure
- Top‐level scripts:
- neural_ilt.py – main on‐neural‐network ILT correction loop
- pretrain_model.py – backbone pretraining
- eval.py – mask printability evaluation
- run_litho_sim_batch.py – batch calls into lithography simulator
- Data loading:
- dataloader/refine_data_loader.py
- dataloader/train_data_loader.py
- dataset/ispd21_train_dataset.zip
- Core ML code & losses:
- neural_ilt_backbone.py, neural_ilt.py
- ilt_loss_layer.py
- utils/unet_torch.py, utils/train_utils.py, utils/ilt_utils.py, utils/utils.py
- Simulation engine:
- lithosim/
– lithosim_cuda.py (Python/CUDA Bridge)
– lithosim_kernels/ (binary focus/defocus data + .pt tensors)
- Results and stats:
- stat/variation_test_neural_ilt.xlsx

##### README
- Confirms it is a GPU‐accelerated PyTorch project for ILT; highlights two flows—backbone pretraining and iterative mask refinement—and a final evaluation step.
- Dependencies: Python 3.7.3, PyTorch 1.8.0, CUDA 11.x, torchvision, PIL.

##### Main components & interactions
a. User / CLI
- Entry point scripts (neural_ilt.py, pretrain_model.py, eval.py) accept flags and kick off pipelines.
b. Data Layer
- Raw layout/mask data in dataset/ -> fed through dataloader/ modules -> PyTorch DataLoader objects.
c. Preprocessing & Utilities
- utils/ routines for cropping, margin, EPE checking, complexity calculation.
d. Neural Network Backbone
- UNet‐style or custom nets in neural_ilt_backbone.py + utils/unet_torch.py.
e. Training & Refinement Loop
- For backbone: pretrain_model.py → DataLoader → Model → loss (cycle L2 + complexity) → optimizer → checkpoint.
- For Neural‐ILT: neural_ilt.py → DataLoader → Model output mask → ilt_loss_layer.py (L2 + complexity) + lithosim simulation call → backprop → update mask.
f. Simulation Engine
- lithosim_cuda.py orchestrates calls to precompiled binary kernels and Torch‐tensor kernels in lithosim_kernels/ → returns simulated intensity / gradients.
g. Evaluation
- eval.py calls simulation + EPE checker to report printability score.
h. Persistence & Stats
- Checkpoints & logs written to disk; stat/ holds XLS of variation tests.

##### Architectural patterns & principles
- Modular separation of concerns: Data / Model / Simulation / Loss / Utils / Scripts
- Pipeline pattern: sequential flow from data to final output, with clear hand‐offs.
- GPU‐accelerated compute: heavy compute in CUDA kernels wrapped by Python.
- Extensibility: utils and dataloader modules can be swapped for new datasets or network architectures.

##### Final advice
- Be exhaustive: break the system into as many logical subcomponents as are meaningful.
- Interplay between the neural network routines and the CUDA‐based lithography simulator.
- To show both training (pretrain) and refinement (Neural‐ILT) workflows, plus the evaluation step.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User / CLI layer
    subgraph "User / CLI layer"
        direction TB
        PretrainScript["pretrain_model.py"]:::script
        NeuralILTScript["neural_ilt.py"]:::script
        EvalScript["eval.py"]:::script
        BatchScript["run_litho_sim_batch.py"]:::script
    end

    %% Data & Preprocessing layer
    subgraph "Data Ingestion & Preprocessing layer"
        direction TB
        Dataset["ispd21_train_dataset.zip"]:::data
        TrainLoader["train_data_loader.py"]:::data
        RefineLoader["refine_data_loader.py"]:::data
        Utils["utils/utils.py"]:::util
        TrainUtils["utils/train_utils.py"]:::util
        ILTUtils["utils/ilt_utils.py"]:::util
        EPEChecker["utils/epe_checker.py"]:::util
    end

    %% Model & Training layer
    subgraph "Model & Training layer"
        direction TB
        Backbone["neural_ilt_backbone.py"]:::compute
        UNet["utils/unet_torch.py"]:::compute
        ILTLoss["ilt_loss_layer.py"]:::compute
    end

    %% Simulation Engine layer
    subgraph "Simulation Engine layer"
        direction TB
        LithoSim["lithosim_cuda.py"]:::sim
        LithoKernels["lithosim_kernels/"]:::sim
    end

    %% Evaluation & Output layer
    subgraph "Evaluation & Output layer"
        direction TB
        EvalScript2["eval.py"]:::script
        EPEChecker2["utils/epe_checker.py"]:::util
        Variations["variation_test_neural_ilt.xlsx"]:::data
    end

    %% Connections for Pretrain pipeline
    PretrainScript -->|starts| TrainLoader
    TrainLoader -->|provides batch of crops| Backbone
    Backbone -->|computes features| ILTLoss
    ILTLoss -->|loss value| PretrainScript
    PretrainScript -->|saves checkpoint| Variations

    %% Connections for Refinement pipeline
    NeuralILTScript -->|starts| RefineLoader
    RefineLoader -->|provides batch of crops| Backbone
    Backbone -->|predicts mask| ILTLoss
    ILTLoss -->|loss & gradients| LithoSim
    LithoSim -->|calls kernels| LithoKernels
    LithoSim -->|simulated intensity + gradients| ILTLoss
    ILTLoss -->|updates mask| NeuralILTScript

    %% Batch simulation
    BatchScript -->|batch sim calls| LithoSim

    %% Evaluation pipeline
    EvalScript2 -->|requests sim| LithoSim
    LithoSim -->|intensity| EPEChecker2
    EPEChecker2 -->|printability score| EvalScript2
    EvalScript2 -->|writes report| Variations

    %% Utility usage
    PretrainScript --> Utils
    NeuralILTScript --> Utils
    Backbone --> TrainUtils
    Backbone --> ILTUtils
    EvalScript2 --> EPEChecker2

    %% Click Events
    click PretrainScript "https://github.com/cuhk-eda/neural-ilt/blob/tcad_epe_version/pretrain_model.py"
    click NeuralILTScript "https://github.com/cuhk-eda/neural-ilt/blob/tcad_epe_version/neural_ilt.py"
    click EvalScript "https://github.com/cuhk-eda/neural-ilt/blob/tcad_epe_version/eval.py"
    click BatchScript "https://github.com/cuhk-eda/neural-ilt/blob/tcad_epe_version/lithosim/run_litho_sim_batch.py"
    click Dataset "https://github.com/cuhk-eda/neural-ilt/blob/tcad_epe_version/dataset/ispd21_train_dataset.zip"
    click TrainLoader "https://github.com/cuhk-eda/neural-ilt/blob/tcad_epe_version/dataloader/train_data_loader.py"
    click RefineLoader "https://github.com/cuhk-eda/neural-ilt/blob/tcad_epe_version/dataloader/refine_data_loader.py"
    click Backbone "https://github.com/cuhk-eda/neural-ilt/blob/tcad_epe_version/neural_ilt_backbone.py"
    click UNet "https://github.com/cuhk-eda/neural-ilt/blob/tcad_epe_version/utils/unet_torch.py"
    click ILTLoss "https://github.com/cuhk-eda/neural-ilt/blob/tcad_epe_version/ilt_loss_layer.py"
    click Utils "https://github.com/cuhk-eda/neural-ilt/blob/tcad_epe_version/utils/utils.py"
    click TrainUtils "https://github.com/cuhk-eda/neural-ilt/blob/tcad_epe_version/utils/train_utils.py"
    click ILTUtils "https://github.com/cuhk-eda/neural-ilt/blob/tcad_epe_version/utils/ilt_utils.py"
    click EPEChecker "https://github.com/cuhk-eda/neural-ilt/blob/tcad_epe_version/utils/epe_checker.py"
    click LithoSim "https://github.com/cuhk-eda/neural-ilt/blob/tcad_epe_version/lithosim/lithosim_cuda.py"
    click LithoKernels "https://github.com/cuhk-eda/neural-ilt/tree/tcad_epe_version/lithosim/lithosim_kernels/"
    click EvalScript2 "https://github.com/cuhk-eda/neural-ilt/blob/tcad_epe_version/eval.py"
    click EPEChecker2 "https://github.com/cuhk-eda/neural-ilt/blob/tcad_epe_version/utils/epe_checker.py"
    click Variations "https://github.com/cuhk-eda/neural-ilt/blob/tcad_epe_version/stat/variation_test_neural_ilt.xlsx"

    %% Styles
    classDef data fill:#B3CDE3,stroke:#333,stroke-width:1px
    classDef compute fill:#C7E9C0,stroke:#333,stroke-width:1px
    classDef sim fill:#FDB462,stroke:#333,stroke-width:1px
    classDef util fill:#D9D9D9,stroke:#333,stroke-width:1px
    classDef script fill:#BC80BD,stroke:#333,stroke-width:1px
```
