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.

Contraction of one element

The previous tutorial showed in 0D why the coupling scheme matters. This one does the same with finite elements: a single element of tissue, contracting under a prescribed calcium transient. There is no EP solver yet. The calcium is written straight into the contraction model, so the focus is on the coupling between contraction and mechanics alone.

The pieces are:

  • a mechanics problem from fenicsx-pulse: a hyperelastic, incompressible material with fibres along xx;

  • an activation backend, simcardemsx.backends.GeneratedActivation, which owns the contraction model’s states and turns them into an active stress.

The model

The tissue is a Holzapfel-Ogden material (Holzapfel & Ogden, 2009), with strain energy Ψ(C)\Psi(\mathbf{C}) of the right Cauchy-Green tensor C=FTF\mathbf{C} = \mathbf{F}^T\mathbf{F}. The active tension TaT_a of the cell model is added along the fibres. simcardemsx uses the normalization of Regazzoni & Quarteroni, under which ∣Paf0∣=Ta|P_a f_0| = T_a whatever the stretch:

P=∂Ψ∂F+Ta Ff0⊗f0∣Ff0∣−p JF−T,λ=∣Ff0∣,\mathbf{P} = \frac{\partial \Psi}{\partial \mathbf{F}} + T_a\,\frac{\mathbf{F} f_0 \otimes f_0}{|\mathbf{F} f_0|} - p\,J\mathbf{F}^{-T}, \qquad \lambda = |\mathbf{F} f_0|,

with pp the pressure that keeps the tissue incompressible (J=det⁡F=1J = \det\mathbf{F} = 1). The element is held on three faces by rollers and is otherwise free, so it shortens along the fibre when it contracts.

We use the Cai_i split from tutorial 1, where the whole Land model is on the mechanics side and its only input is the cytosolic calcium cai.

2026-11-09 14:04:50 [info     ] Load ode /__w/simcardemsx/simcardemsx/examples/odefiles/ToRORd_dynCl_endo_caisplit.ode
2026-11-09 14:04:55 [warning  ] Dropping a guard whose replacement failed its numeric check value=0 var=nai
2026-11-09 14:04:55 [warning  ] Dropping a guard whose replacement failed its numeric check value=0 var=ki
2026-11-09 14:04:55 [warning  ] Dropping a guard whose replacement failed its numeric check value=0 var=clss
2026-11-09 14:04:55 [warning  ] Dropping a guard whose replacement failed its numeric check value=0 var=cli
2026-11-09 14:04:55 [info     ] Num states 52                 
2026-11-09 14:04:55 [info     ] Num parameters 140            
the backend needs {'cai': 0} and provides {'J_TRPN': 0}

The mechanics problem

build returns a pulse.StaticProblem (quasistatic, so no inertia) and the backend it uses as its active model. The backend’s states live at the quadrature points of the mechanics form, so its quadrature_degree must be the form’s.

The absolute Newton tolerance snes_atol is tightened from pulse’s default. At rest the first residual is already at round-off, which a purely relative tolerance cannot reduce further.

The time loop

Each mechanics step follows the same protocol, which tutorial 4’s controller also follows:

  1. write the inputs at the new time into backend.inputs, here a prescribed calcium transient peaking at 1 µM;

  2. backend.begin_step(t_n, dt) tells the backend which step is being taken;

  3. problem.solve() runs Newton, which assembles the backend’s active stress;

  4. backend.post_solve() accepts the step: the contraction states, the stretch λ\lambda and the tension of the converged solution become the new “previous” values.

Nothing is accepted before post_solve, so a step whose Newton solve fails leaves the backend as it was.

Newton did not converge after 9 iterations (SNES converged reason -9)
segregated: Newton failed at t = 31.0 ms
<Figure size 1300x340 with 3 Axes>
monolithic  reached  60.0 ms, min stretch 0.8800, peak Ta  1.482 kPa
stabilized  reached  60.0 ms, min stretch 0.8962, peak Ta  3.103 kPa
segregated  reached  30.0 ms, min stretch 0.7377, peak Ta 30.006 kPa

The passive material is soft enough here that the active stiffness exceeds the passive one during the twitch, which is the regime of tutorial 2. As in 0D, the naive segregated scheme oscillates from one step to the next from about 20 ms on, until Newton gives up. The other two shorten the element smoothly as the tension rises.

They do not agree with each other at this time step, though. The stabilized scheme adds a term of order Δt\Delta t, so it is consistent: it converges to the same solution, but at a time step of 1 ms its error is visible. To see both converge, we compare them with a monolithic run at Δt\Delta t = 0.1 ms, at every whole millisecond.

 dt [ms]   monolithic   stabilized   (max |λ - λ_ref|)
    1.00     4.41e-03     2.01e-02
    0.50     1.92e-03     1.10e-02
    0.25     7.13e-04     5.66e-03
<Figure size 550x400 with 1 Axes>

Both converge, at about first order. The stabilized scheme’s error is several times larger at every time step, which is the price of solving the contraction model outside Newton. The monolithic scheme is therefore the default whenever the model can be generated as UFL. The stabilized scheme is the way to couple a model that cannot be.

What the backend computes

GeneratedActivation is a pulse.ActiveModel, so pulse calls its S(C) when it builds the stress. Under scheme="monolithic", the backend takes one generalized Rush-Larsen step of the contraction model inside that expression. The step starts from the last accepted states, with

λ=λ(u),λ˙=λ(u)−λnΔt,\lambda = \lambda(\mathbf{u}), \qquad \dot\lambda = \frac{\lambda(\mathbf{u}) - \lambda_n}{\Delta t},

where u\mathbf{u} is the displacement Newton is currently iterating on. The tension is therefore a UFL function of the displacement, and Newton linearizes through the whole contraction model. That is why the monolithic scheme needs no stabilization.

Besides the stress, the backend exposes a few dolfinx.fem.Functions, written by post_solve:

attributewhat it holds
inputswhat it needs from EP, by name (cai here)
outputswhat it gives back to EP (J_TRPN here, and lmbda)
lmbda_prevthe fibre stretch of the last accepted step
tension_kPaTaT_a at the quadrature points, in kPa
stiffness_kPathe active stiffness Ka=∂Ta/∂λK_a = \partial T_a/\partial\lambda, in kPa
active_tensionTaT_a averaged onto P1, for plotting

The active stiffness is the quantity tutorial 2 compared with the passive one.

at t = 30 ms: Ta = 0.192 kPa
              Ka = 343.1 kPa per unit stretch
              J_TRPN = -1.140e-04 mM/ms

In a full simulation inputs is filled from the EP solver and outputs is sent back to it. The next tutorial hands that bookkeeping to SimulationController.