Myocardial Mesh: Cardiac Simulation Python Library

Situation

The M.Sc. thesis on probabilistic Purkinje-network reconstruction needed a reliable forward simulation: given a Purkinje geometry and a myocardial mesh, produce a 12-lead ECG to compare against measured signals. That pipeline lived in Jupyter notebooks, difficult to share across Python environments and impossible to validate in CI.

Task

Package the notebook simulation as an installable Python library any researcher can import in one line, prove it is identical to the original notebook output, and gate that proof in CI so it can never silently drift.

Action

• Extracted the notebook into a single-entry-point library (MyocardialMesh): load a 3D myocardial mesh, a Purkinje wiring tree, and electrode positions.
• Built an iterative Purkinje-muscle coupling loop: fire the wiring, spread the activation wave through the muscle, synthesise the 12-lead ECG, check convergence, repeat.
• Delegated the wave-speed math to an external FIM solver; the library owns orchestration, I/O, coupling, and ECG assembly.
• Committed the original notebook output as ground truth and added a baseline regression test asserting RMSE < 1e-6 across all 12 ECG leads, gated in tox on Python 3.10 & 3.12 with strict typing and coverage above 80%.

How it works

Click to zoom

Result

Published to PyPI as myocardial-mesh. The library became the forward-simulation backbone for the M.Sc. thesis: PurkinjeUV generates the Purkinje network geometry; myocardial-mesh loads that geometry, runs the coupling loop, and reads out the 12-lead ECG, forming the full simulation pipeline the thesis depends on. The parity test pins the library to within RMSE < 1e-6 of the original notebook across all 12 ECG leads.

Learning

Parity-first refactoring: research code becomes trustworthy not by assuming the rewrite is correct, but by pinning the original output as ground truth and asserting bit-level equivalence, which catches the silent numerical drift that domain-specific code hides.