DistanceDependent

DistanceDependent#

class braintools.conn.DistanceDependent(distance_profile, weight=None, delay=None, allow_self_connections=False, **kwargs)#

Distance-dependent connectivity for spatially arranged point neurons.

This class creates synaptic connections between neurons based on their spatial distances, where the connection probability is determined by a distance-dependent profile. The connectivity pattern enables modeling of local and distance-modulated neural circuits commonly observed in biological neural networks.

The connection generation process:

  1. Computes pairwise distances between pre- and post-synaptic neuron positions

  2. Calculates connection probabilities using the provided distance profile

  3. Stochastically generates connections based on these probabilities

  4. Assigns weights and delays to established connections using initializers

Changed in version 0.4.0: Generation is chunked over pre neurons and never holds an N_pre x N_post array. When the profile has a hard cutoff (the max_distance of the built-in profiles, or the threshold of a StepProfile with outside_prob=0) and positions are given, only the pairs within the cutoff are found (KD-tree search) and drawn, which changes the edges a given seed produces in that case. Without a cutoff, the edges for a given seed are unchanged.

Parameters:
  • distance_profile (Array | ndarray | bool | number | bool | int | float | complex | Quantity | DistanceProfile) –

    A distance profile object that defines how connection probability varies with distance. Common profiles include:

    • GaussianProfile: Probability decreases as a Gaussian function of distance

    • ExponentialProfile: Probability decays exponentially with distance

    • Custom profiles implementing the DistanceProfile interface

    Alternatively, can be an array-like object specifying probabilities directly.

  • weight (Initialization | float | int | ndarray | Array | Quantity | None) –

    Initializer for synaptic weights. Can be:

    • A constant value (e.g., 1.0 * u.nS)

    • An initializer object (e.g., Normal(mean=1.0*u.nS, std=0.1*u.nS))

    • None to create unweighted connections

    Some initializers support distance-dependent weight generation.

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

    Initializer for synaptic delays. Can be:

    • A constant value (e.g., 1.0 * u.ms)

    • An initializer object (e.g., Uniform(0.5*u.ms, 2.0*u.ms))

    • None to create connections without explicit delays

  • allow_self_connections (bool) – Whether to keep self-connections (autapses) when pre and post are the same population (the same position array object, or equal-size populations with identical positions).

  • **kwargs – Additional keyword arguments passed to the parent PointConnectivity class, such as seed for reproducible random number generation.

Returns:

A connection result object containing:

  • pre_indices: Pre-synaptic neuron indices

  • post_indices: Post-synaptic neuron indices

  • weights: Connection weights (if weight initializer provided)

  • delays: Connection delays (if delay initializer provided)

  • metadata: Additional information about the connectivity pattern

Return type:

ConnectionResult

Notes

  • Requires neuron positions to be provided via pre_positions and post_positions arguments when calling the connector, or a pre-computed distances array

  • Position arrays should have shape (n_neurons, n_dimensions) with units

  • Distances are computed with the Euclidean metric over all position dimensions (e.g. a 3D position array uses x, y and z), not just the first two

  • The actual number of connections is stochastic and depends on the distance profile and random sampling

  • Empty connection results are returned if no connections are established

  • When pre and post are the same population, self-connections (autapses) are excluded by default; pass allow_self_connections=True to keep them

  • Connection probabilities are expected in [0, 1] and are clipped to this range

  • Edges are returned sorted by (pre, post)

  • Without a cutoff, distances and probabilities are evaluated in blocks of pre neurons holding at most 2**22 pairs, so memory is bounded but the time is O(N_pre * N_post). With a cutoff, a scipy.spatial.cKDTree search visits only the pairs within it, so time and memory scale with the number of candidate pairs (e.g. 1e5 neurons on a 2-D sheet with about 1e7 edges build in seconds)

  • A pre-computed distances matrix is processed in the same row blocks

  • This is host-side NumPy/SciPy build-time code; it is not traceable by jax.jit, jax.vmap or jax.grad

See also

Gaussian

Specialized class for Gaussian distance-dependent connectivity

Exponential

Specialized class for exponential distance-dependent connectivity

braintools.init.GaussianProfile

Gaussian distance profile

braintools.init.ExponentialProfile

Exponential distance profile

Examples

Basic usage with Gaussian distance profile:

>>> import brainunit as u
>>> import numpy as np
>>> from braintools.conn import DistanceDependent
>>> from braintools.init import GaussianProfile, Normal, Constant
>>>
>>> # Create neuron positions in 2D space
>>> positions = np.random.RandomState(0).uniform(0, 1000, (500, 2)) * u.um
>>>
>>> # Define Gaussian distance-dependent connectivity
>>> conn = DistanceDependent(
...     distance_profile=GaussianProfile(
...         sigma=100 * u.um,
...         max_distance=300 * u.um
...     ),
...     weight=Normal(mean=1.5*u.nS, std=0.3*u.nS),
...     delay=Constant(1.0 * u.ms),
...     seed=42
... )
>>>
>>> # Generate connections
>>> result = conn(
...     pre_size=500,
...     post_size=500,
...     pre_positions=positions,
...     post_positions=positions
... )
>>> print(f"Generated {len(result.pre_indices)} connections")
Generated 12864 connections

Using exponential distance profile:

>>> from braintools.init import ExponentialProfile
>>>
>>> conn = DistanceDependent(
...     distance_profile=ExponentialProfile(
...         decay_constant=150 * u.um,
...         max_distance=500 * u.um
...     ),
...     weight=Constant(2.0 * u.nS)
... )

Pre-computed distances:

>>> # Use pre-computed distance matrix instead of positions
>>> from scipy.spatial.distance import cdist
>>> distances = cdist(positions.mantissa, positions.mantissa) * u.um
>>> result = conn(
...     pre_size=500,
...     post_size=500,
...     distances=distances
... )
generate(pre_size, post_size, pre_positions=None, post_positions=None, **kwargs)[source]#

Generate distance-dependent connections.

Return type:

ConnectionResult