DenseLengthGraph

experimental.network_dynamics.graph.DenseLengthGraph(
    weights,
    lengths,
    speed,
    region_labels=None,
    symmetric=None,
    max_delay_bound=None,
)

Dense delay graph whose delays are derived from tract lengths and speed.

A brain-specific lowering onto the delay representation: it owns lengths (a matrix) and speed (a scalar) and computes delays = lengths / speed as a read-only property. The core (DelayedCoupling, the solver) still only ever sees delays; this type just produces them from the two quantities a structural connectome actually measures.

Because speed is a differentiable pytree leaf, it is directly sweepable and differentiable – the delay-domain twin of the coupling gain G: cfg.graph.speed = x sweeps it, and jax.grad reaches it through delays = lengths / speed by the chain rule, with no core code naming speed.

Args: weights: Weight matrix [n_nodes, n_nodes] lengths: Tract-length matrix [n_nodes, n_nodes], same sparsity pattern as weights; non-negative. speed: Conduction speed, a positive scalar. delays = lengths / speed. region_labels: Optional sequence of region labels. If None, defaults to [‘Region_0’, ‘Region_1’, …] symmetric: Whether to treat as symmetric (None = auto-detect) max_delay_bound: Static bound on the largest representable delay, used to size the history buffer. Required here: speed (or lengths) may be a JAX tracer, so delays is a tracer and the buffer length cannot be read off max(delays). Also gives headroom so speed can be lowered (raising delays) within a sweep or gradient step without re-prepare()-ing.

Attributes

Name	Description
delays	Delay matrix [n_nodes, n_nodes], computed as lengths / speed.
lengths	Tract-length matrix [n_nodes, n_nodes].
max_delay	Largest actual delay, max(lengths) / speed.
speed	Conduction speed (scalar). delays = lengths / speed.

Methods

Name	Description
tree_flatten	Flatten DenseLengthGraph for JAX PyTree.
tree_unflatten	Reconstruct DenseLengthGraph from PyTree data.
verify	Verify length-graph structure.

tree_flatten

experimental.network_dynamics.graph.DenseLengthGraph.tree_flatten()

Flatten DenseLengthGraph for JAX PyTree.

weights, lengths and speed are all children (differentiable leaves), so jax.grad reaches config.graph.speed. delays is not a leaf; it is recomputed from lengths/speed each forward pass.

tree_unflatten

experimental.network_dynamics.graph.DenseLengthGraph.tree_unflatten(
    aux_data,
    children,
)

Reconstruct DenseLengthGraph from PyTree data.

verify

experimental.network_dynamics.graph.DenseLengthGraph.verify(verbose=True)

Verify length-graph structure.

Checks weights (via DenseGraph.verify), non-negative finite lengths, and positive speed. Content checks are guarded behind concreteness so verify() stays trace-safe when speed/lengths is a tracer.