dgl.DGLGraph.edge_ids

DGLGraph.edge_ids(u, v, force_multi=None, return_uv=False, etype=None)

Return the edge ID(s) given the two endpoints of the edge(s).

Parameters

  • u (node IDs) –

    The source node IDs of the edges. The allowed formats are:

    • int: A single node.

    • Int Tensor: Each element is a node ID. The tensor must have the same device type and ID data type as the graph’s.

    • iterable[int]: Each element is a node ID.

  • v (node IDs) –

    The destination node IDs of the edges. The allowed formats are:

    • int: A single node.

    • Int Tensor: Each element is a node ID. The tensor must have the same device type and ID data type as the graph’s.

    • iterable[int]: Each element is a node ID.

  • force_multi (bool, optional) – DEPRECATED, use return_uv instead. Whether to allow the graph to be a multigraph, i.e. there can be multiple edges from one node to another.

  • return_uv (bool, optional) – Whether to return the source and destination node IDs along with the edges. If False (default), it assumes that the graph is a simple graph and there is only one edge from one node to another. If True, there can be multiple edges found from one node to another.

  • etype (str or (str, str, str), optional) –

    The type names of the edges. The allowed type name formats are:

    • (str, str, str) for source node type, edge type and destination node type.

    • or one str edge type name if the name can uniquely identify a triplet format in the graph.

    Can be omitted if the graph has only one type of edges.

Returns

  • If return_uv=False, it returns the edge IDs in a tensor, where the i-th element is the ID of the edge (u[i], v[i]).

  • If return_uv=True, it returns a tuple of three 1D tensors (eu, ev, e). e[i] is the ID of an edge from eu[i] to ev[i]. It returns all edges (including parallel edges) from eu[i] to ev[i] in this case.

Return type

Tensor, or (Tensor, Tensor, Tensor)

Notes

If the graph is a simple graph, return_uv=False, and there are no edges between some pairs of node(s), it will raise an error.

If the graph is a multigraph, return_uv=False, and there are multiple edges between some pairs of node(s), it returns an arbitrary one from them.

Examples

The following example uses PyTorch backend.

>>> import dgl
>>> import torch

Create a homogeneous graph.

>>> g = dgl.graph((torch.tensor([0, 0, 1, 1, 1]), torch.tensor([1, 0, 2, 3, 2])))

Query for the edges.

>>> g.edge_ids(0, 0)
1
>>> g.edge_ids(torch.tensor([1, 0]), torch.tensor([3, 1]))
tensor([3, 0])

Get all edges for pairs of nodes.

>>> g.edge_ids(torch.tensor([1, 0]), torch.tensor([3, 1]), return_uv=True)
(tensor([1, 0]), tensor([3, 1]), tensor([3, 0]))

If the graph has multiple edge types, one need to specify the edge type.

>>> g = dgl.heterograph({
...     ('user', 'follows', 'user'): (torch.tensor([0, 1]), torch.tensor([1, 2])),
...     ('user', 'follows', 'game'): (torch.tensor([0, 1, 2]), torch.tensor([1, 2, 3])),
...     ('user', 'plays', 'game'): (torch.tensor([1, 3]), torch.tensor([2, 3]))
... })
>>> g.edge_ids(torch.tensor([1]), torch.tensor([2]), etype='plays')
tensor([0])

Use a canonical edge type instead when there is ambiguity for an edge type.

>>> g.edge_ids(torch.tensor([0, 1]), torch.tensor([1, 2]),
...            etype=('user', 'follows', 'user'))
tensor([0, 1])
>>> g.edge_ids(torch.tensor([1, 2]), torch.tensor([2, 3]),
...            etype=('user', 'follows', 'game'))
tensor([1, 2])