# vanthienphan2004/physics-informed-neural-networks-for-collective-cancer-invasion architecture

> Architecture diagram of the GitHub repository vanthienphan2004/physics-informed-neural-networks-for-collective-cancer-invasion, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vanthienphan2004/physics-informed-neural-networks-for-collective-cancer-invasion
- Repository: https://github.com/vanthienphan2004/physics-informed-neural-networks-for-collective-cancer-invasion

## Overview

##### Project Type and Purpose
- This is a research‐oriented Python application implementing physics‐informed neural networks (PINNs) and Fourier neural operators (FNOs) to solve coupled reaction‐diffusion PDEs modeling collective cancer invasion.
- It is not a web or distributed microservice but a sequential simulation pipeline: configuration → data generation → model construction → training (with PDE constraints) → results storage → visualization.

##### File Structure Highlights
- Entry point: **main.py**
- Orchestrator: **controller.py** (implements Singleton SimulationController)
- Configuration: **config.json**, loaded at startup
- Scripts directory (**scripts/**):
- data_loader.py (synthetic data + IC/BC enforcement)
- models.py (PINN & FNO architectures)
- trainer.py (physics‐informed loss, PDE residuals, optimization)
- visualization.py (plotting, saving snapshots)
- utils.py (device detection, common helpers)
- Output directories: **results/** (weights, predictions, summaries), **plots/** (visualizations)

##### Core Components
a. Configuration Manager
- Loads **config.json**; exposes parameters (model type, PDE constants, training hyperparameters).
b. SimulationController (Singleton)
- Central orchestrator; instantiated by **main.py**
- Sequence: load config → initialize data pipeline → initialize model → initialize trainer → run training → invoke visualization → save outputs
c. Data Pipeline
- **data_loader.py** generates initial/boundary condition data, prepares PyTorch tensors
d. Model Architectures
- **models.py** defines two types: PINN and FNO classes (e.g., CoupledSpeciesTFNO)
e. Training Engine
- **trainer.py** computes physics‐informed losses, backpropagation, optimizer steps, monitors metrics
f. Results Storage
- File system writes: model_weights.pth, predictions.{npz,csv}, results_summary.json
g. Visualization Module
- **visualization.py** reads predictions → generates plots → writes to **plots/**

##### Relationships and Data Flow
- main.py → SimulationController
- SimulationController
↓ loads
Configuration Manager
↓ passes parameters to
┌───────────────┬───────────────┐
│ Data Pipeline │ Model Factory │
└──────┬────────┴──────┬────────┘
↓               ↓
Training Engine ←───┘
↓
Results Storage
↓
Visualization Module
↓
plots/

##### Architectural Patterns and Principles
- Singleton Pattern: SimulationController ensures single orchestrator instance
- Modular Design: separation of data, model, trainer, visualization
- Configuration-Driven: all parameters in JSON, injected at runtime
- Pipeline Pattern: sequential processing stages
- Type Safety & Exception Handling: clear module boundaries

##### Technologies and Frameworks
- Python 3.12+
- PyTorch 2.9+ (with optional CUDA)
- NumPy for data arrays
- Matplotlib / seaborn for plotting
- JSON for configuration and results summaries

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry Point and Orchestrator
    Main["main.py<br/>Entry Point"]:::orchestration
    Controller["SimulationController<br/>(Singleton)"]:::orchestration
    Config["Configuration Manager"]:::orchestration

    %% Modules
    Data["Data Pipeline"]:::data
    Model["Model Architectures"]:::compute
    Trainer["Training Engine"]:::compute

    %% Storage and Visualization
    Storage[(Results Storage)]:::data
    Visualization["Visualization Module"]:::output
    Plots[(plots/ Directory)]:::output

    %% Flow
    Main -->|"instantiates"| Controller
    Controller -->|"loads parameters"| Config
    Controller -->|"passes config parameters"| Data
    Controller -->|"passes config parameters"| Model
    Data -->|"prepared tensors"| Trainer
    Model -->|"architecture instance"| Trainer
    Trainer -->|"model_weights.pth, predictions, summaries"| Storage
    Storage -->|"results data"| Visualization
    Visualization -->|"plots files"| Plots

    %% Click Events
    click Config "https://github.com/vanthienphan2004/physics-informed-neural-networks-for-collective-cancer-invasion/blob/master/config.json"
    click Main "https://github.com/vanthienphan2004/physics-informed-neural-networks-for-collective-cancer-invasion/blob/master/main.py"
    click Controller "https://github.com/vanthienphan2004/physics-informed-neural-networks-for-collective-cancer-invasion/blob/master/controller.py"
    click Data "https://github.com/vanthienphan2004/physics-informed-neural-networks-for-collective-cancer-invasion/blob/master/scripts/data_loader.py"
    click Model "https://github.com/vanthienphan2004/physics-informed-neural-networks-for-collective-cancer-invasion/blob/master/scripts/models.py"
    click Trainer "https://github.com/vanthienphan2004/physics-informed-neural-networks-for-collective-cancer-invasion/blob/master/scripts/trainer.py"
    click Visualization "https://github.com/vanthienphan2004/physics-informed-neural-networks-for-collective-cancer-invasion/blob/master/scripts/visualization.py"
    click Plots "https://github.com/vanthienphan2004/physics-informed-neural-networks-for-collective-cancer-invasion/tree/master/plots/"

    %% Styles
    classDef orchestration fill:#D0E6FF,stroke:#333,stroke-width:1px;
    classDef data fill:#DFFFD0,stroke:#333,stroke-width:1px;
    classDef compute fill:#FFE0B3,stroke:#333,stroke-width:1px;
    classDef output fill:#F3D1FF,stroke:#333,stroke-width:1px;
```
