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
.odefile 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.