MorphologyDistance#

class braintools.conn.MorphologyDistance(sigma=None, decay_function=None, compartment_mapping=None, weight=None, delay=None, allow_self_connections=False, **kwargs)#

Distance-dependent connectivity based on neuron positions.

Connection probabilities decay with the Euclidean distance between presynaptic and postsynaptic neuron positions (the soma positions passed as pre_positions/post_positions); the chosen target compartments come from compartment_mapping. Positions are required.

For every (source, target) compartment pair, each neuron pair connects with the probability given by the distance profile at their distance.

Parameters:
  • sigma (float | Quantity | None) – Characteristic distance scale of the built-in Gaussian profile (and of the deprecated string decay functions). A plain number is interpreted in the unit of pre_positions. Required unless decay_function is a braintools.init.DistanceProfile, in which case it must be omitted because the profile carries its own length scale.

  • decay_function (DistanceProfile | str | None) –

    Distance-to-probability profile. None (default) is a Gaussian exp(-d**2 / (2 * sigma**2)). A braintools.init.DistanceProfile instance (for example braintools.init.ExponentialProfile(50 * u.um)) is evaluated on the distances expressed in the unit of pre_positions.

    Deprecated since version 0.4.0: The strings 'gaussian', 'exponential' and 'linear' are deprecated and will be removed in 1.0.0. They map to GaussianProfile(sigma), ExponentialProfile(sigma) and LinearProfile(sigma).

  • compartment_mapping (Dict | None) – Mapping of which compartments can connect to which.

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

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

  • allow_self_connections (bool) – Whether a neuron may connect to itself. Default False.

Raises:

ValueError – If sigma is missing while decay_function is not a DistanceProfile, or given while it is. At generation time, if decay_function is not recognised or sigma is not positive.

Warns:

BraintoolsDeprecationWarning – If decay_function is one of the legacy strings.

Notes

Pair probabilities are evaluated in chunks of presynaptic rows of bounded size, so peak memory does not grow with pre_size * post_size. The random draws are the same as in version 0.3, so a given seed gives the same edges. 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 MorphologyDistance, AXON, BASAL_DENDRITE
>>> from braintools.init import ExponentialProfile
>>> gaussian = MorphologyDistance(sigma=50 * u.um)
>>> exponential = MorphologyDistance(
...     decay_function=ExponentialProfile(80 * u.um),
...     compartment_mapping={AXON: [BASAL_DENDRITE]},
...     seed=0,
... )
>>> positions = np.random.RandomState(0).uniform(0, 200, (20, 2)) * u.um
>>> result = exponential(
...     pre_size=20, post_size=20,
...     pre_positions=positions, post_positions=positions,
... )
>>> bool(np.all(result.post_compartments == BASAL_DENDRITE))
True
generate(pre_size, post_size, pre_positions=None, post_positions=None, **kwargs)[source]#

Generate morphology-based distance-dependent connections.

Return type:

ConnectionResult