rename to find_first_connected and update docstring

Signed-off-by: Thijs Baaijen <[email protected]>

Author: Thijss

src/power_grid_model_ds/_core/model/graphs/models/base.py

@@ -238,8 +238,8 @@ def get_connected(
 
         return self._internals_to_externals(nodes)
 
-    def find_connected(self, node_id: int, candidate_node_ids: list[int]) -> int:
-        """Find a connection between a node and a list of candidate nodes.
+    def find_first_connected(self, node_id: int, candidate_node_ids: list[int]) -> int:
+        """Find the first connected node to the node_id from the candidate_node_ids
 
         Note:
             If multiple candidate nodes are connected to the node, the first one found is returned.
@@ -253,20 +253,26 @@ def find_connected(self, node_id: int, candidate_node_ids: list[int]) -> int:
         internal_candidates = self._externals_to_internals(candidate_node_ids)
         if internal_node_id in internal_candidates:
             raise ValueError("node_id cannot be in candidate_node_ids")
-        return self.internal_to_external(self._find_connected(internal_node_id, internal_candidates))
+        return self.internal_to_external(self._find_first_connected(internal_node_id, internal_candidates))
+
+    def get_downstream_nodes(self, node_id: int, start_node_ids: list[int], inclusive: bool = False) -> list[int]:
+        """Find all nodes downstream of the node_id with respect to the start_node_ids
+
+        Example:
+            given this graph: [1] - [2] - [3] - [4]
+            >>> graph.get_downstream_nodes(2, [1]) == [3, 4]
+            >>> graph.get_downstream_nodes(2, [1], inclusive=True) == [2, 3, 4]
 
-    def get_downstream_nodes(self, node_id: int, stop_node_ids: list[int], inclusive: bool = False) -> list[int]:
-        """Find all nodes connected to the node_id
         args:
             node_id: node id to start the search from
-            stop_node_ids: list of node ids to stop the search at
+            start_node_ids: list of node ids considered 'above' the node_id
             inclusive: whether to include the given node id in the result
         returns:
             list of node ids sorted by distance, downstream of to the node id
         """
-        connected_node = self.find_connected(node_id, stop_node_ids)
+        connected_node = self.find_first_connected(node_id, start_node_ids)
         path, _ = self.get_shortest_path(node_id, connected_node)
-        _, upstream_node, *_ = path  # path is at least 2 elements long or find_connected would have raised an error
+        _, upstream_node, *_ = path  # path is at least 2 elements long or find_first_connected would have raised an error
 
         return self.get_connected(node_id, [upstream_node], inclusive)
 
@@ -307,7 +313,7 @@ def _branch_is_relevant(self, branch: BranchArray) -> bool:
     def _get_connected(self, node_id: int, nodes_to_ignore: list[int], inclusive: bool = False) -> list[int]: ...
 
     @abstractmethod
-    def _find_connected(self, node_id: int, candidate_node_ids: list[int]) -> int: ...
+    def _find_first_connected(self, node_id: int, candidate_node_ids: list[int]) -> int: ...
 
     @abstractmethod
     def _has_branch(self, from_node_id, to_node_id) -> bool: ...

src/power_grid_model_ds/_core/model/graphs/models/rustworkx.py

@@ -99,7 +99,7 @@ def _get_connected(self, node_id: int, nodes_to_ignore: list[int], inclusive: bo
 
         return connected_nodes
 
-    def _find_connected(self, node_id: int, candidate_node_ids: list[int]) -> int:
+    def _find_first_connected(self, node_id: int, candidate_node_ids: list[int]) -> int:
         visitor = _NodeFinder(candidate_nodes=candidate_node_ids)
         rx.bfs_search(self._graph, [node_id], visitor)
         if visitor.found_node is None:

src/power_grid_model_ds/_core/model/grids/base.py

@@ -356,7 +356,7 @@ def get_downstream_nodes(self, node_id: int, inclusive: bool = False):
             raise NotImplementedError("get_downstream_nodes is not implemented for substation nodes!")
 
         return self.graphs.active_graph.get_downstream_nodes(
-            node_id=node_id, stop_node_ids=list(substation_nodes.id), inclusive=inclusive
+            node_id=node_id, start_node_ids=list(substation_nodes.id), inclusive=inclusive
         )
 
     def cache(self, cache_dir: Path, cache_name: str, compress: bool = True):