m33 · Capstone: from map to digital twin (OpenEP to openCARP)
Education only. Not for diagnosis, treatment or any clinical decision.
Draft, stage 4 of 6. The derivations, two demos and the code lab are written. Each equation is checked by tests in tests/test_m33_twin.py, the demos by tests/test_m33_demos.py, and the lab runs in CI. Questions and the remaining sections follow in later stages (plan: docs/outlines/m33-outline.md). Nothing here has had expert review yet. No openCARP code or binaries are part of this course; the lab links to openCARP and exports files for it.
In 60 seconds
A map shows what was measured. A twin is a model that can be asked “what if?”. To build one, take the map’s geometry, decide which tissue is which, and tune the model until the activation it predicts matches the activation measured at the map’s points. The hard part is honesty. A model that fits the points it was tuned on can still be wrong between them, and different parameter sets can fit equally well. This capstone builds a small twin from a mapping case and tests it that way.
From the field
Planned in the outline (docs/outlines/m33-outline.md); written in a later stage.
Derivations
Symbols used throughout. \(T(\mathbf{x})\) activation time (ms). \(\mathbf{f}\) the unit fibre direction; \(v_f\) and \(v_t\) the conduction velocities along and across fibres (mm/ms). \(D\) the speed tensor. \(\boldsymbol\theta\) the model parameters, here one velocity per region. \(T_i^{\text{meas}}\) the activation time measured at map point \(i\) and \(T_i(\boldsymbol\theta)\) the model’s time there. \(t_0\) an unknown timing offset (ms). \(\sigma\) a monodomain conductivity.
What a twin is
A cardiac digital twin is a model of one patient’s heart whose anatomy and parameters are inferred from that patient’s data so that it reproduces the available observations (Gillette et al. 2021). The idea is presented as a route to diagnosis, prognosis and treatment tailored to each patient, with early steps and open challenges reviewed in (Corral-Acero et al. 2020). Building a twin from clinical data still needs faster, more robust and more accurate ways of fitting anatomy and parameters (Gillette et al. 2021). For an electroanatomic map the observations are activation times and voltages at the acquired points; the anatomy is the map’s mesh.
A fast forward model
Fitting means running the model many times, so it must be fast. The eikonal model from m30 gives activation times directly. Conduction speed in heart tissue depends on direction relative to the fibres (module m09); with a speed tensor the eikonal equation becomes
\[ \sqrt{\nabla T^\top D\, \nabla T} = 1, \qquad D = v_f^2\,\mathbf{f}\mathbf{f}^\top + v_t^2\left(I - \mathbf{f}\mathbf{f}^\top\right) \tag{1}\]
On a flat sheet with uniform fibres the solution from a point is \(T = \sqrt{(\mathbf{x}\cdot\mathbf{f})^2/v_f^2 + (\mathbf{x}\cdot\mathbf{n})^2/v_t^2}\), with \(\mathbf{n}\) perpendicular to \(\mathbf{f}\): isochrones are ellipses with axis ratio \(v_f/v_t\). Eikonal-based models can be very fast: a reaction–eikonal model reproduced the extracellular potentials, electrograms and ECGs of a full bidomain model at a computational cost more than three orders of magnitude lower (Neic et al. 2017). This capstone keeps the surface isotropic (\(v_f = v_t\)) and fits one speed per region.
What does the speed-up cost? The demo below runs both models on the same sheet: a reaction–diffusion (monodomain) model with Mitchell–Schaeffer membrane kinetics (Mitchell and Schaeffer 2003), and the eikonal model with its speeds set to the reaction–diffusion model’s planar conduction velocities. After removing the best constant offset (Equation 2), the two agree within about 1 ms for a planar wave. With point pacing, the reaction–diffusion wave falls 3–4 ms behind the eikonal one, and most of that lag builds up within 3 mm of the stimulus. Behind a narrow isthmus in a line of block, reaction–diffusion activates about 2.7 ms later than the eikonal model predicts. A twin fitted with the eikonal model absorbs such differences into its fitted speeds and offset; that is one reason fitted speeds are model-specific numbers.
Simulation
Assumptions
- Reaction–diffusion: Mitchell–Schaeffer monodomain model (Mitchell and Schaeffer 2003) on a 30 × 30 mm sheet, 0.2-mm grid, explicit time steps of 0.005 ms. The membrane constants are illustrative; the conductivities were tuned with Equation 3 so that the planar velocity is 1.0 m/s in normal tissue and 0.6 m/s in the slow region, values reported for normal-voltage and low-voltage left atrium (Heil et al. 2023). The line of block is an insulating scar. Activation is the first upward crossing of half the model’s dimensionless voltage.
- Eikonal: the m30 solver on the same grid with those two velocities; the stimulated nodes are its sources.
- Precomputed by
tools/make_m33_d2.py(about a minute) and shown at every second node (0.4 mm), with times rounded to 0.1 ms. A test checks that the data come from the current generator and that the numbers quoted above hold. - Results depend on the membrane model and its parameters, and would change in 3D tissue, with anisotropy or with a different stimulus.
Key takeaways
- Twins are fitted by running a forward model many times; eikonal models make that affordable.
- Anisotropy enters through the speed tensor \(D\).
- The eikonal model misses delays that reaction–diffusion shows near a point stimulus and behind an isthmus; fitted parameters partly compensate.
Fitting the model to the map
The map’s activation times are measured against a reference signal, not against the moment the pacing stimulus or the wave started. So model and data differ by an unknown constant offset \(t_0\). Fit it together with the parameters by least squares:
\[ J(\boldsymbol\theta, t_0) = \sum_i \left(T_i(\boldsymbol\theta) + t_0 - T_i^{\text{meas}}\right)^2, \qquad t_0^\ast = \frac{1}{N}\sum_i \left(T_i^{\text{meas}} - T_i(\boldsymbol\theta)\right) \tag{2}\]
For any \(\boldsymbol\theta\) the best offset is the mean difference, which follows from \(\partial J/\partial t_0 = 0\). Solving it in closed form leaves the optimizer only the velocities. On a test sheet with a fast and a slow half, fitting two speeds to 60 noisy activation times with an unknown offset recovers both speeds to within a few percent.
Key takeaways
- Activation times carry an unknown reference offset; solve it in closed form.
- Fit few parameters: one speed per region the data can actually inform.
From speed to conductivity
The eikonal twin gives velocities; a reaction–diffusion simulator such as openCARP needs conductivities (Plank et al. 2021). In the monodomain equation, multiplying the conductivity by \(k\) and stretching all lengths by \(\sqrt{k}\) leaves the equation unchanged, so the conduction velocity scales as \(\sqrt{k}\):
\[ v \propto \sqrt{\sigma} \quad\Rightarrow\quad \sigma_{\text{new}} = \sigma_{\text{old}} \left(\frac{v_{\text{target}}}{v_{\text{sim}}}\right)^2 \tag{3}\]
for a fixed membrane model and surface-to-volume ratio. A test checks it on a cable: four times the conductivity gives twice the speed, and one correction step reaches a target speed. On a discrete mesh the relation is approximate, which is why parameterization tools iterate until the simulated velocity matches the prescribed one (Costa et al. 2013).
Key takeaways
- Speed scales with the square root of conductivity; correct conductivity by the squared speed ratio.
- Iterate on real meshes: discretization bends the rule.
Is the twin any good?
Error on the points used for fitting says little. Split the points into \(K\) folds, fit the twin without fold \(k\), and predict fold \(k\):
\[ E_{\text{CV}} = \sqrt{\frac{1}{N}\sum_{k=1}^{K}\sum_{i \in \mathcal{F}_k} \left(T_i(\hat{\boldsymbol\theta}_{-k}) + t_0^\ast - T_i^{\text{meas}}\right)^2} \tag{4}\]
where \(\hat{\boldsymbol\theta}_{-k}\) is fitted without fold \(\mathcal{F}_k\). With an exact model and no noise, \(E_{\text{CV}}\) is close to zero. A model with too many parameters fits its training points better and predicts held-out points worse; the tests show this with polynomials. For twins, also refit from many starting points: if quite different parameter sets give the same error, the data do not identify those parameters.
The demo fits twins with 1 to 16 regions to activation times from a sheet with a hidden slow region. More regions always fit the measured points at least as well; the held-out error tells you when the extra regions have started fitting noise. A region with no measured point inside it is constrained only indirectly, through points the wave reaches after crossing it; the demo grays such regions out.
Simulation
Assumptions
- Truth: an eikonal model on a 30 × 30 mm sheet with a 1-mm triangulated grid, paced at the middle of the left edge. Speed is 1.0 m/s, except 0.6 m/s inside a disc of radius 7 mm; these are values reported for normal-voltage and low-voltage left atrium (Heil et al. 2023). The disc’s size and place are illustrative.
- Measurements: activation times at random grid points, plus Gaussian annotation noise and an unknown timing offset of 20 ms (any offset gives the same fit). The default noise of 1 ms and the default of 60 points are illustrative inputs; typical clinical values:
TODO(source). - Twin: the same eikonal solver (fast-sweeping order, same fixed point as the Python solver in the tests) with one speed per square region, fitted by Levenberg–Marquardt on log speed within 0.1–3 m/s; the offset is solved in closed form (Equation 2). Held-out error is 5-fold cross-validation (Equation 4).
- Ignored: anisotropy, curvature of the atrial wall, wall thickness, and errors in point position. A real twin also faces annotation bias, which noise of zero mean does not model.
Key takeaways
- Judge a twin on held-out points, not on the points it was tuned to.
- Equal fits from different parameters means the data do not identify them; report the spread.
Clinical correlate
Planned in the outline. Requires sign-off by an EP physician.
Visual summary
Planned in the outline.
How experts think
Planned in the outline.
Cheat sheet
Planned in the outline.
Interview questions
Planned in the outline.
Code lab
The lab builds a small twin from a synthetic mapping case and tests it the way this module says a twin should be tested. The truth is known, so every number the twin reports can be checked. It runs in about a minute.
| Part | What you do | Data |
|---|---|---|
| A | Build a mapping case on an atrium-sized sphere: a pacing site, a slow region (0.6 m/s) in normal tissue (1.0 m/s) (Heil et al. 2023), and a scar; acquire 200 points with position error, annotation noise, an unknown offset and relative voltages | synthetic |
| B | Choose the twin’s mesh: eikonal error and run time at three resolutions (m30) | synthetic |
| C | Label low-voltage regions by interpolating point voltages and applying a threshold; score the labels against the truth | synthetic |
| D | Calibrate regional speeds with the closed-form offset (Equation 2) for four twins, and see how the labels bias the fitted slow speed | synthetic |
| E | Cross-validate the twins (Equation 4); refit a 24-region twin from three starts and see which speeds the data do not determine | synthetic |
| F | Write the twin in openCARP’s mesh formats (nodes in micrometres, Tr triangles with region tags, one fibre vector per element) (File Formats 2026), and turn speeds into conductivity scale factors (Equation 3) |
synthetic |
- Python notebook: labs/python/m33_lab.ipynb. Run it from the course repository after
pip install -r requirements.txt, or open it in Google Colab. - The lab stops at the exported files. openCARP is not part of this course: its simulator and binaries are under the openCARP Academic Public License (openCARP License 2026). The notebook ends with the steps to run the twin in openCARP yourself.
- The sphere’s size, the regions’ sizes and places, the error sizes and the relative voltages are illustrative inputs.
Each part ends with checks: lines that pass with the code as given. If you change something and a check fails, that is information, not an error to hide.
Self-check
Planned in the outline.
Literature figures
Planned in the outline.
Further reading
Planned in the outline.