ModularRandom

ModularRandom#

class braintools.conn.ModularRandom(n_modules, intra_prob=0.3, inter_prob=0.01, weight=None, delay=None, **kwargs)#

Modular network with intra-module and inter-module random connectivity.

This class creates a modular network structure where neurons are divided into distinct modules (communities) with different connection probabilities within and between modules. Intra-module connections (within the same module) typically have higher probability than inter-module connections (between different modules), creating a community structure [1].

Modular organization is a fundamental feature of brain networks [2], observed across multiple scales from cortical columns to large-scale brain areas. This topology enables specialized local processing within modules while maintaining global integration through sparse inter-module connections. It balances functional segregation with integration, supporting both specialized and distributed information processing.

Parameters:
  • n_modules (int) – Number of modules (communities) to divide the network into. Must not exceed the network size. Neurons are distributed approximately evenly across modules (the first remainder modules each receive one extra neuron).

  • intra_prob (float) – Connection probability for neuron pairs within the same module. Valid range is [0, 1]. Higher values create denser intra-module connectivity and stronger community structure.

  • inter_prob (float) – Connection probability for neuron pairs in different modules. Valid range is [0, 1]. Typically much smaller than intra_prob to create distinct modules. The ratio intra_prob/inter_prob determines the strength of modularity.

  • weight (Initialization | float | int | ndarray | Array | Quantity | None) – Weight initialization for all connections (both intra and inter-module). Can be a scalar value, array, or an Initializer instance for more complex initialization patterns. If None, no weights are generated.

  • delay (Initialization | float | int | ndarray | Array | Quantity | None) – Delay initialization for all connections (both intra and inter-module). Can be a scalar value, array, or an Initializer instance for more complex initialization patterns. If None, no delays are generated.

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

Notes

  • This connectivity pattern requires pre_size == post_size (recurrent connectivity)

  • Neurons are assigned to modules in sequential order using a balanced split (every module gets at least one neuron; n_modules must not exceed the network size)

  • Self-connections are automatically excluded

  • The same weight and delay initialization is used for all connections

  • For module-specific connectivity patterns, use ModularGeneral instead

  • Expected number of connections: n² * ((intra_prob + (n_modules-1)*inter_prob) / n_modules)

  • Modularity strength can be quantified by the Q-statistic (Newman, 2006)

  • See [1] and [2] for modular structure in networks and brains.

  • Generation runs on the host with NumPy and cannot be traced by jax.jit, jax.vmap or jax.grad.

Changed in version 0.4.0: Each block of neuron pairs is sampled by drawing a binomial edge count and then that many distinct pairs, without a dense pre_size x post_size matrix, so time and memory grow with the number of edges. The edge set for a given seed differs from 0.3 (same distribution); edges are sorted by pre, then post index. Probabilities outside [0, 1] now raise ValueError (0.3 treated them as 0 or 1).

References

See also

ModularGeneral

Modular network with custom connectivity patterns per module

Examples

Create a modular network with 5 modules:

>>> import brainunit as u
>>> from braintools.conn import ModularRandom
>>> mod = ModularRandom(n_modules=5, intra_prob=0.3, inter_prob=0.01, seed=0)
>>> result = mod(pre_size=1000, post_size=1000)
>>> result.n_connections
67881

Create a strongly modular network with sparse inter-module connections:

>>> mod = ModularRandom(
...     n_modules=10,
...     intra_prob=0.4,
...     inter_prob=0.005,
...     weight=1.0 * u.nS,
...     delay=2.0 * u.ms
... )
>>> result = mod(pre_size=500, post_size=500)

Create a weakly modular network:

>>> mod = ModularRandom(n_modules=3, intra_prob=0.2, inter_prob=0.1)
>>> result = mod(pre_size=1000, post_size=1000)

Use with custom initializers:

>>> from braintools.init import Normal
>>> mod = ModularRandom(
...     n_modules=8,
...     intra_prob=0.25,
...     inter_prob=0.02,
...     weight=Normal(mean=1.0, std=0.1)
... )
>>> result = mod(pre_size=800, post_size=800)
generate(pre_size, post_size, pre_positions=None, post_positions=None, **kwargs)[source]#

Generate modular network.

Return type:

ConnectionResult