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:
Computes pairwise distances between pre- and post-synaptic neuron positions
Calculates connection probabilities using the provided distance profile
Stochastically generates connections based on these probabilities
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_postarray. When the profile has a hard cutoff (themax_distanceof the built-in profiles, or thethresholdof aStepProfilewithoutside_prob=0) and positions are given, only the pairs within the cutoff are found (KD-tree search) and drawn, which changes the edges a givenseedproduces in that case. Without a cutoff, the edges for a givenseedare 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 distanceExponentialProfile: Probability decays exponentially with distanceCustom profiles implementing the
DistanceProfileinterface
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))Noneto 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))Noneto create connections without explicit delays
allow_self_connections (
bool) – Whether to keep self-connections (autapses) whenpreandpostare the same population (the same position array object, or equal-size populations with identical positions).**kwargs – Additional keyword arguments passed to the parent
PointConnectivityclass, such asseedfor reproducible random number generation.
- Returns:
A connection result object containing:
pre_indices: Pre-synaptic neuron indicespost_indices: Post-synaptic neuron indicesweights: Connection weights (if weight initializer provided)delays: Connection delays (if delay initializer provided)metadata: Additional information about the connectivity pattern
- Return type:
Notes
Requires neuron positions to be provided via
pre_positionsandpost_positionsarguments when calling the connector, or a pre-computeddistancesarrayPosition arrays should have shape
(n_neurons, n_dimensions)with unitsDistances 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
preandpostare the same population, self-connections (autapses) are excluded by default; passallow_self_connections=Trueto keep themConnection probabilities are expected in
[0, 1]and are clipped to this rangeEdges are returned sorted by
(pre, post)Without a cutoff, distances and probabilities are evaluated in blocks of pre neurons holding at most
2**22pairs, so memory is bounded but the time isO(N_pre * N_post). With a cutoff, ascipy.spatial.cKDTreesearch 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
distancesmatrix is processed in the same row blocksThis is host-side NumPy/SciPy build-time code; it is not traceable by
jax.jit,jax.vmaporjax.grad
See also
GaussianSpecialized class for Gaussian distance-dependent connectivity
ExponentialSpecialized class for exponential distance-dependent connectivity
braintools.init.GaussianProfileGaussian distance profile
braintools.init.ExponentialProfileExponential 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 ... )