feat: allow zero-copy conversion from NumPy arrays to igraph vector views where possible

Author: ntamas

src/codegen/internal_lib.py.in

@@ -75,7 +75,7 @@ igraph_vector_init_array.restype = handle_igraph_error_t
 igraph_vector_init_array.argtypes = [POINTER(igraph_vector_t), POINTER(igraph_real_t), igraph_integer_t]
 
 igraph_vector_view = _lib.igraph_vector_view
-igraph_vector_view.restype = handle_igraph_error_t
+igraph_vector_view.restype = POINTER(igraph_vector_t)
 igraph_vector_view.argtypes = [POINTER(igraph_vector_t), POINTER(igraph_real_t), igraph_integer_t]
 
 igraph_vector_e = _lib.igraph_vector_e
@@ -109,7 +109,7 @@ igraph_vector_int_init_array.restype = handle_igraph_error_t
 igraph_vector_int_init_array.argtypes = [POINTER(igraph_vector_int_t), POINTER(igraph_integer_t), igraph_integer_t]
 
 igraph_vector_int_view = _lib.igraph_vector_int_view
-igraph_vector_int_view.restype = handle_igraph_error_t
+igraph_vector_int_view.restype = POINTER(igraph_vector_int_t)
 igraph_vector_int_view.argtypes = [POINTER(igraph_vector_int_t), POINTER(igraph_integer_t), igraph_integer_t]
 
 igraph_vector_int_e = _lib.igraph_vector_int_e
@@ -143,7 +143,7 @@ igraph_vector_bool_init_array.restype = handle_igraph_error_t
 igraph_vector_bool_init_array.argtypes = [POINTER(igraph_vector_bool_t), POINTER(igraph_bool_t), igraph_integer_t]
 
 igraph_vector_bool_view = _lib.igraph_vector_bool_view
-igraph_vector_bool_view.restype = handle_igraph_error_t
+igraph_vector_bool_view.restype = POINTER(igraph_vector_bool_t)
 igraph_vector_bool_view.argtypes = [POINTER(igraph_vector_bool_t), POINTER(igraph_bool_t), igraph_integer_t]
 
 igraph_vector_bool_e = _lib.igraph_vector_bool_e
@@ -187,7 +187,7 @@ igraph_matrix_init_array.argtypes = [
 ]
 
 igraph_matrix_view = _lib.igraph_matrix_view
-igraph_matrix_view.restype = handle_igraph_error_t
+igraph_matrix_view.restype = POINTER(igraph_matrix_t)
 igraph_matrix_view.argtypes = [
     POINTER(igraph_matrix_t),
     POINTER(igraph_real_t),
@@ -236,7 +236,7 @@ igraph_matrix_int_init_array.argtypes = [
 ]
 
 igraph_matrix_int_view = _lib.igraph_matrix_int_view
-igraph_matrix_int_view.restype = handle_igraph_error_t
+igraph_matrix_int_view.restype = POINTER(igraph_matrix_int_t)
 igraph_matrix_int_view.argtypes = [
     POINTER(igraph_matrix_int_t),
     POINTER(igraph_integer_t),

src/igraph_ctypes/_internal/conversion.py

@@ -161,9 +161,7 @@ def edge_weights_to_igraph_vector_t_view(
     When the input is `None`, the return value will also be `None`, which is
     interpreted by the C core of igraph as all edges having equal weight.
     """
-    return (
-        edge_weights_to_igraph_vector_t(weights, graph) if weights is not None else None
-    )
+    return iterable_to_igraph_vector_t_view(weights) if weights is not None else None
 
 
 def iterable_edge_indices_to_igraph_vector_int_t(
@@ -173,7 +171,7 @@ def iterable_edge_indices_to_igraph_vector_int_t(
     of edge IDs.
     """
     if isinstance(indices, np.ndarray):
-        return numpy_array_to_igraph_vector_int_t(indices)
+        return numpy_array_to_igraph_vector_int_t(indices, flatten=True)
 
     result: _VectorInt = _VectorInt.create(0)
     for index in indices:
@@ -199,16 +197,18 @@ def iterable_to_igraph_vector_bool_t_view(items: Iterable[Any]) -> _VectorBool:
     booleans based on their truth values, possibly creating a shallow view if
     the input is an appropriate NumPy array.
     """
-    # TODO(ntamas)
-    return iterable_to_igraph_vector_bool_t(items)
+    if isinstance(items, np.ndarray):
+        return numpy_array_to_igraph_vector_bool_t_view(items)
+    else:
+        return iterable_to_igraph_vector_bool_t(items)
 
 
 def iterable_to_igraph_vector_int_t(items: Iterable[int]) -> _VectorInt:
     """Converts an iterable containing Python integers to an igraph vector of
     integers.
     """
     if isinstance(items, np.ndarray):
-        return numpy_array_to_igraph_vector_int_t(items)
+        return numpy_array_to_igraph_vector_int_t(items, flatten=True)
     else:
         result = _VectorInt.create(0)
         for item in items:
@@ -221,27 +221,34 @@ def iterable_to_igraph_vector_int_t_view(items: Iterable[Any]) -> _VectorInt:
     integers, possibly creating a shallow view if the input is an appropriate
     NumPy array.
     """
-    # TODO(ntamas)
-    return iterable_to_igraph_vector_int_t(items)
+    if isinstance(items, np.ndarray):
+        return numpy_array_to_igraph_vector_int_t_view(items, flatten=True)
+    else:
+        return iterable_to_igraph_vector_int_t(items)
 
 
 def iterable_to_igraph_vector_t(items: Iterable[float]) -> _Vector:
     """Converts an iterable containing Python integers or floats to an igraph
     vector of floats.
     """
-    result: _Vector = _Vector.create(0)
-    for item in items:
-        igraph_vector_push_back(result, item)
-    return result
+    if isinstance(items, np.ndarray):
+        return numpy_array_to_igraph_vector_t(items)
+    else:
+        result: _Vector = _Vector.create(0)
+        for item in items:
+            igraph_vector_push_back(result, item)
+        return result
 
 
 def iterable_to_igraph_vector_t_view(items: Iterable[float]) -> _Vector:
     """Converts an iterable containing Python integers or floats to an igraph
     vector of floats, possibly creating a shallow view if the input is an
     appropriate NumPy array.
     """
-    # TODO(ntamas)
-    return iterable_to_igraph_vector_t(items)
+    if isinstance(items, np.ndarray):
+        return numpy_array_to_igraph_vector_t_view(items)
+    else:
+        return iterable_to_igraph_vector_t(items)
 
 
 def iterable_vertex_indices_to_igraph_vector_int_t(
@@ -251,7 +258,7 @@ def iterable_vertex_indices_to_igraph_vector_int_t(
     of vertex IDs.
     """
     if isinstance(indices, np.ndarray):
-        return numpy_array_to_igraph_vector_int_t(indices)
+        return numpy_array_to_igraph_vector_int_t(indices, flatten=True)
 
     result: _VectorInt = _VectorInt.create(0)
     for index in indices:
@@ -322,15 +329,21 @@ def _ensure_matrix(items: Sequence[Sequence[Any]]) -> None:
 
 
 def _force_into_1d_numpy_array(arr: np.ndarray, np_type, flatten: bool) -> np.ndarray:
+    """Ensures that the given NumPy array is one-dimensional and matches the
+    given NumPy type, avoiding copies during the conversion if possible.
+    """
     if len(arr.shape) != 1:
         if flatten:
-            arr = arr.reshape((-1,))
+            arr = arr.reshape(-1)
         else:
             raise TypeError("NumPy array must be one-dimensional")
     return np.ravel(arr.astype(np_type, order="C", casting="safe", copy=False))
 
 
 def _force_into_2d_numpy_array(arr: np.ndarray, np_type) -> np.ndarray:
+    """Ensures that the given NumPy array is two-dimensional and matches the
+    given NumPy type, avoiding copies during the conversion if possible.
+    """
     if len(arr.shape) != 2:
         raise TypeError("NumPy array must be two-dimensional")
     return arr.astype(np_type, order="C", casting="safe", copy=False)
@@ -365,31 +378,69 @@ def numpy_array_to_igraph_vector_bool_t(
 ) -> _VectorBool:
     """Converts a one-dimensional NumPy array to an igraph vector of booleans."""
     arr = _force_into_1d_numpy_array(arr, np_type_of_igraph_bool_t, flatten=flatten)
-    arr = np.ravel(
-        arr.astype(np_type_of_igraph_bool_t, order="C", casting="safe", copy=False)
-    )
     return _VectorBool.create_with(
         igraph_vector_bool_init_array,
         arr.ctypes.data_as(POINTER(igraph_bool_t)),
         arr.shape[0],
     )
 
 
+def numpy_array_to_igraph_vector_bool_t_view(
+    arr: np.ndarray, flatten: bool = False
+) -> _VectorBool:
+    """Provides a view into an existing one-dimensional NumPy array with an
+    igraph boolean vector view if the data type and the layout of the NumPy
+    array is suitable. If the NumPy array is not suitable, it will be copied
+    into the appropriate layout and data type first and then a view will be
+    provided into the copy.
+    """
+    arr = _force_into_1d_numpy_array(arr, np_type_of_igraph_real_t, flatten=flatten)
+
+    result = _VectorBool()
+    igraph_vector_bool_view(
+        result, arr.ctypes.data_as(POINTER(igraph_bool_t)), arr.shape[0]
+    )
+
+    # Destructor must not be called so we never mark result as initialized;
+    # this is intentional
+
+    return result
+
+
 def numpy_array_to_igraph_vector_int_t(
     arr: np.ndarray, flatten: bool = False
 ) -> _VectorInt:
     """Converts a one-dimensional NumPy array to an igraph vector of integers."""
     arr = _force_into_1d_numpy_array(arr, np_type_of_igraph_integer_t, flatten=flatten)
-    arr = np.ravel(
-        arr.astype(np_type_of_igraph_integer_t, order="C", casting="safe", copy=False)
-    )
     return _VectorInt.create_with(
         igraph_vector_int_init_array,
         arr.ctypes.data_as(POINTER(igraph_integer_t)),
         arr.shape[0],
     )
 
 
+def numpy_array_to_igraph_vector_int_t_view(
+    arr: np.ndarray, flatten: bool = False
+) -> _VectorInt:
+    """Provides a view into an existing one-dimensional NumPy array with an
+    igraph integer vector view if the data type and the layout of the NumPy
+    array is suitable. If the NumPy array is not suitable, it will be copied
+    into the appropriate layout and data type first and then a view will be
+    provided into the copy.
+    """
+    arr = _force_into_1d_numpy_array(arr, np_type_of_igraph_integer_t, flatten=flatten)
+
+    result = _VectorInt()
+    igraph_vector_int_view(
+        result, arr.ctypes.data_as(POINTER(igraph_integer_t)), arr.shape[0]
+    )
+
+    # Destructor must not be called so we never mark result as initialized;
+    # this is intentional
+
+    return result
+
+
 def numpy_array_to_igraph_vector_t(arr: np.ndarray, flatten: bool = False) -> _Vector:
     """Converts a one-dimensional NumPy array to an igraph vector of reals."""
     arr = _force_into_1d_numpy_array(arr, np_type_of_igraph_real_t, flatten=flatten)
@@ -400,6 +451,26 @@ def numpy_array_to_igraph_vector_t(arr: np.ndarray, flatten: bool = False) -> _V
     )
 
 
+def numpy_array_to_igraph_vector_t_view(
+    arr: np.ndarray, flatten: bool = False
+) -> _Vector:
+    """Provides a view into an existing one-dimensional NumPy array with an
+    igraph floating-point vector view if the data type and the layout of the NumPy
+    array is suitable. If the NumPy array is not suitable, it will be copied
+    into the appropriate layout and data type first and then a view will be
+    provided into the copy.
+    """
+    arr = _force_into_1d_numpy_array(arr, np_type_of_igraph_real_t, flatten=flatten)
+
+    result = _Vector()
+    igraph_vector_view(result, arr.ctypes.data_as(POINTER(igraph_real_t)), arr.shape[0])
+
+    # Destructor must not be called so we never mark result as initialized;
+    # this is intentional
+
+    return result
+
+
 def vertexlike_to_igraph_integer_t(vertex: VertexLike) -> igraph_integer_t:
     """Converts a vertex-like object to an igraph integer."""
     if isinstance(vertex, int) and vertex >= 0:

src/igraph_ctypes/_internal/functions.py

@@ -2366,7 +2366,23 @@ def topological_sorting(graph: _Graph, mode: NeighborMode = NeighborMode.OUT) ->
     # Construct return value
     return res
 
-# igraph_feedback_arc_set: no Python type known for type: FAS_ALGORITHM
+
+def feedback_arc_set(graph: _Graph, weights: Optional[Iterable[float]] = None, algo: FeedbackArcSetAlgorithm = FeedbackArcSetAlgorithm.APPROX_EADES) -> npt.NDArray[np_type_of_igraph_integer_t]:
+    """Type-annotated wrapper for ``igraph_feedback_arc_set``."""
+    # Prepare input arguments
+    c_graph = graph
+    c_result = _VectorInt.create(0)
+    c_weights = edge_weights_to_igraph_vector_t_view(weights, graph)
+    c_algo = c_int(algo)
+
+    # Call wrapped function
+    igraph_feedback_arc_set(c_graph, c_result, c_weights, c_algo)
+
+    # Prepare output arguments
+    result = igraph_vector_int_t_to_numpy_array(c_result)
+
+    # Construct return value
+    return result
 
 
 def is_loop(graph: _Graph, es: EdgeSelector = "all") -> npt.NDArray[np_type_of_igraph_bool_t]:

src/igraph_ctypes/_internal/lib.py

@@ -75,7 +75,7 @@ def _load_igraph_c_library():
 igraph_vector_init_array.argtypes = [POINTER(igraph_vector_t), POINTER(igraph_real_t), igraph_integer_t]
 
 igraph_vector_view = _lib.igraph_vector_view
-igraph_vector_view.restype = handle_igraph_error_t
+igraph_vector_view.restype = POINTER(igraph_vector_t)
 igraph_vector_view.argtypes = [POINTER(igraph_vector_t), POINTER(igraph_real_t), igraph_integer_t]
 
 igraph_vector_e = _lib.igraph_vector_e
@@ -109,7 +109,7 @@ def _load_igraph_c_library():
 igraph_vector_int_init_array.argtypes = [POINTER(igraph_vector_int_t), POINTER(igraph_integer_t), igraph_integer_t]
 
 igraph_vector_int_view = _lib.igraph_vector_int_view
-igraph_vector_int_view.restype = handle_igraph_error_t
+igraph_vector_int_view.restype = POINTER(igraph_vector_int_t)
 igraph_vector_int_view.argtypes = [POINTER(igraph_vector_int_t), POINTER(igraph_integer_t), igraph_integer_t]
 
 igraph_vector_int_e = _lib.igraph_vector_int_e
@@ -143,7 +143,7 @@ def _load_igraph_c_library():
 igraph_vector_bool_init_array.argtypes = [POINTER(igraph_vector_bool_t), POINTER(igraph_bool_t), igraph_integer_t]
 
 igraph_vector_bool_view = _lib.igraph_vector_bool_view
-igraph_vector_bool_view.restype = handle_igraph_error_t
+igraph_vector_bool_view.restype = POINTER(igraph_vector_bool_t)
 igraph_vector_bool_view.argtypes = [POINTER(igraph_vector_bool_t), POINTER(igraph_bool_t), igraph_integer_t]
 
 igraph_vector_bool_e = _lib.igraph_vector_bool_e
@@ -187,7 +187,7 @@ def _load_igraph_c_library():
 ]
 
 igraph_matrix_view = _lib.igraph_matrix_view
-igraph_matrix_view.restype = handle_igraph_error_t
+igraph_matrix_view.restype = POINTER(igraph_matrix_t)
 igraph_matrix_view.argtypes = [
     POINTER(igraph_matrix_t),
     POINTER(igraph_real_t),
@@ -236,7 +236,7 @@ def _load_igraph_c_library():
 ]
 
 igraph_matrix_int_view = _lib.igraph_matrix_int_view
-igraph_matrix_int_view.restype = handle_igraph_error_t
+igraph_matrix_int_view.restype = POINTER(igraph_matrix_int_t)
 igraph_matrix_int_view.argtypes = [
     POINTER(igraph_matrix_int_t),
     POINTER(igraph_integer_t),

src/igraph_ctypes/constructors.py

@@ -1,4 +1,9 @@
+from typing import Iterable
+
 from .graph import Graph
+from ._internal.functions import create
+
+__all__ = ("create_empty_graph", "create_graph_from_edge_list")
 
 
 def create_empty_graph(n: int, directed: bool = False) -> Graph:
@@ -9,3 +14,16 @@ def create_empty_graph(n: int, directed: bool = False) -> Graph:
         directed: whether the graph is directed
     """
     return Graph(n, directed)
+
+
+def create_graph_from_edge_list(
+    edges: Iterable[int], n: int = 0, directed: bool = False
+) -> Graph:
+    """Creates a graph from the given edge list.
+
+    Parameters:
+        edges: the list of edges in the graph
+        n: the number of vertices in the graph if it cannot be inferred from
+            the maximum edge ID in the edge list
+    """
+    return Graph(_wrap=create(edges, n, directed))

src/igraph_ctypes/graph.py

@@ -11,6 +11,7 @@
     edge,
     empty,
     get_eid,
+    incident,
     is_directed,
     neighbors,
     vcount,
@@ -83,6 +84,11 @@ def get_edge_id(
         """
         return get_eid(self._instance, from_, to, directed, error)
 
+    def incident(
+        self, vid: VertexLike, mode: NeighborMode = NeighborMode.ALL
+    ) -> NDArray[np_type_of_igraph_integer_t]:
+        return incident(self._instance, vid, mode)
+
     def is_directed(self) -> bool:
         """Returns whether the graph is directed."""
         return is_directed(self._instance)