# amir-cardiolab/pcnde architecture

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

- Interactive diagram: https://gitdiagram.com/amir-cardiolab/pcnde
- Repository: https://github.com/amir-cardiolab/pcnde

## Overview

##### Project Purpose and Type
- This is a research and simulation codebase for physics‐constrained coupled neural differential equations applied to blood flow modeling.
- It implements training (via Julia scripts) and inference (via a Jupyter Notebook) for models that blend physical laws (momentum and continuity equations) with neural networks.
- The code supports both training of different equation components (momentum & continuity and pressure) and subsequent inference with visualization (plots from the paper).

##### File Structure & Key Components
- Training Components:
– PCNDE_train_QS.jl: The main Julia script that carries out training of the momentum and continuity models.
– src/ directory: Contains helper modules such as numerical_derivatives.jl and train_utils.jl used throughout training.
- Inference & Visualization:
– PCNDE_InferenceFitPressure.ipynb: Jupyter Notebook that runs the inference phase for both the PCNDE model and the pressure model, and plots results.
- Data Management:
– data/ directory: Houses datasets in two categories. The 1D FEM data is used for comparison, whereas 3D averaged data is used for training.
- Model Storage:
– trained_weights/ directory: Contains trained weights (stored in .jld2 format) for the models (momentum, continuity, and pressure).

a. Main Components to Represent:
– Data Sources:
- 1D FEM data
- 3D averaged data (organized by cases)
– Preprocessing/ Utility Layer:
- Utility functions for numerical derivatives (src/numerical_derivatives.jl)
- Training helpers (src/train_utils.jl)
– Training Module:
- The training process executed by PCNDE_train_QS.jl – this module takes in the data, uses utility functions, performs training (fitting the physics-based constraints), and produces trained models.
– Model Storage:
- The trained_weights repository where model weights (for momentum, continuity, and pressure) are saved.
– Inference & Visualization Module:
- The Jupyter Notebook (PCNDE_InferenceFitPressure.ipynb) that loads the trained weights, performs inference, and generates figures (plots corresponding to Figs. 4, 5, 6, 7 in the paper).

b. Relationships & Data Flow:
– Data flows from the input datasets (data directory) into the Training Module.
– The Training Module uses the utility functions (from the src/ folder) to perform numerical differentiation and optimize model parameters.
– Trained models (i.e., their weights) are then stored in the trained_weights directory.
– For inference, the PCNDE_InferenceFitPressure Notebook retrieves these weights and processes new or test data (again, from the data directory) to produce predictions and plots.

c. Architectural Patterns & Principles:
– Separation of Concerns: Clearly demarcate training (data ingestion, optimization, weight storage) from inference (loading models, plotting results).
– Modular Design: Utility code in src is abstracted from the main training/inference files.
– Data-Driven Pipeline: Illustrate how raw datasets are transformed by the different processing stages.

d. Relevant Technologies and Formats:
– Julia language is the primary programming language.
– Jupyter Notebook for interactive inference and plotting.
– Use of JLD2 file format for storing model weights.
– Emphasis on numerical methods (e.g., numerical derivatives) integrated with physics-based constraints.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Data Layer"
        DS["Data Sources (1D FEM & 3D Averaged)"]:::data
    end

    subgraph "Utility Layer"
        ND["Numerical Derivatives"]:::processing
        TU["Training Helpers"]:::processing
    end

    subgraph "Application Layer"
        TR["Training Module – PCNDE_train_QS.jl"]:::processing
    end

    subgraph "Storage Layer"
        WS["Trained Weights (.jld2 files in trained_weights)"]:::storage
    end

    subgraph "Inference Layer"
        INF["Inference & Plotting (PCNDE_InferenceFitPressure.ipynb)"]:::inference
    end

    DS -->|"Input Data"| TR
    ND -->|"Numeric_Derivative_Computations"| TR
    TU -->|"Training_Assistance"| TR
    TR -->|"Optimized Weights"| WS
    WS -->|"Weights_Access"| INF
    DS -->|"Test_Data"| INF

    click DS "https://github.com/amir-cardiolab/pcnde/tree/main/data/"
    click ND "https://github.com/amir-cardiolab/pcnde/blob/main/src/numerical_derivatives.jl"
    click TU "https://github.com/amir-cardiolab/pcnde/blob/main/src/train_utils.jl"
    click TR "https://github.com/amir-cardiolab/pcnde/blob/main/PCNDE_train_QS.jl"
    click WS "https://github.com/amir-cardiolab/pcnde/tree/main/trained_weights/"
    click INF "https://github.com/amir-cardiolab/pcnde/blob/main/PCNDE_InferenceFitPressure.ipynb"

    classDef data fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef processing fill:#FFA500,stroke:#000,stroke-width:2px;
    classDef storage fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef inference fill:#DDA0DD,stroke:#000,stroke-width:2px;
```
