edsger 0.1.4__cp311-cp311-win32.whl → 0.1.6__cp311-cp311-win32.whl

edsger/bfs.pyx

@@ -0,0 +1,243 @@
+"""
+Breadth-First Search (BFS) implementation.
+
+cpdef functions:
+
+- bfs_csr
+    Compute BFS tree using CSR format (forward traversal). Returns predecessors.
+- bfs_csc
+    Compute BFS tree using CSC format (backward traversal). Returns predecessors.
+"""
+
+# cython: language_level=3
+# cython: boundscheck=False
+# cython: wraparound=False
+# cython: embedsignature=False
+# cython: cdivision=True
+# cython: initializedcheck=False
+
+cimport numpy as cnp
+import numpy as np
+
+cpdef cnp.ndarray bfs_csr(
+        cnp.uint32_t[::1] csr_indptr,
+        cnp.uint32_t[::1] csr_indices,
+        int start_vert_idx,
+        int vertex_count,
+        int sentinel=-9999):
+    """
+    Compute BFS tree using CSR format (forward traversal from start vertex).
+
+    Parameters
+    ----------
+    csr_indptr : cnp.uint32_t[::1]
+        Pointers in the CSR format
+    csr_indices : cnp.uint32_t[::1]
+        Indices in the CSR format
+    start_vert_idx : int
+        Starting vertex index
+    vertex_count : int
+        Total number of vertices
+    sentinel : int, optional
+        Sentinel value for unreachable nodes and start vertex (default: -9999)
+
+    Returns
+    -------
+    predecessors : cnp.ndarray
+        Predecessor array where predecessors[i] contains the predecessor
+        of vertex i in the BFS tree. Unreachable vertices and the start
+        vertex have the sentinel value.
+    """
+
+    cdef:
+        size_t tail_vert_idx, head_vert_idx, idx
+        size_t queue_head = 0, queue_tail = 0
+        size_t start = <size_t>start_vert_idx
+        cnp.uint32_t[::1] queue
+        cnp.int8_t[::1] visited
+        cnp.int32_t[::1] predecessors
+
+    # Allocate arrays
+    queue = np.empty(vertex_count, dtype=np.uint32)
+    visited = np.zeros(vertex_count, dtype=np.int8)
+    predecessors = np.full(vertex_count, sentinel, dtype=np.int32)
+
+    with nogil:
+        # Initialize: mark start vertex as visited and enqueue it
+        visited[start] = 1
+        queue[queue_tail] = start
+        queue_tail += 1
+
+        # BFS main loop
+        while queue_head < queue_tail:
+            tail_vert_idx = queue[queue_head]
+            queue_head += 1
+
+            # Process all outgoing edges from tail_vert_idx
+            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]
+
+                # If not visited, mark as visited and enqueue
+                if visited[head_vert_idx] == 0:
+                    visited[head_vert_idx] = 1
+                    predecessors[head_vert_idx] = <int>tail_vert_idx
+                    queue[queue_tail] = head_vert_idx
+                    queue_tail += 1
+
+    # Convert to numpy array
+    return np.asarray(predecessors)
+
+
+cpdef cnp.ndarray bfs_csc(
+        cnp.uint32_t[::1] csc_indptr,
+        cnp.uint32_t[::1] csc_indices,
+        int start_vert_idx,
+        int vertex_count,
+        int sentinel=-9999):
+    """
+    Compute BFS tree using CSC format (backward traversal from start vertex).
+
+    Parameters
+    ----------
+    csc_indptr : cnp.uint32_t[::1]
+        Pointers in the CSC format
+    csc_indices : cnp.uint32_t[::1]
+        Indices in the CSC format
+    start_vert_idx : int
+        Starting vertex index
+    vertex_count : int
+        Total number of vertices
+    sentinel : int, optional
+        Sentinel value for unreachable nodes and start vertex (default: -9999)
+
+    Returns
+    -------
+    predecessors : cnp.ndarray
+        Predecessor array where predecessors[i] contains the successor
+        of vertex i in the BFS tree (since we're traversing backward).
+        Unreachable vertices and the start vertex have the sentinel value.
+    """
+
+    cdef:
+        size_t tail_vert_idx, head_vert_idx, idx
+        size_t queue_head = 0, queue_tail = 0
+        size_t start = <size_t>start_vert_idx
+        cnp.uint32_t[::1] queue
+        cnp.int8_t[::1] visited
+        cnp.int32_t[::1] predecessors
+
+    # Allocate arrays
+    queue = np.empty(vertex_count, dtype=np.uint32)
+    visited = np.zeros(vertex_count, dtype=np.int8)
+    predecessors = np.full(vertex_count, sentinel, dtype=np.int32)
+
+    with nogil:
+        # Initialize: mark start vertex as visited and enqueue it
+        visited[start] = 1
+        queue[queue_tail] = start
+        queue_tail += 1
+
+        # BFS main loop (processing incoming edges using CSC)
+        while queue_head < queue_tail:
+            head_vert_idx = queue[queue_head]
+            queue_head += 1
+
+            # Process all incoming edges to head_vert_idx
+            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]
+
+                # If not visited, mark as visited and enqueue
+                if visited[tail_vert_idx] == 0:
+                    visited[tail_vert_idx] = 1
+                    predecessors[tail_vert_idx] = <int>head_vert_idx
+                    queue[queue_tail] = tail_vert_idx
+                    queue_tail += 1
+
+    # Convert to numpy array
+    return np.asarray(predecessors)
+
+
+# ============================================================================ #
+# tests                                                                        #
+# ============================================================================ #
+
+
+cdef generate_simple_graph_csr():
+    """
+    Generate a simple directed graph in CSR format.
+
+    Graph structure:
+    0 -> 1 -> 3
+    0 -> 2 -> 3
+
+    4 vertices, 4 edges
+    """
+    csr_indptr = np.array([0, 2, 3, 4, 4], dtype=np.uint32)
+    csr_indices = np.array([1, 2, 3, 3], dtype=np.uint32)
+    return csr_indptr, csr_indices
+
+
+cdef generate_simple_graph_csc():
+    """
+    Generate a simple directed graph in CSC format.
+
+    Graph structure (same as CSR version):
+    0 -> 1 -> 3
+    0 -> 2 -> 3
+
+    4 vertices, 4 edges
+    """
+    csc_indptr = np.array([0, 0, 1, 2, 4], dtype=np.uint32)
+    csc_indices = np.array([0, 0, 1, 2], dtype=np.uint32)
+    return csc_indptr, csc_indices
+
+
+cpdef test_bfs_csr_01():
+    """Test BFS CSR on simple graph from vertex 0."""
+    cdef int UNREACHABLE = -9999
+    csr_indptr, csr_indices = generate_simple_graph_csr()
+
+    predecessors = bfs_csr(csr_indptr, csr_indices, 0, 4)
+
+    # Expected: 0 is start, 1 and 2 have predecessor 0, 3 has predecessor 1 or 2
+    assert predecessors[0] == UNREACHABLE  # start vertex
+    assert predecessors[1] == 0
+    assert predecessors[2] == 0
+    assert predecessors[3] in [1, 2]  # could be reached from either 1 or 2
+
+
+cpdef test_bfs_csc_01():
+    """Test BFS CSC on simple graph to vertex 3."""
+    cdef int UNREACHABLE = -9999
+    csc_indptr, csc_indices = generate_simple_graph_csc()
+
+    predecessors = bfs_csc(csc_indptr, csc_indices, 3, 4)
+
+    # Expected: working backward from 3
+    assert predecessors[3] == UNREACHABLE  # start vertex
+    assert predecessors[1] in [3, UNREACHABLE] or predecessors[2] in [3, UNREACHABLE]
+    assert predecessors[0] in [1, 2, UNREACHABLE]
+
+
+cpdef test_bfs_unreachable():
+    """Test BFS with unreachable vertices."""
+    cdef int UNREACHABLE = -9999
+    # Graph: 0 -> 1, 2 -> 3 (two disconnected components)
+    csr_indptr = np.array([0, 1, 1, 2, 2], dtype=np.uint32)
+    csr_indices = np.array([1, 3], dtype=np.uint32)
+
+    predecessors = bfs_csr(csr_indptr, csr_indices, 0, 4)
+
+    # From 0, can reach 1 but not 2 or 3
+    assert predecessors[0] == UNREACHABLE  # start
+    assert predecessors[1] == 0
+    assert predecessors[2] == UNREACHABLE  # unreachable
+    assert predecessors[3] == UNREACHABLE  # unreachable
+
+
+# author : Francois Pacull
+# copyright : Architecture & Performance
+# email: francois.pacull@architecture-performance.fr
+# license : MIT

edsger/commons.pyx

@@ -2,6 +2,13 @@
 Common definitions.
 """
 
+# cython: language_level=3
+# cython: boundscheck=False
+# cython: wraparound=False
+# cython: embedsignature=False
+# cython: cdivision=True
+# cython: initializedcheck=False
+
 import numpy as np
 
 DTYPE_PY = np.float64

edsger/dijkstra.pyx

@@ -29,6 +29,13 @@ cpdef functions:
     are reached. Compute successors.
 """
 
+# cython: language_level=3
+# cython: boundscheck=False
+# cython: wraparound=False
+# cython: embedsignature=False
+# cython: cdivision=True
+# cython: initializedcheck=False
+
 cimport numpy as cnp
 
 from edsger.commons cimport (

edsger/graph_importer.py

@@ -0,0 +1,340 @@
+"""
+Graph importer module for converting various DataFrame formats to NumPy-backed pandas DataFrames.
+
+This module provides a unified interface for importing graph data from different DataFrame libraries
+(pandas with NumPy backend, pandas with Arrow backend, Polars, etc.) and converting them to a
+standardized NumPy-backed pandas DataFrame format that is optimal for the graph algorithms.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Optional, List
+import warnings
+
+import numpy as np
+import pandas as pd
+
+
+class GraphImporter(ABC):
+    """
+    Abstract base class for importing graph data from various DataFrame libraries.
+
+    All importers convert their input format to a NumPy-backed pandas DataFrame
+    with contiguous memory layout for optimal performance in Cython algorithms.
+    """
+
+    def __init__(self, edges_df):
+        """
+        Initialize the importer with a DataFrame.
+
+        Parameters
+        ----------
+        edges_df : DataFrame-like
+            The edges DataFrame in the specific library format.
+        """
+        self.edges_df = edges_df
+
+    @staticmethod
+    def from_dataframe(  # pylint: disable=too-many-arguments,too-many-positional-arguments
+        edges,
+        tail: str = "tail",
+        head: str = "head",
+        weight: Optional[str] = None,
+        trav_time: Optional[str] = None,
+        freq: Optional[str] = None,
+    ) -> "GraphImporter":
+        """
+        Factory method to create the appropriate importer based on DataFrame type.
+
+        Parameters
+        ----------
+        edges : DataFrame-like
+            The edges DataFrame to import.
+        tail : str
+            Column name for tail vertices.
+        head : str
+            Column name for head vertices.
+        weight : str, optional
+            Column name for edge weights (for shortest path algorithms).
+        trav_time : str, optional
+            Column name for travel time (for hyperpath algorithms).
+        freq : str, optional
+            Column name for frequency (for hyperpath algorithms).
+
+        Returns
+        -------
+        GraphImporter
+            An instance of the appropriate importer subclass.
+        """
+        # Note: tail, head, weight, trav_time, freq are part of API but not used here
+        # They're used by calling code after factory creates the importer
+        # pylint: disable=unused-argument
+        try:
+            # Check for Polars DataFrame
+            if hasattr(edges, "__class__") and edges.__class__.__module__.startswith(
+                "polars"
+            ):
+                return PolarsImporter(edges)
+        except (AttributeError, TypeError):
+            # If __class__ or __module__ access fails, continue to other checks
+            pass
+
+        # Check for pandas DataFrame
+        if isinstance(edges, pd.DataFrame):
+            try:
+                # Check if any column has Arrow backend
+                has_arrow = any(
+                    hasattr(dtype, "pyarrow_dtype") for dtype in edges.dtypes
+                )
+
+                if has_arrow:
+                    return PandasArrowImporter(edges)
+                return PandasNumpyImporter(edges)
+            except (AttributeError, TypeError):
+                # If dtype checking fails, assume NumPy backend
+                return PandasNumpyImporter(edges)
+
+        # Unknown type - try to convert to pandas
+        warnings.warn(
+            f"Unknown DataFrame type {type(edges)}. Attempting to convert to pandas.",
+            UserWarning,
+        )
+        return PandasNumpyImporter(pd.DataFrame(edges))
+
+    @abstractmethod
+    def to_numpy_edges(self, columns: List[str]) -> pd.DataFrame:
+        """
+        Convert the DataFrame to a NumPy-backed pandas DataFrame.
+
+        Parameters
+        ----------
+        columns : List[str]
+            List of column names to extract.
+
+        Returns
+        -------
+        pd.DataFrame
+            A pandas DataFrame with NumPy backend and contiguous memory.
+        """
+
+    def _ensure_contiguous(self, array: np.ndarray) -> np.ndarray:
+        """
+        Ensure the array is C-contiguous.
+
+        Parameters
+        ----------
+        array : np.ndarray
+            Input array.
+
+        Returns
+        -------
+        np.ndarray
+            C-contiguous array.
+        """
+        if not array.flags["C_CONTIGUOUS"]:
+            return np.ascontiguousarray(array)
+        return array
+
+
+class PandasNumpyImporter(GraphImporter):
+    """
+    Importer for pandas DataFrames with NumPy backend.
+
+    This is the most efficient case as it requires minimal conversion.
+    """
+
+    def to_numpy_edges(self, columns: List[str]) -> pd.DataFrame:
+        """
+        Extract columns and ensure they are NumPy-backed.
+
+        For NumPy-backed pandas, this is mostly a pass-through operation
+        with validation to ensure contiguous memory.
+        """
+        # Extract only the needed columns
+        result_df = self.edges_df[columns].copy(deep=True)
+
+        # Ensure all columns are contiguous NumPy arrays
+        for col in columns:
+            if not isinstance(result_df[col].values, np.ndarray):
+                # Convert to NumPy if somehow not already
+                result_df[col] = result_df[col].to_numpy()
+
+        return result_df
+
+
+class PandasArrowImporter(GraphImporter):
+    """
+    Importer for pandas DataFrames with Arrow backend.
+
+    Converts Arrow-backed columns to NumPy arrays with proper data types.
+    """
+
+    def to_numpy_edges(self, columns: List[str]) -> pd.DataFrame:
+        """
+        Convert Arrow-backed columns to NumPy arrays.
+
+        Uses to_numpy() method which ensures contiguous memory layout.
+        """
+        result_data = {}
+
+        for col in columns:
+            series = self.edges_df[col]
+
+            # Determine target dtype based on column values
+            if col in columns[:2]:  # Assume first two are vertex indices (tail, head)
+                # Try to use uint32 for vertex indices if possible
+                max_val = series.max()
+                if max_val < np.iinfo(np.uint32).max:
+                    target_dtype = np.uint32
+                else:
+                    target_dtype = np.uint64
+            else:
+                # Use float64 for weights/times/frequencies
+                target_dtype = np.float64
+
+            # Convert to NumPy with specified dtype
+            if hasattr(series, "to_numpy"):
+                # Use to_numpy() for Arrow-backed series
+                result_data[col] = series.to_numpy(dtype=target_dtype, copy=True)
+            else:
+                # Fallback for older pandas versions
+                result_data[col] = series.values.astype(target_dtype)
+
+            # Ensure contiguous
+            result_data[col] = self._ensure_contiguous(result_data[col])
+
+        return pd.DataFrame(result_data)
+
+
+class PolarsImporter(GraphImporter):
+    """
+    Importer for Polars DataFrames.
+
+    Converts Polars DataFrames to NumPy-backed pandas DataFrames.
+    """
+
+    def to_numpy_edges(
+        self, columns: List[str]
+    ) -> pd.DataFrame:  # pylint: disable=too-many-branches
+        """
+        Convert Polars DataFrame to NumPy-backed pandas DataFrame.
+
+        Uses Polars' to_pandas() method or to_numpy() depending on what's available.
+        """
+        try:
+            import polars  # pylint: disable=import-outside-toplevel,unused-import
+        except ImportError as exc:
+            raise ImportError(
+                "Polars is required to import Polars DataFrames. "
+                "Install it with: pip install polars"
+            ) from exc
+
+        # Select only needed columns
+        selected_df = self.edges_df.select(columns)
+
+        # Method 1: Direct to_pandas() conversion (simplest)
+        if hasattr(selected_df, "to_pandas"):
+            result_df = selected_df.to_pandas()
+
+            # Handle empty DataFrames
+            if len(result_df) == 0:
+                return result_df
+
+            # Ensure proper dtypes
+            for i, col in enumerate(columns):
+                if i < 2:  # Vertex indices
+                    # Check if column contains numeric data
+                    if np.issubdtype(result_df[col].dtype, np.integer):
+                        # Try to use uint32 for efficiency
+                        max_val = result_df[col].max()
+                        if not pd.isna(max_val) and max_val < np.iinfo(np.uint32).max:
+                            result_df[col] = result_df[col].astype(np.uint32)
+                    # If not numeric (e.g., strings), leave as is
+                else:
+                    # Weights/times/frequencies
+                    result_df[col] = result_df[col].astype(np.float64)
+
+            return result_df
+
+        # Method 2: Column-by-column conversion
+        result_data = {}
+
+        # Handle empty DataFrames
+        if len(selected_df) == 0:
+            return selected_df.to_pandas()
+
+        for i, col in enumerate(columns):
+            series = selected_df[col]
+
+            # Determine target dtype
+            if i < 2:  # Vertex indices
+                # Check if the series contains numeric data
+                if hasattr(series, "dtype") and series.dtype.is_integer():
+                    max_val = series.max()
+                    if max_val is not None and max_val < np.iinfo(np.uint32).max:
+                        target_dtype = np.uint32
+                    else:
+                        target_dtype = np.uint64
+                else:
+                    # Non-numeric columns, convert to pandas as is
+                    result_data[col] = series.to_pandas()
+                    continue
+            else:
+                target_dtype = np.float64
+
+            # Convert to NumPy
+            if hasattr(series, "to_numpy"):
+                np_array = series.to_numpy().astype(target_dtype)
+            else:
+                # Fallback for older Polars versions
+                np_array = series.to_list()
+                np_array = np.array(np_array, dtype=target_dtype)
+
+            # Ensure contiguous
+            result_data[col] = self._ensure_contiguous(np_array)
+
+        return pd.DataFrame(result_data)
+
+
+def standardize_graph_dataframe(  # pylint: disable=too-many-arguments,too-many-positional-arguments
+    edges,
+    tail: str = "tail",
+    head: str = "head",
+    weight: Optional[str] = None,
+    trav_time: Optional[str] = None,
+    freq: Optional[str] = None,
+) -> pd.DataFrame:
+    """
+    Convenience function to standardize any DataFrame format to NumPy-backed pandas.
+
+    Parameters
+    ----------
+    edges : DataFrame-like
+        Input edges DataFrame in any supported format.
+    tail : str
+        Column name for tail vertices.
+    head : str
+        Column name for head vertices.
+    weight : str, optional
+        Column name for edge weights.
+    trav_time : str, optional
+        Column name for travel time.
+    freq : str, optional
+        Column name for frequency.
+
+    Returns
+    -------
+    pd.DataFrame
+        NumPy-backed pandas DataFrame with only the specified columns.
+    """
+    # Determine which columns to extract
+    columns = [tail, head]
+    if weight is not None:
+        columns.append(weight)
+    if trav_time is not None:
+        columns.append(trav_time)
+    if freq is not None:
+        columns.append(freq)
+
+    # Create appropriate importer and convert
+    importer = GraphImporter.from_dataframe(edges, tail, head, weight, trav_time, freq)
+    return importer.to_numpy_edges(columns)

edsger/networks.py

@@ -31,7 +31,7 @@ class SiouxFalls:
     """
 
     @property
-    def edges(self):
+    def edges(self) -> pd.DataFrame:
         """
         A DataFrame containing the edges of the Sioux Falls network.
 
@@ -130,7 +130,9 @@ class SiouxFalls:
         return graph_edges
 
 
-def create_sf_network(dwell_time=1.0e-6, board_alight_ratio=0.5):
+def create_sf_network(
+    dwell_time: float = 1.0e-6, board_alight_ratio: float = 0.5
+) -> pd.DataFrame:
     """
     Example network from Spiess, H. and Florian, M. (1989).
     Optimal strategies: A new assignment model for transit networks.