# rayzhangzirui/pinngbm architecture

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

- Interactive diagram: https://gitdiagram.com/rayzhangzirui/pinngbm
- Repository: https://github.com/rayzhangzirui/pinngbm

## Overview

##### Project type and purpose
- This is a scientific research codebase implementing patient-specific glioblastoma infiltration prediction. It combines:
- Mathematical tumor‐growth models (e.g., script_exact_solver.py, growth.py)
- Physics‐Informed Neural Networks (PINNs) (pinn.py, nn.py, Geonn.py)
- Multimodal scan data ingestion and visualization (DataSet.py, loaddetail.py, loadpred.py, util_visual.py)
- The goal is to train a PINN guided by PDE (losses.py) and analytic solutions to forecast tumor spread for patients P1–P8.

##### File structure
- Top‐level orchestrator:
- main.py — parses options (options.py), reads config.py, kicks off training or inference
- sync.sh — auxiliary script for data syncing
- Data ingestion & preprocessing:
- DataSet.py — dataset abstraction
- loaddetail.py, loadpred.py — loading ground‐truth and prediction targets
- Modeling components:
- script_exact_solver.py — solves the PDE model exactly for baseline comparisons
- growth.py, glioma.py — biological tumor growth modules
- Neural network modules:
- nn.py — network layer definitions
- pinn.py, Geonn.py — PINN wrappers, geometric neural nets
- Training & optimization:
- losses.py — physics‐informed loss (PDE residual, data‐fitting)
- tflbfgs.py — custom L-BFGS optimizer (TensorFlow/PyTorch implied)
- simple.py, weight.py — simple baselines and weight initializers
- utilgpu.py — GPU utilities and device management
- Utilities & visualization:
- util.py — general helpers
- util_visual.py — plotting and saving intermediate results
- peekmat.py — quick matrix or result inspection

##### README for additional insights
- Confirms the dual‐model approach: traditional PDE solver + PINN
- Shows an overview.png with a linear pipeline: Data → Model → Training → Prediction → Visualization
- Notes that data is dragged from Google Drive, and the code reproduces experiments from the 2025 paper.

1. Data Layer
– Source: multimodal MRI scans, patient metadata
– Modules: DataSet.py, loaddetail.py, loadpred.py
2. Preprocessing Layer
– Normalization, mesh generation (if any), data batching
– util.py, utilgpu.py
3. Analytical Solver
– script_exact_solver.py, growth.py, glioma.py
– Produces baseline PDE‐based infiltration maps
4. PINN Model
– Neural net definitions (nn.py)
– Physics constraints (pinn.py, Geonn.py)
5. Loss Computation
– losses.py (PDE residual loss + data fit loss)
6. Optimizer
– tflbfgs.py (L-BFGS), simple optimizers in simple.py
7. Orchestration & Configuration
– main.py, config.py, options.py
8. Output & Visualization
– util_visual.py, peekmat.py, weight.py
– Exports prediction maps, PDFs, logs

– Data Layer → Preprocessing → PINN Model
– Analytical Solver → Loss Computation
– PINN Model → Loss Computation
– Loss Computation → Optimizer → PINN Model (feedback loop)
– Orchestration → all components (drives pipeline)
– Final PINN Model & Analytical Solver → Output & Visualization

c. Architectural patterns & principles
– Modular separation of concerns (data I/O vs. modeling vs. training)
– Config‐driven pipeline (all parameters in config.py + options.py)
– Plugin‐style optimizers and loss functions (easy to swap in/out)
– GPU abstraction layer for hardware portability (utilgpu.py)

d. Key technologies & frameworks
– Python 3.x
– Likely TensorFlow or PyTorch (inferred from tflbfgs.py, GPU utils)
– NumPy/SciPy for PDE solver
– Matplotlib or similar for visualization
– Google Drive for data storage

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Data Layer"
        DS["DataSet.py"]:::data
        LD["loaddetail.py"]:::data
        LP["loadpred.py"]:::data
    end

    subgraph "Preprocessing Layer"
        U["util.py"]:::data
        UG["utilgpu.py"]:::data
    end

    subgraph "Modeling Layer"
        subgraph "Analytical Solver"
            SES["script_exact_solver.py"]:::model
            GROW["growth.py"]:::model
            GLI["glioma.py"]:::model
        end
        subgraph "PINN Model"
            NN["nn.py"]:::model
            PINN["pinn.py"]:::model
            GEO["Geonn.py"]:::model
        end
    end

    subgraph "Training Components"
        subgraph "Loss Computation"
            LOSS["losses.py"]:::train
        end
        subgraph "Optimizer"
            LBFGS["tflbfgs.py"]:::train
            SIMPLE["simple.py"]:::train
        end
    end

    subgraph "Orchestration & Configuration"
        MAIN["main.py"]:::orch
        CFG["config.py"]:::orch
        OPTS["options.py"]:::orch
        SYNC["sync.sh"]:::orch
    end

    subgraph "Output & Visualization"
        UV["util_visual.py"]:::output
        PM["peekmat.py"]:::output
        WT["weight.py"]:::output
    end

    DS -->|"raw scans"| U
    LD -->|"patient metadata"| U
    LP -->|"prediction targets"| U
    U -->|"preprocessed data"| NN

    SES -->|"baseline maps"| LOSS
    NN -->|"PDE residual & data fit"| LOSS

    LOSS -->|"loss values"| LBFGS
    LBFGS -->|"updated weights"| NN

    MAIN --> DS
    MAIN --> SES
    MAIN --> NN
    MAIN --> LOSS
    MAIN --> LBFGS
    MAIN --> UV

    SES -->|"baseline output"| UV
    NN -->|"prediction maps"| UV

    click DS "https://github.com/rayzhangzirui/pinngbm/blob/main/DataSet.py"
    click LD "https://github.com/rayzhangzirui/pinngbm/blob/main/loaddetail.py"
    click LP "https://github.com/rayzhangzirui/pinngbm/blob/main/loadpred.py"
    click U "https://github.com/rayzhangzirui/pinngbm/blob/main/util.py"
    click UG "https://github.com/rayzhangzirui/pinngbm/blob/main/utilgpu.py"
    click SES "https://github.com/rayzhangzirui/pinngbm/blob/main/script_exact_solver.py"
    click GROW "https://github.com/rayzhangzirui/pinngbm/blob/main/growth.py"
    click GLI "https://github.com/rayzhangzirui/pinngbm/blob/main/glioma.py"
    click NN "https://github.com/rayzhangzirui/pinngbm/blob/main/nn.py"
    click PINN "https://github.com/rayzhangzirui/pinngbm/blob/main/pinn.py"
    click GEO "https://github.com/rayzhangzirui/pinngbm/blob/main/Geonn.py"
    click LOSS "https://github.com/rayzhangzirui/pinngbm/blob/main/losses.py"
    click LBFGS "https://github.com/rayzhangzirui/pinngbm/blob/main/tflbfgs.py"
    click SIMPLE "https://github.com/rayzhangzirui/pinngbm/blob/main/simple.py"
    click MAIN "https://github.com/rayzhangzirui/pinngbm/blob/main/main.py"
    click CFG "https://github.com/rayzhangzirui/pinngbm/blob/main/config.py"
    click OPTS "https://github.com/rayzhangzirui/pinngbm/blob/main/options.py"
    click SYNC "https://github.com/rayzhangzirui/pinngbm/blob/main/sync.sh"
    click UV "https://github.com/rayzhangzirui/pinngbm/blob/main/util_visual.py"
    click PM "https://github.com/rayzhangzirui/pinngbm/blob/main/peekmat.py"
    click WT "https://github.com/rayzhangzirui/pinngbm/blob/main/weight.py"

    classDef data fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef model fill:#98FB98,stroke:#000,stroke-width:1px
    classDef train fill:#FFA500,stroke:#000,stroke-width:1px
    classDef orch fill:#DDA0DD,stroke:#000,stroke-width:1px
    classDef output fill:#D3D3D3,stroke:#000,stroke-width:1px
```
