finitewave-model-barkley 0.2.0__tar.gz

finitewave_model_barkley-0.2.0/.gitignore

@@ -0,0 +1,207 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/

finitewave_model_barkley-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Finitewave
+
+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.

finitewave_model_barkley-0.2.0/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: finitewave-model-barkley
+Version: 0.2.0
+Summary: Barkley model.
+License: MIT
+License-File: LICENSE
+Keywords: cardiac,electrophysiology,finitewave,model
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+## Barkley Finitewave model
+
+The Barkley model is a simplified two-variable reaction–diffusion system
+originally developed to study wave propagation in excitable media. While it is 
+not biophysically detailed, it captures essential qualitative features of 
+cardiac-like excitation dynamics such as spiral waves, wave break, and reentry.
+
+This model implementation can be used separately from the Finitewave, allowing for standalone simulations and testing of the model dynamics without the need for the entire framework.
+
+### Reference
+Barkley, D. (1991).
+A model for fast computer simulation of waves in excitable media.
+Physica D: Nonlinear Phenomena, 61-70.
+
+DOI: https://doi.org/10.1016/0167-2789(86)90198-1.
+
+### How to use (quickstart)
+```bash
+python -m examples.barkley_example
+```
+
+### How to test
+```bash
+python -m pytest -q
+```
+
+### Repository structure
+```text
+.
+├── barkley/                 # equations package (ops.py)
+│   ├── __init__.py
+│   └── ops.py               # model equations (pure functions)
+├── implementation/          # 0D model implementation
+│   ├── __init__.py
+│   └── barkley_0d.py
+├── example/
+│   └── barkley_example.py   # minimal script to run a short trace
+├── tests/
+│   └── test.py              # smoke test; reproducibility checks
+├── .gitignore
+├── LICENSE                  # MIT
+├── pyproject.toml           # configuration file
+└── README.md                # this file
+```
+
+### Variables
+- `u` — Transmembrane potential (dimensionless).
+- `v` — Recovery variable (dimensionless).
+
+### Parameters
+- `a = 0.75`   - Threshold-like parameter controlling excitability.
+- `b = 0.02`   - Recovery time scale.
+- `eps = 0.02` - Controls sharpness of the activation term (nonlinear gain).

finitewave_model_barkley-0.2.0/README.md

@@ -0,0 +1,53 @@
+## Barkley Finitewave model
+
+The Barkley model is a simplified two-variable reaction–diffusion system
+originally developed to study wave propagation in excitable media. While it is 
+not biophysically detailed, it captures essential qualitative features of 
+cardiac-like excitation dynamics such as spiral waves, wave break, and reentry.
+
+This model implementation can be used separately from the Finitewave, allowing for standalone simulations and testing of the model dynamics without the need for the entire framework.
+
+### Reference
+Barkley, D. (1991).
+A model for fast computer simulation of waves in excitable media.
+Physica D: Nonlinear Phenomena, 61-70.
+
+DOI: https://doi.org/10.1016/0167-2789(86)90198-1.
+
+### How to use (quickstart)
+```bash
+python -m examples.barkley_example
+```
+
+### How to test
+```bash
+python -m pytest -q
+```
+
+### Repository structure
+```text
+.
+├── barkley/                 # equations package (ops.py)
+│   ├── __init__.py
+│   └── ops.py               # model equations (pure functions)
+├── implementation/          # 0D model implementation
+│   ├── __init__.py
+│   └── barkley_0d.py
+├── example/
+│   └── barkley_example.py   # minimal script to run a short trace
+├── tests/
+│   └── test.py              # smoke test; reproducibility checks
+├── .gitignore
+├── LICENSE                  # MIT
+├── pyproject.toml           # configuration file
+└── README.md                # this file
+```
+
+### Variables
+- `u` — Transmembrane potential (dimensionless).
+- `v` — Recovery variable (dimensionless).
+
+### Parameters
+- `a = 0.75`   - Threshold-like parameter controlling excitability.
+- `b = 0.02`   - Recovery time scale.
+- `eps = 0.02` - Controls sharpness of the activation term (nonlinear gain).

finitewave_model_barkley-0.2.0/barkley/__init__.py

@@ -0,0 +1 @@
+from . import ops

finitewave_model_barkley-0.2.0/barkley/ops.py

@@ -0,0 +1,77 @@
+"""
+ops.py — mathematical core of the model.
+
+This module provides functions to compute the model equations,
+as well as functions to retrieve default parameters and initial
+values for the state variables.
+
+References:
+"""
+
+__all__ = (
+    "get_variables",
+    "get_parameters",
+    "calc_rhs",
+    "calc_dv",
+)
+
+
+def get_variables() -> dict[str, float]:
+    """
+    Returns default initial values for state variables.
+    """
+    return {"u": 0.0, "v": 0.0}
+
+
+def get_parameters() -> dict[str, float]:
+    """
+    Returns default parameter values for the model.
+    """
+    return {"a": 0.75, "b": 0.02, "eps": 0.02}
+
+
+def calc_rhs(u, v, a, b, eps) -> float:
+    """
+    Computes the right-hand side of the model.
+
+    Parameters
+    ----------
+    u : float
+        Current value of the excitation variable.
+    v : float
+        Current value of the recovery variable.
+    a : float
+        Parameter controlling the excitation threshold.
+    b : float
+        Parameter influencing the recovery dynamics.
+    eps : float
+        Parameter scaling the time dynamics.
+    
+    Returns
+    -------
+    float
+        Right-hand side of the model.
+    """
+    return (u*(1 - u)*(u - (v + b)/a))/eps
+
+
+def calc_dv(v, u):
+    """
+    Calculates the recovery variable v for the Barkley model.
+
+    The recovery variable follows a simple linear relaxation toward the
+    excitation variable `u`, simulating return to the resting state after excitation.
+
+    Parameters
+    ----------
+    v : float
+        Current value of the recovery variable.
+    u : float
+        Current value of the excitation variable.
+
+    Returns
+    -------
+    float
+        Updated value of the recovery variable.
+    """
+    return (u-v)

finitewave_model_barkley-0.2.0/examples/barkley_example.py

@@ -0,0 +1,27 @@
+"""
+Example script to run a 0D model simulation and plot the results.
+
+This script sets up a simple stimulation protocol, runs the simulation,
+and plots the membrane potential over time.
+"""
+
+import numpy as np
+import matplotlib.pyplot as plt
+
+from implementation.barkley_0d import Barkley0D, Stimulation
+
+
+stimulations = [Stimulation(t_start=0.1, duration=0.2, amplitude=1.0)]
+t_max = 100.0
+
+model = Barkley0D(dt=0.01, stimulations=stimulations)
+model.run(t_max=t_max)
+
+time = np.arange(0, t_max, model.dt)
+plt.plot(time, model.history['u'])
+plt.xlabel('Time (s)')
+plt.ylabel('Membrane Potential (u)')
+plt.title('0D Model Simulation')
+plt.grid()
+plt.show()
+

finitewave_model_barkley-0.2.0/implementation/barkley_0d.py

@@ -0,0 +1,106 @@
+"""
+This module provides a simple interface to run the model in a 0D setting,
+i.e., without spatial dimensions. It includes class for defining stimulation protocols
+and a class for the 0D model itself.
+
+"""
+
+from barkley import ops
+
+
+class Stimulation:
+    """
+    Stimulus protocol for the 0D model.
+
+    Parameters
+    ----------
+    t_start : float
+        Start time (ms) of the first stimulus window.
+    duration : float
+        Duration (ms) of a single pulse.
+    amplitude : float
+        Pulse amplitude in the same units as du/dt contribution (typically "units/ms").
+
+    Method
+    ------
+    stim(t: float) -> float
+        Returns the instantaneous stimulus value at time t.
+
+    """
+
+    def __init__(self, t_start: float, duration: float, amplitude: float):
+        self.t_start = t_start
+        self.duration = duration
+        self.amplitude = amplitude
+
+    def stim(self, t: float) -> float:
+        return self.amplitude if self.t_start <= t < self.t_start + self.duration else 0.0
+
+
+class Barkley0D:
+    """
+    Model OD implementation.
+
+    Parameters
+    ----------
+
+    dt : float
+        Time step size (ms).
+    stimulations : list[Stimulation]
+        List of stimulation protocols to apply during the simulation.
+
+    Attributes
+    ----------
+    variables : dict[str, float]
+        Current state variables of the model.
+    parameters : dict[str, float]
+        Model parameters.
+    history : dict[str, list[float]]
+        Time history of state variables for post-processing.
+    
+    Methods
+    -------
+    step(i: int)
+        Perform a single time step update.
+    run(t_max: float)
+        Run the simulation up to time t_max.
+    """
+    def __init__(self, dt: float, stimulations: list[Stimulation]):
+        self.dt = dt
+        self.stimulations = stimulations
+        self.variables = ops.get_variables()
+        self.parameters = ops.get_parameters()
+        self.history = {s: [] for s in self.variables}
+
+    def step(self, i: int):
+        """
+        Perform a single time step update.
+
+        Parameters
+        ----------
+        i : int
+            Current time step index.
+        """
+        self.variables["v"] += self.dt*ops.calc_dv(self.variables["v"], self.variables["u"])
+
+        self.variables["u"] += self.dt*(ops.calc_rhs(self.variables["u"],
+                                                self.variables["v"], 
+                                                self.parameters["a"], 
+                                                self.parameters["b"],
+                                                self.parameters["eps"])
+                                + sum(stim.stim(t=self.dt*i) for stim in self.stimulations))
+
+    def run(self, t_max: float):
+        """
+        Run the simulation up to time t_max.
+        
+        Parameters
+        ----------
+        t_max : float
+            Maximum simulation time.
+        """
+        n_steps = int(round(t_max/self.dt))
+        for i in range(n_steps):
+            self.step(i)
+            for s in self.variables:
+                self.history[s].append(self.variables[s])

finitewave_model_barkley-0.2.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["hatchling>=1.21.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "finitewave-model-barkley"
+version = "0.2.0"
+description = "Barkley model."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+keywords = ["cardiac", "electrophysiology", "finitewave", "model"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Intended Audience :: Science/Research",
+  "Topic :: Scientific/Engineering :: Medical Science Apps."
+]
+
+dependencies = []
+
+[project.entry-points."finitewave.models"]
+barkley = "barkley.ops"
+
+[tool.hatch.build.targets.wheel]
+packages = ["barkley"]
+
+[tool.hatch.metadata]
+allow-direct-references = true

finitewave_model_barkley-0.2.0/tests/barkley_test.py

@@ -0,0 +1,102 @@
+import numpy as np
+import pytest
+
+from implementation.barkley_0d import Barkley0D, Stimulation
+
+
+def prepare_model(model_class, dt, curr_dur, curr_value, t_prebeats):
+    """
+    Prepares a 2D cardiac model with a stimulation protocol.
+
+    Parameters
+    ----------
+    model_class : Callable
+        The cardiac model class to be instantiated.
+    dt : float
+        Time step for the simulation (ms or model units).
+    curr_value : float
+        Amplitude of the stimulus current (μA/cm² or model units).
+    curr_dur : float
+        Duration of each stimulus pulse (ms or model units).
+    t_prebeats : float
+        Interval between preconditioning stimuli (ms or model units).
+
+    Returns
+    -------
+    model : Model
+        Configured and initialized model ready for simulation.
+    """
+
+    stimulations = [Stimulation(t_start=0.0, duration=curr_dur, amplitude=curr_value),
+                    Stimulation(t_start=t_prebeats, duration=curr_dur, amplitude=curr_value),
+                    Stimulation(t_start=2*t_prebeats, duration=curr_dur, amplitude=curr_value),
+                    Stimulation(t_start=3*t_prebeats, duration=curr_dur, amplitude=curr_value)]
+
+    model = model_class(dt=dt, stimulations=stimulations)
+
+    return model
+
+
+def calculate_apd(u, dt, threshold, beat_index=3):
+    """
+    Calculates the action potential duration (APD) for a single beat (third by default).
+
+    Parameters
+    ----------
+    u : np.ndarray
+        Membrane potential time series.
+    dt : float
+        Time step of the simulation (ms).
+    threshold : float
+        Voltage threshold to define APD90 (e.g., -70 mV or 0.1 for normalized models).
+    beat_index : int, optional
+        Index of the beat to analyze (default is 3).
+
+    Returns
+    -------
+    apd : float or None
+        Duration of the action potential (ms or model units), or None if no complete AP was found.
+    """
+    up_idx = np.where((u[:-1] < threshold) & (u[1:] >= threshold))[0]
+    down_idx = np.where((u[:-1] > threshold) & (u[1:] <= threshold))[0]
+
+    if len(up_idx) <= beat_index or len(down_idx) == 0:
+        return None
+
+    ap_start = up_idx[beat_index]
+    ap_end_candidates = down_idx[down_idx > ap_start]
+    if len(ap_end_candidates) == 0:
+        return None
+
+    ap_end = ap_end_candidates[0]
+    return (ap_end - ap_start) * dt
+
+
+def test_model_attributes():
+    """
+    Test that the model has the expected attributes.
+    Checks for the presence of key variables and parameters in the 0D Model.
+    """
+    model = Barkley0D(dt=0.01, stimulations=[])
+
+    assert 'u' in model.variables, "Model should have variable 'u'"
+
+
+def test_model_run():
+    """
+    Test the model run for a short simulation.
+    Runs the 0D Model with a predefined stimulation protocol and checks
+    that the membrane potential 'u' stays within expected physiological ranges.
+    """
+    t_prebeats = 60.0 # interval between preconditioning stimuli (ms or model units).
+    t_calc = 80.0     # time after the last preconditioning beat to continue recording (ms or model units).
+    t_max = 3*t_prebeats + t_calc
+    model = prepare_model(Barkley0D, dt=0.01, curr_dur=0.1, curr_value=5.0, t_prebeats=t_prebeats)
+    model.run(t_max=t_max)
+    u = np.array(model.history['u'])
+
+    assert np.max(u) == pytest.approx(1.0, abs=0.1)
+    assert np.min(u) == pytest.approx(0.0, abs=0.01)
+
+    apd = calculate_apd(u, model.dt, threshold=0.1)
+    assert 1 <= apd <= 4, f"Model is out of expected range {apd}"