feat: exposed igraph_is_bigraphical(), closes #708

Author: ntamas

CHANGELOG.md

@@ -1,5 +1,11 @@
 # igraph Python interface changelog
 
+## [master]
+
+### Added 
+
+- Added `is_bigraphical()` to test whether a pair of integer sequences can be the degree sequence of some bipartite graph.
+
 ## [0.10.7] - 2023-09-04
 
 ### Added

src/_igraph/igraphmodule.c

@@ -520,19 +520,39 @@ PyObject* igraphmodule_is_graphical_degree_sequence(PyObject *self,
 }
 
 
+static PyObject* igraphmodule_i_is_graphical_or_bigraphical(
+  PyObject *self, PyObject *args, PyObject *kwds, igraph_bool_t is_bigraphical
+);
+
 PyObject* igraphmodule_is_graphical(PyObject *self, PyObject *args, PyObject *kwds) {
-  static char* kwlist[] = { "out_deg", "in_deg", "loops", "multiple", NULL };
+  return igraphmodule_i_is_graphical_or_bigraphical(self, args, kwds, /* is_bigraphical = */ false);
+}
+
+PyObject* igraphmodule_is_bigraphical(PyObject *self, PyObject *args, PyObject *kwds) {
+  return igraphmodule_i_is_graphical_or_bigraphical(self, args, kwds, /* is_bigraphical = */ true);
+}
+
+static PyObject* igraphmodule_i_is_graphical_or_bigraphical(
+  PyObject *self, PyObject *args, PyObject *kwds, igraph_bool_t is_bigraphical
+) {
+  static char* kwlist_graphical[] = { "out_deg", "in_deg", "loops", "multiple", NULL };
+  static char* kwlist_bigraphical[] = { "degrees1", "degrees2", "loops", "multiple", NULL };
   PyObject *out_deg_o = 0, *in_deg_o = 0;
   PyObject *loops = Py_False, *multiple = Py_False;
   igraph_vector_int_t out_deg, in_deg;
   igraph_bool_t is_directed, result;
   int allowed_edge_types;
-
-  if (!PyArg_ParseTupleAndKeywords(args, kwds, "O|OOO", kwlist,
-      &out_deg_o, &in_deg_o, &loops, &multiple))
+  igraph_error_t retval;
+
+  if (!PyArg_ParseTupleAndKeywords(
+      args, kwds,
+      is_bigraphical ? "OO|OO" : "O|OOO",
+      is_bigraphical ? kwlist_bigraphical : kwlist_graphical,
+      &out_deg_o, &in_deg_o, &loops, &multiple
+  ))
     return NULL;
 
-  is_directed = (in_deg_o != 0 && in_deg_o != Py_None);
+  is_directed = (in_deg_o != 0 && in_deg_o != Py_None) || is_bigraphical;
 
   if (igraphmodule_PyObject_to_vector_int_t(out_deg_o, &out_deg))
     return NULL;
@@ -550,7 +570,11 @@ PyObject* igraphmodule_is_graphical(PyObject *self, PyObject *args, PyObject *kw
     allowed_edge_types |= IGRAPH_MULTI_SW;
   }
 
-  if (igraph_is_graphical(&out_deg, is_directed ? &in_deg : 0, allowed_edge_types, &result)) {
+  retval = is_bigraphical
+    ? igraph_is_bigraphical(&out_deg, is_directed ? &in_deg : 0, allowed_edge_types, &result)
+    : igraph_is_graphical(&out_deg, is_directed ? &in_deg : 0, allowed_edge_types, &result);
+
+  if (retval) {
     igraphmodule_handle_igraph_error();
     igraph_vector_int_destroy(&out_deg);
     if (is_directed) {
@@ -794,6 +818,20 @@ static PyMethodDef igraphmodule_methods[] =
     "@return: C{True} if there exists some graph that can realize the given degree\n"
     "  sequence, C{False} otherwise.\n"
   },
+  {"is_bigraphical", (PyCFunction)igraphmodule_is_bigraphical,
+    METH_VARARGS | METH_KEYWORDS,
+    "is_bigraphical(degrees1, degrees2, loops=False, multiple=False)\n--\n\n"
+    "Returns whether two sequences of integers can be the degree sequences of a\n"
+    "bipartite graph.\n\n"
+    "The bipartite graph may or may not have multiple and loop edges, depending\n"
+    "on the allowed edge types in the remaining arguments.\n\n"
+    "@param degrees1: the list of degrees in the first partition.\n"
+    "@param degrees2: the list of degrees in the second partition.\n"
+    "@param loops: whether loop edges are allowed.\n"
+    "@param multiple: whether multiple edges are allowed.\n"
+    "@return: C{True} if there exists some bipartite graph that can realize the\n"
+    "  given degree sequences with the given edge types, C{False} otherwise.\n"
+  },
   {"is_graphical", (PyCFunction)igraphmodule_is_graphical,
     METH_VARARGS | METH_KEYWORDS,
     "is_graphical(out_deg, in_deg=None, loops=False, multiple=False)\n--\n\n"

src/igraph/__init__.py

@@ -65,6 +65,7 @@
     arpack_options as default_arpack_options,
     community_to_membership,
     convex_hull,
+    is_bigraphical,
     is_degree_sequence,
     is_graphical,
     is_graphical_degree_sequence,
@@ -1183,6 +1184,7 @@ def write(graph, filename, *args, **kwds):
     'hsl_to_rgb',
     'hsva_to_rgba',
     'hsv_to_rgb',
+    'is_bigraphical',
     'is_degree_sequence',
     'is_graphical',
     'is_graphical_degree_sequence',