Skip to main content

simcardemsx

Cardiac electro-mechanics in FEniCSx.

simcardemsx couples a model of cardiac electrophysiology (EP) to a model of tissue mechanics, with the contraction of each cell in between. It does not solve either physics itself. It connects two solvers that do:

  • fenicsx-beat for EP (the monodomain model);
  • fenicsx-pulse for the mechanics, from a single element to a beating heart in a circulation model.

The cell model, EP and contraction alike, is a single gotranx .ode file. simcardemsx splits it in two and generates code for each half. The EP half is NumPy code for beat. The contraction half is UFL, which the mechanics solver can differentiate through, so the contraction model can be stepped inside the mechanics Newton iteration. That removes the instability the usual staggered coupling suffers from when the tissue is soft (Regazzoni & Quarteroni, 2021). Models that cannot be written in UFL, such as the NumPy models of crossbridge, are coupled with the stabilized scheme of the same paper instead.

📖 Documentation: https://computationalphysiology.github.io/simcardemsx

Features

  • One .ode file for the whole cell, split anywhere between EP and contraction. Which variables cross between the two sides is read off the generated code, not configured by hand.
  • Separate meshes and time steps for EP and mechanics.
  • Three coupling schemes: monolithic (the default), stabilized segregated, and the naive segregated scheme for comparison.
  • Static and dynamic mechanics, closed-loop circulation (Regazzoni's 0D circuit) and open-loop cardiac cycles, through pulse.
  • Rollback of a failed time step, and checkpoints that a run continues from in a new process (bit for bit under pulse's default direct solver).

Installation

simcardemsx needs DOLFINx, which is not installable from PyPI on its own. The simplest way to get it is the DOLFINx container:

docker run -ti -v $(pwd):/home/shared -w /home/shared ghcr.io/fenics/dolfinx/dolfinx:stable

Inside it, install simcardemsx with pip:

python3 -m pip install simcardemsx

or from source, with the dependencies of the examples:

git clone https://github.com/ComputationalPhysiology/simcardemsx.git
cd simcardemsx
python3 -m pip install -e ".[demo]"

The extras are demo (the examples), test, docs and dev.

A first look

Generate the two halves of a cell model and see what crosses between them:

from pathlib import Path

from simcardemsx.ode_model import load_ode_modules

odefile = Path("examples/odefiles/ToRORd_dynCl_endo_zetasplit.ode")
modules = load_ode_modules(odefile, Path("generated_odes"))

print(modules.mechanics.missing)  # what contraction needs from EP: {'XS': 0, 'XW': 1}
print(modules.ep.missing)  # what EP needs back: {'Zetas': 0, 'Zetaw': 1}

The contraction half becomes the active stress of a pulse model:

from simcardemsx.backends import GeneratedActivation

backend = GeneratedActivation(modules.mechanics, mesh, f0, quadrature_degree=4)
model = pulse.CardiacModel(material=material, active=backend, compressibility=compressibility)

and SimulationController steps EP and mechanics together:

from simcardemsx.controller import SimulationController

controller = SimulationController(
    mechanics=problem,  # a pulse.StaticProblem or DynamicProblem using `model`
    ep_solver=ep_solver,  # a beat.MonodomainSplittingSolver
    backend=backend,
    ode_modules=modules,
    dt_mech=1.0,  # ms
    dt_ep=0.05,  # ms
)
while controller.t < 200.0:
    controller.step()

The tutorials build this up step by step, from one cell to a coupled slab.

Examples

examples/ holds four short tutorials and four larger applications:

  • an electro-mechanical slab, for any split, scheme or contraction model;
  • a biventricular heart beating in a closed-loop circulation;
  • a biventricular heart from the Rodero cohort, driven through the cardiac cycle;
  • a convergence study of the coupling schemes.

Development

python3 -m pip install -e ".[dev,test]"
python3 -m pytest                 # the test suite
python3 -m pytest -m "not slow"   # the fast part of it
pre-commit run --all              # ruff, mypy, cspell, …

The documentation is built with MyST. See docs/README.md.

References

  • F. Regazzoni and A. Quarteroni. An oscillation-free fully staggered algorithm for velocity-dependent active models of cardiac mechanics. Computer Methods in Applied Mechanics and Engineering 373, 113506 (2021).
  • J. Tomek et al. Development, calibration, and validation of a novel human ventricular myocyte model in health, disease, and drug block. eLife 8, e48890 (2019).
  • S. Land et al. A model of cardiac contraction based on novel measurements of tension development in human cardiomyocytes. Journal of Molecular and Cellular Cardiology 106, 68–83 (2017).

Authors

Henrik Finsberg (henriknf@simula.no)

License

MIT. See LICENSE.

Metadata

Release files for simcardemsx 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for simcardemsx 0.1.1
File Size Uploaded Provenance Actions
simcardemsx-0.1.1.tar.gz 170.2 kB With provenance Details for simcardemsx-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for simcardemsx 0.1.1
File Interpreter ABI Platform Actions
simcardemsx-0.1.1-py3-none-any.whl Python 3 none any Details for simcardemsx-0.1.1-py3-none-any.whl

Total release size: 245.4 kB

Release files / simcardemsx-0.1.1.tar.gz

Download URL simcardemsx-0.1.1.tar.gz
Size 170.2 kB
Tags Source
SHA-256 checksum
How to use checksums
31b0832c7f0f52461b970f7e6f372ab240bac2ad27e7ee0ea769b6601b930e64
BLAKE2b-256 checksum
How to use checksums
2f43b97ea1184f4759694e582fadc231f69a208403f0e93fcea9e495d58a4266
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

Release files / simcardemsx-0.1.1-py3-none-any.whl

Download URL simcardemsx-0.1.1-py3-none-any.whl
Size 75.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7e16379632ae0d9e0674c484aed95576db20a68c824c5b74006be3beadd4658d
BLAKE2b-256 checksum
How to use checksums
c8d154912d59f830002f164dbed34fac879d9718af2618f754cffd3df7576024
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

Security for simcardemsx 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for simcardemsx-0.1.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page