[FEATURE] Provide more basic graph tools

[mgovers]

Describe the feature request

Currently, the graph representation only contains some more global tools (e.g.: get all cycles). However, it would be nice if there would be some tool to step locally through a graph (e.g.: get adjacent nodes/edges). The functionality already exists in the graph implementation, but is not yet exposed over the API and requires one to rebuild the graph from scratch.

[vincentkoppen]

If you have a specific request as an addition to the API then we are definitely open to discuss (and afterwards review) these. The examples you provided sound like useful additions indeed.

The reason we do not (currently) expose the rustworkx graph object itself, is that with the current API based implementation we allow ourself as maintainers to change the underlying dependency (e.g change from rustworkx to igraph) without any breaking change for the user.
We implemented this, since we initially used a different library that became unmaintained, which forced us to a different graph library.

If you see a way for us to expose the graph object, while keeping this flexibility I'm definitely open we are definitely open to that.

[mgovers]

I think these tools should be exposed via the BaseGraphModel interface. In particular, the following operations are supported by (almost) every graph library:

• adjacent(node: int) -> list[int]
  • Get the list of all nodes
• adjacent_edges(node: int) -> list[int]
  • Get the list of all edges connected to the node
• other_node(node: int, edge: int) -> int
  • Step through an edge. This can already be done by accessing the edge in the PGM grid but not via the Graph interface.
• bfs / breath_first_search; I do know you already have get_downstream_nodes so this can probably just be an alias, or vice versa
• dfs / depth_first_search; The current interface does not seem to support this yet

Optionally, we can also expose other useful functionalities like

• adjacent(node: Int, excluding: list[int] = []) -> list[int]
  • Same as adjacent(node: int) -> list[int] but do not return any nodes in the excluded list
  • This is particularly useful when you do a local search but don't want to visit any nodes twice

[vincentkoppen]

Thanks for the examples:

• adjacent(node:int) -> list[int] and adjacent_edges definitely agree and open to PR's or might implement this myself when I have time
  • On: adjacent_edges will return a list[tuple[int,int]] since we don't have branch id's on the graph
  • On: adjacent(node: int, excluding: list[int]) -> list[int]: seems like a nice optional argument indeed. Nit: would change the excluding to either be set[int] (for performance) or Container[int] to support any structure that support the x in excluded_list check.
• Since we don't have branch ids on the graph, currently other_node doesn't seem useful. Since a branch is just a tuple of the two nodes.

The above also shows that we might want to think about supported edge_id (from our branches/three winding transformers) on our graphs.

For bfs / dfs I agree that these are useful, will try to find some time in the upcoming weeks to see if I can get a grasp of what a good interface could look like.