Head direction flexibility

[TomGeorge1234]

Egocentric representations (e.g. HeadDirectionCells and egocentric BoundaryVectorCells) require the agents head direction to calculate their firing rates. Currently the head direction of the Agent is assumed to just be the normalised velocity. This is a little restrictive. It would be better if there was a separate variable which could, in theory, be independent from velocity. Here's what I propose:

A new variable Agent.head_direction : np.ndarray(shape=(2,). By default Agent.head_direction is updated to be equal to the (normalised) Agent.velocity at each time step. However, if a new input parameter ("head_direction_smoothing_timescale" defaulting to zero) is non-zero then the head direction can be equal to the velocity vector smoothed by an exponential kernel. This should allowhead_direction` to be less noisy even if the velocity vector is noisy.

In the future users could generalise this further and even have entirely independent dynamics for the head direction vector.

[TomGeorge1234]

To clarify for @mehulrastogi:

• [ ] Head direction should be a variable called Agent.head_direction.

• [ ] It should be saved to the history dictionary each timestep, just like Ag.pos and Ag.velocity

• [ ] Inside the Agent params dictionary there should be a new param called head_direction_smoothing_timescale : float (in the equation below this is $\tau$). This defaults to $0.0$.

• [ ] Update the doc string to clarify what this param does

• [ ] Within Agent.update() there should be a call to a function called self.update_head_direction(dt)

• [ ] The update rule should be as follows (where $\hat{v}$ is the normalised velocity vector): $$hd = (1 - \frac{dt}{\tau}) \cdot hd + \frac{dt}{\tau} \hat{v}$$ then normalise it $$hd = \frac{hd}{|hd|}$$ Note: you'll need a catch for if $\tau==0$ when the update should just be $hd = \hat{v}$ or else you'll get divide by zero error. Even better would be an additional warning if $\tau$ is non-zero but smaller than $dt$ as this is when the equation breaks down. This warning should strongly advise then to increase $\tau$ or decrease $dt$ to avoid numerical problems but otherwise probably let them go ahead.

• [ ] This change should then reflected in the following Neurons classes which use head direction:

• ObjectVectorCells

• BoundaryVectorCells

• HeadDirectionCells

• [ ] It would be nice to keep support for 1D too even though here head direction is trivial, just a 1D array either [1.0] (forward) or [-1.0] (backwards).

Thanks! Let me know if you run into any troubles