canns 0.12.6__py3-none-any.whl → 0.13.0__py3-none-any.whl

canns/models/basic/hierarchical_model.py

@@ -744,12 +744,29 @@ class GridCell(BasicModel):
 class HierarchicalPathIntegrationModel(BasicModelGroup):
     """A hierarchical model combining band cells and grid cells for path integration.
 
-    This model forms a single grid module. It consists of three `BandCell` modules,
-    each with a different preferred orientation (separated by 60 degrees), and one
-    `GridCell` module. The band cells integrate velocity along their respective
-    directions, and their combined outputs provide the input to the `GridCell`
-    network, effectively driving the grid cell's activity bump. The model can
-    also project its grid cell activity to a population of place cells.
+    This model forms a single grid module. It consists of three `BandCell` modules
+    (60 degrees apart) plus one `GridCell`. The band cells integrate velocity,
+    and their combined output drives the grid cell bump. The grid cell activity
+    can be projected to place cells.
+
+    Examples:
+        >>> import brainpy.math as bm
+        >>> from canns.models.basic.hierarchical_model import HierarchicalPathIntegrationModel
+        >>>
+        >>> bm.set_dt(0.1)
+        >>> place_center = bm.array([[0.0, 0.0], [1.0, 1.0]])
+        >>> model = HierarchicalPathIntegrationModel(
+        ...     spacing=2.5,
+        ...     angle=0.0,
+        ...     place_center=place_center,
+        ...     band_size=30,
+        ...     grid_num=10,
+        ... )
+        >>> velocity = bm.array([0.0, 0.0])
+        >>> position = bm.array([0.0, 0.0])
+        >>> model.update(velocity=velocity, loc=position, loc_input_stre=0.0)
+        >>> model.grid_output.value.shape
+        (2,)
 
     Attributes:
         band_cell_x (BandCell): The first band cell module (orientation `angle`).
@@ -988,6 +1005,16 @@ class HierarchicalPathIntegrationModel(BasicModelGroup):
         )
 
     def update(self, velocity, loc, loc_input_stre=0.0):
+        """Advance the model by one time step.
+
+        Args:
+            velocity (Array): 2D velocity vector, shape ``(2,)``.
+            loc (Array): 2D position vector, shape ``(2,)``.
+            loc_input_stre (float): Strength of optional location-based input.
+
+        Returns:
+            None
+        """
         self.band_cell_x(velocity=velocity, loc=loc, loc_input_stre=loc_input_stre)
         self.band_cell_y(velocity=velocity, loc=loc, loc_input_stre=loc_input_stre)
         self.band_cell_z(velocity=velocity, loc=loc, loc_input_stre=loc_input_stre)
@@ -1030,11 +1057,20 @@ class HierarchicalPathIntegrationModel(BasicModelGroup):
 class HierarchicalNetwork(BasicModelGroup):
     """A full hierarchical network composed of multiple grid modules.
 
-    This class creates and manages a collection of `HierarchicalPathIntegrationModel`
-    modules, each with a different grid spacing. By combining the outputs of these
-    modules, the network can represent position unambiguously over a large area.
-    The final output is a population of place cells whose activities are used to
-    decode the animal's estimated position.
+    Each module is a `HierarchicalPathIntegrationModel` with a different grid
+    spacing. The module outputs are combined to decode a single 2D position.
+
+    Examples:
+        >>> import brainpy.math as bm
+        >>> from canns.models.basic import HierarchicalNetwork
+        >>>
+        >>> bm.set_dt(0.1)
+        >>> model = HierarchicalNetwork(num_module=1, num_place=3)
+        >>> velocity = bm.array([0.0, 0.0])
+        >>> position = bm.array([0.0, 0.0])
+        >>> model.update(velocity=velocity, loc=position, loc_input_stre=0.0)
+        >>> model.decoded_pos.value.shape
+        (2,)
 
     Attributes:
         num_module (int): The number of grid modules in the network.
@@ -1163,6 +1199,16 @@ class HierarchicalNetwork(BasicModelGroup):
         self.decoded_pos = bm.Variable(bm.zeros(2))
 
     def update(self, velocity, loc, loc_input_stre=0.0):
+        """Advance the full network by one time step.
+
+        Args:
+            velocity (Array): 2D velocity vector, shape ``(2,)``.
+            loc (Array): 2D position vector, shape ``(2,)``.
+            loc_input_stre (float): Strength of optional location-based input.
+
+        Returns:
+            None
+        """
         grid_output = bm.zeros(self.num_place)
         for i in range(self.num_module):
             # update the band cell module

canns/models/brain_inspired/hopfield.py

@@ -9,18 +9,25 @@ __all__ = ["AmariHopfieldNetwork"]
 
 
 class AmariHopfieldNetwork(BrainInspiredModel):
-    """
-    Amari-Hopfield Network implementation supporting both discrete and continuous dynamics.
-
-    This class implements Hopfield networks with flexible activation functions,
-    supporting both discrete binary states and continuous dynamics. The network
-    performs pattern completion through energy minimization using asynchronous
-    or synchronous updates.
-
-    The network energy function:
-    E = -0.5 * Σ_ij W_ij * s_i * s_j
-
-    Where s_i can be discrete {-1, +1} or continuous depending on activation function.
+    """Amari-Hopfield network with discrete or continuous dynamics.
+
+    The model performs pattern completion by iteratively updating the state
+    vector ``s`` to reduce energy:
+        E = -0.5 * sum_ij W_ij * s_i * s_j
+
+    Examples:
+        >>> import jax.numpy as jnp
+        >>> from canns.models.brain_inspired import AmariHopfieldNetwork
+        >>>
+        >>> model = AmariHopfieldNetwork(num_neurons=3, activation="sign")
+        >>> pattern = jnp.array([1.0, -1.0, 1.0], dtype=jnp.float32)
+        >>> weights = jnp.outer(pattern, pattern)
+        >>> weights = weights - jnp.diag(jnp.diag(weights))  # zero diagonal
+        >>> model.W.value = weights
+        >>> model.s.value = jnp.array([1.0, 1.0, -1.0], dtype=jnp.float32)
+        >>> model.update(None)
+        >>> model.s.value.shape
+        (3,)
 
     Reference:
         Amari, S. (1977). Neural theory of association and concept-formation.
@@ -78,8 +85,13 @@ class AmariHopfieldNetwork(BrainInspiredModel):
             raise ValueError(f"Unknown activation type: {activation}")
 
     def update(self, e_old):
-        """
-        Update network state for one time step.
+        """Update network state for one time step.
+
+        Args:
+            e_old: Unused placeholder for trainer compatibility.
+
+        Returns:
+            None
         """
         if self.asyn:
             self._asynchronous_update()

canns/models/brain_inspired/linear.py

@@ -11,22 +11,22 @@ __all__ = ["LinearLayer"]
 
 
 class LinearLayer(BrainInspiredModel):
-    """
-    Generic linear feedforward layer supporting multiple brain-inspired learning rules.
-
-    This model provides a simple linear transformation with optional sliding threshold
-    for BCM-style plasticity. It can be used with various trainers:
-    - OjaTrainer: Normalized Hebbian learning for PCA
-    - BCMTrainer: Sliding threshold plasticity (requires use_bcm_threshold=True)
-    - HebbianTrainer: Standard Hebbian learning
+    """Generic linear feedforward layer for brain-inspired learning rules.
 
-    Computation:
+    It computes a simple linear transform:
         y = W @ x
 
-    where W is the weight matrix, x is the input, and y is the output.
+    You can pair it with trainers like ``OjaTrainer``, ``BCMTrainer``, or
+    ``HebbianTrainer``.
 
-    For BCM learning, an optional sliding threshold θ tracks output activity:
-        θ ← θ + (1/τ) * (y² - θ)
+    Examples:
+        >>> import jax.numpy as jnp
+        >>> from canns.models.brain_inspired import LinearLayer
+        >>>
+        >>> layer = LinearLayer(input_size=3, output_size=2)
+        >>> y = layer.forward(jnp.array([1.0, 0.5, -1.0], dtype=jnp.float32))
+        >>> y.shape
+        (2,)
 
     References:
         - Oja (1982): Simplified neuron model as a principal component analyzer
@@ -73,14 +73,13 @@ class LinearLayer(BrainInspiredModel):
             self.theta = bm.Variable(jnp.ones(self.output_size, dtype=jnp.float32) * 0.1)
 
     def forward(self, x: jnp.ndarray) -> jnp.ndarray:
-        """
-        Forward pass through the layer.
+        """Compute the layer output for one input vector.
 
         Args:
-            x: Input vector of shape (input_size,)
+            x: Input vector of shape ``(input_size,)``.
 
         Returns:
-            Output vector of shape (output_size,)
+            Output vector of shape ``(output_size,)``.
         """
         self.x.value = jnp.asarray(x, dtype=jnp.float32)
         self.y.value = self.W.value @ self.x.value

canns/models/brain_inspired/spiking.py

@@ -12,15 +12,9 @@ __all__ = ["SpikingLayer"]
 
 
 class SpikingLayer(BrainInspiredModel):
-    """
-    Simple Leaky Integrate-and-Fire (LIF) spiking neuron layer.
+    """Simple Leaky Integrate-and-Fire (LIF) spiking neuron layer.
 
-    This model provides a minimal spiking neuron implementation for demonstrating
-    spike-timing-dependent plasticity (STDP). It features:
-    - Leaky integration of input currents
-    - Threshold-based spike generation
-    - Reset mechanism after spiking
-    - Exponential spike traces for STDP learning
+    It supports STDP-style training by maintaining pre/post spike traces.
 
     Dynamics:
         v[t+1] = leak * v[t] + W @ x[t]
@@ -28,6 +22,23 @@ class SpikingLayer(BrainInspiredModel):
         v = v_reset if spike else v
         trace = decay * trace + spike
 
+    Notes:
+        - x[t] denotes the input current at time t. It can take arbitrary continuous
+          values; binary {0, 1} spike trains are a special case of such inputs.
+        - The layer does not internally binarize x; thresholding only applies to the
+          membrane potential to generate output spikes.
+
+    Examples:
+        >>> import jax.numpy as jnp
+        >>> from canns.models.brain_inspired import SpikingLayer
+        >>>
+        >>> layer = SpikingLayer(input_size=3, output_size=2, threshold=0.5)
+        >>> # Continuous input currents (binary spikes {0,1} are a special case)
+        >>> x = jnp.array([0.2, 0.5, 1.3], dtype=jnp.float32)
+        >>> spikes = layer.forward(x)
+        >>> spikes.shape
+        (2,)
+
     References:
         - Gerstner & Kistler (2002): Spiking Neuron Models
         - Morrison et al. (2008): Phenomenological models of synaptic plasticity
@@ -88,14 +99,14 @@ class SpikingLayer(BrainInspiredModel):
         self.trace_post = bm.Variable(jnp.zeros(self.output_size, dtype=jnp.float32))
 
     def forward(self, x: jnp.ndarray) -> jnp.ndarray:
-        """
-        Forward pass through the spiking layer.
+        """Compute spikes for one time step.
 
         Args:
-            x: Input spikes of shape (input_size,) with binary values (0 or 1)
+            x: Input currents of shape ``(input_size,)``. Can be continuous-valued
+                (e.g., synaptic currents) or binary spikes {0, 1} as a special case.
 
         Returns:
-            Output spikes of shape (output_size,) with binary values (0 or 1)
+            Output spikes of shape ``(output_size,)`` with values 0 or 1.
         """
         self.x.value = jnp.asarray(x, dtype=jnp.float32)
 

canns/pipeline/__init__.py

@@ -7,15 +7,11 @@ the underlying implementations.
 """
 
 from ._base import Pipeline
-from .theta_sweep import (
-    ThetaSweepPipeline,
-    batch_process_trajectories,
-    load_trajectory_from_csv,
-)
+from .asa import ASAApp
+from .asa import main as asa_main
 
 __all__ = [
     "Pipeline",
-    "ThetaSweepPipeline",
-    "load_trajectory_from_csv",
-    "batch_process_trajectories",
+    "ASAApp",
+    "asa_main",
 ]

canns/pipeline/asa/__init__.py

@@ -0,0 +1,21 @@
+"""ASA TUI - Terminal User Interface for ASA Analysis.
+
+This module provides a Textual-based TUI for running ASA (Attractor State Analysis)
+with 7 analysis modules: TDA, CohoMap, PathCompare, CohoSpace, FR, FRM, and GridScore.
+"""
+
+import os
+
+__all__ = ["ASAApp", "main"]
+
+
+def main():
+    """Entry point for canns-tui command."""
+    os.environ.setdefault("MPLBACKEND", "Agg")
+    from .app import ASAApp
+
+    app = ASAApp()
+    app.run()
+
+
+from .app import ASAApp

canns/pipeline/asa/__main__.py

@@ -0,0 +1,11 @@
+"""Main entry point for running ASA TUI as a module."""
+
+import os
+
+os.environ.setdefault("MPLBACKEND", "Agg")
+
+from .app import ASAApp
+
+if __name__ == "__main__":
+    app = ASAApp()
+    app.run()