src.canns.models.basic.hierarchical_model

Classes

BandCell	A model of a band cell module for path integration.
GaussRecUnits	A model of recurrently connected units with Gaussian connectivity.
GridCell	A model of a grid cell module using a 2D continuous attractor network.
HierarchicalNetwork	A full hierarchical network composed of multiple grid modules.
HierarchicalPathIntegrationModel	A hierarchical model combining band cells and grid cells for path integration.
NonRecUnits	A model of non-recurrently connected units.

Module Contents

class src.canns.models.basic.hierarchical_model.BandCell(angle, spacing, size=180, z_min=-bm.pi, z_max=bm.pi, noise=2.0, w_L2S=0.2, w_S2L=1.0, gain=0.2, gauss_tau=1.0, gauss_J0=1.1, gauss_k=0.0005, gauss_a=2 / 9 * bm.pi, nonrec_tau=0.1, **kwargs)

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

A model of a band cell module for path integration.

This model represents a set of neurons whose receptive fields form parallel bands across a 2D space. It is composed of a central GaussRecUnits attractor network (the band cells proper) that represents a 1D phase, and two NonRecUnits populations (left and right) that help shift the activity in the attractor network based on velocity input. This mechanism allows the module to integrate the component of velocity along its preferred direction.

size

The number of neurons in each sub-population.

Type:

int

spacing

The spacing between the bands in the 2D environment.

Type:

float

angle

The orientation angle of the bands.

Type:

float

proj_k

The projection vector for converting 2D position/velocity to 1D phase.

Type:

bm.math.ndarray

band_cells

The core recurrent network representing the phase.

Type:

GaussRecUnits

left

A population of non-recurrent units for positive shifts.

Type:

NonRecUnits

right

A population of non-recurrent units for negative shifts.

Type:

NonRecUnits

w_L2S

Connection weight from band cells to left/right units.

Type:

float

w_S2L

Connection weight from left/right units to band cells.

Type:

float

gain

A gain factor for velocity-modulated input.

Type:

float

center_ideal

The ideal, noise-free center based on velocity integration.

Type:

bm.Variable

center

The actual decoded center of the band cell activity bump.

Type:

bm.Variable

Initializes the BandCell model.

Parameters:

• angle (float) – The orientation angle of the bands.

• spacing (float) – The spacing between the bands.

• size (int, optional) – The number of neurons in each group. Defaults to 180.

• z_min (float, optional) – The minimum value of the feature space (phase). Defaults to -pi.

• z_max (float, optional) – The maximum value of the feature space (phase). Defaults to pi.

• noise (float, optional) – The noise level for the neuron groups. Defaults to 2.0.

• w_L2S (float, optional) – Weight from band cells to shifter units. Defaults to 0.2.

• w_S2L (float, optional) – Weight from shifter units to band cells. Defaults to 1.0.

• gain (float, optional) – A gain factor for the velocity signal. Defaults to 0.2.

• gauss_tau (float, optional) – Time constant for GaussRecUnits. Defaults to 1.0.

• gauss_J0 (float, optional) – Connection strength scaling factor for GaussRecUnits. Defaults to 1.1.

• gauss_k (float, optional) – Global inhibition strength for GaussRecUnits. Defaults to 5e-4.

• gauss_a (float, optional) – Gaussian connection width for GaussRecUnits. Defaults to 2/9*pi.

• nonrec_tau (float, optional) – Time constant for NonRecUnits. Defaults to 0.1.

• **kwargs – Additional keyword arguments for the base class.

Postophase(pos)

Projects a 2D position to a 1D phase.

This function converts a 2D coordinate in the environment into a 1D phase value based on the band cell’s preferred angle and spacing.

Parameters:

pos (Array) – The 2D position vector.

Returns:

The corresponding 1D phase.

Return type:

float

dist(d)

Calculates the periodic distance in the feature space.

Parameters:

d (Array) – The array of distances.

Returns:

The wrapped distances.

Return type:

Array

get_center()

Decodes and updates the current center of the band cell activity.

get_stimulus_by_pos(pos)

Generates a stimulus input based on a 2D position.

This creates a Gaussian bump of input centered on the phase corresponding to the given position, which can be used to anchor the network’s activity.

Parameters:

pos (Array) – The 2D position vector.

Returns:

The stimulus input vector for the band cells.

Return type:

Array

make_conn(shift)

Creates a shifted Gaussian connection profile.

This is used to create the connections from the left/right shifter units to the band cells, which implements the bump-shifting mechanism.

Parameters:

shift (float) – The amount to shift the connection profile by.

Returns:

The shifted connection matrix.

Return type:

Array

move_heading(shift)

Manually shifts the activity bump in the band cells.

This is a utility function for testing purposes.

Parameters:

shift (int) – The number of neurons to roll the activity by.

reset()

Resets the synaptic inputs of the left and right shifter units.

synapses()

Defines the synaptic connections between the neuron groups.

This method sets up the shifted connections from the left/right shifter populations to the central band cell attractor network, as well as the one-to-one connections from the band cells to the shifters.

update(velocity, loc, loc_input_stre)

Updates the BandCell module for one time step.

It integrates the component of velocity along the module’s preferred direction to update the phase representation. The activity bump is shifted by modulating the inputs from the left/right shifter populations. It can also incorporate a direct location-based input.

Parameters:

• velocity (Array) – The 2D velocity vector.

• loc (Array) – The current 2D location.

• loc_input_stre (float) – The strength of the location-based input.

angle

band_cells

center

center_ideal

dx

gain = 0.2

left

phase_shift

proj_k

rho

right

size = 180

spacing

w_L2S = 0.2

w_S2L = 1.0

x

z_max

z_min

z_range

class src.canns.models.basic.hierarchical_model.GaussRecUnits(size, tau=1.0, J0=1.1, k=0.0005, a=2 / 9 * bm.pi, z_min=-bm.pi, z_max=bm.pi, noise=2.0)

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

A model of recurrently connected units with Gaussian connectivity.

This class implements a 1D continuous attractor neural network (CANN). The network maintains a stable “bump” of activity that can represent a continuous variable, such as heading direction. The connectivity between neurons is Gaussian, and the network dynamics include divisive normalization.

size

The number of neurons in the network.

Type:

int

tau

The time constant for the synaptic input u.

Type:

float

k

The inhibition strength for divisive normalization.

Type:

float

a

The width of the Gaussian connection profile.

Type:

float

noise_0

The standard deviation of the Gaussian noise added to the system.

Type:

float

z_min

The minimum value of the encoded feature space.

Type:

float

z_max

The maximum value of the encoded feature space.

Type:

float

z_range

The range of the feature space (z_max - z_min).

Type:

float

x

The preferred feature values for each neuron.

Type:

bm.math.ndarray

rho

The neural density (number of neurons per unit of feature space).

Type:

float

dx

The stimulus density (feature space range per neuron).

Type:

float

J

The final connection strength, scaled by J0.

Type:

float

conn_mat

The connection matrix.

Type:

bm.math.ndarray

r

The firing rates of the neurons.

Type:

bm.Variable

u

The synaptic inputs to the neurons.

Type:

bm.Variable

center

The decoded center of the activity bump.

Type:

bm.Variable

input

The external input to the network.

Type:

bm.Variable

Initializes the GaussRecUnits model.

Parameters:

• size (int) – The number of neurons in the network.

• tau (float, optional) – The time constant of the neurons. Defaults to 1.0.

• J0 (float, optional) – A scaling factor for the critical connection strength. Defaults to 1.1.

• k (float, optional) – The strength of the global inhibition. Defaults to 5e-4.

• a (float, optional) – The width of the Gaussian connection profile. Defaults to 2/9*pi.

• z_min (float, optional) – The minimum value of the feature space. Defaults to -pi.

• z_max (float, optional) – The maximum value of the feature space. Defaults to pi.

• noise (float, optional) – The level of noise in the system. Defaults to 2.0.

Jc()

Calculates the critical connection strength.

This is the minimum connection strength required to sustain a stable activity bump in the attractor network.

decode(r, axis=0)

Decodes the center of the activity bump.

This method uses a population vector average to compute the center of the neural activity bump from the firing rates.

Parameters:

• r (Array) – The firing rates of the neurons.

• axis (int, optional) – The axis along which to perform the decoding. Defaults to 0.

Returns:

The angle representing the decoded center of the bump.

Return type:

float

dist(d)

Calculates the periodic distance in the feature space.

This function wraps distances to ensure they fall within the periodic boundaries of the feature space, i.e., [-z_range/2, z_range/2].

Parameters:

d (bm.math.ndarray) – The array of distances.

make_conn()

Constructs the periodic Gaussian connection matrix.

The connection strength between two neurons depends on the periodic distance between their preferred feature values, following a Gaussian profile.

update(input)

J

a

center

conn_mat

dx

input

k = 0.0005

noise_0 = 2.0

r

rho

size

tau = 1.0

u

x

z_max

z_min

z_range

class src.canns.models.basic.hierarchical_model.GridCell(num, angle, spacing, tau=0.1, tau_v=10.0, k=0.005, a=bm.pi / 9, A=1.0, J0=1.0, mbar=1.0)

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

A model of a grid cell module using a 2D continuous attractor network.

This class implements a 2D continuous attractor network on a toroidal manifold to model the firing patterns of grid cells. The network dynamics include synaptic depression or adaptation, which helps stabilize the activity bumps. The connectivity is defined on a hexagonal grid structure.

num

The total number of neurons (num_side x num_side).

Type:

int

tau

The synaptic time constant for u.

Type:

float

tau_v

The time constant for the adaptation variable v.

Type:

float

k

The degree of rescaled inhibition.

Type:

float

a

The half-width of the excitatory connection range.

Type:

float

A

The magnitude of the external input.

Type:

float

J0

The maximum connection value.

Type:

float

m

The strength of the adaptation.

Type:

float

angle

The orientation of the grid.

Type:

float

value_grid

The (x, y) preferred phase coordinates for each neuron.

Type:

bm.math.ndarray

conn_mat

The connection matrix.

Type:

bm.math.ndarray

r

The firing rates of the neurons.

Type:

bm.Variable

u

The synaptic inputs to the neurons.

Type:

bm.Variable

v

The adaptation variables for the neurons.

Type:

bm.Variable

center

The decoded 2D center of the activity bump.

Type:

bm.Variable

Initializes the GridCell model.

Parameters:

• num (int) – The number of neurons along one dimension of the square grid.

• angle (float) – The orientation angle of the grid pattern.

• spacing (float) – The spacing of the grid pattern.

• tau (float, optional) – The synaptic time constant. Defaults to 0.1.

• tau_v (float, optional) – The adaptation time constant. Defaults to 10.0.

• k (float, optional) – The strength of global inhibition. Defaults to 5e-3.

• a (float, optional) – The width of the connection profile. Defaults to pi/9.

• A (float, optional) – The magnitude of external input. Defaults to 1.0.

• J0 (float, optional) – The maximum connection strength. Defaults to 1.0.

• mbar (float, optional) – The base strength of adaptation. Defaults to 1.0.

circle_period(d)

Wraps values into the periodic range [-pi, pi].

Parameters:

d (Array) – The input values.

Returns:

The wrapped values.

Return type:

Array

dist(d)

Calculates the distance on the hexagonal grid.

It first maps the periodic difference vector d into a Cartesian coordinate system that reflects the hexagonal lattice structure and then computes the Euclidean distance.

Parameters:

d (Array) – An array of difference vectors in the phase space.

Returns:

The corresponding distances on the hexagonal lattice.

Return type:

Array

get_center()

Decodes and updates the 2D center of the activity bump.

It uses a population vector average for both the x and y dimensions of the phase space.

make_conn()

Constructs the connection matrix for the 2D attractor network.

The connection strength between two neurons is a Gaussian function of the hexagonal distance between their preferred phases.

Returns:

The connection matrix (num x num).

Return type:

Array

reset_state(*args, **kwargs)

Resets the state variables of the model to zeros.

update(input)

A = 1.0

J0 = 1.0

a

angle

center

conn_mat

coor_transform

property derivative

dxy

input

integral

k = 0.005

m = 0.01

num

r

ratio

rho

rot

tau = 0.1

tau_v = 10.0

u

v

value_grid

x

x_grid

x_range

y_grid

class src.canns.models.basic.hierarchical_model.HierarchicalNetwork(num_module, num_place, spacing_min=2.0, spacing_max=5.0, module_angle=0.0, band_size=180, band_noise=0.0, band_w_L2S=0.2, band_w_S2L=1.0, band_gain=0.2, grid_num=20, grid_tau=0.1, grid_tau_v=10.0, grid_k=0.005, grid_a=bm.pi / 9, grid_A=1.0, grid_J0=1.0, grid_mbar=1.0, gauss_tau=1.0, gauss_J0=1.1, gauss_k=0.0005, gauss_a=2 / 9 * bm.pi, nonrec_tau=0.1)

Bases: src.canns.models.basic._base.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.

num_module

The number of grid modules in the network.

Type:

int

num_place

The number of place cells in the output layer.

Type:

int

place_center

The center locations of the place cells.

Type:

bm.math.ndarray

MEC_model_list

A list containing all the HierarchicalPathIntegrationModel instances.

Type:

list

grid_fr

The firing rates of the grid cell population.

Type:

bm.Variable

band_x_fr

The firing rates of the x-oriented band cell population.

Type:

bm.Variable

band_y_fr

The firing rates of the y-oriented band cell population.

Type:

bm.Variable

place_fr

The firing rates of the place cell population.

Type:

bm.Variable

decoded_pos

The final decoded 2D position.

Type:

bm.Variable

References

Anonymous Author(s) “Unfolding the Black Box of Recurrent Neural Networks for Path Integration” (under review).

Initializes the HierarchicalNetwork.

Parameters:

• num_module (int) – The number of grid modules to create.

• num_place (int) – The number of place cells along one dimension of a square grid.

• spacing_min (float, optional) – Minimum spacing for grid modules. Defaults to 2.0.

• spacing_max (float, optional) – Maximum spacing for grid modules. Defaults to 5.0.

• module_angle (float, optional) – Base orientation angle for all modules. Defaults to 0.0.

• band_size (int, optional) – Number of neurons in each BandCell group. Defaults to 180.

• band_noise (float, optional) – Noise level for BandCells. Defaults to 0.0.

• band_w_L2S (float, optional) – Weight from band cells to shifter units. Defaults to 0.2.

• band_w_S2L (float, optional) – Weight from shifter units to band cells. Defaults to 1.0.

• band_gain (float, optional) – Gain factor for velocity signal in BandCells. Defaults to 0.2.

• grid_num (int, optional) – Number of neurons per dimension for GridCell. Defaults to 20.

• grid_tau (float, optional) – Synaptic time constant for GridCell. Defaults to 0.1.

• grid_tau_v (float, optional) – Adaptation time constant for GridCell. Defaults to 10.0.

• grid_k (float, optional) – Global inhibition strength for GridCell. Defaults to 5e-3.

• grid_a (float, optional) – Connection width for GridCell. Defaults to pi/9.

• grid_A (float, optional) – External input magnitude for GridCell. Defaults to 1.0.

• grid_J0 (float, optional) – Maximum connection strength for GridCell. Defaults to 1.0.

• grid_mbar (float, optional) – Base adaptation strength for GridCell. Defaults to 1.0.

• gauss_tau (float, optional) – Time constant for GaussRecUnits in BandCells. Defaults to 1.0.

• gauss_J0 (float, optional) – Connection strength scaling for GaussRecUnits. Defaults to 1.1.

• gauss_k (float, optional) – Global inhibition for GaussRecUnits. Defaults to 5e-4.

• gauss_a (float, optional) – Connection width for GaussRecUnits. Defaults to 2/9*pi.

• nonrec_tau (float, optional) – Time constant for NonRecUnits in BandCells. Defaults to 0.1.

update(velocity, loc, loc_input_stre=0.0)

MEC_model_list = []

band_x_fr

band_y_fr

decoded_pos

grid_fr

num_module

num_place

place_center

place_fr

class src.canns.models.basic.hierarchical_model.HierarchicalPathIntegrationModel(spacing, angle, place_center=None, band_size=180, band_noise=0.0, band_w_L2S=0.2, band_w_S2L=1.0, band_gain=0.2, grid_num=20, grid_tau=0.1, grid_tau_v=10.0, grid_k=0.005, grid_a=bm.pi / 9, grid_A=1.0, grid_J0=1.0, grid_mbar=1.0, gauss_tau=1.0, gauss_J0=1.1, gauss_k=0.0005, gauss_a=2 / 9 * bm.pi, nonrec_tau=0.1)

Bases: src.canns.models.basic._base.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.

band_cell_x

The first band cell module (orientation angle).

Type:

BandCell

band_cell_y

The second band cell module (orientation angle + 60 deg).

Type:

BandCell

band_cell_z

The third band cell module (orientation angle + 120 deg).

Type:

BandCell

grid_cell

The grid cell module driven by the band cells.

Type:

GridCell

place_center

The center locations of the target place cells.

Type:

bm.math.ndarray

Wg2p

The connection weights from grid cells to place cells.

Type:

bm.math.ndarray

grid_output

The activity of the place cells.

Type:

bm.Variable

Initializes the HierarchicalPathIntegrationModel.

Parameters:

• spacing (float) – The spacing of the grid pattern for this module.

• angle (float) – The base orientation angle for the module.

• place_center (bm.math.ndarray, optional) – The center locations of the target place cell population. Defaults to a random distribution.

• band_size (int, optional) – Number of neurons in each BandCell group. Defaults to 180.

• band_noise (float, optional) – Noise level for BandCells. Defaults to 0.0.

• band_w_L2S (float, optional) – Weight from band cells to shifter units. Defaults to 0.2.

• band_w_S2L (float, optional) – Weight from shifter units to band cells. Defaults to 1.0.

• band_gain (float, optional) – Gain factor for velocity signal in BandCells. Defaults to 0.2.

• grid_num (int, optional) – Number of neurons per dimension for GridCell. Defaults to 20.

• grid_tau (float, optional) – Synaptic time constant for GridCell. Defaults to 0.1.

• grid_tau_v (float, optional) – Adaptation time constant for GridCell. Defaults to 10.0.

• grid_k (float, optional) – Global inhibition strength for GridCell. Defaults to 5e-3.

• grid_a (float, optional) – Connection width for GridCell. Defaults to pi/9.

• grid_A (float, optional) – External input magnitude for GridCell. Defaults to 1.0.

• grid_J0 (float, optional) – Maximum connection strength for GridCell. Defaults to 1.0.

• grid_mbar (float, optional) – Base adaptation strength for GridCell. Defaults to 1.0.

• gauss_tau (float, optional) – Time constant for GaussRecUnits in BandCells. Defaults to 1.0.

• gauss_J0 (float, optional) – Connection strength scaling for GaussRecUnits. Defaults to 1.1.

• gauss_k (float, optional) – Global inhibition for GaussRecUnits. Defaults to 5e-4.

• gauss_a (float, optional) – Connection width for GaussRecUnits. Defaults to 2/9*pi.

• nonrec_tau (float, optional) – Time constant for NonRecUnits in BandCells. Defaults to 0.1.

Postophase(pos)

Projects a 2D position to the 2D phase space of the grid module.

Parameters:

pos (Array) – The 2D position vector.

Returns:

The corresponding 2D phase vector.

Return type:

Array

dist(d)

Calculates the distance on the hexagonal grid.

Parameters:

d (Array) – An array of difference vectors in the phase space.

Returns:

The corresponding distances on the hexagonal lattice.

Return type:

Array

get_input(Phase)

Generates a stimulus input for the grid cell based on a 2D phase.

Parameters:

Phase (Array) – The 2D phase vector.

Returns:

The stimulus input vector for the grid cells.

Return type:

Array

make_Wg2p()

Creates the connection weights from grid cells to place cells.

The connection strength is determined by the proximity of a place cell’s center to a grid cell’s firing field, calculated in the phase domain.

make_conn()

Creates the connection matrices from the band cells to the grid cells.

The connection from a band cell to a grid cell is strong if the grid cell’s preferred phase along the band cell’s direction matches the band cell’s preferred phase.

update(velocity, loc, loc_input_stre=0.0)

band_cell_x

band_cell_y

band_cell_z

coor_transform

grid_cell

grid_output

num_place

place_center = None

proj_k_x

proj_k_y

class src.canns.models.basic.hierarchical_model.NonRecUnits(size, tau=0.1, z_min=-bm.pi, z_max=bm.pi, noise=2.0)

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

A model of non-recurrently connected units.

This class implements a simple leaky integrator model for a population of neurons that do not have recurrent connections among themselves. They respond to external inputs and have a non-linear activation function.

size

The number of neurons.

Type:

int

noise_0

The standard deviation of the Gaussian noise.

Type:

float

tau

The time constant for the synaptic input u.

Type:

float

z_min

The minimum value of the encoded feature space.

Type:

float

z_max

The maximum value of the encoded feature space.

Type:

float

z_range

The range of the feature space.

Type:

float

x

The preferred feature values for each neuron.

Type:

bm.ndarray

rho

The neural density.

Type:

float

dx

The stimulus density.

Type:

float

r

The firing rates of the neurons.

Type:

bm.Variable

u

The synaptic inputs to the neurons.

Type:

bm.Variable

input

The external input to the neurons.

Type:

bm.Variable

Initializes the NonRecUnits model.

Parameters:

• size (int) – The number of neurons.

• tau (float, optional) – The time constant of the neurons. Defaults to 0.1.

• z_min (float, optional) – The minimum value of the feature space. Defaults to -pi.

• z_max (float, optional) – The maximum value of the feature space. Defaults to pi.

• noise (float, optional) – The level of noise in the system. Defaults to 2.0.

activate(x)

Applies an activation function to the input.

Parameters:

x (Array) – The input to the activation function (e.g., synaptic input u).

Returns:

The result of the activation function (ReLU).

Return type:

Array

dist(d)

Calculates the periodic distance in the feature space.

This function wraps distances to ensure they fall within the periodic boundaries of the feature space.

Parameters:

d (Array) – The array of distances.

Returns:

The wrapped distances.

Return type:

Array

update(input)

dx

input

noise_0 = 2.0

r

rho

size

tau = 0.1

u

x

z_max

z_min

z_range