Distance dependent structural plasticity

[FinnBurkhardt]

Description

This pull request introduces new functionality to handle distance-dependent connection probabilities in the SPManager class. The following methods have been added or modified:

New Features

• gather_global_positions_and_ids()
  Collects and verifies global neuron positions and IDs.
  Ensures that neurons are spatially distributed, raising an error if positions are undefined while distance dependency is enabled.

• gaussian_kernel()
  Computes a probability based on the Gaussian distance kernel between two neuron positions.

• build_probability_list()
  Constructs a probability list for all neuron pairs based on their spatial positions.
  Supports caching for efficient repeated lookups.

• get_neuron_pair_index()
  Maps two neuron IDs to a unique index for accessing pair-specific probabilities in the probability_list.

• global_shuffle_spatial()
  Implements distance-dependent shuffling for pairing neurons based on spatial proximity and probability.

• roulette_wheel_selection()
  Performs a weighted random selection of post-synaptic neurons based on precomputed probabilities.

Modified Methods

• enable_structural_plasticity()
  Integrates calls to gather_global_positions_and_ids() and build_problist() when distance dependency is enabled.

---

Distance-Dependent Features

• Enable Distance Dependency
  Distance dependency can be enabled by setting structural_plasticity_gaussian_kernel_sigma to a positive value. This parameter controls the width of the Gaussian kernel used for connection probabilities. Higher values result in reduced sensitivity to distance, making distant neurons more likely to connect.

• Caching Connection Probabilities
  If structural_plasticity_cache_probabilities is set to true, connection probabilities will be precomputed and cached. This can improve performance, particularly in long-running simulations.

---

Testing

The following tests have been added to validate the new functionality:

C++ Tests:

• test_gaussian_kernel
  Tests Gaussian kernel computations for various distances and sigma values.

• test_get_neuron_pair_index
  Confirms correct mapping of neuron pairs to unique indices.

• test_global_shuffle_spatial
  Validates spatially aware shuffling logic.
  Ensures connections favor spatial proximity and prevent self-connections.

Python Tests:

• test_distance_dependent_without_positions()
  Ensures an error is raised when distance dependency is enabled, but positions are not provided.

• test_gaussian_kernel()
  Tests probability computation using Gaussian distance dependency.

• test_probability_list_building()
  Verifies the correct initialization and population of the probability list.

• test_roulette_wheel_selection()
  Confirms that weighted random selection behaves as expected.

• test_structural_plasticity_with_positions()
  Ensures structural plasticity works correctly when neuron positions are defined.

• test_synapse_creation_distance_dependent()
  Validates distance-dependent synapse formation using position data.

---

Related Issue:

Incorporate Distance-Dependent Connection Probability in Structural Plasticity Module #3209

[alpinangu]

Looks good. We might reduce some overhead by passing a pointer to the relevant element in the global_position vector along with its dimension directly to the gaussianKernel function instead of creating and passing subvectors on each iteration, but for a small number of neurons it would not be noticeable

[jhnnsnk]

Thank you very much for this PR! At a first glance, I have the following comments:

• I suggest to improve the interface a bit: Can nest.EnableStructuralPlasticity() get arguments instead of having nest.structural_plasticity_gaussian_kernel_sigma and nest.structural_plasticity_cache_probabilities separately?
• Using structural_plasticity_gaussian_kernel_sigma = -1 as default is misleading. How about an argument such as use_Gaussian_kernel=true instead and then allowing only values for sigma that actually make sense (and allowing to set this value only if the Gaussian kernel is enabled)?
• How does the performance compare if you connect and simulate without the Gaussian kernel? And with and without cached probabilities?
• Could you please document what caching probabilities actually does?
• I suggest to move the pytests for the spatial version into a separate file in test_sp.
• The test test_distance_dependent_without_positions appears twice.
• How are autapses and multapses handled during the creation and later during the simulation?
• Can masks be supported (as a maximum distance)?

[FinnBurkhardt]

@alpinangu ,@jhnnsnk Thank you so much for your feedback! I'm working on the suggested changes and the performance comparisons.

[terhorstd]

@FinnBurkhardt could you have a quick look at the CI messages, probably it's only merge master…

[FinnBurkhardt]

I’ve removed the caching for now.
It needs more work and benchmarking, so I think it should go in a separate PR.
I’ll provide a performance comparison with and without the Gaussian kernel shortly.