openpnm.topotools.find_neighbor_sites(sites, am, flatten=True, include_input=False, logic='or')[source]

Given a symmetric adjacency matrix, finds all sites that are connected to the input sites.

  • am (scipy.sparse matrix) – The adjacency matrix of the network. Must be symmetrical such that if sites i and j are connected, the matrix contains non-zero values at locations (i, j) and (j, i).

  • flatten (bool) – If True (default) 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.

  • include_input (bool) – If False (default) the input sites will be removed from the result.

  • 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 sites filtered by the given logic. If

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

  • neighbors of each input site.

See also



The logic options are applied to neighboring sites only, thus it is not possible to obtain sites that are part of the global set but not neighbors. This is because (a) the list global sites 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.