fenicsx-beat 0.0.1__tar.gz

fenicsx_beat-0.0.1/LICENSE

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

fenicsx_beat-0.0.1/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.1
+Name: fenicsx-beat
+Version: 0.0.1
+Summary: Library to run cardiac EP simulations
+Author-email: Henrik Finsberg <henriknf@simula.no>
+License: MIT
+Project-URL: Homepage, https://finsberg.github.io/fenicsx-beat
+Project-URL: Documentation, https://finsberg.github.io/fenicsx-beat
+Project-URL: Source, https://github.com/finsberg/fenicsx-beat
+Project-URL: Tracker, https://github.com/finsberg/fenicsx-beat/issues
+Keywords: cardiac,electrophysiology
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: scifem>=0.2.14
+Requires-Dist: pint
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Provides-Extra: dev
+Requires-Dist: pre-commit; extra == "dev"
+Provides-Extra: pypi
+Requires-Dist: twine; extra == "pypi"
+Requires-Dist: build; extra == "pypi"
+Provides-Extra: demos
+Requires-Dist: cardiac-geometriesx; extra == "demos"
+Requires-Dist: fenicsx-ldrb; extra == "demos"
+Requires-Dist: gotranx; extra == "demos"
+Provides-Extra: docs
+Requires-Dist: jupyter-book; extra == "docs"
+Requires-Dist: jupytext; extra == "docs"
+Requires-Dist: fenicsx-beat[demos]; extra == "docs"
+Requires-Dist: ipywidgets; extra == "docs"
+Requires-Dist: imageio; extra == "docs"
+Requires-Dist: pyvista[jupyter]; extra == "docs"
+Provides-Extra: all
+Requires-Dist: fenicsx-beat[test]; extra == "all"
+Requires-Dist: fenicsx-beat[docs]; extra == "all"
+Requires-Dist: fenicsx-beat[pypi]; extra == "all"
+Requires-Dist: fenicsx-beat[dev]; extra == "all"
+Requires-Dist: fenicsx-beat[demos]; extra == "all"
+Provides-Extra: testpaths
+Requires-Dist: tests; extra == "testpaths"
+
+![_](https://raw.githubusercontent.com/finsberg/fenicsx-beat/refs/heads/main/docs/_static/logo.png)
+
+# fenicsx-beat
+Cardiac electrophysiology simulator in FEniCSx
+
+- Source code: https://github.com/finsberg/fenicsx-beat
+- Documentation: https://finsberg.github.io/fenicsx-beat
+
+
+## Install
+You can install the library with pip
+```
+python3 -m pip install fenicsx-beat
+```
+
+
+## Getting started
+
+```python
+from mpi4py import MPI
+import dolfinx
+import ufl
+import beat
+
+comm = MPI.COMM_WORLD
+mesh = dolfinx.mesh.create_unit_square(comm, 10, 10, dolfinx.cpp.mesh.CellType.triangle)
+time = dolfinx.fem.Constant(mesh, dolfinx.default_scalar_type(0.0))
+# Create stimulus
+stim_expr = ufl.conditional(ufl.And(ufl.ge(time, 0.0), ufl.le(time, 0.5)),200.0, 0.0)
+stim_marker = 1
+cells = dolfinx.mesh.locate_entities(mesh, mesh.topology.dim, lambda x: np.logical_and(x[0] <= 0.5, x[1] <= 0.5))
+stim_tags = dolfinx.mesh.meshtags(
+    mesh,
+    mesh.topology.dim,
+    cells,
+    np.full(len(cells), stim_marker, dtype=np.int32),
+)
+dx = ufl.Measure("dx", domain=mesh, subdomain_data=stim_tags)
+I_s = beat.Stimulus(expr=stim_expr, dZ=dx, marker=stim_marker)
+# Create PDE model
+pde = beat.MonodomainModel(time=time, mesh=mesh, M=0.01, I_s=I_s, dx=dx)
+# Define scheme to solve ODE
+def fun(t, states, parameters, dt):
+    v, s = states
+    a, b = parameters
+    values = np.zeros_like(states)
+    values[0] = v - a * s * dt
+    values[1] = s + b * v * dt
+    return values
+# Define ODE solver
+ode_space = dolfinx.fem.functionspace(mesh, ("P", 1))
+parameters = np.array([1.0, 1.0])
+init_states = np.array([0.0, 0.0])
+ode = beat.odesolver.DolfinODESolver(
+    v_ode=dolfinx.fem.Function(ode_space),
+    v_pde=pde.state,
+    fun=fun,
+    init_states=states,
+    parameters=parameters,
+    num_states=2,
+    v_index=1,
+)
+# Combine PDE and ODE solver
+solver = beat.MonodomainSplittingSolver(pde=pde, ode=ode)
+# Solve
+T = 5.0
+t = 0.0
+i = 0
+while t < T:
+    v = solver.pde.state.x.array
+    solver.step((t, t + dt))
+    i += 1
+    t += dt
+```
+![_](https://raw.githubusercontent.com/finsberg/fenicsx-beat/refs/heads/main/docs/_static/simple.gif)
+
+See more examples in the [documentation](https://finsberg.github.io/fenicsx-beat)
+
+## License
+MIT
+
+## Need help or having issues
+Please submit an [issue](https://github.com/finsberg/fenicsx-beat/issues)

fenicsx_beat-0.0.1/README.md

@@ -0,0 +1,83 @@
+![_](https://raw.githubusercontent.com/finsberg/fenicsx-beat/refs/heads/main/docs/_static/logo.png)
+
+# fenicsx-beat
+Cardiac electrophysiology simulator in FEniCSx
+
+- Source code: https://github.com/finsberg/fenicsx-beat
+- Documentation: https://finsberg.github.io/fenicsx-beat
+
+
+## Install
+You can install the library with pip
+```
+python3 -m pip install fenicsx-beat
+```
+
+
+## Getting started
+
+```python
+from mpi4py import MPI
+import dolfinx
+import ufl
+import beat
+
+comm = MPI.COMM_WORLD
+mesh = dolfinx.mesh.create_unit_square(comm, 10, 10, dolfinx.cpp.mesh.CellType.triangle)
+time = dolfinx.fem.Constant(mesh, dolfinx.default_scalar_type(0.0))
+# Create stimulus
+stim_expr = ufl.conditional(ufl.And(ufl.ge(time, 0.0), ufl.le(time, 0.5)),200.0, 0.0)
+stim_marker = 1
+cells = dolfinx.mesh.locate_entities(mesh, mesh.topology.dim, lambda x: np.logical_and(x[0] <= 0.5, x[1] <= 0.5))
+stim_tags = dolfinx.mesh.meshtags(
+    mesh,
+    mesh.topology.dim,
+    cells,
+    np.full(len(cells), stim_marker, dtype=np.int32),
+)
+dx = ufl.Measure("dx", domain=mesh, subdomain_data=stim_tags)
+I_s = beat.Stimulus(expr=stim_expr, dZ=dx, marker=stim_marker)
+# Create PDE model
+pde = beat.MonodomainModel(time=time, mesh=mesh, M=0.01, I_s=I_s, dx=dx)
+# Define scheme to solve ODE
+def fun(t, states, parameters, dt):
+    v, s = states
+    a, b = parameters
+    values = np.zeros_like(states)
+    values[0] = v - a * s * dt
+    values[1] = s + b * v * dt
+    return values
+# Define ODE solver
+ode_space = dolfinx.fem.functionspace(mesh, ("P", 1))
+parameters = np.array([1.0, 1.0])
+init_states = np.array([0.0, 0.0])
+ode = beat.odesolver.DolfinODESolver(
+    v_ode=dolfinx.fem.Function(ode_space),
+    v_pde=pde.state,
+    fun=fun,
+    init_states=states,
+    parameters=parameters,
+    num_states=2,
+    v_index=1,
+)
+# Combine PDE and ODE solver
+solver = beat.MonodomainSplittingSolver(pde=pde, ode=ode)
+# Solve
+T = 5.0
+t = 0.0
+i = 0
+while t < T:
+    v = solver.pde.state.x.array
+    solver.step((t, t + dt))
+    i += 1
+    t += dt
+```
+![_](https://raw.githubusercontent.com/finsberg/fenicsx-beat/refs/heads/main/docs/_static/simple.gif)
+
+See more examples in the [documentation](https://finsberg.github.io/fenicsx-beat)
+
+## License
+MIT
+
+## Need help or having issues
+Please submit an [issue](https://github.com/finsberg/fenicsx-beat/issues)

fenicsx_beat-0.0.1/pyproject.toml

@@ -0,0 +1,151 @@
+[build-system] # Require setuptool version due to https://github.com/pypa/setuptools/issues/2938
+requires = ["setuptools>=61.0.0", "wheel"]
+
+[project]
+name = "fenicsx-beat"
+version = "0.0.1"
+description = "Library to run cardiac EP simulations"
+authors = [{name = "Henrik Finsberg", email = "henriknf@simula.no"}]
+license = {text = "MIT"}
+readme = "README.md"
+requires-python = ">=3.8"
+keywords = ["cardiac", "electrophysiology"]
+dependencies = [
+    "numpy",
+    "scipy",
+    "scifem>=0.2.14",
+    "pint",
+]
+
+[project.urls]
+Homepage = "https://finsberg.github.io/fenicsx-beat"
+Documentation = "https://finsberg.github.io/fenicsx-beat"
+Source = "https://github.com/finsberg/fenicsx-beat"
+Tracker = "https://github.com/finsberg/fenicsx-beat/issues"
+
+[project.optional-dependencies]
+test = [
+    "pytest",
+    "pytest-cov",
+]
+dev = [
+    "pre-commit",
+]
+pypi = [
+    "twine",
+    "build"
+]
+demos = [
+   "cardiac-geometriesx",
+   "fenicsx-ldrb",
+   "gotranx"
+]
+docs = [
+   "jupyter-book",
+   "jupytext",
+   "fenicsx-beat[demos]",
+   "ipywidgets",
+   "imageio",
+   "pyvista[jupyter]",
+]
+all = [
+   "fenicsx-beat[test]",
+   "fenicsx-beat[docs]",
+   "fenicsx-beat[pypi]",
+   "fenicsx-beat[dev]",
+   "fenicsx-beat[demos]"
+]
+
+
+testpaths = [
+    "tests"
+]
+[tool.ruff]
+# Exclude a variety of commonly ignored directories.
+exclude = [
+    "demo/*.py",
+    ".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",
+    "demos",
+]
+
+# Same as Black.
+line-length = 100
+
+# Allow unused variables when underscore-prefixed.
+
+# Assume Python 3.10.
+target-version = "py310"
+
+
+[tool.ruff.lint]
+# Enable pycodestyle (`E`) and Pyflakes (`F`) codes by default.
+select = ["E", "F", "I"]
+ignore = ["E402", "E741", "E743", "E731"]
+
+# Allow autofix for all enabled rules (when `--fix`) is provided.
+fixable = ["A", "B", "C", "D", "E", "F", "I"]
+unfixable = []
+
+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.isort]
+known-third-party = [
+    "basix",
+    "dolfinx",
+    "ffcx",
+    "ufl",
+    "gmsh",
+    "numpy",
+    "pytest",
+]
+section-order = [
+    "future",
+    "standard-library",
+    "mpi",
+    "third-party",
+    "first-party",
+    "local-folder",
+]
+[tool.ruff.lint.isort.sections]
+"mpi" = ["mpi4py", "petsc4py"]
+
+
+[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.0.1"
+
+
+[[tool.bumpversion.files]]
+filename = "pyproject.toml"
+search = 'version = "{current_version}"'
+replace = 'version = "{new_version}"'

fenicsx_beat-0.0.1/setup.cfg

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

fenicsx_beat-0.0.1/src/beat/__init__.py

@@ -0,0 +1,32 @@
+from . import (
+    base_model,
+    conductivities,
+    ecg,
+    geometry,
+    monodomain_model,
+    monodomain_solver,
+    odesolver,
+    single_cell,
+    stimulation,
+    utils,
+)
+from .monodomain_model import MonodomainModel
+from .monodomain_solver import MonodomainSplittingSolver
+from .stimulation import Stimulus
+
+__all__ = [
+    "monodomain_model",
+    "odesolver",
+    "base_model",
+    "MonodomainModel",
+    "monodomain_solver",
+    "MonodomainSplittingSolver",
+    "utils",
+    "conductivities",
+    "stimulation",
+    "geometry",
+    "single_cell",
+    "stimulation",
+    "ecg",
+    "Stimulus",
+]

fenicsx_beat-0.0.1/src/beat/base_model.py

@@ -0,0 +1,268 @@
+from __future__ import annotations
+
+import abc
+import logging
+from enum import Enum, auto
+from typing import Any, Literal, NamedTuple, Sequence
+
+from petsc4py import PETSc
+
+import dolfinx
+import dolfinx.fem.petsc
+import ufl
+from ufl.core.expr import Expr
+
+from .stimulation import Stimulus
+
+logger = logging.getLogger(__name__)
+
+
+class Status(str, Enum):
+    OK = auto()
+    NOT_CONVERGING = auto()
+
+
+class Results(NamedTuple):
+    state: dolfinx.fem.Function
+    status: Status
+
+
+def _transform_I_s(
+    I_s: Stimulus | Sequence[Stimulus] | ufl.Coefficient | None,
+    dZ: ufl.Measure,
+) -> list[Stimulus]:
+    if I_s is None:
+        return [Stimulus(expr=ufl.zero(), dZ=dZ)]
+    if isinstance(I_s, Stimulus):
+        return [I_s]
+    if isinstance(I_s, ufl.core.expr.Expr):
+        return [Stimulus(expr=I_s, dZ=dZ)]
+
+    # FIXME: Might need more checks here
+    return list(I_s)
+
+
+class BaseModel:
+    """
+    Base class for models.
+
+    Parameters
+    ----------
+    time : dolfinx.fem.Constant
+        The current time
+    mesh : dolfinx.mesh.Mesh
+        The mesh
+    dx : ufl.Measure, optional
+        The measure for the spatial domain, by default None
+    params : dict, optional
+        Parameters for the model, by default None
+    I_s : Stimulus | Sequence[Stimulus] | ufl.Coefficient, optional
+        The stimulus, by default None
+    jit_options : dict, optional
+        JIT options, by default None
+    form_compiler_options : dict, optional
+        Form compiler options, by default None
+    petsc_options : dict, optional
+        PETSc options, by default None
+
+    """
+
+    def __init__(
+        self,
+        time: dolfinx.fem.Constant,
+        mesh: dolfinx.mesh.Mesh,
+        dx: ufl.Measure | None = None,
+        params: dict[str, Any] | None = None,
+        I_s: Stimulus | Sequence[Stimulus] | ufl.Coefficient | None = None,
+        jit_options: dict[str, Any] | None = None,
+        form_compiler_options: dict[str, Any] | None = None,
+        petsc_options: dict[str, Any] | None = None,
+    ) -> None:
+        self._mesh = mesh
+        self.time = time
+        self.dx = dx or ufl.dx(domain=mesh)
+
+        self.parameters = type(self).default_parameters()
+        if params is not None:
+            self.parameters.update(params)
+
+        self._I_s = _transform_I_s(I_s, dZ=self.dx)
+
+        self._setup_state_space()
+
+        self._timestep = dolfinx.fem.Constant(mesh, self.parameters["default_timestep"])
+        a, L = self.variational_forms(self._timestep)
+        self._solver = dolfinx.fem.petsc.LinearProblem(
+            a,
+            L,
+            u=self.state,
+            form_compiler_options=form_compiler_options,
+            jit_options=jit_options,
+            petsc_options=petsc_options,
+        )
+        dolfinx.fem.petsc.assemble_matrix(self._solver.A, self._solver.a)  # type: ignore
+        self._solver.A.assemble()
+
+    @abc.abstractmethod
+    def _setup_state_space(self) -> None: ...
+
+    @property
+    @abc.abstractmethod
+    def state(self) -> dolfinx.fem.Function: ...
+
+    @abc.abstractmethod
+    def assign_previous(self) -> None: ...
+
+    @staticmethod
+    def default_parameters(
+        solver_type: Literal["iterative", "direct"] = "direct",
+    ) -> dict[str, Any]:
+        if solver_type == "iterative":
+            petsc_options = {
+                "ksp_type": "cg",
+                # "pc_type": "hypre",
+                "pc_type": "petsc_amg",
+                "pc_hypre_type": "boomeramg",
+                # "ksp_norm_type": "unpreconditioned",
+                # "ksp_atol": 1e-15,
+                # "ksp_rtol": 1e-10,
+                # "ksp_max_it": 10_000,
+                # "ksp_error_if_not_converged": False,
+            }
+        else:
+            petsc_options = {
+                "ksp_type": "preonly",
+                "pc_type": "lu",
+                "pc_factor_mat_solver_type": "mumps",
+            }
+        return {
+            "theta": 0.5,
+            "degree": 1,
+            "family": "Lagrange",
+            "default_timestep": 1.0,
+            "jit_options": {},
+            "form_compiler_options": {},
+            "petsc_options": petsc_options,
+        }
+
+    @abc.abstractmethod
+    def variational_forms(self, dt: Expr | float) -> tuple[ufl.Form, ufl.Form]:
+        """Create the variational forms corresponding to the given
+        discretization of the given system of equations.
+
+        Parameters
+        ----------
+        dt : Expr | float
+            The time step
+
+        Returns
+        -------
+        tuple[ufl.Form, ufl.Form]
+            The variational form and the precondition
+
+        """
+        ...
+
+    def _update_matrices(self):
+        """
+        Re-assemble matrix.
+        """
+        self._solver.A.zeroEntries()
+        dolfinx.fem.petsc.assemble_matrix(self._solver.A, self._solver.a)  # type: ignore
+        self._solver.A.assemble()
+
+    def _update_rhs(self):
+        """
+        Re-assemble RHS vector
+        """
+        with self._solver.b.localForm() as b_loc:
+            b_loc.set(0)
+        dolfinx.fem.petsc.assemble_vector(self._solver.b, self._solver.L)
+        self._solver.b.ghostUpdate(
+            addv=PETSc.InsertMode.ADD,
+            mode=PETSc.ScatterMode.REVERSE,
+        )
+
+    def step(self, interval):
+        """
+        Perform a single time step.
+
+        Parameters
+        ----------
+        interval : tuple[float, float]
+            The time interval (T0, T)
+
+        """
+
+        # timer = dolfin.Timer("PDE Step")
+
+        # Extract interval and thus time-step
+        (t0, t1) = interval
+        dt = t1 - t0
+        theta = self.parameters["theta"]
+        t = t0 + theta * dt
+        self.time.value = t
+
+        # Update matrix and linear solvers etc as needed
+        timestep_unchanged = abs(dt - float(self._timestep)) < 1.0e-12
+        if not timestep_unchanged:
+            self._timestep.value = dt
+            self._update_matrices()
+
+        self._update_rhs()
+        # Solve linear system and update ghost values in the solution
+
+        self._solver.solver.solve(self._solver.b, self.state.x.petsc_vec)
+        self.state.x.scatter_forward()
+
+    def _G_stim(self, w):
+        return sum([i.expr * w * i.dz for i in self._I_s])
+
+    def solve(
+        self,
+        interval: tuple[float, float],
+        dt: float | None = None,
+    ) -> Results:
+        """
+        Solve on the given time interval.
+
+        Parameters
+        ----------
+        interval : tuple[float, float]
+            The time interval (T0, T)
+        dt : float, optional
+            The time step, by default None
+
+        Returns
+        -------
+        Results
+            The results of the solution
+
+        """
+
+        # Initial set-up
+        # Solve on entire interval if no interval is given.
+        (T0, T) = interval
+        if dt is None:
+            dt = T - T0
+        t0 = T0
+        t1 = T0 + dt
+
+        # Step through time steps until at end time
+        while True:
+            logger.info("Solving on t = (%g, %g)" % (t0, t1))
+            self.step((t0, t1))
+
+            # Yield solutions
+            # yield (t0, t1), self.solution_fields()
+
+            # Break if this is the last step
+            if (t1 + dt) > (T + 1e-12):
+                break
+
+            self.assign_previous()
+
+            t0 = t1
+            t1 = t0 + dt
+
+        return Results(state=self.state, status=Status.OK)