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