src.canns.models.basic.theta_sweep_model

Classes

DirectionCellNetwork	1D continuous-attractor direction (head direction) cell network.
GridCellNetwork	2D continuous-attractor grid cell network with hexagonal lattice structure.
PlaceCellNetwork	Graph-based continuous-attractor place cell network using environment geodesic distances.

Functions

calculate_theta_modulation(time_step, linear_gain, ...)

Calculate theta oscillation phase and modulation factors for direction and grid cell networks.

Module Contents

class src.canns.models.basic.theta_sweep_model.DirectionCellNetwork(num, tau=10.0, tau_v=100.0, noise_strength=0.1, k=0.2, adaptation_strength=15.0, a=0.7, A=3.0, J0=1.0, g=1.0, z_min=-bm.pi, z_max=bm.pi, conn_noise=0.0)

Bases: src.canns.models.basic._base.BasicModel

1D continuous-attractor direction (head direction) cell network.

This network implements a ring attractor model for representing head direction with theta-modulated dynamics and spike-frequency adaptation (SFA). The model exhibits key properties of biological head direction cells including: - Persistent activity bumps encoding current heading - Theta phase precession relative to turning angle - Anticipative tracking through adaptation mechanisms

The network dynamics include: - Membrane potential (u) with recurrent excitation and global inhibition - Adaptation variable (v) implementing slow negative feedback - Firing rate (r) computed via divisive normalization - External input modulated by theta oscillations

Parameters:

• num (int) – Number of neurons in the network (resolution of head direction representation)

• tau (float) – Membrane time constant (ms). Controls speed of neural dynamics.

• tau_v (float) – Adaptation time constant (ms). Larger values = slower adaptation.

• noise_strength (float) – Standard deviation of Gaussian noise added to inputs

• k (float) – Global inhibition strength for divisive normalization

• adaptation_strength (float) – Strength of adaptation coupling (dimensionless)

• a (float) – Width of connectivity kernel (radians). Determines bump width.

• A (float) – Amplitude of external input bump

• J0 (float) – Peak recurrent connection strength

• g (float) – Gain parameter for firing rate transformation

• z_min (float) – Minimum value of feature space (default: -π)

• z_max (float) – Maximum value of feature space (default: π)

• conn_noise (float) – Standard deviation of Gaussian noise added to connectivity matrix

num

Number of neurons

Type:

int

x

Preferred directions of neurons, uniformly distributed in [z_min, z_max)

Type:

Array

conn_mat

Recurrent connectivity matrix with Gaussian profile

Type:

Array

r

Firing rates of neurons

Type:

HiddenState

u

Membrane potentials

Type:

HiddenState

v

Adaptation variables

Type:

HiddenState

center

Current bump center position

Type:

State

m

Effective adaptation strength (adaptation_strength * tau / tau_v)

Type:

float

Example

>>> import brainpy.math as bm
>>> from canns.models.basic.theta_sweep_model import DirectionCellNetwork
>>>
>>> bm.set_dt(1.)  # 1ms time step
>>> dc_net = DirectionCellNetwork(num=60)
>>>
>>> # Update with head direction and theta modulation
>>> head_direction = 0.5  # radians
>>> theta_modulation = 1.2  # theta phase-dependent gain
>>> dc_net.update(head_direction, theta_modulation)

References

Ji, Z., Lomi, E., Jeffery, K., Mitchell, A. S., & Burgess, N. (2025). Phase Precession Relative to Turning Angle in Theta‐Modulated Head Direction Cells. Hippocampus, 35(2), e70008.

calculate_dist(d)

Calculate distance on circular feature space with periodic boundary.

Parameters:

d – Raw angular difference

Returns:

Shortest angular distance considering periodicity

static get_bump_center(r, x)

Decode bump center from population activity using circular mean.

Parameters:

• r – Firing rate vector

• x – Preferred direction vector

Returns:

Decoded center position in radians

static handle_periodic_condition(A)

input_bump(head_direction)

Generate Gaussian-shaped external input centered on target direction.

Parameters:

head_direction – Center of input bump in radians

Returns:

Input vector of shape (num,)

make_connection()

Generate recurrent connectivity matrix with Gaussian profile.

Creates a circulant connectivity matrix where connection strength decreases with distance according to a Gaussian kernel.

Returns:

Connectivity matrix

Return type:

Array of shape (num, num)

update(head_direction, theta_input)

Single time-step update of network dynamics.

Parameters:

• head_direction – Target head direction in radians [-π, π]

• theta_input – Theta modulation factor (typically 1.0 ± theta_strength)

A = 3.0

J0 = 1.0

a = 0.7

adaptation_strength = 15.0

center

centerI

conn_mat

Initialize network state variables.

Creates and initializes: - r: Firing rates (all zeros) - u: Membrane potentials (all zeros) - v: Adaptation variables (all zeros) - center: Current bump center (zero) - centerI: Input bump center (zero)

conn_noise = 0.0

property derivative

g = 1.0

integral

k = 0.2

m = 1.5

noise_strength = 0.1

num

r

tau = 10.0

tau_v = 100.0

u

v

x

z_max

z_min

z_range

class src.canns.models.basic.theta_sweep_model.GridCellNetwork(num_dc=100, num_gc_x=100, tau=10.0, tau_v=100.0, noise_strength=0.1, conn_noise=0.0, k=1.0, adaptation_strength=15.0, a=0.8, A=3.0, J0=5.0, g=1000.0, mapping_ratio=1, phase_offset=1.0 / 20)

Bases: src.canns.models.basic._base.BasicModel

2D continuous-attractor grid cell network with hexagonal lattice structure.

This network implements a twisted torus topology that generates grid cell-like spatial representations with hexagonal periodicity. The model combines: - 2D continuous attractor dynamics on a twisted manifold - Spike-frequency adaptation for theta modulation - Integration of direction cell inputs via conjunctive cells - Phase offset mechanism for theta sweeps

The network operates in a transformed coordinate system where grid cells form a hexagonal lattice, enabling realistic grid field spacing and orientation.

Parameters:

• num_dc (int) – Number of direction cells providing heading input

• num_gc_x (int) – Number of grid cells along one dimension (total = num_gc_x^2)

• tau (float) – Membrane time constant (ms)

• tau_v (float) – Adaptation time constant (ms). Larger = slower adaptation.

• noise_strength (float) – Standard deviation of activity noise

• conn_noise (float) – Standard deviation of connectivity noise

• k (float) – Global inhibition strength for divisive normalization

• adaptation_strength (float) – Coupling strength between u and v

• a (float) – Width of connectivity kernel. Determines bump width.

• A (float) – Amplitude of external input

• J0 (float) – Peak recurrent connection strength

• g (float) – Firing rate gain factor (scales to biological range)

• mapping_ratio (float) – Controls grid spacing (larger = smaller spacing). Grid spacing λ = 2π / mapping_ratio

• phase_offset (float) – Phase shift for conjunctive input, drives theta sweeps. Expressed as fraction of [-π, π] range (default: 1/20)

num

Total number of grid cells (num_gc_x^2)

Type:

int

x_grid, y_grid

Grid cell preferred phases in [-π, π]

Type:

Array

value_grid

Neuron positions in phase space, shape (num, 2)

Type:

Array

Lambda

Grid spacing in real space

Type:

float

coor_transform

Hexagonal to rectangular coordinate transform

Type:

Array

conn_mat

Recurrent connectivity matrix

Type:

Array

candidate_centers

Grid of candidate bump centers for decoding

Type:

Array

r

Firing rates

Type:

HiddenState

u

Membrane potentials

Type:

HiddenState

v

Adaptation variables

Type:

HiddenState

center_phase

Decoded bump center in phase space

Type:

State

center_position

Decoded position in real space

Type:

State

gc_bump

Grid cell bump activity pattern

Type:

State

Example

>>> import brainpy.math as bm
>>> from canns.models.basic.theta_sweep_model import GridCellNetwork
>>>
>>> bm.set_dt(1.0)
>>> gc_net = GridCellNetwork(num_dc=60, num_gc_x=30, mapping_ratio=1.5)
>>>
>>> # Update with position, direction activity, and theta modulation
>>> position = [0.5, 0.3]  # animal position
>>> dir_activity = np.random.rand(60)  # direction cell firing
>>> theta_mod = 1.2  # theta phase modulation
>>> gc_net.update(position, dir_activity, theta_mod)

References

Ji, Z., Chu, T., Wu, S., & Burgess, N. (2025). A systems model of alternating theta sweeps via firing rate adaptation. Current Biology, 35(4), 709-722.

calculate_dist(d)

d: (…, 2) displacement in original (x,y). Return Euclidean distance after transform (hex/rect).

calculate_input_from_conjgc(animal_pos, direction_activity, theta_modulation)

Calculate external input to grid cells from conjunctive grid cells.

Conjunctive cells integrate position and direction to generate grid cell inputs with phase offsets. This drives theta sweeps when modulated by theta oscillations.

Parameters:

• animal_pos – Current position [x, y]

• direction_activity – Direction cell firing rates (shape: num_dc)

• theta_modulation – Theta phase-dependent gain factor

Returns:

Weighted conjunctive input to grid cells

Return type:

Array of shape (num_gc,)

get_unique_activity_bump(network_activity, animal_posistion)

Estimate a unique bump (activity peak) from the current network state, given the animal’s actual position.

Returns:

(2,) array

Phase coordinates of bump center on the manifold.

center_position(2,) array

Real-space position of the bump (nearest candidate).

bump(N,) array

Gaussian bump template centered at center_position.

Return type:

center_phase

handle_periodic_condition(d)

Apply periodic boundary conditions to wrap phases into [-π, π].

Parameters:

d – Phase values (any shape)

Returns:

Wrapped phase values in [-π, π]

make_candidate_centers(Lambda)

Generate grid of candidate bump centers for decoding.

Creates a regular lattice of potential activity bump locations used for disambiguating position from grid cell phases.

Parameters:

Lambda – Grid spacing in real space

Returns:

Candidate centers in transformed coordinates

Return type:

Array of shape (N_c*N_c, 2)

make_connection()

Generate recurrent connectivity matrix with 2D Gaussian kernel.

Uses hexagonal lattice geometry via coordinate transformation. Connection strength decays with distance in transformed space.

Returns:

Recurrent connectivity matrix

Return type:

Array of shape (num, num)

position2phase(position)

Convert real-space position to grid cell phase coordinates.

Applies coordinate transformation and wraps to periodic boundaries. Each grid cell’s preferred phase is determined by the animal’s position on the hexagonal lattice.

Parameters:

position – Real-space coordinates, shape (2,) or (2, N)

Returns:

Phase coordinates in [-π, π] per axis

Return type:

Array of shape (2,) or (2, N)

update(animal_posistion, direction_activity, theta_modulation)

Single time-step update of grid cell network dynamics.

Integrates conjunctive inputs from direction cells, applies theta modulation, and updates grid cell activity via continuous attractor dynamics with adaptation.

Parameters:

• animal_posistion – Current position [x, y] for disambiguating grid phase

• direction_activity – Direction cell firing rates (shape: num_dc)

• theta_modulation – Theta phase-dependent gain factor

A = 3.0

J0 = 5.0

Lambda

a = 0.8

adaptation_strength = 15.0

candidate_centers

center_phase

center_position

conj_input

conn_mat

Initialize network state variables.

Creates and initializes: - r: Firing rates (shape: num) - u: Membrane potentials (shape: num) - v: Adaptation variables (shape: num) - gc_bump: Grid cell bump pattern (shape: num) - conj_input: Conjunctive cell input (shape: num) - center_phase: Bump center in phase space (shape: 2) - center_position: Decoded position in real space (shape: 2)

conn_noise = 0.0

coor_transform

coor_transform_inv

property derivative

g = 1000.0

gc_bump

integral

k = 1.0

m = 1.5

mapping_ratio = 1

noise_strength = 0.1

num = 10000

num_dc = 100

num_gc_1side = 100

phase_offset = 0.05

r

tau = 10.0

tau_v = 100.0

u

v

value_bump

value_grid

x_grid

y_grid

class src.canns.models.basic.theta_sweep_model.PlaceCellNetwork(geodesic_result, tau=10.0, tau_v=100.0, noise_strength=0.0, k=0.2, m=3.0, a=0.2, A=5.0, J0=1.0, g=1.0, conn_noise=0.0)

Bases: src.canns.models.basic._base.BasicModel

Graph-based continuous-attractor place cell network using environment geodesic distances.

This network implements a place cell representation where neurons are tuned to discrete locations in a navigation environment. Connectivity is based on geodesic (shortest path) distances within the environment, allowing the network to adapt to complex non-convex spaces with obstacles.

Key features: - Connectivity matrix based on geodesic distances (not Euclidean) - Replaces NetworkX graph representation with grid-based geodesic computation - Uses GeodesicDistanceResult for environment definition and distance computation - Continuous attractor dynamics with spike-frequency adaptation - Supports arbitrary environment shapes (rectangular, T-maze, complex polygons with holes/walls)

Parameters:

• geodesic_result – Geodesic distance computation result from navigation task

• tau (float) – Membrane time constant (ms). Controls speed of neural dynamics.

• tau_v (float) – Adaptation time constant (ms). Larger values = slower adaptation.

• noise_strength (float) – Standard deviation of Gaussian noise added to inputs

• k (float) – Global inhibition strength for divisive normalization

• m (float) – Strength of adaptation coupling (dimensionless)

• a (float) – Width of connectivity kernel. Determines bump width in grid units.

• A (float) – Amplitude of external input bump

• J0 (float) – Peak recurrent connection strength

• g (float) – Gain parameter for firing rate transformation

• conn_noise (float) – Standard deviation of Gaussian noise added to connectivity matrix

geodesic_result

Geodesic distance computation result

Type:

GeodesicDistanceResult

cell_num

Number of place cells (= number of accessible grid cells)

Type:

int

D

Geodesic distance matrix of shape (cell_num, cell_num)

Type:

Array

accessible_indices

Grid indices of accessible cells (cell_num, 2)

Type:

Array

cost_grid

Grid cost information for position lookups

Type:

MovementCostGrid

conn_mat

Recurrent connectivity matrix with Gaussian profile

Type:

Array

r

Firing rates of place cells

Type:

HiddenState

u

Membrane potentials

Type:

HiddenState

v

Adaptation variables

Type:

HiddenState

center

Current decoded bump center

Type:

State

m

Effective adaptation strength (adaptation_strength * tau / tau_v)

Type:

float

get_bump_center(r, x)

Decode bump center from population activity.

Uses weighted average of cell indices, normalized by total activity.

Parameters:

r – Firing rate vector (cell_num,)

Returns:

Decoded center index (scalar)

get_geodesic_index_by_pos(pos)

Get the geodesic index of the grid cell containing the given position.

Parameters:

pos – (x, y) coordinates of the position

Returns:

Index of the grid cell in the geodesic distance matrix, or None if the position is out of bounds or in an impassable cell.

input_bump(animal_pos)

Generate Gaussian bump external input centered on the animal’s current position.

Parameters:

animal_pos – Current position (x, y) tuple or array

Returns:

Input vector of shape (cell_num,)

make_connection()

Generate recurrent connectivity matrix with Gaussian profile based on geodesic distance.

Connection strength between place cells decays with geodesic distance according to a normalized Gaussian kernel.

Returns:

Connectivity matrix

Return type:

Array of shape (cell_num, cell_num)

update(animal_pos, theta_input)

Single time-step update of network dynamics.

Parameters:

• animal_pos – Current position (x, y) tuple or array

• theta_input – Theta modulation factor (typically 1.0 ± theta_strength)

A = 5.0

D

J0 = 1.0

a = 0.2

accessible_indices

cell_num

center

conn_mat

Initialize network state variables.

Creates and initializes: - r: Firing rates (all zeros) - u: Membrane potentials (all zeros) - v: Adaptation variables (all zeros) - center: Current bump center (zero)

conn_noise = 0.0

cost_grid

property derivative

g = 1.0

geodesic_result

integral

k = 0.2

m = 3.0

noise_strength = 0.0

r

tau = 10.0

tau_v = 100.0

u

v

x

src.canns.models.basic.theta_sweep_model.calculate_theta_modulation(time_step, linear_gain, ang_gain, theta_strength_hd=0.0, theta_strength_gc=0.0, theta_cycle_len=100.0, dt=None)

Calculate theta oscillation phase and modulation factors for direction and grid cell networks.

Parameters:

• time_step (int) – Current time step index

• linear_gain (float) – Normalized linear speed gain [0,1]

• ang_gain (float) – Normalized angular speed gain [-1,1]

• theta_strength_hd (float) – Theta modulation strength for head direction cells

• theta_strength_gc (float) – Theta modulation strength for grid cells

• theta_cycle_len (float) – Length of theta cycle in time units

• dt (float) – Time step size (if None, uses bm.get_dt())

Returns:

(theta_phase, theta_modulation_hd, theta_modulation_gc)

• theta_phase: Current theta phase [-π, π]

• theta_modulation_hd: Theta modulation for direction cells

• theta_modulation_gc: Theta modulation for grid cells

Return type:

tuple