crossbridge

crossbridge is a Python library for simulating cardiac myofilament activation and crossbridge dynamics.

The Mathematical Models

crossbridge implements several reduced-order models of cardiac myofilament activation (RDQ18, RDQ20-MF, Land2017, Lewalle2024), all sharing a common interface so that a coupled electromechanics simulation can swap between them with minimal code changes. See docs/models for a description and reference for each model.

Installation

You can install the base package and its dependencies using pip.

To install the library you can use pip:

python3 -m pip install crossbridge

To install with optional dependencies (for running demos, tests, or building docs):

python3 -m pip install "crossbridge[demos]"  # Installs scipy, matplotlib, gotranx, numba, zero-mech, etc.
python3 -m pip install "crossbridge[test]"   # Installs pytest and coverage tools
python3 -m pip install "crossbridge[docs]"   # Installs jupyter-book and sphinx plugins
python3 -m pip install "crossbridge[all]"    # Installs everything

Documentation

Documentation is available at https://computationalphysiology.github.io/crossbridge. It includes a user guide, API reference, and model background/references.

Basic Usage

To most basic usage its to solve for a single cell. The RDQ18 class provides an advance_ODE method that takes in the time step, calcium concentration, and sarcomere length to update the internal state of the model. This can then be used to compute an active tension based on the fraction of permissive crossbridges.

import numpy as np
from crossbridge import RDQ18, calcium_trace, sl_trace

# Initialize a model with 1 cell
num_cells = 1
dt = 0.01
dt_sarc = 2.5e-5
sarcomere = RDQ18(num_cells=num_cells, Ta_max=60.0, params={"dt": dt_sarc})

# Inputs
t = np.arange(0, 1, dt)  # Time array [s]
Ca = calcium_trace(t)
SL = sl_trace(t)

Ta = np.zeros((len(t), num_cells))  # Active tension array [kPa]
# Advance the ODEs by one time step
for i, (Cai, SLi) in enumerate(zip(Ca, SL)):
    sarcomere.advance_ODE(dt, Cai, SLi)  # Advance the model by one time step)
    Ta[i, :] = sarcomere.get_active_tension()  # Get the active tension for each cell

import matplotlib.pyplot as plt

fig, ax = plt.subplots(3, 1, sharex=True, figsize=(8, 6))
ax[0].plot(t, Ca)
ax[0].set_ylabel("Calcium [uM]")
ax[1].plot(t, SL)
ax[1].set_ylabel("Sarcomere Length [um]")
ax[2].plot(t, Ta)
ax[2].set_ylabel("Active Tension [kPa]")
ax[2].set_xlabel("Time [s]")
fig.tight_layout()
plt.show()

Coupling to Electrophysiology and Mechanics

Most cellular and tissue-level simulations will require coupling the RDQ18 model to electrophysiology and mechanics. The advance_ODE method is designed to be called at every time step of a larger simulation loop, allowing the sarcomere dynamics to evolve in response to changing calcium and length conditions.

The calcium concentration can be either a scalar (if all cells/integration points are assumed to have the same calcium transient) or an array with one entry per cell/integration point. The sarcomere length can similarly be a scalar or an array. Below is a pseudo-code example of how this coupling might look in a larger simulation loop:

...

SL = np.full(num_cells, 2.2)  # Initial sarcomere length [um]
for t in time_steps:
    # Compute calcium from electrophysiology model
    Cai = compute_calcium(t)
    sarcomere.advance_ODE(dt, Cai, SL)
    # Compute active tension and update mechanics
    active_tension = sarcomere.get_active_tension()
    # Update mechanics model with new active tension
    # and compute new sarcomere length (SL) based on
    # the mechanical response of the tissue
    SL = compute_new_length(active_tension, SL)
...

Examples & Demos

The demo/ folder contains several scripts demonstrating how to couple the crossbridge model to different physics scales. See demos for a description of each demo and how to run them.

Testing and Development

We use pytest for unit testing. To run the test suite and check code coverage:

pytest

To run the pre-commit linters (Ruff and MyPy):

pre-commit run --all-files

License

This project is licensed under the MIT License. See the LICENSE file for details.