A Physics-Informed Eikonal Model for Simulating Arrhythmias in the Human Heart in Real-Time

PIE-Model-Experiments

This repository provides a guide and the necessary resources for reproducing the experimental results of the publication: "A Physics-Informed Eikonal Model for Simulating Arrhythmias in the Human Heart in Real-Time". The provided .zip files contain the compressed data from the setups, scripts, calibration and results directories from the public GitHub repository PIE-Model-Experiments, including the setup data for the whole-heart experiment, computed results and rendered videos of each experiment.

Description

 The setups directory contains the six experimental setups from the study:

• A_restitution: the left-hand face of a strip of healthy tissue is paced with a dynamic pacing protocol to investigate APD and CV restitution properties.
• B_curvature: concave and convex wave fronts are induced in healthy tissue to investigate curvature properties.
• C_diffusion: an interface between healthy and borderzone tissue types is paced at the bottom face to investigate diffusion properties.
• D_anatomical: an anatomically induced reentry is simulated by pacing below an isthmus-shaped scar using a S1-S2 protocol.
• E_functional: a functional reentry is induced by stimulating a patch of tissue that overlaps with the waveback of a preceding planar wave front.
• F_wholeheart: a ventricular tachycardia is simulated in an anatomically detailed human whole heart model that incorporates a structurally accurate infarct scar.

Each setup consists of mesh files and one or multiple simulation plans in .json format. Meshes are stored in binary CARP (.bpts, .belem, .blon) and Visual Toolkit (.vtk) formats which can be visualized in either NumeriCor Studio or ParaView. The human whole-heart experiment was carried over from [1] and additionally contains the lead-field data required for ECG reconstruction. 

Note: The meshes for each setup, except the F_wholeheart, are generated at runtime if not present. 

The calibration directory contains files with captured physiological properties that were aquired through ForCEPSS [2] and are referenced by each simulation plan. These consist of ionic model state vectors, action potential (AP) shapes, action pontential duration (APD) and conduction velocity (CV) restitution curves.

The scripts directory contains a collection of python scripts to generate, process or visualize the experimental data:

• meshgen.py: performs automatic mesh generation for an experiment in case of absence.
• visualize_calibration.py: visualizes the calibration results.
• generate_lf.py: generation of lead-field data using GIZMO.
• dat2bdat.py: converts lead-field data from text to binary format.
• apply_tstart_offset.py: corrects the timing offset of LAT files due to prepacing.
• error_density.py: plots LAT, CV and LRT error density maps for a given setup.
• track_phase_singularity.py: performs phase singularity tracking and visualization.
• phase_singularity_error.py: computes quantiative phase singularity error metrics.
• frequency_maps.py: computes and plots dominant frequency maps from nodal PSDs.
• phasefield_correlation.py: computes phasemaps and phase correlation coefficients over time.
• plot_outliers.py: visualization of LAT, CV and LRT outliers.
• ecg_comparison.py: visualization of computed ECGs (legacy version).
• ecg_comparison_v2.py: visualization of computed ECGs (current version).
• ecg_quantitative.py: computes quantitative ECG metrics, including PCC, DTW and R-R intervals.
• performance_scaling.py: conducts the performance scaling experiment using the E_functional benchmark.
• performance_eval.py: conducts a performance evaluation of PIE simulations.

The results directory contains the computed experimental data, including simulation data sim and computed ECGs ecg.

Note: The transmembrane voltage maps of the F_wholeheart experiment amount to a size of 600GB in total and could thus not be uploaded to this repository.

The eval.sh bash file automatically runs all operations for reproducing the experimental data.

The clean.sh bash file cleans generated data within this repository.

Setup

The evaluation relies on the openCARP simulation framework which also includes mesher and MeshTool that are required for mesh generation. Two options are presented to meet the dependencies for reproducing the experimental results:

Docker Setup

All neccessary prequesites for reproducing the experimental data are available within the openCARP. A Dockerfile is provided within this repository to build an image with all dependencies:

docker build -t pie-img .
docker run --rm -it --shm-size=512m pie-img
cd PIE-Model-Experiments

Note: shared memory was increased to run openCARP within the container.

Manual Setup

A python3 environment is required to reproduce the experimental data of the PIE model. For example, use Miniconda3 to create a suitable environment on your machine:

conda create --name pie-env --file requirements.txt
conda activate pie-env

To install the openCARP simulation framework please refer to the official Documentation as instructions are diverse between operating systems. Finally, clone the repository using the following command:

git clone https://github.com/medunigraz/PIE-Model-Experiments.git
cd PIE-Model-Experiments

Optional: Zenodo

The mesh files of the human whole-heart model are exclusively available on this Zenodo repository. Download the zipped setups.zip file into the PIE-Model-Experiments repository and run the following commands to add the whole-heart model files:

apt-get update
apt-get install unzip
cd PIE-Model-Experiments
unzip setups.zip

Note: the experimental results were computed using the PIE-Solver executable version 1.0. The executable itself cannot be publicly disclosed because it relies on proprietary libraries. However, binary executables compiled for the major platforms (Linux, macOS or Windows) can be provided upon request by contacting the corresponding authors.

Experimental Results

Running the following command reproduces the experimental results:

./eval.sh -np=32

where the option -np=<int> allows to specify the number of threads used for computation. Reproducing all results, except the whole-heart model reference, took roughly 20 minutes on the test system. 

Computing the reference RD simulation for the human whole-heart experiment requires multiple hours, even with substantial computational resources. Our results were computed within 17 hours on the Austrian Scientific Cluster. The PIE simulation of the whole-heart experiment was computed within 4 minutes on the test system.

Run the following command to clean the repository:

./clean.sh

Test System Information

Testing was conducted on an Ubuntu 22.04 LTS system equipped with 32 cores of AMD Threadripper PRO 5975WX CPU and 128GB of system memory.

References

[1] Gillette, K., Gsell, M.A.F., Prassl, A., Karabelas, E., Reiter, U., Reiter, G., Grandits, T., Stern, D., Urschler, M., Bayer, J., Augustin, C.M., Neic, A., Pock, T., Vigmond, E., Plank, G.: A Framework for the Generation of Digital Twins of Cardiac Electrophysiology from Clinical 12-leads ECGs. Med. Imag. Anal. 71, 102080 (2021)

[2] Gsell, M.A.F., Neic, A., Bishop, M.J., Gillette, K., Prassl, A.J., Augustin, C.M., Vigmond, E.J., Plank, G.: ForCEPSS—A framework for cardiac electrophysiology simulations standardization. Comput. Methods Programs Biomed. 251, 108189 (2024)

How to Cite

When using the data provided in this repository, please cite the paper A Physics-Informed Eikonal Model for Simulating Arrhythmias in the Human Heart in Real-Time. 

Licence

This repository is released under the Creative Commons Attribution 4.0 International License (CC BY 4.0).