openpnm.topotools.find_neighbor_bonds(sites, im=None, am=None, flatten=True, logic='or')[source]

Given an incidence matrix, finds all sites that are connected to the input sites.

This function accepts either an incidence or adjacency matrix.

  • im (scipy.sparse matrix) – The incidence matrix of the network. Must be shaped as (N-sites, N-bonds), with non-zeros indicating which sites are connected. Either am or im must be given. Passing in im is slower, but more powerful as it allows for an unflattened list of neighbors.

  • am (scipy.sparse matrix (optional)) – The adjacency matrix of the network. Either am or im must be given. Passing in am is faster, but does not allow for an unflattened list.

  • flatten (bool (default is True)) – Indicates whether the returned result is a compressed array of all neighbors, or a list of lists with each sub-list containing the neighbors for each input site. Note that an unflattened list might be slow to generate since it is a Python list rather than a Numpy array.

  • logic (str) –

    Specifies logic to filter the resulting list. Options are:

    ’or’ : (default) All neighbors of the input sites. This is also known as the ‘union’ in set theory or ‘any’ in boolean logic. Both keywords are accepted and treated as ‘or’.

    ’xor’ : Only neighbors of one and only one input site. This is useful for finding the sites that are not shared by any of the input sites. ‘exclusive_or’ is also accepted’.

    ’xnor’ : Neighbors that are shared by two or more input sites. This is equivalent to finding all neighbors with ‘or’, minus those found with ‘xor’, and is useful for finding neighbors that the inputs have in common. ‘nxor’ is also accepted.

    ’and’ : Only neighbors shared by all input sites. This is also known as ‘intersection’ in set theory and (somtimes) as ‘all’ in boolean logic. Both keywords are accepted and treated as ‘and’.


  • An array containing the neighboring bonds filtered by the given logic. If

  • flatten is False then the result is a list of lists containing the

  • neighbors of each given input site.

See also



The logic options are applied to neighboring bonds only, thus it is not possible to obtain bonds that are part of the global set but not neighbors. This is because (a) the list of global bonds might be very large, and (b) it is not possible to return a list of neighbors for each input site if global sites are considered.