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.0

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.0
File Size Uploaded Provenance Actions
simcardemsx-0.1.0.tar.gz 170.9 kB Without provenance Details for simcardemsx-0.1.0.tar.gz

Built distribution (wheel)

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

Total release size: 246.1 kB

Release files / simcardemsx-0.1.0.tar.gz

Download URL simcardemsx-0.1.0.tar.gz
Size 170.9 kB
Tags Source
SHA-256 checksum
How to use checksums
3f6a01a75f10de08339a1526dac92511dcee82043015226ad5d39ed645f8b6b0
BLAKE2b-256 checksum
How to use checksums
7dea605e1c76f1441b3f4abd9409573de636f8f387204a51121b48e35c173aa3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.6

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

Download URL simcardemsx-0.1.0-py3-none-any.whl
Size 75.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
eb4be8784b1863de5bb89bfdcbeccc4c798e1040964a8cf263b0f17819c1f9da
BLAKE2b-256 checksum
How to use checksums
87d66960bfc0ccb7b51cb9b29dac49c15373ac6d75420ef285d6385bbfb4460d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.6

Security for simcardemsx 0.1.0

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.

No provenance found

None of the files in this release were uploaded with provenance metadata.

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.0 This release

2 release files No 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