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.

How simcardemsx works

A simulation couples two solvers, each on its own mesh and with its own time step, and exchanges state between them once every mechanics step. This page names the pieces and shows how a time step goes. The pages after it describe the models, the coupling schemes, and mechanics, circulation and output.

The pieces

PieceWhat it isWhere it comes from
Cell modelOne gotranx .ode file with EP and contraction, one component marked "mechanics"Your own, or examples/odefiles/
Generated modulesThe EP half as NumPy code and the contraction half as UFL, written by load_ode_modulessimcardemsx.ode_model
EP solverA beat.MonodomainSplittingSolver, whose ODE half steps the EP module at every nodefenicsx-beat
Activation backendOwns the contraction states, and turns them into an active stress for pulsesimcardemsx.backends
Mechanics problemA pulse.StaticProblem or pulse.DynamicProblem whose active model is the backendfenicsx-pulse
Mechanics driverHow one mechanics step is taken: a plain solve, a circulation clock, or a cycle controllersimcardemsx.mechanics
Transfer planMoves what crosses between the EP mesh and the mechanics meshsimcardemsx.transfer_plan
ControllerThe time loop over all of the abovesimcardemsx.controller

What crosses, and how it is decided

Nothing in a simulation script lists the variables that cross between EP and mechanics. Each generated module carries three dictionaries, read off the .ode file:

simcardemsx.transfer_plan.resolve(ep_module, backend) pairs each side’s missing against the other’s provides. If either side needs something the other does not produce, it raises a ValueError naming everything that is missing in both directions. This guards against a mismatched split or stale generated code. The fibre stretch λ\lambda is not produced by the ODE but by the mechanics solve, so it is sent back to EP whenever the EP module has a parameter called lmbda.

The TransferPlan then moves the values at run time:

One time step

SimulationController.step() advances everything from tnt_n to tn+1=tn+Δtmecht_{n+1} = t_n + \Delta t_{mech}:

Nothing in the backend is accepted before post_solve. If anything before the mechanics callback raises, or the solve does not converge, the controller restores the snapshot. EP’s states, the transfer arrays, the displacement, any cavity pressures and circuit states, and the backend are then exactly as they were before the step. It then raises. The caller can retry the step, for example with a smaller time step.

When the controller is built it checks that:

Units

simcardemsx works in milliseconds throughout, like beat and the .ode files. The exceptions are converted at the edges: