edsger 0.1.2__cp312-cp312-win32.whl → 0.1.4__cp312-cp312-win32.whl

edsger/_version.py

@@ -1 +1 @@
-__version__ = "0.1.2"
+__version__ = "0.1.4"

edsger/dijkstra.pyx

@@ -9,12 +9,24 @@ cpdef functions:
 - compute_sssp_w_path
     Compute single-source shortest path (from one vertex to all vertices).
     Compute predecessors.
+- compute_sssp_early_termination
+    Compute single-source shortest path with early termination when target nodes
+    are reached. Does not return predecessors.
+- compute_sssp_w_path_early_termination
+    Compute single-source shortest path with early termination when target nodes
+    are reached. Compute predecessors.
 - compute_stsp
     Compute single-target shortest path (from all vertices to one vertex). Does
     not return successors.
 - compute_stsp_w_path
     Compute single-target shortest path (from all vertices to one vertex).
     Compute successors.
+- compute_stsp_early_termination
+    Compute single-target shortest path with early termination when target nodes
+    are reached. Does not return successors.
+- compute_stsp_w_path_early_termination
+    Compute single-target shortest path with early termination when target nodes
+    are reached. Compute successors.
 """
 
 cimport numpy as cnp
@@ -23,7 +35,7 @@ from edsger.commons cimport (
     DTYPE_INF, UNLABELED, SCANNED, DTYPE_t, ElementState)
 cimport edsger.pq_4ary_dec_0b as pq  # priority queue
 
-# Memory prefetching support (x86/x64 only)
+# memory prefetching support (x86/x64 only)
 cdef extern from "prefetch_compat.h":
     void prefetch_hint(char*, int) nogil
     int PREFETCH_T0
@@ -89,14 +101,14 @@ cpdef cnp.ndarray compute_sssp(
 
                 head_vert_idx = <size_t>csr_indices[idx]
 
-                # Prefetch next iteration data to improve cache performance
+                # prefetch next iteration data to improve cache performance
                 if idx + 1 < <size_t>csr_indptr[tail_vert_idx + 1]:
                     prefetch_hint(<char*>&csr_indices[idx + 1], PREFETCH_T0)
                     prefetch_hint(<char*>&csr_data[idx + 1], PREFETCH_T0)
 
                 vert_state = pqueue.Elements[head_vert_idx].state
                 if vert_state != SCANNED:
-                    # Prefetch priority queue element data for the vertex
+                    # prefetch priority queue element data for the vertex
                     prefetch_hint(<char*>&pqueue.Elements[head_vert_idx], PREFETCH_T0)
 
                     head_vert_val = tail_vert_val + csr_data[idx]
@@ -114,6 +126,109 @@ cpdef cnp.ndarray compute_sssp(
     return path_lengths
 
 
+cpdef cnp.ndarray compute_sssp_early_termination(
+        cnp.uint32_t[::1] csr_indptr,
+        cnp.uint32_t[::1] csr_indices,
+        DTYPE_t[::1] csr_data,
+        cnp.uint32_t[::1] termination_nodes,
+        int source_vert_idx,
+        int vertex_count,
+        int heap_length):
+    """
+    Compute single-source shortest path with early termination when target
+    nodes are reached.
+    Parameters
+    ----------
+    csr_indices : cnp.uint32_t[::1]
+        indices in the CSR format
+    csr_indptr : cnp.uint32_t[::1]
+        pointers in the CSR format
+    csr_data DTYPE_t[::1]
+        data (edge weights) in the CSR format
+    termination_nodes : cnp.uint32_t[::1]
+        target node indices for early termination
+    source_vert_idx : int
+        source vertex index
+    vertex_count : int
+        vertex count
+    heap_length : int
+        heap length
+
+    Returns
+    -------
+    path_lengths : cnp.ndarray
+        shortest path length for each termination node
+    """
+
+    cdef:
+        size_t tail_vert_idx, head_vert_idx, idx, i
+        DTYPE_t tail_vert_val, head_vert_val
+        pq.PriorityQueue pqueue
+        ElementState vert_state
+        size_t source = <size_t>source_vert_idx
+        size_t target_count = termination_nodes.shape[0]
+        size_t visited_targets = 0
+        size_t iteration_count = 0
+        size_t check_frequency = 16
+
+    with nogil:
+
+        # initialization of the heap elements
+        # all nodes have INFINITY key and UNLABELED state
+        pq.init_pqueue(&pqueue, <size_t>heap_length, <size_t>vertex_count)
+
+        # the key is set to zero for the source vertex,
+        # which is inserted into the heap
+        pq.insert(&pqueue, source, 0.0)
+
+        # main loop
+        while pqueue.size > 0:
+            tail_vert_idx = pq.extract_min(&pqueue)
+            tail_vert_val = pqueue.Elements[tail_vert_idx].key
+
+            # check for early termination every check_frequency iterations
+            iteration_count += 1
+            if iteration_count % check_frequency == 0:
+                visited_targets = 0
+                for i in range(target_count):
+                    if pqueue.Elements[termination_nodes[i]].state == SCANNED:
+                        visited_targets += 1
+                if visited_targets == target_count:
+                    break
+
+            # loop on outgoing edges
+            for idx in range(<size_t>csr_indptr[tail_vert_idx],
+                             <size_t>csr_indptr[tail_vert_idx + 1]):
+
+                head_vert_idx = <size_t>csr_indices[idx]
+
+                # prefetch next iteration data to improve cache performance
+                if idx + 1 < <size_t>csr_indptr[tail_vert_idx + 1]:
+                    prefetch_hint(<char*>&csr_indices[idx + 1], PREFETCH_T0)
+                    prefetch_hint(<char*>&csr_data[idx + 1], PREFETCH_T0)
+
+                vert_state = pqueue.Elements[head_vert_idx].state
+                if vert_state != SCANNED:
+                    # prefetch priority queue element data for the vertex
+                    prefetch_hint(<char*>&pqueue.Elements[head_vert_idx], PREFETCH_T0)
+
+                    head_vert_val = tail_vert_val + csr_data[idx]
+                    if vert_state == UNLABELED:
+                        pq.insert(&pqueue, head_vert_idx, head_vert_val)
+                    elif pqueue.Elements[head_vert_idx].key > head_vert_val:
+                        pq.decrease_key(&pqueue, head_vert_idx, head_vert_val)
+
+    # copy only the termination nodes' results into a numpy array
+    cdef cnp.ndarray path_lengths = np.empty(target_count, dtype=DTYPE_PY)
+    for i in range(target_count):
+        path_lengths[i] = pqueue.Elements[termination_nodes[i]].key
+
+    # cleanup
+    pq.free_pqueue(&pqueue)
+
+    return path_lengths
+
+
 cpdef cnp.ndarray compute_sssp_w_path(
         cnp.uint32_t[::1] csr_indptr,
         cnp.uint32_t[::1] csr_indices,
@@ -179,14 +294,14 @@ cpdef cnp.ndarray compute_sssp_w_path(
 
                 head_vert_idx = <size_t>csr_indices[idx]
 
-                # Prefetch next iteration data to improve cache performance
+                # prefetch next iteration data to improve cache performance
                 if idx + 1 < <size_t>csr_indptr[tail_vert_idx + 1]:
                     prefetch_hint(<char*>&csr_indices[idx + 1], PREFETCH_T0)
                     prefetch_hint(<char*>&csr_data[idx + 1], PREFETCH_T0)
 
                 vert_state = pqueue.Elements[head_vert_idx].state
                 if vert_state != SCANNED:
-                    # Prefetch priority queue element data for the vertex
+                    # prefetch priority queue element data for the vertex
                     prefetch_hint(<char*>&pqueue.Elements[head_vert_idx], PREFETCH_T0)
 
                     head_vert_val = tail_vert_val + csr_data[idx]
@@ -206,6 +321,115 @@ cpdef cnp.ndarray compute_sssp_w_path(
     return path_lengths
 
 
+cpdef cnp.ndarray compute_sssp_w_path_early_termination(
+        cnp.uint32_t[::1] csr_indptr,
+        cnp.uint32_t[::1] csr_indices,
+        DTYPE_t[::1] csr_data,
+        cnp.uint32_t[::1] predecessor,
+        cnp.uint32_t[::1] termination_nodes,
+        int source_vert_idx,
+        int vertex_count,
+        int heap_length):
+    """
+    Compute single-source shortest path with path tracking and early termination.
+    Parameters
+    ----------
+    csr_indices : cnp.uint32_t[::1]
+        indices in the CSR format
+    csr_indptr : cnp.uint32_t[::1]
+        pointers in the CSR format
+    csr_data : DTYPE_t[::1]
+        data (edge weights) in the CSR format
+    predecessor : cnp.uint32_t[::1]
+        array of indices, one for each vertex of the graph. Each vertex'
+        entry contains the index of its predecessor in a path from the
+        source, through the graph.
+    termination_nodes : cnp.uint32_t[::1]
+        target node indices for early termination
+    source_vert_idx : int
+        source vertex index
+    vertex_count : int
+        vertex count
+    heap_length : int
+        heap length
+
+    Returns
+    -------
+    path_lengths : cnp.ndarray
+        shortest path length for each termination node
+    """
+
+    cdef:
+        size_t tail_vert_idx, head_vert_idx, idx, i
+        DTYPE_t tail_vert_val, head_vert_val
+        pq.PriorityQueue pqueue
+        ElementState vert_state
+        size_t source = <size_t>source_vert_idx
+        size_t target_count = termination_nodes.shape[0]
+        size_t visited_targets = 0
+        size_t iteration_count = 0
+        size_t check_frequency = 16
+
+    with nogil:
+
+        # initialization of the heap elements
+        # all nodes have INFINITY key and UNLABELED state
+        pq.init_pqueue(&pqueue, <size_t>heap_length, <size_t>vertex_count)
+
+        # the key is set to zero for the source vertex,
+        # which is inserted into the heap
+        pq.insert(&pqueue, source, 0.0)
+
+        # main loop
+        while pqueue.size > 0:
+            tail_vert_idx = pq.extract_min(&pqueue)
+            tail_vert_val = pqueue.Elements[tail_vert_idx].key
+
+            # check for early termination every check_frequency iterations
+            iteration_count += 1
+            if iteration_count % check_frequency == 0:
+                visited_targets = 0
+                for i in range(target_count):
+                    if pqueue.Elements[termination_nodes[i]].state == SCANNED:
+                        visited_targets += 1
+                if visited_targets == target_count:
+                    break
+
+            # loop on outgoing edges
+            for idx in range(<size_t>csr_indptr[tail_vert_idx],
+                             <size_t>csr_indptr[tail_vert_idx + 1]):
+
+                head_vert_idx = <size_t>csr_indices[idx]
+
+                # prefetch next iteration data to improve cache performance
+                if idx + 1 < <size_t>csr_indptr[tail_vert_idx + 1]:
+                    prefetch_hint(<char*>&csr_indices[idx + 1], PREFETCH_T0)
+                    prefetch_hint(<char*>&csr_data[idx + 1], PREFETCH_T0)
+
+                vert_state = pqueue.Elements[head_vert_idx].state
+                if vert_state != SCANNED:
+                    # prefetch priority queue element data for the vertex
+                    prefetch_hint(<char*>&pqueue.Elements[head_vert_idx], PREFETCH_T0)
+
+                    head_vert_val = tail_vert_val + csr_data[idx]
+                    if vert_state == UNLABELED:
+                        pq.insert(&pqueue, head_vert_idx, head_vert_val)
+                        predecessor[head_vert_idx] = tail_vert_idx
+                    elif pqueue.Elements[head_vert_idx].key > head_vert_val:
+                        pq.decrease_key(&pqueue, head_vert_idx, head_vert_val)
+                        predecessor[head_vert_idx] = tail_vert_idx
+
+    # copy only the termination nodes' results into a numpy array
+    cdef cnp.ndarray path_lengths = np.empty(target_count, dtype=DTYPE_PY)
+    for i in range(target_count):
+        path_lengths[i] = pqueue.Elements[termination_nodes[i]].key
+
+    # cleanup
+    pq.free_pqueue(&pqueue)
+
+    return path_lengths
+
+
 cpdef cnp.ndarray compute_stsp(
         cnp.uint32_t[::1] csc_indptr,
         cnp.uint32_t[::1] csc_indices,
@@ -265,8 +489,17 @@ cpdef cnp.ndarray compute_stsp(
                              <size_t>csc_indptr[head_vert_idx + 1]):
 
                 tail_vert_idx = <size_t>csc_indices[idx]
+
+                # prefetch next iteration data to improve cache performance
+                if idx + 1 < <size_t>csc_indptr[head_vert_idx + 1]:
+                    prefetch_hint(<char*>&csc_indices[idx + 1], PREFETCH_T0)
+                    prefetch_hint(<char*>&csc_data[idx + 1], PREFETCH_T0)
+
                 vert_state = pqueue.Elements[tail_vert_idx].state
                 if vert_state != SCANNED:
+                    # prefetch priority queue element data for the vertex
+                    prefetch_hint(<char*>&pqueue.Elements[tail_vert_idx], PREFETCH_T0)
+
                     tail_vert_val = head_vert_val + csc_data[idx]
                     if vert_state == UNLABELED:
                         pq.insert(&pqueue, tail_vert_idx, tail_vert_val)
@@ -342,8 +575,17 @@ cpdef cnp.ndarray compute_stsp_w_path(
                              <size_t>csc_indptr[head_vert_idx + 1]):
 
                 tail_vert_idx = <size_t>csc_indices[idx]
+
+                # prefetch next iteration data to improve cache performance
+                if idx + 1 < <size_t>csc_indptr[head_vert_idx + 1]:
+                    prefetch_hint(<char*>&csc_indices[idx + 1], PREFETCH_T0)
+                    prefetch_hint(<char*>&csc_data[idx + 1], PREFETCH_T0)
+
                 vert_state = pqueue.Elements[tail_vert_idx].state
                 if vert_state != SCANNED:
+                    # prefetch priority queue element data for the vertex
+                    prefetch_hint(<char*>&pqueue.Elements[tail_vert_idx], PREFETCH_T0)
+
                     tail_vert_val = head_vert_val + csc_data[idx]
                     if vert_state == UNLABELED:
                         pq.insert(&pqueue, tail_vert_idx, tail_vert_val)
@@ -361,6 +603,216 @@ cpdef cnp.ndarray compute_stsp_w_path(
     return path_lengths
 
 
+cpdef cnp.ndarray compute_stsp_early_termination(
+        cnp.uint32_t[::1] csc_indptr,
+        cnp.uint32_t[::1] csc_indices,
+        DTYPE_t[::1] csc_data,
+        cnp.uint32_t[::1] termination_nodes,
+        int target_vert_idx,
+        int vertex_count,
+        int heap_length):
+    """
+    Compute single-target shortest path with early termination when target
+    nodes are reached.
+    Parameters
+    ----------
+    csc_indices : cnp.uint32_t[::1]
+        indices in the CSC format
+    csc_indptr : cnp.uint32_t[::1]
+        pointers in the CSC format
+    csc_data : DTYPE_t[::1]
+        data (edge weights) in the CSC format
+    termination_nodes : cnp.uint32_t[::1]
+        target node indices for early termination
+    target_vert_idx : int
+        target vertex index
+    vertex_count : int
+        vertex count
+    heap_length : int
+        heap length
+
+    Returns
+    -------
+    path_lengths : cnp.ndarray
+        shortest path length for each termination node
+    """
+
+    cdef:
+        size_t tail_vert_idx, head_vert_idx, idx, i
+        DTYPE_t tail_vert_val, head_vert_val
+        pq.PriorityQueue pqueue
+        ElementState vert_state
+        size_t target = <size_t>target_vert_idx
+        size_t target_count = termination_nodes.shape[0]
+        size_t visited_targets = 0
+        size_t iteration_count = 0
+        size_t check_frequency = 16
+
+    with nogil:
+
+        # initialization of the heap elements
+        # all nodes have INFINITY key and UNLABELED state
+        pq.init_pqueue(&pqueue, <size_t>heap_length, <size_t>vertex_count)
+
+        # the key is set to zero for the target vertex,
+        # which is inserted into the heap
+        pq.insert(&pqueue, target, 0.0)
+
+        # main loop
+        while pqueue.size > 0:
+            head_vert_idx = pq.extract_min(&pqueue)
+            head_vert_val = pqueue.Elements[head_vert_idx].key
+
+            # check for early termination every check_frequency iterations
+            iteration_count += 1
+            if iteration_count % check_frequency == 0:
+                visited_targets = 0
+                for i in range(target_count):
+                    if pqueue.Elements[termination_nodes[i]].state == SCANNED:
+                        visited_targets += 1
+                if visited_targets == target_count:
+                    break
+
+            # loop on incoming edges
+            for idx in range(<size_t>csc_indptr[head_vert_idx],
+                             <size_t>csc_indptr[head_vert_idx + 1]):
+
+                tail_vert_idx = <size_t>csc_indices[idx]
+
+                # prefetch next iteration data to improve cache performance
+                if idx + 1 < <size_t>csc_indptr[head_vert_idx + 1]:
+                    prefetch_hint(<char*>&csc_indices[idx + 1], PREFETCH_T0)
+                    prefetch_hint(<char*>&csc_data[idx + 1], PREFETCH_T0)
+
+                vert_state = pqueue.Elements[tail_vert_idx].state
+                if vert_state != SCANNED:
+                    # prefetch priority queue element data for the vertex
+                    prefetch_hint(<char*>&pqueue.Elements[tail_vert_idx], PREFETCH_T0)
+
+                    tail_vert_val = head_vert_val + csc_data[idx]
+                    if vert_state == UNLABELED:
+                        pq.insert(&pqueue, tail_vert_idx, tail_vert_val)
+                    elif pqueue.Elements[tail_vert_idx].key > tail_vert_val:
+                        pq.decrease_key(&pqueue, tail_vert_idx, tail_vert_val)
+
+    # copy only the termination nodes' results into a numpy array
+    cdef cnp.ndarray path_lengths = np.empty(target_count, dtype=DTYPE_PY)
+    for i in range(target_count):
+        path_lengths[i] = pqueue.Elements[termination_nodes[i]].key
+
+    # cleanup
+    pq.free_pqueue(&pqueue)
+
+    return path_lengths
+
+
+cpdef cnp.ndarray compute_stsp_w_path_early_termination(
+        cnp.uint32_t[::1] csc_indptr,
+        cnp.uint32_t[::1] csc_indices,
+        DTYPE_t[::1] csc_data,
+        cnp.uint32_t[::1] successor,
+        cnp.uint32_t[::1] termination_nodes,
+        int target_vert_idx,
+        int vertex_count,
+        int heap_length):
+    """
+    Compute single-target shortest path with path tracking and early termination.
+    Parameters
+    ----------
+    csc_indices : cnp.uint32_t[::1]
+        Indices in the CSC format.
+    csc_indptr : cnp.uint32_t[::1]
+        Pointers in the CSC format.
+    csc_data : DTYPE_t[::1]
+        Data (edge weights) in the CSC format.
+    successor : cnp.uint32_t[::1]
+        Array of successor indices for path reconstruction.
+    termination_nodes : cnp.uint32_t[::1]
+        target node indices for early termination
+    target_vert_idx : int
+        Target vertex index.
+    vertex_count : int
+        Vertex count.
+    heap_length : int
+        heap_length.
+
+    Returns
+    -------
+    path_lengths : cnp.ndarray
+        shortest path length for each termination node
+    """
+
+    cdef:
+        size_t tail_vert_idx, head_vert_idx, idx, i
+        DTYPE_t tail_vert_val, head_vert_val
+        pq.PriorityQueue pqueue
+        ElementState vert_state
+        size_t target = <size_t>target_vert_idx
+        size_t target_count = termination_nodes.shape[0]
+        size_t visited_targets = 0
+        size_t iteration_count = 0
+        size_t check_frequency = 16
+
+    with nogil:
+
+        # initialization of the heap elements
+        # all nodes have INFINITY key and UNLABELED state
+        pq.init_pqueue(&pqueue, <size_t>heap_length, <size_t>vertex_count)
+
+        # the key is set to zero for the target vertex,
+        # which is inserted into the heap
+        pq.insert(&pqueue, target, 0.0)
+
+        # main loop
+        while pqueue.size > 0:
+            head_vert_idx = pq.extract_min(&pqueue)
+            head_vert_val = pqueue.Elements[head_vert_idx].key
+
+            # check for early termination every check_frequency iterations
+            iteration_count += 1
+            if iteration_count % check_frequency == 0:
+                visited_targets = 0
+                for i in range(target_count):
+                    if pqueue.Elements[termination_nodes[i]].state == SCANNED:
+                        visited_targets += 1
+                if visited_targets == target_count:
+                    break
+
+            # loop on incoming edges
+            for idx in range(<size_t>csc_indptr[head_vert_idx],
+                             <size_t>csc_indptr[head_vert_idx + 1]):
+
+                tail_vert_idx = <size_t>csc_indices[idx]
+
+                # prefetch next iteration data to improve cache performance
+                if idx + 1 < <size_t>csc_indptr[head_vert_idx + 1]:
+                    prefetch_hint(<char*>&csc_indices[idx + 1], PREFETCH_T0)
+                    prefetch_hint(<char*>&csc_data[idx + 1], PREFETCH_T0)
+
+                vert_state = pqueue.Elements[tail_vert_idx].state
+                if vert_state != SCANNED:
+                    # prefetch priority queue element data for the vertex
+                    prefetch_hint(<char*>&pqueue.Elements[tail_vert_idx], PREFETCH_T0)
+
+                    tail_vert_val = head_vert_val + csc_data[idx]
+                    if vert_state == UNLABELED:
+                        pq.insert(&pqueue, tail_vert_idx, tail_vert_val)
+                        successor[tail_vert_idx] = head_vert_idx
+                    elif pqueue.Elements[tail_vert_idx].key > tail_vert_val:
+                        pq.decrease_key(&pqueue, tail_vert_idx, tail_vert_val)
+                        successor[tail_vert_idx] = head_vert_idx
+
+    # copy only the termination nodes' results into a numpy array
+    cdef cnp.ndarray path_lengths = np.empty(target_count, dtype=DTYPE_PY)
+    for i in range(target_count):
+        path_lengths[i] = pqueue.Elements[termination_nodes[i]].key
+
+    # cleanup
+    pq.free_pqueue(&pqueue)
+
+    return path_lengths
+
+
 # ============================================================================ #
 # tests                                                                        #
 # ============================================================================ #
@@ -521,6 +973,56 @@ cpdef compute_stsp_02():
     assert np.allclose(path_lengths_ref, path_lengths)
 
 
+cpdef compute_sssp_early_termination_01():
+    """
+    Test SSSP early termination on Braess-like network.
+    """
+
+    csr_indptr, csr_indices, csr_data = generate_braess_network_csr()
+
+    # from vertex 0, stop when vertices 1 and 3 are reached
+    target_nodes = np.array([1, 3], dtype=np.uint32)
+    path_lengths = compute_sssp_early_termination(
+        csr_indptr, csr_indices, csr_data, target_nodes, 0, 4, 4
+    )
+
+    # should return path lengths only for termination nodes [1, 3]
+    path_lengths_ref = np.array([1., 2.], dtype=DTYPE_PY)  # lengths to nodes 1 and 3
+    assert np.allclose(path_lengths_ref, path_lengths)
+
+    # test with path tracking
+    predecessor = np.arange(0, 4, dtype=np.uint32)
+    path_lengths_w_path = compute_sssp_w_path_early_termination(
+        csr_indptr, csr_indices, csr_data, predecessor, target_nodes, 0, 4, 4
+    )
+    assert np.allclose(path_lengths_ref, path_lengths_w_path)
+
+
+cpdef compute_stsp_early_termination_01():
+    """
+    Test STSP early termination on Braess-like network.
+    """
+
+    csc_indptr, csc_indices, csc_data = generate_braess_network_csc()
+
+    # to vertex 3, stop when vertices 0 and 2 are reached
+    target_nodes = np.array([0, 2], dtype=np.uint32)
+    path_lengths = compute_stsp_early_termination(
+        csc_indptr, csc_indices, csc_data, target_nodes, 3, 4, 4
+    )
+
+    # should return path lengths only for termination nodes [0, 2]
+    path_lengths_ref = np.array([2., 1.], dtype=DTYPE_PY)  # lengths to nodes 0 and 2
+    assert np.allclose(path_lengths_ref, path_lengths)
+
+    # test with path tracking
+    successor = np.arange(0, 4, dtype=np.uint32)
+    path_lengths_w_path = compute_stsp_w_path_early_termination(
+        csc_indptr, csc_indices, csc_data, successor, target_nodes, 3, 4, 4
+    )
+    assert np.allclose(path_lengths_ref, path_lengths_w_path)
+
+
 # author : Francois Pacull
 # copyright : Architecture & Performance
 # email: francois.pacull@architecture-performance.fr

edsger/path.py

@@ -17,8 +17,12 @@ from edsger.commons import (
 from edsger.dijkstra import (
     compute_sssp,
     compute_sssp_w_path,
+    compute_sssp_early_termination,
+    compute_sssp_w_path_early_termination,
     compute_stsp,
     compute_stsp_w_path,
+    compute_stsp_early_termination,
+    compute_stsp_w_path_early_termination,
 )
 from edsger.path_tracking import compute_path
 from edsger.spiess_florian import compute_SF_in
@@ -285,6 +289,7 @@ class Dijkstra:
         return_inf=True,
         return_series=False,
         heap_length_ratio=1.0,
+        termination_nodes=None,
     ):
         """
         Runs shortest path algorithm between a given vertex and all other vertices in the graph.
@@ -303,6 +308,11 @@ class Dijkstra:
             as values.
         heap_length_ratio : float, optional (default=1.0)
             The heap length as a fraction of the number of vertices. Must be in the range (0, 1].
+        termination_nodes : array-like, optional (default=None)
+            List or array of vertex indices for early termination. For SSSP (orientation='out'),
+            these are target nodes to reach. For STSP (orientation='in'), these are source nodes
+            to find paths from. When provided, the algorithm stops once all specified nodes have
+            been processed, potentially improving performance. If None, runs to completion.
 
         Returns
         -------
@@ -355,49 +365,140 @@ class Dijkstra:
             )
         heap_length = int(np.rint(heap_length_ratio * self._n_vertices))
 
+        # validate and process termination_nodes
+        termination_nodes_array = None
+        if termination_nodes is not None:
+            try:
+                termination_nodes_array = np.array(termination_nodes, dtype=np.uint32)
+            except (ValueError, TypeError):
+                raise TypeError(
+                    "argument 'termination_nodes' must be array-like of integers"
+                )
+
+            if termination_nodes_array.ndim != 1:
+                raise ValueError("argument 'termination_nodes' must be 1-dimensional")
+
+            if len(termination_nodes_array) == 0:
+                raise ValueError("argument 'termination_nodes' must not be empty")
+
+            # handle vertex permutation if needed
+            if self._permute:
+                termination_nodes_permuted = []
+                for termination_node in termination_nodes_array:
+                    if termination_node not in self._permutation.vert_idx_old.values:
+                        raise ValueError(
+                            f"termination node {termination_node} not found in graph"
+                        )
+                    termination_node_new = self._permutation.loc[
+                        self._permutation.vert_idx_old == termination_node,
+                        "vert_idx_new",
+                    ].iloc[0]
+                    termination_nodes_permuted.append(termination_node_new)
+                termination_nodes_array = np.array(
+                    termination_nodes_permuted, dtype=np.uint32
+                )
+            else:
+                # validate that termination nodes exist
+                if np.any(termination_nodes_array >= self._n_vertices) or np.any(
+                    termination_nodes_array < 0
+                ):
+                    raise ValueError(
+                        "termination_nodes contains invalid vertex indices"
+                    )
+
         # compute path length
         if not path_tracking:
             self._path_links = None
-            if self._orientation == "in":
-                path_length_values = compute_stsp(
-                    self.__indptr,
-                    self.__indices,
-                    self.__edge_weights,
-                    vertex_new,
-                    self._n_vertices,
-                    heap_length,
-                )
+            if termination_nodes_array is not None:
+                # use early termination algorithms
+                if self._orientation == "in":
+                    path_length_values = compute_stsp_early_termination(
+                        self.__indptr,
+                        self.__indices,
+                        self.__edge_weights,
+                        termination_nodes_array,
+                        vertex_new,
+                        self._n_vertices,
+                        heap_length,
+                    )
+                else:
+                    path_length_values = compute_sssp_early_termination(
+                        self.__indptr,
+                        self.__indices,
+                        self.__edge_weights,
+                        termination_nodes_array,
+                        vertex_new,
+                        self._n_vertices,
+                        heap_length,
+                    )
             else:
-                path_length_values = compute_sssp(
-                    self.__indptr,
-                    self.__indices,
-                    self.__edge_weights,
-                    vertex_new,
-                    self._n_vertices,
-                    heap_length,
-                )
+                # use standard algorithms
+                if self._orientation == "in":
+                    path_length_values = compute_stsp(
+                        self.__indptr,
+                        self.__indices,
+                        self.__edge_weights,
+                        vertex_new,
+                        self._n_vertices,
+                        heap_length,
+                    )
+                else:
+                    path_length_values = compute_sssp(
+                        self.__indptr,
+                        self.__indices,
+                        self.__edge_weights,
+                        vertex_new,
+                        self._n_vertices,
+                        heap_length,
+                    )
         else:
             self._path_links = np.arange(0, self._n_vertices, dtype=np.uint32)
-            if self._orientation == "in":
-                path_length_values = compute_stsp_w_path(
-                    self.__indptr,
-                    self.__indices,
-                    self.__edge_weights,
-                    self._path_links,
-                    vertex_new,
-                    self._n_vertices,
-                    heap_length,
-                )
+            if termination_nodes_array is not None:
+                # use early termination algorithms with path tracking
+                if self._orientation == "in":
+                    path_length_values = compute_stsp_w_path_early_termination(
+                        self.__indptr,
+                        self.__indices,
+                        self.__edge_weights,
+                        self._path_links,
+                        termination_nodes_array,
+                        vertex_new,
+                        self._n_vertices,
+                        heap_length,
+                    )
+                else:
+                    path_length_values = compute_sssp_w_path_early_termination(
+                        self.__indptr,
+                        self.__indices,
+                        self.__edge_weights,
+                        self._path_links,
+                        termination_nodes_array,
+                        vertex_new,
+                        self._n_vertices,
+                        heap_length,
+                    )
             else:
-                path_length_values = compute_sssp_w_path(
-                    self.__indptr,
-                    self.__indices,
-                    self.__edge_weights,
-                    self._path_links,
-                    vertex_new,
-                    self._n_vertices,
-                    heap_length,
-                )
+                # use standard algorithms with path tracking
+                if self._orientation == "in":
+                    path_length_values = compute_stsp_w_path(
+                        self.__indptr,
+                        self.__indices,
+                        self.__edge_weights,
+                        self._path_links,
+                        vertex_new,
+                        self._n_vertices,
+                        heap_length,
+                    )
+                else:
+                    path_length_values = compute_sssp_w_path(
+                        self.__indptr,
+                        self.__indices,
+                        self.__edge_weights,
+                        self._path_links,
+                        vertex_new,
+                        self._n_vertices,
+                        heap_length,
+                    )
 
             if self._permute:
                 # permute back the path vertex indices
@@ -445,7 +546,7 @@ class Dijkstra:
 
         # reorder path lengths
         if return_series:
-            if self._permute:
+            if self._permute and termination_nodes_array is None:
                 self._permutation["path_length"] = path_length_values
                 path_lengths_df = self._permutation[
                     ["vert_idx_old", "path_length"]
@@ -457,9 +558,16 @@ class Dijkstra:
                 path_lengths_series = pd.Series(path_length_values)
                 path_lengths_series.index.name = "vertex_idx"
                 path_lengths_series.name = "path_length"
+                if self._permute and termination_nodes_array is not None:
+                    # For early termination with permutation, use original termination node indices
+                    path_lengths_series.index = termination_nodes
 
             return path_lengths_series
 
+        # For early termination, return results directly (already in correct order)
+        if termination_nodes_array is not None:
+            return path_length_values
+
         if self._permute:
             self._permutation["path_length"] = path_length_values
             if return_inf:

{edsger-0.1.2.dist-info → edsger-0.1.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: edsger
-Version: 0.1.2
+Version: 0.1.4
 Summary: Graph algorithms in Cython.
 Author-email: François Pacull <francois.pacull@architecture-performance.fr>
 Maintainer-email: François Pacull <francois.pacull@architecture-performance.fr>
@@ -42,7 +42,8 @@ Dynamic: license-file
 
 ![Tests Status](https://github.com/aetperf/edsger/actions/workflows/tests.yml/badge.svg?branch=release)
 [![codecov](https://codecov.io/gh/aetperf/edsger/branch/release/graph/badge.svg)](https://codecov.io/gh/aetperf/edsger)
-[![PyPI version](https://img.shields.io/pypi/v/edsger.svg)](https://pypi.org/project/edsger/)
+[![Documentation Status](https://readthedocs.org/projects/edsger/badge/?version=latest)](https://edsger.readthedocs.io/en/latest/?badge=latest)
+[![PyPI version](https://img.shields.io/pypi/v/edsger.svg?refresh=1)](https://pypi.org/project/edsger/)
 [![Downloads](https://static.pepy.tech/badge/edsger)](https://pepy.tech/project/edsger)
 [![Python 3.9 | 3.10 | 3.11 | 3.12 | 3.13](https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue)](https://pypi.org/project/edsger/)
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
@@ -75,14 +76,14 @@ edges = pd.DataFrame({
 edges
 ```
 
-    |    |   tail |   head |   weight |
-    |---:|-------:|-------:|---------:|
-    |  0 |      0 |      1 |      1.0 |
-    |  1 |      0 |      2 |      4.0 |
-    |  2 |      1 |      2 |      2.0 |
-    |  3 |      2 |      3 |      1.5 |
-    |  4 |      2 |      4 |      3.0 |
-    |  5 |      3 |      4 |      1.0 |
+|    |   tail |   head |   weight |
+|---:|-------:|-------:|---------:|
+|  0 |      0 |      1 |      1.0 |
+|  1 |      0 |      2 |      4.0 |
+|  2 |      1 |      2 |      2.0 |
+|  3 |      2 |      3 |      1.5 |
+|  4 |      2 |      4 |      3.0 |
+|  5 |      3 |      4 |      1.0 |
 
 ```python
 # Initialize the Dijkstra object
@@ -97,13 +98,19 @@ print("Shortest paths:", shortest_paths)
 
 We get the shortest paths from the source node 0 to all other nodes in the graph. The output is an array with the shortest path length to each node. A path length is the sum of the weights of the edges in the path.
 
-## Why Use Edsger?
+## Installation
+
+### Standard Installation
 
-Edsger is designed to be **dataframe-friendly**, providing seamless integration with pandas workflows for graph algorithms. Also it is rather efficient. Our benchmarks on the USA road network (23.9M vertices, 57.7M edges) demonstrate nice performance:
+```bash
+pip install edsger
+```
+
+## Why Use Edsger?
 
-<img src="docs/source/assets/dijkstra_benchmark_comparison.png" alt="Dijkstra Performance Comparison" width="700">
+Edsger is designed to be **dataframe-friendly**, providing seamless integration with pandas workflows for graph algorithms. Also it is rather efficient on Linux. Our benchmarks on the USA road network (23.9M vertices, 57.7M edges) demonstrate nice performance:
 
-*Benchmark performed on Intel i9-12900H laptop.*
+<img src="https://raw.githubusercontent.com/aetperf/edsger/release/docs/source/assets/dijkstra_benchmark_comparison.png" alt="Dijkstra Performance Comparison" width="700">
 
 ## Contributing
 

edsger-0.1.4.dist-info/RECORD

@@ -0,0 +1,27 @@
+edsger/.gitignore,sha256=mr9Izcwvjgv215xjRKhWEZ7vsyrKWhMqvWjSLHRYDjk,13
+edsger/__init__.py,sha256=lgtGe3cqdwWdO1DLEOx7fX3i8D4Z_2rXHSq7Xecf-NM,41
+edsger/_version.py,sha256=JMD28FXYHc_TM03visyUSd3UA9FZAaJMRStnfZoq50Y,21
+edsger/commons.cp312-win32.pyd,sha256=Ij8OCS8r0EYdUGeU8sokLJRYItAKYa9boIJ_PTPPKnw,20480
+edsger/commons.pxd,sha256=UshKjr5ve3Or9u75xGyGPKRz1RwCCb5N-xgNevXZ4j4,464
+edsger/commons.pyx,sha256=6Ze22eE_zwXPRAe550DEhEvu-b7hvKmwQu73rzzWMUE,839
+edsger/dijkstra.cp312-win32.pyd,sha256=TCNFPOoVvGeRGn_n_G00zWWRwl9PWGWonD5Iydyv6h8,214016
+edsger/dijkstra.pyx,sha256=kBXFya0bugjp97xas145sZEUXtb89_Sg9v8IdWiURoE,37542
+edsger/networks.py,sha256=hH9sgT5Ic4TLVCjxPNzMDWNjNDbqpXMxXxLeWxCpdLE,10730
+edsger/path.py,sha256=2NtkhwN2HQUsoZn0Sl6UbFKWIcWVTvnE6D8IH-xEG88,35768
+edsger/path_tracking.cp312-win32.pyd,sha256=gjsAtjRWQ4itlrdmklw2H-pS-q4OcKNl7jJFvlF_SqY,116736
+edsger/path_tracking.pyx,sha256=H24TLmC53I8LjbM1S5E7gS8WEb5uE_PZ8nhG6BteMYA,1900
+edsger/pq_4ary_dec_0b.cp312-win32.pyd,sha256=1_pXQ1Xtxwx1rCo9AzFvKFUFW9rryU7by4GD0sYIERk,142848
+edsger/pq_4ary_dec_0b.pxd,sha256=VvXcQzJq3OGBptrbawtemagPimuqSCayGQ91Jrad894,1098
+edsger/pq_4ary_dec_0b.pyx,sha256=IzvzQerf-LYy7weQpgI0f28Q8gUrR4ENaedekXs1Jeg,18486
+edsger/prefetch_compat.h,sha256=AyAYq_ZHKk5ChaJDrZOAOYe6SprL0_2byjRbjcBGrsU,826
+edsger/spiess_florian.cp312-win32.pyd,sha256=KHt94IJ_Xvhs9a2VAtPS1cMamFypM7VdnGJDtDybmus,162304
+edsger/spiess_florian.pyx,sha256=tjfF9Iv8nqpp4lnv4KAjF-37ij0_SgQ0fnacVVKx-CE,9934
+edsger/star.cp312-win32.pyd,sha256=8LFDWdmxlNrI_PfdRcFzJz4IEBceYrZYtqJi8UqrpF0,154112
+edsger/star.pyx,sha256=9LAIXhlccEeDgT41ico7n57FJ7PKCzhPv4f22Lphn78,9602
+edsger/utils.py,sha256=xYfOFIbYpAiZljhUOgGWy0TVNvWaMFCwbCLPBkzdVos,2097
+edsger-0.1.4.dist-info/licenses/AUTHORS.rst,sha256=8udN6bgZHdHYcVzV38y6SPnF-x6Ks0uXxxFsic6Aces,110
+edsger-0.1.4.dist-info/licenses/LICENSE,sha256=w7gRlruGxK3_4KTZAyJsOR2tML4UQgB-GNm2LerwJS0,1132
+edsger-0.1.4.dist-info/METADATA,sha256=fl_OoQXbo9d0B0sIkuOSDD5JAB-CgxWA6dRNujINONc,5494
+edsger-0.1.4.dist-info/WHEEL,sha256=LwxTQZ0gyDP_uaeNCLm-ZIktY9hv6x0e22Q-hgFd-po,97
+edsger-0.1.4.dist-info/top_level.txt,sha256=QvhzFORJIIot6GzSnDrtGa9KQt9iifCbOC5ULlzY5dg,7
+edsger-0.1.4.dist-info/RECORD,,

edsger-0.1.2.dist-info/RECORD

@@ -1,27 +0,0 @@
-edsger/.gitignore,sha256=mr9Izcwvjgv215xjRKhWEZ7vsyrKWhMqvWjSLHRYDjk,13
-edsger/__init__.py,sha256=lgtGe3cqdwWdO1DLEOx7fX3i8D4Z_2rXHSq7Xecf-NM,41
-edsger/_version.py,sha256=K5SiDdEGYMpdqXThrqwTqECJJBOQNTQDrnpc2K5mzKs,21
-edsger/commons.cp312-win32.pyd,sha256=A4VhAzKWRKdaOm2qAydr-Yw2K4JRz1k2A9CLGhBGqHs,19968
-edsger/commons.pxd,sha256=UshKjr5ve3Or9u75xGyGPKRz1RwCCb5N-xgNevXZ4j4,464
-edsger/commons.pyx,sha256=6Ze22eE_zwXPRAe550DEhEvu-b7hvKmwQu73rzzWMUE,839
-edsger/dijkstra.cp312-win32.pyd,sha256=rwRaxfFz0SUpuKKoMNlk-0KTRkqMdCTq9PCg1M85uZ0,171008
-edsger/dijkstra.pyx,sha256=5yjCC2NqXrfBe8tp1sN_XSsWF92IHFrOu-QdbOV8Rvo,17915
-edsger/networks.py,sha256=hH9sgT5Ic4TLVCjxPNzMDWNjNDbqpXMxXxLeWxCpdLE,10730
-edsger/path.py,sha256=OnXbP8Mf1rcO_9m6XsDrdXCRcLMeOb2vOAb1eHcZfM8,30395
-edsger/path_tracking.cp312-win32.pyd,sha256=zKOdWTiOOLtihPEsKDMRcSMnygp0v6MjQ1uEDwjday4,113664
-edsger/path_tracking.pyx,sha256=H24TLmC53I8LjbM1S5E7gS8WEb5uE_PZ8nhG6BteMYA,1900
-edsger/pq_4ary_dec_0b.cp312-win32.pyd,sha256=_g51tHNv46-1KGSuFYR1Od8MvBn9GnDK9XKu3rB32mM,139776
-edsger/pq_4ary_dec_0b.pxd,sha256=VvXcQzJq3OGBptrbawtemagPimuqSCayGQ91Jrad894,1098
-edsger/pq_4ary_dec_0b.pyx,sha256=IzvzQerf-LYy7weQpgI0f28Q8gUrR4ENaedekXs1Jeg,18486
-edsger/prefetch_compat.h,sha256=AyAYq_ZHKk5ChaJDrZOAOYe6SprL0_2byjRbjcBGrsU,826
-edsger/spiess_florian.cp312-win32.pyd,sha256=mF_MRkXyjQJfWzQr-EiJoBIOPqT6-UFJJLFgEjNU2rE,159232
-edsger/spiess_florian.pyx,sha256=tjfF9Iv8nqpp4lnv4KAjF-37ij0_SgQ0fnacVVKx-CE,9934
-edsger/star.cp312-win32.pyd,sha256=sLn5npOoHmJJXTZW8-rNM7kX_yP8g67CZPBoy4wamGs,151040
-edsger/star.pyx,sha256=9LAIXhlccEeDgT41ico7n57FJ7PKCzhPv4f22Lphn78,9602
-edsger/utils.py,sha256=xYfOFIbYpAiZljhUOgGWy0TVNvWaMFCwbCLPBkzdVos,2097
-edsger-0.1.2.dist-info/licenses/AUTHORS.rst,sha256=8udN6bgZHdHYcVzV38y6SPnF-x6Ks0uXxxFsic6Aces,110
-edsger-0.1.2.dist-info/licenses/LICENSE,sha256=w7gRlruGxK3_4KTZAyJsOR2tML4UQgB-GNm2LerwJS0,1132
-edsger-0.1.2.dist-info/METADATA,sha256=Z2KnsYE4vh_m5tvRYU-LIyDso2Kpdl7iQQeFYH_zfhM,5273
-edsger-0.1.2.dist-info/WHEEL,sha256=LwxTQZ0gyDP_uaeNCLm-ZIktY9hv6x0e22Q-hgFd-po,97
-edsger-0.1.2.dist-info/top_level.txt,sha256=QvhzFORJIIot6GzSnDrtGa9KQt9iifCbOC5ULlzY5dg,7
-edsger-0.1.2.dist-info/RECORD,,