PurkinjeUV: Python Package for Cardiac Simulation

Situation

This package repackages the Purkinje-network growth algorithm from Sahli Costabal et al. [2] as an installable Python library. The method was central to an M.Sc. thesis at PUC Chile on probabilistic reconstruction of the Purkinje network from ECG signals [1]: the research produced working geometry code that needed to be tested, shared, and reproducible beyond a single lab environment.

1. [1]Felipe Álvarez-Barrientos, Mariana Salinas-Camus, Simone Pezzuto, and Francisco Sahli Costabal. Probabilistic learning of the Purkinje network from the electrocardiogram. arXiv:2312.09887, 2023.
2. [2]Francisco Sahli Costabal, Daniel E. Hurtado, and Ellen Kuhl. Generating Purkinje networks in the human heart. Journal of Biomechanics, 49(12):2455–2465, 2016.

Task

Take a published computational method for generating Purkinje networks and turn it into something any researcher can install in one command, run on their own mesh, and cite: a proper Python package with documentation, worked examples, and an automated release pipeline.

Action

• Built around one idea: grow the tree in a flattened 2D UV chart, then map it back to 3D.
• Mesh.uvmap solves two Laplace problems and carries a per-triangle arc-length metric $\frac{1}{2}\mathrm{trace}({\mathbf{F}}^{\top }\mathbf{F})$ so 2D steps stay correct on the curved surface.
• FractalTree.grow_tree runs the fractal growth (trunk → fascicles → ±angle bifurcation → repulsion-gradient growth → collision termination).
• PurkinjeTree.activate_fim adds an opt-in eikonal activation solve at a fixed conduction velocity.
• Reads OBJ/VTU, emits VTU/VTP line meshes via meshio and VTK.

How it works

Click to zoom

Result

Published to PyPI as purkinje-uv. The committed end-to-end artifact grows a 3,094-node / 3,093-segment fractal Purkinje network on the ellipsoid demo mesh and runs it through the eikonal activation solve. The package ships with worked examples and a Google Colab notebook, so the method is reproducible without a local install.

Learning

The hard part was never a model: it was the parameterization. Growing the tree directly in 3D is a misery of projection and collision tests; flattening the surface into a Laplacian UV chart and carrying a per-triangle arc-length metric turns it into tractable 2D geometry you map back at the end.