crossbridge 0.1.0__tar.gz

crossbridge-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Computational Physiology at Simula Research Laboratory
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

crossbridge-0.1.0/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: crossbridge
+Version: 0.1.0
+Summary: Cardiac crossbridge models
+Author-email: Henrik Finsberg <henriknf@simula.no>
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: scipy
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Provides-Extra: demos
+Requires-Dist: matplotlib; extra == "demos"
+Requires-Dist: zero-mech; extra == "demos"
+Requires-Dist: gotranx; extra == "demos"
+Requires-Dist: scipy; extra == "demos"
+Requires-Dist: tqdm; extra == "demos"
+Requires-Dist: numba; extra == "demos"
+Provides-Extra: docs
+Requires-Dist: jupyter-book<2.0; extra == "docs"
+Requires-Dist: jupytext; extra == "docs"
+Requires-Dist: crossbridge[demos]; extra == "docs"
+Requires-Dist: sphinxcontrib-bibtex; extra == "docs"
+Provides-Extra: all
+Requires-Dist: crossbridge[test]; extra == "all"
+Requires-Dist: crossbridge[demos]; extra == "all"
+Requires-Dist: crossbridge[docs]; extra == "all"
+Dynamic: license-file
+
+# crossbridge
+
+**crossbridge** is a highly efficient, vectorized Python library for simulating cardiac myofilament activation and crossbridge dynamics.
+
+## The Mathematical Models
+`crossbridge` implements several reduced-order models of cardiac myofilament activation
+([RDQ18](docs/models/rdq18.md), [RDQ20-MF](docs/models/rdq20mf.md), [Land2017](docs/models/land2017.md),
+[Lewalle2024](docs/models/lewalle2024.md)), all sharing a common interface (see "Choosing a Model"
+below) so that a coupled electromechanics simulation can swap between them with minimal code
+changes. See [docs/models](docs/models/index.md) for a description and reference for each model.
+
+## Installation
+
+The package requires Python 3.11+. You can install the base package and its dependencies using `pip`.
+
+To install the library from the source code:
+```bash
+git clone https://github.com/ComputationalPhysiology/crossbridge.git
+cd crossbridge
+pip install .
+```
+
+To install with optional dependencies (for running demos, tests, or building docs):
+```bash
+pip install ".[demos]"  # Installs scipy, matplotlib, gotranx, numba, zero-mech, etc.
+pip install ".[test]"   # Installs pytest and coverage tools
+pip install ".[docs]"   # Installs jupyter-book and sphinx plugins
+pip install ".[all]"    # Installs everything
+```
+
+## 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.
+
+```python
+import numpy as np
+from crossbridge import RDQ18, calcium_trace, sl_trace
+
+# Initialize a model with 1000 cells/integration points
+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)  # Calcium transient [uM]
+SL = sl_trace(t)  # Sarcomere length transient [um]
+
+
+Ta = np.zeros(len(t))
+# Advance the ODEs by one time step
+for i, (Cai, SLi) in enumerate(zip(Ca, SL)):
+    sarcomere.advance_ODE(dt, Cai, np.array([SLi]))
+
+    # Compute the fraction of permissive crossbridges (proxy for active tension)
+    permissivity = sarcomere.compute_permissivity()[0]
+    active_tension = sarcomere.Ta_max * permissivity
+    Ta[i] = active_tension
+
+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](https://github.com/user-attachments/assets/4d07bea6-9f5d-4aae-a1df-2debe6199999)
+
+
+## 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:
+
+```python
+...
+
+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
+    permissivity = sarcomere.compute_permissivity()[0]
+    active_tension = sarcomere.Ta_max * permissivity
+    # 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](demo/index.md) 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:
+```bash
+pytest
+```
+To run the pre-commit linters (Ruff and MyPy):
+```bash
+pre-commit run --all-files
+```
+
+## License
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

crossbridge-0.1.0/README.md

@@ -0,0 +1,115 @@
+# crossbridge
+
+**crossbridge** is a highly efficient, vectorized Python library for simulating cardiac myofilament activation and crossbridge dynamics.
+
+## The Mathematical Models
+`crossbridge` implements several reduced-order models of cardiac myofilament activation
+([RDQ18](docs/models/rdq18.md), [RDQ20-MF](docs/models/rdq20mf.md), [Land2017](docs/models/land2017.md),
+[Lewalle2024](docs/models/lewalle2024.md)), all sharing a common interface (see "Choosing a Model"
+below) so that a coupled electromechanics simulation can swap between them with minimal code
+changes. See [docs/models](docs/models/index.md) for a description and reference for each model.
+
+## Installation
+
+The package requires Python 3.11+. You can install the base package and its dependencies using `pip`.
+
+To install the library from the source code:
+```bash
+git clone https://github.com/ComputationalPhysiology/crossbridge.git
+cd crossbridge
+pip install .
+```
+
+To install with optional dependencies (for running demos, tests, or building docs):
+```bash
+pip install ".[demos]"  # Installs scipy, matplotlib, gotranx, numba, zero-mech, etc.
+pip install ".[test]"   # Installs pytest and coverage tools
+pip install ".[docs]"   # Installs jupyter-book and sphinx plugins
+pip install ".[all]"    # Installs everything
+```
+
+## 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.
+
+```python
+import numpy as np
+from crossbridge import RDQ18, calcium_trace, sl_trace
+
+# Initialize a model with 1000 cells/integration points
+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)  # Calcium transient [uM]
+SL = sl_trace(t)  # Sarcomere length transient [um]
+
+
+Ta = np.zeros(len(t))
+# Advance the ODEs by one time step
+for i, (Cai, SLi) in enumerate(zip(Ca, SL)):
+    sarcomere.advance_ODE(dt, Cai, np.array([SLi]))
+
+    # Compute the fraction of permissive crossbridges (proxy for active tension)
+    permissivity = sarcomere.compute_permissivity()[0]
+    active_tension = sarcomere.Ta_max * permissivity
+    Ta[i] = active_tension
+
+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](https://github.com/user-attachments/assets/4d07bea6-9f5d-4aae-a1df-2debe6199999)
+
+
+## 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:
+
+```python
+...
+
+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
+    permissivity = sarcomere.compute_permissivity()[0]
+    active_tension = sarcomere.Ta_max * permissivity
+    # 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](demo/index.md) 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:
+```bash
+pytest
+```
+To run the pre-commit linters (Ruff and MyPy):
+```bash
+pre-commit run --all-files
+```
+
+## License
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

crossbridge-0.1.0/pyproject.toml

@@ -0,0 +1,126 @@
+[build-system] # Require setuptool version due to https://github.com/pypa/setuptools/issues/2938
+requires = ["setuptools>=61.0.0", "wheel"]
+
+[project]
+name = "crossbridge"
+version = "0.1.0"
+description = "Cardiac crossbridge models"
+authors = [{ name = "Henrik Finsberg", email = "henriknf@simula.no" }]
+license = "MIT"
+license-files = ["LICENSE"]
+readme = "README.md"
+dependencies = [
+    "numpy",
+    "scipy"
+]
+requires-python = ">=3.11"
+
+
+[project.optional-dependencies]
+test = ["pytest", "pytest-cov"]
+demos = ["matplotlib", "zero-mech", "gotranx", "scipy", "tqdm", "numba"]
+docs = [
+    "jupyter-book<2.0",
+    "jupytext",
+    "crossbridge[demos]",
+    "sphinxcontrib-bibtex",
+]
+all = [
+    "crossbridge[test]",
+    "crossbridge[demos]",
+    "crossbridge[docs]",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+
+[tool.pytest.ini_options]
+addopts = [
+    "--cov=crossbridge",
+    "--cov-report=html",
+    "--cov-report=term-missing",
+    "-v",
+]
+
+testpaths = ["tests"]
+
+[tool.mypy]
+files = ["src/crossbridge", "tests"]
+ignore_missing_imports = true
+exclude = [
+    "docs",
+    "examples",
+]
+
+
+
+[tool.ruff]
+
+# Exclude a variety of commonly ignored directories.
+exclude = [
+    "examples",
+    ".bzr",
+    ".direnv",
+    ".eggs",
+    ".git",
+    ".hg",
+    ".mypy_cache",
+    ".nox",
+    ".pants.d",
+    ".pytype",
+    ".ruff_cache",
+    ".svn",
+    ".tox",
+    ".venv",
+    "__pypackages__",
+    "_build",
+    "buck-out",
+    "build",
+    "dist",
+    "node_modules",
+    "venv",
+]
+
+# Same as Black.
+line-length = 100
+
+# Assume Python 3.12.
+target-version = "py312"
+
+[tool.ruff.lint]
+# Enable pycodestyle (`E`) and Pyflakes (`F`) codes by default.
+select = ["E", "F"]
+ignore = ["E402", "E741", "E743", "E731"]
+
+# Allow autofix for all enabled rules (when `--fix`) is provided.
+fixable = ["A", "B", "C", "D", "E", "F"]
+unfixable = []
+
+# Allow unused variables when underscore-prefixed.
+dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
+
+
+[tool.ruff.lint.mccabe]
+# Unlike Flake8, default to a complexity level of 10.
+max-complexity = 10
+
+[tool.ruff.lint.per-file-ignores]
+# Ignore "Line too long" (E501) for all files in the specific folder
+"demo/*" = ["E501"]
+
+[tool.bumpversion]
+allow_dirty = false
+commit = true
+message = "Bump version: {current_version} → {new_version}"
+tag = true
+sign_tags = false
+tag_name = "v{new_version}"
+tag_message = "Bump version: {current_version} → {new_version}"
+current_version = "0.1.0"
+
+
+[[tool.bumpversion.files]]
+filename = "pyproject.toml"
+search = 'version = "{current_version}"'
+replace = 'version = "{new_version}"'

crossbridge-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

crossbridge-0.1.0/src/crossbridge/__init__.py

@@ -0,0 +1,56 @@
+from .base import CardiacActivationModel
+from .rdq18 import RDQ18
+from .rdq20mf import RDQ20MF
+from .lewalle2024 import Lewalle2024
+from .land17 import Land2017
+from . import utils
+from .utils import calcium_trace, sl_trace
+
+#: Maps a short model name to its class, so a model can be selected by name
+#: (e.g. from a config file) instead of importing the class directly. Every
+#: model here is a `CardiacActivationModel` and can be constructed uniformly
+#: as `ModelClass(num_cells, Ta_max, params)`, so switching between them
+#: requires no other code changes beyond the name/class used.
+MODEL_REGISTRY: dict[str, type[CardiacActivationModel]] = {
+    "RDQ18": RDQ18,
+    "RDQ20MF": RDQ20MF,
+    "Lewalle2024": Lewalle2024,
+    "Land2017": Land2017,
+}
+
+
+def get_model(name: str) -> type[CardiacActivationModel]:
+    """
+    Look up a `CardiacActivationModel` subclass by name.
+
+    Parameters
+    ----------
+    name : str
+        One of the keys in `MODEL_REGISTRY` (e.g. "RDQ18", "RDQ20MF",
+        "Lewalle2024").
+
+    Returns
+    -------
+    type[CardiacActivationModel]
+        The model class, ready to be instantiated as
+        `get_model(name)(num_cells, Ta_max, params)`.
+    """
+    try:
+        return MODEL_REGISTRY[name]
+    except KeyError:
+        available = ", ".join(sorted(MODEL_REGISTRY))
+        raise KeyError(f"Unknown model {name!r}. Available models: {available}") from None
+
+
+__all__ = [
+    "CardiacActivationModel",
+    "RDQ18",
+    "RDQ20MF",
+    "Lewalle2024",
+    "Land2017",
+    "MODEL_REGISTRY",
+    "get_model",
+    "utils",
+    "calcium_trace",
+    "sl_trace",
+]

crossbridge-0.1.0/src/crossbridge/base.py

@@ -0,0 +1,80 @@
+from abc import ABC, abstractmethod
+import numpy as np
+import numpy.typing as npt
+
+
+class CardiacActivationModel(ABC):
+    """
+    Abstract base class for all reduced-order cardiac activation models.
+    Designed to support vectorized execution across multiple cells or
+    integration points.
+    """
+
+    @abstractmethod
+    def __init__(self, num_cells: int, Ta_max: float, params: dict | None = None):
+        """
+        Initialize the model state and precompute necessary constants.
+
+        Parameters:
+        -----------
+        num_cells : int
+            The number of independent spatial units to simulate simultaneously.
+        Ta_max : float
+            The maximum active tension scaling factor.
+        params : dict, optional
+            Model-specific parameters to override defaults.
+        """
+        self.num_cells = num_cells
+        self.Ta_max = Ta_max
+
+    @classmethod
+    @abstractmethod
+    def default_parameters(cls) -> dict:
+        """
+        Return a dictionary of the default physiological parameters for the model.
+        """
+        pass
+
+    @abstractmethod
+    def advance_step(
+        self,
+        dt: float,
+        Ca_val: float | npt.NDArray[np.float64],
+        SL_vals: float | npt.NDArray[np.float64],
+        dSL_vals: float | npt.NDArray[np.float64] | None = None,
+    ) -> None:
+        """
+        Integrate the model's internal states forward by a single time step.
+
+        Parameters:
+        -----------
+        dt : float
+            The time step size in seconds.
+        Ca_val : float or np.ndarray
+            Intracellular calcium concentration.
+        SL_vals : float or np.ndarray
+            Current sarcomere length(s).
+        dSL_vals : float or np.ndarray, optional
+            Current sarcomere shortening velocity. Defaults to 0 if not provided.
+        """
+        pass
+
+    @abstractmethod
+    def get_active_tension(self) -> npt.NDArray[np.float64]:
+        """
+        Compute and return the macroscopic active tension (Ta) generated.
+
+        Returns:
+        --------
+        np.ndarray
+            The active tension for each cell/integration point (shape: `num_cells`).
+        """
+        pass
+
+    @abstractmethod
+    def reset(self) -> None:
+        """
+        Reset the model's internal state to its initial condition (as set by
+        `__init__`), without re-allocating precomputed constants.
+        """
+        pass