finitewave 0.9.0__py3-none-any.whl

finitewave/README.md

@@ -0,0 +1,20 @@
+# Finitewave
+
+Package for a wide range of tasks in modeling cardiac electrophysiology using
+finite-difference methods.
+
+## Package structure
+
+### core
+
+Base classes subpackage. Use this subpackage to create your own implementation
+and incorporate it in the package logic.
+
+### cpuwave
+
+Ready-to-use implementation for cardiac modeling problems. Contains prepared models,
+tissue generation methods, optimized numerical schemes and specialized tools.  
+
+### tools
+
+Additional methods to treat the results and make different visual representations.

finitewave/__init__.py

@@ -0,0 +1,126 @@
+
+"""
+finitewave
+==========
+
+A Python package for simulating cardiac electrophysiology in 2D and 3D using
+the finite difference method.
+
+This package provides a set of tools for simulating cardiac electrophysiology
+in 2D and 3D using the finite difference method. The package includes classes
+for creating cardiac tissue models, tracking electrical activity, and
+visualizing simulation results. The package is designed to be flexible and
+extensible, allowing users to create custom models and trackers for their
+specific research needs.
+
+"""
+
+from finitewave.core import (
+    Command,
+    CommandSequence,
+    FibrosisPattern,
+    CardiacModel,
+    StateLoader,
+    StateSaver,
+    StateSaverCollection,
+    Stencil,
+    StimCurrent,
+    StimSequence,
+    StimVoltage,
+    Stim,
+    CardiacTissue,
+    Tracker,
+    TrackerSequence
+)
+
+from finitewave.cpuwave import (
+    # IncorrectWeightsModeError2D,
+    DiffusePattern,
+    StructuralPattern,
+    AlievPanfilov,
+    Barkley,
+    MitchellSchaeffer,
+    FentonKarma,
+    BuenoOrovio,
+    LuoRudy91,
+    TenTusscherPanfilov2006,
+    Courtemanche,
+    AsymmetricStencil2D,
+    # SymmetricStencil2D,
+    IsotropicStencil2D,
+    StimCurrentArea,
+    StimCurrentCoord,
+    StimVoltageCoord,
+    StimCurrentMatrix,
+    StimVoltageMatrix,
+    ActionPotentialTracker,
+    ActivationTimeTracker,
+    AnimationTracker,
+    ECGTracker,
+    LocalActivationTimeTracker,
+    PeriodTracker,
+    # PeriodAnimationTracker,
+    SpiralWaveCoreTracker,
+    VariablesTracker,
+)
+
+from finitewave.tools import (
+    Animation2DBuilder,
+    Animation3DBuilder,
+    VisMeshBuilder3D,
+    Velocity2DCalculation,
+    Velocity3DCalculation,
+)
+
+
+# compatibility with older versions:
+
+CardiacTissue2D = CardiacTissue
+CardiacTissue3D = CardiacTissue
+
+AlievPanfilov2D = AlievPanfilov
+AlievPanfilov3D = AlievPanfilov
+Barkley2D = Barkley
+Barkley3D = Barkley
+MitchellSchaeffer2D = MitchellSchaeffer
+MitchellSchaeffer3D = MitchellSchaeffer
+FentonKarma2D = FentonKarma
+FentonKarma3D = FentonKarma
+BuenoOrovio2D = BuenoOrovio
+BuenoOrovio3D = BuenoOrovio
+LuoRudy912D = LuoRudy91
+LuoRudy913D = LuoRudy91
+TP062D = TenTusscherPanfilov2006
+TP063D = TenTusscherPanfilov2006
+Courtemanche2D = Courtemanche
+Courtemanche3D = Courtemanche
+
+StimCurrentArea2D = StimCurrentArea
+StimCurrentArea3D = StimCurrentArea
+StimCurrentCoord2D = StimCurrentCoord
+StimCurrentCoord3D = StimCurrentCoord
+StimVoltageCoord2D = StimVoltageCoord
+StimVoltageCoord3D = StimVoltageCoord
+StimCurrentMatrix2D = StimCurrentMatrix
+StimCurrentMatrix3D = StimCurrentMatrix
+StimVoltageMatrix2D = StimVoltageMatrix
+StimVoltageMatrix3D = StimVoltageMatrix
+
+ActionPotential2DTracker = ActionPotentialTracker
+ActionPotential3DTracker = ActionPotentialTracker
+ActivationTime2DTracker = ActivationTimeTracker
+ActivationTime3DTracker = ActivationTimeTracker
+Animation2DTracker = AnimationTracker
+Animation3DTracker = AnimationTracker
+ECG2DTracker = ECGTracker
+ECG3DTracker = ECGTracker
+LocalActivationTime2DTracker = LocalActivationTimeTracker
+LocalActivationTime3DTracker = LocalActivationTimeTracker
+Period2DTracker = PeriodTracker
+Period3DTracker = PeriodTracker
+SpiralWaveCore2DTracker = SpiralWaveCoreTracker
+SpiralWaveCore3DTracker = SpiralWaveCoreTracker
+Variables2DTracker = VariablesTracker
+Variables3DTracker = VariablesTracker
+MultiVariable2DTracker = VariablesTracker
+MultiVariable3DTracker = VariablesTracker

finitewave/core/__init__.py

@@ -0,0 +1,8 @@
+from finitewave.core.command import Command, CommandSequence
+from finitewave.core.fibrosis import FibrosisPattern 
+from finitewave.core.model import CardiacModel
+from finitewave.core.state import StateLoader, StateSaver, StateSaverCollection
+from finitewave.core.stencil import Stencil
+from finitewave.core.stimulation import StimCurrent, StimSequence, StimVoltage, Stim
+from finitewave.core.tissue import CardiacTissue
+from finitewave.core.tracker import Tracker, TrackerSequence

finitewave/core/command/__init__.py

@@ -0,0 +1,2 @@
+from finitewave.core.command.command import Command
+from finitewave.core.command.command_sequence import CommandSequence

finitewave/core/command/command.py

@@ -0,0 +1,52 @@
+from abc import ABC, abstractmethod
+
+
+class Command(ABC):
+    """Base class for a command to be executed during a simulation.
+
+    Attributes
+    ----------
+    t : float
+        The time at which the command should be executed.
+
+    passed : bool
+        Flag indicating whether the command has been executed.
+    """
+
+    def __init__(self, time=None):
+        """
+        Initializes a Command instance with the specified execution time.
+
+        Parameters
+        ----------
+        time : float
+            The time at which the command should be executed.
+        """
+        self.t = time
+        self.passed = False
+
+    @abstractmethod
+    def execute(self, model):
+        """
+        Abstract method for executing the command. This method should be
+        implemented by subclasses to define the specific behavior of the
+        command.
+
+        Parameters
+        ----------
+        model : CardiacModel
+            The cardiac model instance on which the command will be executed.
+        """
+        pass
+
+    def update_status(self, model):
+        """
+        Marks the command as executed.
+
+        Parameters
+        ----------
+        model : CardiacModel
+            The cardiac model instance on which the command was executed
+        """
+        self.passed = model.t >= self.t
+        return self.passed

finitewave/core/command/command_sequence.py

@@ -0,0 +1,59 @@
+
+
+class CommandSequence:
+    """Manages a sequence of commands to be executed during a simulation.
+
+    Attributes
+    ----------
+    sequence : list
+        A list of ``Command`` instances representing the sequence of commands
+        to be executed.
+
+    model : CardiacModel
+        The cardiac model instance on which commands will be executed.
+    """
+
+    def __init__(self):
+        self.sequence = []
+        self.model = None
+
+    def initialize(self, model):
+        """
+        Initializes the CommandSequence with the specified model and resets
+        the execution status of all commands.
+
+        Parameters
+        ----------
+        model : CardiacModel
+            The cardiac model instance to be used for command execution.
+        """
+        self.model = model
+        for command in self.sequence:
+            command.passed = False
+
+    def add_command(self, command):
+        """
+        Adds a ``Command`` instance to the sequence.
+
+        Parameters
+        ----------
+        command : Command
+            The command instance to be added to the sequence.
+        """
+        self.sequence.append(command)
+
+    def remove_commands(self):
+        """
+        Clears the sequence of all commands.
+        """
+        self.sequence = []
+
+    def execute_next(self):
+        """
+        Executes commands whose time has arrived and which have not been
+        executed yet.
+        """
+        for command in self.sequence:
+            if not command.passed and command.update_status(self.model):
+                command.execute(self.model)
+

finitewave/core/exception/__init__.py

@@ -0,0 +1 @@
+from finitewave.core.exception.exceptions import IncorrectNumberOfWeights

finitewave/core/exception/exceptions.py

@@ -0,0 +1,46 @@
+
+
+class IncorrectWeightsShapeError(Exception):
+    def __init__(self, *args: object) -> None:
+        super().__init__(*args)
+
+
+class IncorrectNumberOfWeights(Exception):
+    """Exception raised for errors in the shape of weights in the
+    ``CardiacTissue`` class.
+
+    This exception is used to indicate that the shape of weights provided does
+    not match the expected dimensions. It includes details about the incorrect
+    shape and the expected shapes.
+
+    Parameters
+    ----------
+    number_of_weights : int
+        The number of weights in the incorrect shape.
+
+    n1 : int
+        The target number of weights in one dimension.
+
+    n2 : int
+        The target number of weights in another dimension.
+    """
+
+    def __init__(self, number_of_weights, n1, n2):
+        """
+        Initializes the ``IncorrectNumberOfWeights`` with details about the
+        incorrect shape and expected dimensions.
+
+        Parameters
+        ----------
+        number_of_weights : int
+            The number of weights in the incorrect shape.
+
+        n1 : int
+            The target number of weights in one dimension.
+
+        n2 : int
+            The target number of weights in another dimension.
+        """
+        self.message = (f"Number of weights provided ({number_of_weights})" +
+                        f"does not match the expected {n1} or {n2}.")
+        super().__init__(self.message)

finitewave/core/fibrosis/__init__.py

@@ -0,0 +1 @@
+from finitewave.core.fibrosis.fibrosis_pattern import FibrosisPattern

finitewave/core/fibrosis/fibrosis_pattern.py

@@ -0,0 +1,51 @@
+from abc import ABC, abstractmethod
+
+
+class FibrosisPattern(ABC):
+    """Abstract base class for generating and applying fibrosis patterns to
+    cardiac tissue.
+
+    This class defines an interface for creating fibrosis patterns and applying
+    them to cardiac tissue models. Subclasses must implement the ``generate``
+    method to define specific patterns. The ``apply`` method uses the generated
+    pattern to modify the mesh of the cardiac tissue.
+    """
+    def __init__(self):
+        pass
+
+    @abstractmethod
+    def generate(self, shape=None, mesh=None):
+        """
+        Generates a fibrosis pattern for the given shape and optionally based
+        on the provided mesh.
+
+        Parameters
+        ----------
+        shape : tuple
+            The shape of the mesh (e.g., (ni, nj) or (ni, nj, nk)).
+        mesh : numpy.ndarray, optional
+            The existing mesh to base the pattern on. Default is None.
+
+        Returns
+        -------
+        numpy.ndarray
+            A new mesh array with the applied fibrosis pattern.
+        """
+
+    def apply(self, cardiac_tissue):
+        """
+        Applies the generated fibrosis pattern to the specified cardiac tissue
+        object.
+
+        This method calls the ``generate`` method to create the pattern and
+        then updates the ``mesh`` attribute of the ``cardiac_tissue`` object
+        with the generated pattern.
+
+        Parameters
+        ----------
+        cardiac_tissue : CardiacTissue
+            The cardiac tissue object to which the fibrosis pattern will be
+            applied. The ``mesh`` attribute of this object will be updated with
+            the generated pattern.
+        """
+        cardiac_tissue.mesh = self.generate(mesh=cardiac_tissue.mesh)

finitewave/core/model/__init__.py

@@ -0,0 +1 @@
+from finitewave.core.model.cardiac_model import CardiacModel

finitewave/core/model/cardiac_model.py

@@ -0,0 +1,315 @@
+from abc import ABC, abstractmethod
+import copy
+import warnings
+from tqdm import tqdm
+import numpy as np
+import numba
+
+
+class CardiacModel(ABC):
+    """
+    Base class for electrophysiological models.
+
+    This class serves as the base for implementing various cardiac models.
+    It provides methods for initializing the model, running simulations,
+    and managing the state of the simulation.
+
+    Attributes
+    ----------
+    cardiac_tissue : CardiacTissue
+        The tissue object that represents the cardiac tissue in the simulation.
+    stim_sequence : StimSequence
+        The sequence of stimuli applied to the cardiac tissue.
+    tracker_sequence : TrackerSequence
+        The sequence of trackers used to monitor the simulation.
+    command_sequence : CommandSequence
+        The sequence of commands to execute during the simulation.
+    state_loader : StateLoader
+        The object responsible for loading the state of the simulation.
+    state_saver : StateSaver
+        The object responsible for saving the state of the simulation.
+    stencil : Stencil
+        The stencil used for numerical computations.
+    u : ndarray
+        Array representing the action potential (mV) across the tissue.
+    u_new : ndarray
+        Array for storing the updated action potential values.
+    dt : float
+        Time step for the simulation.
+    dr : float
+        Spatial step for the simulation.
+    t_max : float
+        Maximum time for the simulation (model units).
+    t : float
+        Current time in the simulation (model units).
+    step : int
+        Current step or iteration in the simulation.
+    D_model : float
+        Model-specific diffusion coefficient.
+    prog_bar : bool
+        Whether to display a progress bar during simulation.
+    npfloat : type
+        The floating-point type used for numerical computations.
+    state_vars : list
+        List of state variables to save and load during simulation.
+    """
+    def __init__(self):
+        self.meta = {}
+        self.cardiac_tissue = None
+        self.stim_sequence = None
+        self.tracker_sequence = None
+        self.command_sequence = None
+        self.state_loader = None
+        self.state_saver = None
+        self.stencil = None
+
+        self.observers = []
+        self._buffs = [] # observer buffers
+
+        self.diffusion_kernel = None
+        self.ionic_kernel = None
+
+        self.u = np.ndarray
+        self.u_new = np.ndarray
+        self.weights = np.ndarray
+        self.dt = 0.
+        self.dr = 0.
+        self.t_max = 0.
+        self.t = 0
+        self.step = 0
+        self.D_model = 1.
+
+        self.prog_bar = True
+        self.npfloat = np.float64
+        self.state_vars = []
+
+    @abstractmethod
+    def run_ionic_kernel(self):
+        """
+        Abstract method for running the ionic kernel. Must be implemented by
+        subclasses.
+        """
+        pass
+
+    def initialize(self):
+        """
+        Initializes the model for simulation. Sets up arrays, computes weights,
+        and initializes stimuli, trackers, and commands.
+        """
+        self.u = np.zeros_like(self.cardiac_tissue.mesh, dtype=self.npfloat)
+        self.u_new = self.u.copy()
+        self.step = 0
+        self.t = 0
+
+        self.compute_weights()
+        self.diffusion_kernel = self.stencil.select_diffusion_kernel()
+
+        if self.stim_sequence:
+            self.stim_sequence.initialize(self)
+
+        if self.tracker_sequence:
+            self.tracker_sequence.initialize(self)
+
+        if self.command_sequence:
+            self.command_sequence.initialize(self)
+
+        if self.state_loader:
+            self.state_loader.initialize(self)
+
+        if self.state_saver:
+            self.state_saver.initialize(self)
+
+    def compute_weights(self):
+        """
+        Computes the weights for the stencil.
+        """
+        self.cardiac_tissue.compute_myo_indexes()
+
+        if self.stencil is None:
+            self.stencil = self.select_stencil(self.cardiac_tissue)
+
+        self.weights = self.stencil.compute_weights(self, self.cardiac_tissue)
+
+    def run(self, initialize=True, num_of_threads=None):
+        """
+        Runs the simulation loop. Handles stimuli, diffusion, ionic kernel
+        updates, and tracking.
+
+        Parameters
+        ----------
+        initialize : bool, optional
+            Whether to (re)initialize the model before running the simulation.
+            Default is True.
+        """
+        if initialize:
+            self.initialize()
+
+        numba.set_num_threads(numba.config.NUMBA_NUM_THREADS)
+
+        if num_of_threads is not None:
+            if num_of_threads > numba.config.NUMBA_NUM_THREADS:
+                warnings.warn(
+                    f"Selected number of threads ({num_of_threads}) exceeds the available threads ({numba.config.NUMBA_NUM_THREADS}). "
+                    f"Using the maximum available threads instead."
+                )
+            num_of_theads = min(num_of_threads, numba.config.NUMBA_NUM_THREADS)
+            numba.set_num_threads(num_of_theads)
+
+        if self.t_max < self.t:
+            raise ValueError("t_max must be greater than current t.")
+
+        if self.state_loader:
+            self.state_loader.load()
+
+        iters = int(np.ceil((self.t_max - self.t) / self.dt))
+        bar_desc = f"Running {self.__class__.__name__}"
+
+        for _ in tqdm(range(iters), total=iters, desc=bar_desc,
+                      disable=not self.prog_bar):
+
+            if self.stim_sequence:
+                self.stim_sequence.stimulate_next()
+
+            self.run_diffusion_kernel()
+            self.run_ionic_kernel()
+
+            if self.tracker_sequence:
+                self.tracker_sequence.tracker_next()
+
+            self.t += self.dt
+            self.step += 1
+            self.u_new, self.u = self.u, self.u_new
+
+            if self.command_sequence:
+                self.command_sequence.execute_next()
+
+            if self.state_saver:
+                self.state_saver.save()
+
+            if self.check_termination():
+                if self.state_saver:
+                    self.state_saver.save()
+                break
+
+    def check_termination(self):
+        """
+        Checks whether the simulation should terminate based on the current
+        time. The ``CommandSequence`` may change the ``t_max`` value during
+        execution to control the simulation duration.
+
+        Returns
+        -------
+        bool
+            True if the simulation should terminate, False otherwise.
+        """
+        max_iters = int(np.ceil(self.t_max / self.dt))
+        return (self.t > self.t_max) or (self.step > max_iters)
+
+    def run_diffusion_kernel(self):
+        """
+        Executes the diffusion kernel computation using the current parameters
+        and tissue weights.
+        """
+        self.diffusion_kernel(self.u_new, self.u, self.weights,
+                              self.cardiac_tissue.myo_indexes)
+
+    @abstractmethod
+    def select_stencil(self, cardiac_tissue):
+        """
+        Selects the appropriate stencil based on the cardiac tissue properties.
+
+        Parameters
+        ----------
+        cardiac_tissue : CardiacTissue
+            The tissue object representing the cardiac tissue.
+
+        Returns
+        -------
+        Stencil
+            The stencil object to use for diffusion computations.
+        """
+        pass
+
+    def clone(self):
+        """
+        Creates a deep copy of the current model instance.
+
+        Returns
+        -------
+        CardiacModel
+            A deep copy of the current CardiacModel instance.
+        """
+        return copy.deepcopy(self)
+    
+    def _initialize_variables_and_parameters(self, ops):
+        self.default_parameters = ops.get_parameters()
+        self.default_variables = ops.get_variables()
+
+        self.state_vars = self.default_variables.keys()
+        self.state_pars = list(self.default_parameters.keys())
+
+        # expose parameters as direct attributes (scalar or array)
+        for name, value in self.default_parameters.items():
+            setattr(self, name, value)
+
+        # expose initial conditions as init_*
+        for name, value in self.default_variables.items():
+            setattr(self, f"init_{name}", value)
+
+        # declare arrays (optional, for readability/debug)
+        for name in self.default_variables.keys():
+            setattr(self, name, np.ndarray)      
+
+    def _allocate_state_arrays(self):
+        # allocate state arrays
+        for name in self.default_variables.keys():
+            init_val = getattr(self, f"init_{name}")
+            setattr(self, name, init_val * np.ones_like(self.u, dtype=self.npfloat))
+            if name == 'u':
+                self.u_new = self.u.copy()
+
+        # validate parameter fields shapes if they are arrays
+        tissue_shape = self.cardiac_tissue.mesh.shape
+        for name in self.default_parameters.keys():
+            par = getattr(self, name)
+            if isinstance(par, np.ndarray):
+                if par.shape != tissue_shape:
+                    raise ValueError(
+                        f"param '{name}' shape {par.shape} != tissue shape {tissue_shape}"
+                    ) 
+    
+    def _initialize_kernel(self, kernel, exclude_params=[]):
+        gen = kernel()
+        self._kernel_args_order = gen.args_order[:]
+
+        # args_order: state vars first, then all parameters (stable order for call site)
+        param_names = list(self.default_parameters.keys())
+        var_names = list(self.default_variables.keys())
+
+        # Tell generator which names are arrays vs scalars (for indexing decisions)
+        for name in var_names:
+            gen.arrays.append(name)
+
+        for name in param_names:
+            if name in exclude_params: # computed internally
+                continue
+            par = getattr(self, name)
+            if np.isscalar(par):
+                gen.scalars.append(name)
+            elif isinstance(par, np.ndarray):
+                gen.arrays.append(name)
+
+        return gen
+
+    def _form_and_verify_observers(self):
+        buffs = []
+        for obs in self.observers:
+            name = obs["name"] 
+            try:
+                buffs.append(getattr(self, name))
+            except AttributeError as e:
+                raise AttributeError(
+                    f"Observer buffer '{name}' not found on model. "
+                    f"Create it before initialize(), e.g.: model.{name} = np.zeros(...)."
+                ) from e
+        return buffs