Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

A cardiac cell, and how simcardemsx splits it

Everything in simcardemsx starts from a single cell model: a system of ordinary differential equations (ODEs) describing one cardiomyocyte. This first tutorial uses no mesh and no finite elements. It runs the cell model on its own, then shows how simcardemsx cuts it in two so that it can be coupled to tissue mechanics.

The cell model

The model used throughout these tutorials joins two published models in one gotranx .ode file:

  • Electrophysiology (EP): the ToR-ORd model of a human ventricular myocyte (Tomek et al., eLife 2019), in its dynamic-chloride variant for endocardial cells. It describes the membrane potential vv, the ion currents that shape the action potential, and the calcium handling that releases calcium into the cytosol ([Ca2+]i[Ca^{2+}]_i).

  • Contraction: the Land model of human cardiac muscle (Land et al., J Mol Cell Cardiol 2017). Calcium binds to troponin (CaTrpn), which frees myosin to form crossbridges. These attach in a weakly bound state (XW) and move to a strongly bound state (XS). Two distortion states (Zetas, Zetaw) follow how far the attached crossbridges are stretched when the fibre lengthens or shortens. The active tension TaT_a the cell generates is

    Ta=h(λ) Trefrs[XS (ζs+1)+XW ζw],T_a = h(\lambda)\,\frac{T_{ref}}{r_s}\Big[X_S\,(\zeta_s + 1) + X_W\,\zeta_w\Big],

    where λ\lambda is the stretch of the fibre and h(λ)h(\lambda) its length dependence. Through λ\lambda and the stretch rate λ˙\dot\lambda (dLambda), the tension depends on what the tissue is doing. That is what makes the coupling between cell and tissue two-way.

The contraction and EP equations are joined in both directions. Calcium drives the contraction, and the calcium bound to troponin is taken out of the cytosol, which feeds back onto EP. This is mechano-electric feedback.

The repository ships the same cell model in three .ode files, in examples/odefiles. They differ only in where the line between EP and mechanics is drawn, which we come back to below.

Running the whole cell

gotranx turns an .ode file into Python code. Here we generate the whole model as plain NumPy, with the generalized Rush-Larsen (GRL) scheme, which takes exponential steps for the gating variables and so allows a much larger time step than forward Euler.

2026-11-09 14:05:38 [info     ] Load ode /__w/simcardemsx/simcardemsx/examples/odefiles/ToRORd_dynCl_endo_zetasplit.ode
2026-11-09 14:05:42 [warning  ] Dropping a guard whose replacement failed its numeric check value=0 var=clss
2026-11-09 14:05:42 [warning  ] Dropping a guard whose replacement failed its numeric check value=0 var=nai
2026-11-09 14:05:42 [warning  ] Dropping a guard whose replacement failed its numeric check value=0 var=ki
2026-11-09 14:05:42 [warning  ] Dropping a guard whose replacement failed its numeric check value=0 var=cli
2026-11-09 14:05:43 [info     ] Num states 52                 
2026-11-09 14:05:43 [info     ] Num parameters 140            
52 states, 140 parameters
components: CaMK, ICaL, ICab, ICl, IK1, IKb, IKr, IKs, INa, INaCa, INaK, INaL, INab, I_katp, IpCa, Ito, SERCA, cell_geometry, diff, environment, extracellular, intracellular_ions, mechanics, mechanics-ep, membrane, physical_constants, reversal_potentials, ryr, trans_flux

The fibre stretch λ\lambda (lmbda) and its rate (dLambda) are parameters of the cell model. Left at their defaults (λ=1\lambda = 1, λ˙=0\dot\lambda = 0) the cell contracts isometrically: it generates tension but cannot shorten. The model’s own stimulus current fires at t=0t = 0 and then once every second.

<Figure size 1200x320 with 3 Axes>

The three traces follow each other. The action potential opens the L-type calcium channels, which triggers calcium release from the sarcoplasmic reticulum. The calcium transient peaks a few tens of milliseconds later, and tension follows more slowly still, peaking well after the calcium has started to fall.

peak v         37.6 mV at    1.6 ms
peak cai      0.452 µM at   41.1 ms
peak Ta       20.30 kPa at  144.4 ms

Splitting the cell in two

In a tissue simulation the two halves of this model do not live in the same place.

  • EP is solved by fenicsx-beat. It steps the ODE at every node of the EP mesh with a small time step (0.05 ms here), with a reaction-diffusion equation (the monodomain model) spreading the action potential between the nodes.

  • Mechanics is solved by fenicsx-pulse, on its own mesh and with a larger time step (1 ms or more). The tension enters the stress at every quadrature point of the mechanics mesh.

Each .ode file therefore marks one component as "mechanics". Those states are stepped on the mechanics mesh, and everything else is stepped by EP. simcardemsx.ode_model.load_ode_modules cuts the file along that line and generates two modules. The EP half is NumPy code for beat. The mechanics half is UFL, the symbolic form language of FEniCSx, so the mechanics solver can differentiate through it (tutorial 3 shows why that matters).

Generating ToR-ORd takes about 15 seconds. The code is cached in the output folder and reused until the .ode file or gotranx changes.

EP module:         49 states
mechanics module:  3 states: ['Zetaw', 'Zetas', 'Cd']

Each generated module records, as plain dictionaries, what it needs from the other side (missing) and what it hands over (provides). In this split, the mechanics side holds only the two distortion states and Cd. To compute the tension it needs XS and XW from EP, and EP in turn needs Zetas and Zetaw back from mechanics.

mechanics needs    {'XS': 0, 'XW': 1}
EP provides        {'XS': 0, 'XW': 1}
EP needs           {'Zetas': 0, 'Zetaw': 1}
mechanics provides {'Zetas': 0, 'Zetaw': 1}

The fibre stretch is the other quantity that crosses back. It is not produced by the ODE at all but by the mechanics solve, so it crosses as the EP parameter lmbda, if EP has one.

lmbda is an EP parameter: True

The three splits

The same cell can be cut in different places. The further the cut is moved towards EP, the more of the contraction model is stepped on the mechanics mesh, and the fewer variables have to cross.

split        EP states mech states  EP → mechanics      mechanics → EP
zetasplit           49           3  XS, XW              Zetas, Zetaw, lmbda
2026-11-09 14:06:06 [info     ] Load ode /__w/simcardemsx/simcardemsx/examples/odefiles/ToRORd_dynCl_endo_catrpnsplit.ode
2026-11-09 14:06:11 [warning  ] Dropping a guard whose replacement failed its numeric check value=0 var=clss
2026-11-09 14:06:11 [warning  ] Dropping a guard whose replacement failed its numeric check value=0 var=nai
2026-11-09 14:06:11 [warning  ] Dropping a guard whose replacement failed its numeric check value=0 var=ki
2026-11-09 14:06:11 [warning  ] Dropping a guard whose replacement failed its numeric check value=0 var=cli
2026-11-09 14:06:11 [info     ] Num states 52                 
2026-11-09 14:06:11 [info     ] Num parameters 145            
catrpnsplit         46           6  CaTrpn              lmbda
caisplit            45           7  cai                 J_TRPN
  • zeta split: only the distortion states are on the mechanics side. The crossbridge populations come from EP.

  • CaTrpn split: the whole Land model except troponin binding is on the mechanics side. Only CaTrpn crosses, and nothing comes back.

  • Cai_i split: the whole Land model is on the mechanics side. It receives the cytosolic calcium and returns the troponin buffering flux J_TRPN to EP.

Whatever is on the mechanics side lives at the quadrature points of the mechanics mesh. The stretch λ\lambda it sees there is the true fibre stretch of the deforming tissue, not an average carried over from EP. The next tutorial shows why it matters how that stretch is fed into the contraction model.