GaborKernel

GaborKernel#

class braintools.conn.GaborKernel(sigma, frequency, theta, phase=0.0, max_distance=None, allow_self_connections=False, weight=None, delay=None, **kwargs)#

Gabor kernel connectivity for orientation-selective receptive fields.

Implements Gabor filters in spatial connectivity, useful for creating orientation-selective neurons similar to V1 simple cells.

Only the first two position dimensions (x, y) are used; any extra columns (e.g. z) are ignored.

Parameters:
  • sigma (Array | ndarray | bool | number | bool | int | float | complex | Quantity) – Standard deviation of Gaussian envelope.

  • frequency (float) – Frequency of the sinusoidal component, expressed in cycles per position-unit (i.e. 1 / pos_unit). This is NOT unit-converted: the rotated coordinates are taken in the position unit, so the wavelength changes if the position unit changes. Express frequency in the same length unit as the positions.

  • theta (float) – Orientation angle in radians.

  • phase (float) – Phase offset in radians (default: 0).

  • max_distance (Array | ndarray | bool | number | bool | int | float | complex | Quantity | None) – Maximum distance for connections (default: 3*sigma).

  • allow_self_connections (bool) – Whether a neuron may connect to itself when pre and post are the same population (default: False).

  • weight (Initialization | float | int | ndarray | Array | Quantity | None) – Weight initialization (Gabor values are multiplied by this).

  • delay (Initialization | float | int | ndarray | Array | Quantity | None) – Delay initialization.

Raises:

ValueError – At generation time, if sigma is not positive.

Notes

For a pre neuron at offset (dx, dy) from a post neuron, the weight is G(r) * cos(2 * pi * frequency * x_rot + phase), where r is the distance, x_rot = dx * cos(theta) + dy * sin(theta) and the Gaussian envelope G is evaluated by braintools.init.GaussianProfile. Weights whose magnitude is not above 1e-3 are dropped.

Candidate pairs are found with a k-d tree over the positions and handled in chunks of bounded size, so memory grows with the number of edges rather than with pre_size * post_size. The edges, their order and the weights are the same as in version 0.3 (up to rounding). Generation runs on the host with NumPy and cannot be traced by jax.jit, jax.vmap or jax.grad.

Examples

>>> import brainunit as u
>>> import numpy as np
>>> from braintools.conn import GaborKernel
>>> positions = np.random.RandomState(0).uniform(0, 1000, (500, 2)) * u.um
>>> gabor = GaborKernel(
...     sigma=50 * u.um,
...     frequency=0.02,  # 1 cycle per 50 um
...     theta=np.pi / 4,  # 45 degrees
...     weight=1.0 * u.nS
... )
>>> result = gabor(
...     pre_size=500, post_size=500,
...     pre_positions=positions, post_positions=positions
... )
>>> result.n_connections
15086
generate(pre_size, post_size, pre_positions=None, post_positions=None, **kwargs)[source]#

Generate Gabor kernel connections.

Return type:

ConnectionResult