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

canns/analyzer/visualization/theta_sweep_plots.py

@@ -25,7 +25,6 @@ from tqdm import tqdm
 
 from .core.backend import (
     emit_backend_warnings,
-    get_imageio_writer_kwargs,
     get_multiprocessing_context,
     get_optimal_worker_count,
     select_animation_backend,
@@ -501,21 +500,35 @@ def plot_population_activity_with_theta(
     save_path: str | None = None,
     **kwargs,
 ) -> tuple[plt.Figure, plt.Axes]:
-    """
-    Plot neural population activity with theta oscillation markers and direction trace.
+    """Plot neural population activity with theta phase markers.
 
     Args:
-        time_steps: Array of time points
-        theta_phase: Array of theta phase values [-π, π]
-        net_activity: 2D array of network activity (time, neurons)
-        direction: Array of direction values
-        config: PlotConfig object for unified configuration
-        add_lines: Whether to add vertical lines at theta phase zeros
-        atol: Tolerance for detecting theta phase zeros
-        **kwargs: Additional parameters for backward compatibility
+        time_steps: Array of time points.
+        theta_phase: Theta phase values in ``[-pi, pi]``.
+        net_activity: 2D array of network activity ``(time, neurons)``.
+        direction: Direction values (radians) over time.
+        config: PlotConfig object for unified configuration.
+        add_lines: Whether to add vertical lines at theta phase zeros.
+        atol: Tolerance for detecting theta phase zeros.
+        **kwargs: Additional parameters for backward compatibility.
 
     Returns:
-        tuple: (figure, axis) objects
+        tuple: ``(figure, axis)`` objects.
+
+    Examples:
+        >>> import numpy as np
+        >>> from canns.analyzer.visualization import plot_population_activity_with_theta, PlotConfig
+        >>>
+        >>> time_steps = np.linspace(0, 1, 5)
+        >>> theta_phase = np.linspace(-np.pi, np.pi, 5)
+        >>> net_activity = np.random.rand(5, 4)
+        >>> direction = np.linspace(-np.pi, np.pi, 5)
+        >>> config = PlotConfig(show=False)
+        >>> fig, ax = plot_population_activity_with_theta(
+        ...     time_steps, theta_phase, net_activity, direction, config=config
+        ... )
+        >>> print(fig is not None)
+        True
     """
     # Handle configuration
     if config is None:
@@ -649,18 +662,28 @@ def plot_grid_cell_manifold(
     save_path: str | None = None,
     **kwargs,
 ) -> tuple[plt.Figure, plt.Axes]:
-    """
-    Plot grid cell activity on the twisted torus manifold.
+    """Plot grid cell activity on the twisted torus manifold.
 
     Args:
-        value_grid_twisted: Coordinates on twisted manifold
-        grid_cell_activity: 2D array of grid cell activities
-        config: PlotConfig object for unified configuration
-        ax: Optional axis to draw on instead of creating a new figure
-        **kwargs: Additional parameters for backward compatibility
+        value_grid_twisted: Coordinates on the twisted manifold ``(N, 2)``.
+        grid_cell_activity: 2D array of grid cell activities.
+        config: PlotConfig object for unified configuration.
+        ax: Optional axis to draw on instead of creating a new figure.
+        **kwargs: Additional parameters for backward compatibility.
 
     Returns:
-        tuple: (figure, axis) objects
+        tuple: ``(figure, axis)`` objects.
+
+    Examples:
+        >>> import numpy as np
+        >>> from canns.analyzer.visualization import plot_grid_cell_manifold, PlotConfig
+        >>>
+        >>> value_grid_twisted = np.random.rand(9, 2)
+        >>> grid_cell_activity = np.random.rand(3, 3)
+        >>> config = PlotConfig(show=False)
+        >>> fig, ax = plot_grid_cell_manifold(value_grid_twisted, grid_cell_activity, config=config)
+        >>> print(fig is not None)
+        True
     """
     # Handle configuration
     if config is None:
@@ -827,9 +850,10 @@ def _render_single_place_cell_frame(
     options: _PlaceCellRenderOptions,
 ) -> np.ndarray:
     """Render a single frame for place cell animation (module-level for pickling)."""
+    from io import BytesIO
+
     import matplotlib.pyplot as plt
     import numpy as np
-    from io import BytesIO
 
     fig, axes = plt.subplots(1, 2, figsize=options.figsize, width_ratios=[1, 1])
     ax_env, ax_activity = axes
@@ -959,32 +983,51 @@ def create_theta_sweep_place_cell_animation(
     render_start_method: str | None = None,
     **kwargs,
 ) -> FuncAnimation | None:
-    """
-    Create theta sweep animation for place cell network with 2 panels:
-    1. Environment trajectory with place cell bump overlay
-    2. Population activity heatmap over time
+    """Create theta sweep animation for a place cell network.
 
     Args:
-        position_data: Animal position data (time, 2)
-        pc_activity_data: Place cell activity (time, num_cells)
-        pc_network: PlaceCellNetwork instance
-        navigation_task: BaseNavigationTask instance for environment visualization
-        dt: Time step size
-        config: PlotConfig object for unified configuration
-        n_step: Subsample every n_step frames for animation
-        fps: Frames per second for animation
-        figsize: Figure size (width, height)
-        save_path: Path to save animation (GIF or MP4)
-        show: Whether to display animation
-        show_progress_bar: Whether to show progress bar during saving
-        render_backend: Rendering backend ('imageio', 'matplotlib', or 'auto')
-        output_dpi: DPI for rendered frames (affects file size and quality)
-        render_workers: Number of parallel workers (None = auto-detect)
-        render_start_method: Multiprocessing start method ('fork', 'spawn', or None)
-        **kwargs: Additional parameters (cmap, alpha, etc.)
+        position_data: Animal position data ``(time, 2)``.
+        pc_activity_data: Place cell activity ``(time, num_cells)``.
+        pc_network: PlaceCellNetwork-like object with ``geodesic_result``.
+        navigation_task: BaseNavigationTask-like object with ``env``.
+        dt: Time step size.
+        config: PlotConfig object for unified configuration.
+        n_step: Subsample every n_step frames for animation.
+        fps: Frames per second for animation.
+        figsize: Figure size (width, height).
+        save_path: Path to save animation (GIF or MP4).
+        show: Whether to display animation.
+        show_progress_bar: Whether to show progress bar during saving.
+        render_backend: Rendering backend ('imageio', 'matplotlib', or 'auto').
+        output_dpi: DPI for rendered frames (affects file size and quality).
+        render_workers: Number of parallel workers (None = auto-detect).
+        render_start_method: Multiprocessing start method ('fork', 'spawn', or None).
+        **kwargs: Additional parameters (cmap, alpha, etc.).
 
     Returns:
-        FuncAnimation: Matplotlib animation object
+        FuncAnimation: Matplotlib animation object.
+
+    Examples:
+        This example demonstrates the basic structure. For complete usage, see the
+        documentation or example scripts.
+
+        >>> import numpy as np
+        >>> from canns.analyzer.visualization import PlotConfig
+        >>>
+        >>> # Prepare your data from simulation
+        >>> position_data = np.array([[0.1, 0.1], [0.2, 0.2], [0.3, 0.3]])
+        >>> pc_activity_data = np.random.rand(3, 4)  # (time, num_cells)
+        >>>
+        >>> # Assuming you have pc_network and navigation_task from your model
+        >>> # anim = create_theta_sweep_place_cell_animation(
+        >>> #     position_data,
+        >>> #     pc_activity_data,
+        >>> #     pc_network,  # Your PlaceCellNetwork instance
+        >>> #     navigation_task,  # Your BaseNavigationTask instance
+        >>> #     config=PlotConfig(show=False),
+        >>> #     n_step=1,
+        >>> #     fps=10,
+        >>> # )  # doctest: +SKIP
     """
     # Handle configuration
     if config is None:
@@ -1180,8 +1223,9 @@ def create_theta_sweep_place_cell_animation(
         if backend == "imageio":
             # Use imageio backend with parallel rendering
             workers = render_workers if render_workers is not None else get_optimal_worker_count()
-            ctx = get_multiprocessing_context(prefer_fork=(render_start_method == "fork"))
-            start_method = ctx.method if ctx is not None else None
+            ctx, start_method = get_multiprocessing_context(
+                prefer_fork=(render_start_method == "fork")
+            )
 
             _emit_info(
                 f"Parallel rendering enabled: {workers} workers (start_method={start_method})"
@@ -1190,7 +1234,11 @@ def create_theta_sweep_place_cell_animation(
             # Prepare environment data
             env = navigation_task.env
             boundary_array = np.array(env.boundary) if env.boundary is not None else None
-            walls_arrays = [np.array(wall) for wall in env.walls] if env.walls is not None and len(env.walls) > 0 else None
+            walls_arrays = (
+                [np.array(wall) for wall in env.walls]
+                if env.walls is not None and len(env.walls) > 0
+                else None
+            )
 
             # Get accessible indices
             accessible_indices = pc_network.geodesic_result.accessible_indices
@@ -1215,11 +1263,14 @@ def create_theta_sweep_place_cell_animation(
             writer_kwargs, mode = get_imageio_writer_kwargs(config.save_path, config.fps)
 
             try:
-                import imageio
                 from functools import partial
 
+                import imageio
+
                 # Create partial function with data and options
-                render_func = partial(_render_single_place_cell_frame, data=data, options=render_options)
+                render_func = partial(
+                    _render_single_place_cell_frame, data=data, options=render_options
+                )
 
                 with imageio.get_writer(config.save_path, mode=mode, **writer_kwargs) as writer:
                     if workers > 1 and ctx is not None:
@@ -1335,32 +1386,69 @@ def create_theta_sweep_grid_cell_animation(
     render_start_method: str | None = None,
     **kwargs,
 ) -> FuncAnimation | None:
-    """
-    Create comprehensive theta sweep animation with 4 panels (optimized for speed):
-    1. Animal trajectory
-    2. Direction cell polar plot
-    3. Grid cell activity on manifold
-    4. Grid cell activity in real space
+    """Create a theta sweep animation with four panels.
+
+    Panels:
+        1) Animal trajectory
+        2) Direction cell polar plot
+        3) Grid cell activity on manifold
+        4) Grid cell activity in real space
 
     Args:
-        position_data: Animal position data (time, 2)
-        direction_data: Direction data (time,)
-        dc_activity_data: Direction cell activity (time, neurons)
-        gc_activity_data: Grid cell activity (time, neurons)
-        gc_network: GridCellNetwork instance for coordinate transformations
-        env_size: Environment size
-        mapping_ratio: Mapping ratio for grid cells
-        dt: Time step size
-        config: PlotConfig object for unified configuration
-        n_step: Subsample every n_step frames for animation
-        render_backend: Rendering backend. Use 'matplotlib', 'imageio', or 'auto'/'None' for auto-detect.
-        output_dpi: Target DPI when rendering frames with non-interactive backends
-        render_workers: Worker processes for imageio backend. ``None`` auto-selects, 0 disables.
-        render_start_method: Multiprocessing start method ('fork', 'spawn', 'forkserver') or None for auto
-        **kwargs: Additional parameters for backward compatibility
+        position_data: Animal position data ``(time, 2)``.
+        direction_data: Direction data ``(time,)``.
+        dc_activity_data: Direction cell activity ``(time, neurons)``.
+        gc_activity_data: Grid cell activity ``(time, neurons)``.
+        gc_network: GridCellNetwork instance for coordinate transforms.
+        env_size: Environment size.
+        mapping_ratio: Mapping ratio for grid cells.
+        dt: Time step size.
+        config: PlotConfig object for unified configuration.
+        n_step: Subsample every n_step frames for animation.
+        render_backend: Rendering backend. Use 'matplotlib', 'imageio', or 'auto'.
+        output_dpi: Target DPI for non-interactive rendering.
+        render_workers: Worker processes for imageio backend.
+        render_start_method: Multiprocessing start method ('fork', 'spawn', or None).
+        **kwargs: Additional parameters for backward compatibility.
 
     Returns:
-        FuncAnimation | None: Matplotlib animation object for interactive backend, otherwise None
+        FuncAnimation | None: Animation object (None if displayed inline).
+
+    Examples:
+        This is a minimal structural example using synthetic data to demonstrate
+        the API. For realistic usage, run a GridCellNetwork simulation to obtain
+        actual activity data.
+
+        >>> import numpy as np
+        >>> import brainpy.math as bm
+        >>> from canns.models.basic.theta_sweep_model import GridCellNetwork
+        >>> from canns.analyzer.visualization import PlotConfig
+        >>>
+        >>> # Minimal example with synthetic data (for structure demonstration)
+        >>> bm.set_dt(1.0)
+        >>> gc_network = GridCellNetwork(num_dc=4, num_gc_x=4, mapping_ratio=1.0)
+        >>> T = 5
+        >>> # NOTE: In real usage, obtain these from actual model simulation
+        >>> position_data = np.random.rand(T, 2)
+        >>> direction_data = np.linspace(-np.pi, np.pi, T)
+        >>> dc_activity_data = np.random.rand(T, gc_network.num_dc)
+        >>> gc_activity_data = np.random.rand(T, gc_network.num)
+        >>>
+        >>> config = PlotConfig(show=False)
+        >>> anim = create_theta_sweep_grid_cell_animation(
+        ...     position_data,
+        ...     direction_data,
+        ...     dc_activity_data,
+        ...     gc_activity_data,
+        ...     gc_network,
+        ...     env_size=1.0,
+        ...     mapping_ratio=1.0,
+        ...     config=config,
+        ...     n_step=1,
+        ...     fps=2,
+        ... )
+        >>> print(anim is not None)
+        True
     """
     # Handle configuration
     if config is None:
@@ -1426,8 +1514,7 @@ def create_theta_sweep_grid_cell_animation(
         workers = render_workers if render_workers is not None else get_optimal_worker_count()
 
         # Get multiprocessing context
-        ctx = get_multiprocessing_context(prefer_fork=True)
-        start_method = ctx.method if ctx is not None else None
+        ctx, start_method = get_multiprocessing_context(prefer_fork=True)
 
         if workers > 0 and ctx is None:
             warnings.warn(

canns/analyzer/visualization/tuning_plots.py

@@ -69,9 +69,6 @@ def tuning_curve(
 ):
     """Plot the tuning curve for one or more neurons.
 
-    The wording mirrors the original ``visualize`` module to avoid API drift and
-    to keep existing references valid.
-
     Args:
         stimulus: 1D array with the stimulus value at each time step.
         firing_rates: 2D array of firing rates shaped ``(timesteps, neurons)``.
@@ -86,6 +83,17 @@ def tuning_curve(
         save_path: Optional location where the figure should be stored.
         show: Whether to display the plot interactively.
         **kwargs: Additional keyword arguments passed through to ``ax.plot``.
+
+    Examples:
+        >>> import numpy as np
+        >>> from canns.analyzer.visualization import tuning_curve, PlotConfigs
+        >>>
+        >>> stimulus = np.linspace(0, 1, 10)
+        >>> firing_rates = np.random.rand(10, 3)
+        >>> config = PlotConfigs.tuning_curve(num_bins=5, pref_stim=np.array([0.2, 0.5, 0.8]), show=False)
+        >>> fig, ax = tuning_curve(stimulus, firing_rates, neuron_indices=[0, 1], config=config)
+        >>> print(fig is not None)
+        True
     """
 
     config = _ensure_plot_config(

canns/data/__init__.py

@@ -1,8 +1,11 @@
-"""
-Data utilities for CANNs.
+"""Data utilities for CANNs.
+
+This namespace provides dataset registry, download helpers, and convenience
+loaders for common CANNs datasets.
 
-This module provides dataset management, loading, and downloading utilities.
-It consolidates data-related functionality previously scattered across the codebase.
+Examples:
+    >>> from canns import data
+    >>> print(list(data.DATASETS))
 """
 
 from .datasets import (

canns/models/__init__.py

@@ -1,3 +1,13 @@
+"""Model definitions for CANNs.
+
+This namespace exposes common model families, such as basic CANNs and
+brain-inspired variants.
+
+Examples:
+    >>> from canns import models
+    >>> print(models.basic)
+"""
+
 from . import basic as basic
 from . import brain_inspired as brain_inspired
 # from .hybrid import *

canns/models/basic/cann.py

@@ -76,11 +76,20 @@ class BaseCANN(BasicModel):
 
 
 class BaseCANN1D(BaseCANN):
-    """
-    Base class for 1D Continuous Attractor Neural Network (CANN) models.
-    This class sets up the fundamental properties of the network, including
-    neuronal properties, feature space, and the connectivity matrix, which
-    are shared by different CANN model variations.
+    """Base class for 1D Continuous Attractor Neural Network (CANN) models.
+
+    It builds the 1D feature space, connectivity kernel, and stimulus helpers
+    shared by 1D CANN variants.
+
+    Examples:
+        >>> import brainpy.math as bm
+        >>> from canns.models.basic.cann import BaseCANN1D
+        >>>
+        >>> bm.set_dt(0.1)
+        >>> model = BaseCANN1D(num=64)
+        >>> stimulus = model.get_stimulus_by_pos(0.0)
+        >>> stimulus.shape
+        (64,)
     """
 
     def __init__(
@@ -181,10 +190,21 @@ class BaseCANN1D(BaseCANN):
 
 
 class CANN1D(BaseCANN1D):
-    """
-    A standard 1D Continuous Attractor Neural Network (CANN) model.
-    This model implements the core dynamics where a localized "bump" of activity
-    can be sustained and moved by external inputs.
+    """Standard 1D Continuous Attractor Neural Network (CANN) model.
+
+    This model sustains a localized "bump" of activity that can be driven by
+    external input.
+
+    Examples:
+        >>> import brainpy.math as bm
+        >>> from canns.models.basic import CANN1D
+        >>>
+        >>> bm.set_dt(0.1)
+        >>> model = CANN1D(num=64)
+        >>> stimulus = model.get_stimulus_by_pos(0.0)
+        >>> model.update(stimulus)
+        >>> model.r.value.shape
+        (64,)
 
     Reference:
         Wu, S., Hamaguchi, K., & Amari, S. I. (2008). Dynamics and computation of continuous attractors.
@@ -210,11 +230,13 @@ class CANN1D(BaseCANN1D):
         self.inp = bm.Variable(bm.zeros(self.shape))
 
     def update(self, inp):
-        """
-        The main update function, defining the dynamics of the network for one time step.
+        """Advance the network by one time step.
 
         Args:
-            inp (Array): The external input for the current time step.
+            inp (Array): External input vector of shape ``(num,)``.
+
+        Returns:
+            None
         """
         self.inp.value = inp
         # The numerator for the firing rate calculation (a non-linear activation function).
@@ -231,10 +253,21 @@ class CANN1D(BaseCANN1D):
 
 
 class CANN1D_SFA(BaseCANN1D):
-    """
-    A 1D CANN model that incorporates Spike-Frequency Adaptation (SFA).
-    SFA is a slow negative feedback mechanism that causes neurons to fire less
-    over time for a sustained input, which can induce anticipative tracking behavior.
+    """1D CANN model with spike-frequency adaptation (SFA).
+
+    SFA adds a slow negative feedback term that can create anticipative tracking
+    under sustained inputs.
+
+    Examples:
+        >>> import brainpy.math as bm
+        >>> from canns.models.basic import CANN1D_SFA
+        >>>
+        >>> bm.set_dt(0.1)
+        >>> model = CANN1D_SFA(num=64)
+        >>> stimulus = model.get_stimulus_by_pos(0.0)
+        >>> model.update(stimulus)
+        >>> model.r.value.shape
+        (64,)
 
     Reference:
         Mi, Y., Fung, C. C., Wong, K. Y., & Wu, S. (2014). Spike frequency adaptation
@@ -278,12 +311,13 @@ class CANN1D_SFA(BaseCANN1D):
         self.inp = bm.Variable(bm.zeros(self.shape))  # External input.
 
     def update(self, inp):
-        """
-        The main update function for the SFA model. It includes dynamics for both
-        the membrane potential and the adaptation variable.
+        """Advance the network by one time step with adaptation.
 
         Args:
-            inp (Array): The external input for the current time step.
+            inp (Array): External input vector of shape ``(num,)``.
+
+        Returns:
+            None
         """
         self.inp.value = inp
         # Firing rate calculation is the same as the standard CANN model.
@@ -302,11 +336,20 @@ class CANN1D_SFA(BaseCANN1D):
 
 
 class BaseCANN2D(BaseCANN):
-    """
-    Base class for 2D Continuous Attractor Neural Network (CANN) models.
-    This class sets up the fundamental properties of the network, including
-    neuronal properties, feature space, and the connectivity matrix, which
-    are shared by different CANN model variations.
+    """Base class for 2D Continuous Attractor Neural Network (CANN) models.
+
+    It builds the 2D feature space, connectivity kernel, and stimulus helpers
+    shared by 2D CANN variants.
+
+    Examples:
+        >>> import brainpy.math as bm
+        >>> from canns.models.basic.cann import BaseCANN2D
+        >>>
+        >>> bm.set_dt(0.1)
+        >>> model = BaseCANN2D(length=16)
+        >>> stimulus = model.get_stimulus_by_pos([0.0, 0.0])
+        >>> stimulus.shape
+        (16, 16)
     """
 
     def __init__(
@@ -456,10 +499,18 @@ class BaseCANN2D(BaseCANN):
 
 
 class CANN2D(BaseCANN2D):
-    """
-    A 2D Continuous Attractor Neural Network (CANN) model.
-    This model extends the base CANN2D class to include specific dynamics
-    and properties for a 2D neural network.
+    """2D Continuous Attractor Neural Network (CANN) model.
+
+    Examples:
+        >>> import brainpy.math as bm
+        >>> from canns.models.basic import CANN2D
+        >>>
+        >>> bm.set_dt(0.1)
+        >>> model = CANN2D(length=16)
+        >>> stimulus = model.get_stimulus_by_pos([0.0, 0.0])
+        >>> model.update(stimulus)
+        >>> model.r.value.shape
+        (16, 16)
 
     Reference:
         Wu, S., Hamaguchi, K., & Amari, S. I. (2008). Dynamics and computation of continuous attractors.
@@ -485,11 +536,13 @@ class CANN2D(BaseCANN2D):
         self.inp = bm.Variable(bm.zeros((self.length, self.length)))
 
     def update(self, inp):
-        """
-        The main update function, defining the dynamics of the network for one time step.
+        """Advance the network by one time step.
 
         Args:
-            inp (Array): The external input to the network, which can be a stimulus or other driving force.
+            inp (Array): External input grid of shape ``(length, length)``.
+
+        Returns:
+            None
         """
         self.inp.value = inp
         # The numerator for the firing rate calculation (a non-linear activation function).
@@ -505,10 +558,18 @@ class CANN2D(BaseCANN2D):
 
 
 class CANN2D_SFA(BaseCANN2D):
-    """
-    A 2D Continuous Attractor Neural Network (CANN) model with a specific
-    implementation of the Synaptic Firing Activity (SFA) dynamics.
-    This model extends the base CANN2D class to include SFA-specific dynamics.
+    """2D CANN model with spike-frequency adaptation (SFA) dynamics.
+
+    Examples:
+        >>> import brainpy.math as bm
+        >>> from canns.models.basic import CANN2D_SFA
+        >>>
+        >>> bm.set_dt(0.1)
+        >>> model = CANN2D_SFA(length=16)
+        >>> stimulus = model.get_stimulus_by_pos([0.0, 0.0])
+        >>> model.update(stimulus)
+        >>> model.r.value.shape
+        (16, 16)
     """
 
     def __init__(
@@ -544,12 +605,13 @@ class CANN2D_SFA(BaseCANN2D):
         self.inp = bm.Variable(bm.zeros((self.length, self.length)))  # External input.
 
     def update(self, inp):
-        """
-        The main update function for the SFA model. It includes dynamics for both
-        the membrane potential and the adaptation variable.
+        """Advance the network by one time step with adaptation.
 
         Args:
-            inp (Array): The external input for the current time step.
+            inp (Array): External input grid of shape ``(length, length)``.
+
+        Returns:
+            None
         """
         self.inp.value = inp
         # Firing rate calculation is the same as the standard CANN model.

canns/models/basic/grid_cell.py

@@ -54,18 +54,19 @@ class GridCell2DPosition(BasicModel):
 
     Example:
         >>> import brainpy.math as bm
-        >>> from canns.models.basic import GridCell2D
+        >>> from canns.models.basic import GridCell2DPosition
         >>>
         >>> bm.set_dt(1.0)
-        >>> model = GridCell2D(length=30, mapping_ratio=1.5)
+        >>> model = GridCell2DPosition(length=16, mapping_ratio=1.5)
         >>>
-        >>> # Update with 2D position
-        >>> position = [0.5, 0.3]
+        >>> # Update with a 2D position
+        >>> position = bm.array([0.5, 0.3])
         >>> model.update(position)
         >>>
         >>> # Access decoded position
         >>> decoded_pos = model.center_position.value
-        >>> print(f"Decoded position: {decoded_pos}")
+        >>> decoded_pos.shape
+        (2,)
 
     References:
         Burak, Y., & Fiete, I. R. (2009).
@@ -387,11 +388,11 @@ class GridCell2DVelocity(BasicModel):
         >>> bm.set_dt(5e-4)  # Small timestep for accurate integration
         >>> model = GridCell2DVelocity(length=40)
         >>>
-        >>> # Healing process (critical!)
-        >>> model.heal_network()
+        >>> # Healing process (recommended before simulation)
+        >>> model.heal_network(num_healing_steps=50, dt_healing=1e-3)
         >>>
         >>> # Update with 2D velocity
-        >>> velocity = [0.1, 0.05]  # [vx, vy] in m/s
+        >>> velocity = bm.array([0.1, 0.05])  # [vx, vy]
         >>> model.update(velocity)
 
     References: