How amir-cardiolab/pcnde works
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.