ConnectionResult#

class braintools.conn.ConnectionResult(pre_indices, post_indices, pre_size, post_size, pre_positions=None, post_positions=None, pre_compartments=None, post_compartments=None, weights=None, delays=None, model_type='point', metadata=None)#

Universal container for connectivity results across all neuron model types.

This class provides a unified interface for representing connections while maintaining type-specific information and capabilities.

Parameters:
  • pre_indices (ndarray) – Presynaptic element indices (neurons, populations, or compartments).

  • post_indices (ndarray) – Postsynaptic element indices (neurons, populations, or compartments).

  • pre_size (int | Sequence[int] | None) – Size of the presynaptic population (number of elements or shape).

  • post_size (int | Sequence[int] | None) – Size of the postsynaptic population (number of elements or shape).

  • weights (ndarray | Quantity | None) – Connection weights with appropriate units for the model type.

  • delays (ndarray | Quantity | None) – Connection delays with time units (e.g., ms).

  • model_type (str) – Type of neuron model (‘point’, ‘population_rate’, ‘multi_compartment’).

  • pre_positions (ndarray | None) – Positions of presynaptic elements (for distance calculations).

  • post_positions (ndarray | None) – Positions of postsynaptic elements (for distance calculations).

  • pre_compartments (ndarray | None) – Presynaptic compartment indices (for multi-compartment models).

  • post_compartments (ndarray | None) – Postsynaptic compartment indices (for multi-compartment models).

  • metadata (Dict[str, Any] | None) – Model-specific metadata and parameters.

delay2csr()[source]#

Convert delays to sparse connectivity matrix in CSR format.

delay2matrix()[source]#

Convert delays to dense connectivity matrix.

get_distances()[source]#

Calculate distances between connected elements.

Return type:

Quantity | None

property n_connections: int#

Number of connections.

property positions: Tuple[ndarray, ndarray] | None#

Backward compatibility property for positions.

property shape: Tuple[int, int]#

Shape of the connectivity (pre_size, post_size).

to_csc(data='weight')[source]#

Export to a brainevent.CSC (compressed sparse column) matrix.

Parameters:

data (str) – Which edge values to store. Missing weights become 1.0 and missing delays 0.0.

Returns:

Matrix of shape (n_pre, n_post); homogeneous values (size 1) stay a scalar and units are kept.

Return type:

CSC

Raises:

ValueError – If data is not 'weight' or 'delay'.

Notes

Host-side export. Works for any connectivity (degrees need not be equal).

Examples

>>> import numpy as np
>>> from braintools.conn import ConnectionResult
>>> result = ConnectionResult(np.array([0, 1, 1]), np.array([2, 0, 2]), pre_size=2,
...                           post_size=3, weights=np.array([1., 2., 3.]))
>>> csc = result.to_csc()
>>> np.asarray(csc.indptr)
array([0, 1, 1, 3], dtype=int32)
>>> np.asarray(csc.todense())
array([[0., 0., 1.],
       [2., 0., 3.]], dtype=float32)
to_fixed_num_per_post(data='weight')[source]#

Export to a brainevent.FixedNumPerPost matrix.

Every postsynaptic neuron must have the same number k of incoming connections (as produced by FixedInDegree).

Parameters:

data (str) – Which edge values to store. Missing weights become 1.0 and missing delays 0.0.

Returns:

Matrix of shape (n_pre, n_post) with indices of shape (n_post, k) and W[indices[j, i], j] = data[j, i]. Homogeneous values (size 1) stay a scalar; units are kept.

Return type:

FixedNumPerPost

Raises:

ValueError – If the in-degrees are not all equal (the message reports the observed range), or data is not 'weight'/'delay'.

Notes

Host-side export; see to_fixed_num_per_pre() for duplicate edges and delays.

Examples

>>> import numpy as np
>>> import jax.numpy as jnp
>>> from braintools.conn import FixedInDegree
>>> result = FixedInDegree(2, seed=0)(pre_size=5, post_size=3)
>>> w = result.to_fixed_num_per_post()
>>> w.shape, w.indices.shape
((5, 3), (3, 2))
>>> spikes = jnp.ones(5)
>>> np.asarray(spikes @ w)  # every post neuron receives 2 inputs
array([2., 2., 2.], dtype=float32)
to_fixed_num_per_pre(data='weight')[source]#

Export to a brainevent.FixedNumPerPre matrix.

Every presynaptic neuron must have the same number k of outgoing connections (as produced by FixedOutDegree).

Parameters:

data (str) – Which edge values to store. Missing weights become 1.0 and missing delays 0.0.

Returns:

Matrix of shape (n_pre, n_post) with indices of shape (n_pre, k) and W[i, indices[i, j]] = data[i, j]. Homogeneous values (size 1) stay a scalar; units are kept.

Return type:

FixedNumPerPre

Raises:

ValueError – If the out-degrees are not all equal (the message reports the observed range), or data is not 'weight'/'delay'.

Notes

Host-side export (indices must be built outside jax.jit); the resulting brainevent object supports jit/vmap/grad in its products. Duplicate edges (from with_replacement=True) are kept as separate slots and are summed by brainevent, whereas weight2dense() keeps only one of them. Delays have no brainevent operator semantics; data='delay' only packs them in the same layout.

Examples

>>> import numpy as np
>>> import brainunit as u
>>> from braintools.conn import FixedOutDegree
>>> result = FixedOutDegree(3, weight=0.5 * u.nS, seed=0)(pre_size=4, post_size=6)
>>> w = result.to_fixed_num_per_pre()
>>> w.shape, w.indices.shape
((4, 6), (4, 3))
>>> w.data
Quantity(0.5, "nS")
>>> bool(u.math.allclose(w.todense(), result.weight2dense()))
True
to_scipy_csr(data='weight', unit=None)[source]#

Export to a host scipy.sparse.csr_matrix.

Parameters:
  • data (str) – Which edge values to store. Missing weights become 1.0 and missing delays 0.0.

  • unit (Unit | None) – Unit in which to express the values. SciPy matrices cannot carry units, so the stored numbers are the mantissa in unit; when omitted they are the mantissa in the values’ own unit (u.get_unit(result.weights)).

Returns:

Matrix of shape (n_pre, n_post) in canonical form (sorted indices, duplicate edges summed).

Return type:

scipy.sparse.csr_matrix

Raises:
  • ValueError – If data is not 'weight' or 'delay'.

  • brainunit.UnitMismatchError – If unit has a different dimension than the values.

Notes

Host-only (NumPy/SciPy); used by braintools.analysis.graph.

Examples

>>> import numpy as np
>>> import brainunit as u
>>> from braintools.conn import ConnectionResult
>>> result = ConnectionResult(np.array([0, 1]), np.array([1, 0]), pre_size=2,
...                           post_size=2, weights=np.array([1., 2.]) * u.nS)
>>> result.to_scipy_csr().toarray()
array([[0., 1.],
       [2., 0.]])
>>> result.to_scipy_csr(unit=u.uS).toarray()
array([[0.   , 0.001],
       [0.002, 0.   ]])
weight2csr()[source]#

Convert to sparse connectivity matrix in CSR format.

weight2dense()[source]#

Convert to dense connectivity matrix.