HierarchicalRandom

class braintools.conn.HierarchicalRandom(n_levels, feedforward_prob=0.3, feedback_prob=0.1, recurrent_prob=0.2, skip_prob=0.0, level_ratios=None, weight=None, delay=None, **kwargs)

Hierarchical network with multiple levels and asymmetric feedforward/feedback connections.

This class creates a hierarchical network structure organized into distinct levels (layers), where connections flow primarily in a feedforward direction from lower to higher levels, with optional feedback connections. Within each level, recurrent connections can be specified. This architecture mirrors the hierarchical organization observed in cortical processing streams and deep neural networks.

Hierarchical organization is fundamental to brain architecture, enabling progressive processing of information from sensory inputs through increasingly abstract representations. Each level performs specialized computations while maintaining bidirectional communication with adjacent levels for top-down modulation and bottom-up information flow.

Parameters:

• n_levels (int) – Number of hierarchical levels in the network. Must be at least 2. Levels are numbered from 0 (lowest/input) to n_levels-1 (highest/output).

• feedforward_prob (float) – Connection probability from level i to level i+1 (feedforward connections). These connections propagate information up the hierarchy. Valid range is [0, 1].

• feedback_prob (float) – Connection probability from level i+1 to level i (feedback connections). These connections enable top-down modulation. Valid range is [0, 1]. Typically lower than feedforward_prob to reflect the asymmetry in cortical connectivity.

• recurrent_prob (float) – Connection probability within each level (recurrent/lateral connections). Valid range is [0, 1]. These connections enable local processing and competition within each level.

• skip_prob (float) – Connection probability for skip connections that bypass adjacent levels (e.g., from level i to level i+2). Valid range is [0, 1]. Skip connections can enable faster information flow and gradient propagation.

• level_ratios (Sequence[int | float] | None) –

  Ratios or sizes for the first n_levels-1 levels. Length must be n_levels-1. Each element can be:

  • int: Fixed size for that level

  • float: Proportion of total size (e.g., 0.3 means 30% of total)

  The last level gets the remaining neurons. If None, levels are evenly divided.

• weight (Initialization | float | int | ndarray | Array | Quantity | None) – Weight initialization for all connections. 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. 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 levels in sequential order

• Self-connections are automatically excluded

• Feedforward connections: level i → level i+1

• Feedback connections: level i+1 → level i

• Skip connections: level i → level i+k where k > 1

• The same weight and delay initialization is used for all connection types

• Expected connectivity follows a hierarchical pattern with stronger feedforward flow

References

[1]

Felleman, D. J., & Van Essen, D. C. (1991). Distributed hierarchical processing in the primate cerebral cortex. Cerebral Cortex, 1(1), 1-47.

[2]

Bastos, A. M., et al. (2012). Canonical microcircuits for predictive coding. Neuron, 76(4), 695-711.

[3]

Markov, N. T., et al. (2013). Cortical high-density counterstream architectures. Science, 342(6158), 1238406.

Examples

Create a 3-level hierarchical network:

>>> import brainunit as u
>>> from braintools.conn import HierarchicalRandom
>>> hier = HierarchicalRandom(
...     n_levels=3,
...     feedforward_prob=0.3,
...     feedback_prob=0.1,
...     recurrent_prob=0.2,
...     weight=1.0 * u.nS
... )
>>> result = hier(pre_size=900, post_size=900)

Create a deep hierarchy with skip connections:

>>> hier = HierarchicalRandom(
...     n_levels=5,
...     feedforward_prob=0.4,
...     feedback_prob=0.15,
...     recurrent_prob=0.25,
...     skip_prob=0.05,
...     weight=0.8 * u.nS,
...     delay=2.0 * u.ms
... )
>>> result = hier(pre_size=1000, post_size=1000)

Create a hierarchy with custom level sizes:

>>> # Bottom-heavy hierarchy (sensory-like)
>>> hier = HierarchicalRandom(
...     n_levels=4,
...     feedforward_prob=0.3,
...     feedback_prob=0.1,
...     level_ratios=[0.4, 0.3, 0.2]  # 40%, 30%, 20%, 10%
... )
>>> result = hier(pre_size=1000, post_size=1000)

Use with custom initializers:

>>> from braintools.init import Normal
>>> hier = HierarchicalRandom(
...     n_levels=3,
...     feedforward_prob=0.35,
...     feedback_prob=0.12,
...     weight=Normal(mean=1.0, std=0.2)
... )
>>> result = hier(pre_size=900, post_size=900)

generate(**kwargs)

Generate hierarchical network.

Return type:

ConnectionResult