Skip to main content

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, Tewari2016, Marzban2020, Musgrave2025), 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()

Example Output

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.

Metadata

Release files for crossbridge 0.5.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 crossbridge 0.5.0
File Size Uploaded Provenance Actions
crossbridge-0.5.0.tar.gz 119.8 kB With provenance Details for crossbridge-0.5.0.tar.gz

Built distribution (wheel)

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

Total release size: 207.6 kB

Release files / crossbridge-0.5.0.tar.gz

Download URL crossbridge-0.5.0.tar.gz
Size 119.8 kB
Tags Source
SHA-256 checksum
How to use checksums
a8af8d91e4c18a0c140ac93c096d47aaff2e52f321ada4be3dad83486d90d2b7
BLAKE2b-256 checksum
How to use checksums
80e7a33a2deb1fb5943122b1204be00a1d5f45f1c5f69d2ea17a6d223eeb7d0a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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 Oct 19, 2026.

Transparency log

Release files / crossbridge-0.5.0-py3-none-any.whl

Download URL crossbridge-0.5.0-py3-none-any.whl
Size 87.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7871f7b39261497412a45d1a693482b6e8e9ffe6629b59dc273ae6160082bf88
BLAKE2b-256 checksum
How to use checksums
77944c6deb06e31d06534500c5a7d22ae6fd9d2c52c6ebb866770872f0207303
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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 Oct 19, 2026.

Transparency log

Security for crossbridge 0.5.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.

Full provenance

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

Select from 2 files

Attestation for crossbridge-0.5.0.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 Oct 19, 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.

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