feat: expose fluid communities to python (#835)

Author: BeaMarton13

src/_igraph/graphobject.c

@@ -13743,6 +13743,38 @@ PyObject *igraphmodule_Graph_community_leiden(igraphmodule_GraphObject *self,
   return error ? NULL : Py_BuildValue("Nd", res, (double) quality);
 }
 
+ /**
+ * Fluid communities
+ */
+PyObject *igraphmodule_Graph_community_fluid_communities(igraphmodule_GraphObject *self,
+                                                        PyObject *args, PyObject *kwds) {
+    static char *kwlist[] = {"no_of_communities", NULL};
+    Py_ssize_t no_of_communities;
+    igraph_vector_int_t membership;
+    PyObject *result;
+
+    // Parse the Python integer argument
+    if (!PyArg_ParseTupleAndKeywords(args, kwds, "n", kwlist, &no_of_communities)) {
+        return NULL;
+    }
+
+    if (igraph_vector_int_init(&membership, 0)) {
+        igraphmodule_handle_igraph_error();
+        return NULL;
+    }
+
+    if (igraph_community_fluid_communities(&self->g, no_of_communities, &membership)) {
+        igraphmodule_handle_igraph_error();
+        igraph_vector_int_destroy(&membership);
+        return NULL;
+    }
+
+    result = igraphmodule_vector_int_t_to_PyList(&membership);
+    igraph_vector_int_destroy(&membership);
+
+    return result;
+}
+
 /**********************************************************************
  * Random walks                                                       *
  **********************************************************************/
@@ -18394,6 +18426,28 @@ struct PyMethodDef igraphmodule_Graph_methods[] = {
    "\n"
    "@see: modularity()\n"
   },
+  {"community_fluid_communities",
+  (PyCFunction) igraphmodule_Graph_community_fluid_communities,
+  METH_VARARGS | METH_KEYWORDS,
+   "community_fluid_communities(no_of_communities)\n--\n\n"
+   "Community detection based on fluids interacting on the graph.\n\n"
+   "The algorithm is based on the simple idea of several fluids interacting\n"
+   "in a non-homogeneous environment (the graph topology), expanding and\n"
+   "contracting based on their interaction and density. Weighted graphs are\n"
+   "not supported.\n\n"
+   "B{Reference}\n\n"
+   "  - Parés F, Gasulla DG, et. al. (2018) Fluid Communities: A Competitive,\n"
+   "    Scalable and Diverse Community Detection Algorithm. In: Complex Networks\n"
+   "    & Their Applications VI: Proceedings of Complex Networks 2017 (The Sixth\n"
+   "    International Conference on Complex Networks and Their Applications),\n"
+   "    Springer, vol 689, p 229. https://doi.org/10.1007/978-3-319-72150-7_19\n\n"
+   "@param no_of_communities: The number of communities to be found. Must be\n"
+   " greater than 0 and fewer than number of vertices in the graph.\n"
+   "@return: a list with the community membership of each vertex.\n"
+   "@note: The graph must be simple and connected. Edge directions will be\n"
+   " ignored if the graph is directed.\n"
+   "@note: Time complexity: O(|E|)\n",
+  },
   {"community_infomap",
    (PyCFunction) igraphmodule_Graph_community_infomap,
    METH_VARARGS | METH_KEYWORDS,
@@ -18402,7 +18456,7 @@ struct PyMethodDef igraphmodule_Graph_methods[] = {
    "method of Martin Rosvall and Carl T. Bergstrom.\n\n"
    "See U{https://www.mapequation.org} for a visualization of the algorithm\n"
    "or one of the references provided below.\n"
-   "B{References}\n"
+   "B{Reference}: "
    "  - M. Rosvall and C. T. Bergstrom: I{Maps of information flow reveal\n"
    "    community structure in complex networks}. PNAS 105, 1118 (2008).\n"
    "    U{https://arxiv.org/abs/0707.0609}\n"

src/igraph/__init__.py

@@ -109,6 +109,7 @@
     _community_multilevel,
     _community_optimal_modularity,
     _community_edge_betweenness,
+    _community_fluid_communities,
     _community_spinglass,
     _community_walktrap,
     _k_core,
@@ -658,6 +659,7 @@ def es(self):
     community_multilevel = _community_multilevel
     community_optimal_modularity = _community_optimal_modularity
     community_edge_betweenness = _community_edge_betweenness
+    community_fluid_communities = _community_fluid_communities
     community_spinglass = _community_spinglass
     community_walktrap = _community_walktrap
     k_core = _k_core
@@ -1100,6 +1102,7 @@ def write(graph, filename, *args, **kwds):
     _community_multilevel,
     _community_optimal_modularity,
     _community_edge_betweenness,
+    _community_fluid_communities,
     _community_spinglass,
     _community_walktrap,
     _k_core,

src/igraph/community.py

@@ -468,6 +468,47 @@ def _community_leiden(
     )
 
 
+def _community_fluid_communities(graph, no_of_communities):
+    """Community detection based on fluids interacting on the graph.
+
+    The algorithm is based on the simple idea of several fluids interacting 
+    in a non-homogeneous environment (the graph topology), expanding and 
+    contracting based on their interaction and density. Weighted graphs are 
+    not supported.
+
+    This function implements the community detection method described in:
+    Parés F, Gasulla DG, et. al. (2018) Fluid Communities: A Competitive,
+    Scalable and Diverse Community Detection Algorithm.
+
+    @param no_of_communities: The number of communities to be found. Must be
+      greater than 0 and fewer than or equal to the number of vertices in the graph.
+    @return: an appropriate L{VertexClustering} object.
+    """
+    # Validate input parameters
+    if no_of_communities <= 0:
+        raise ValueError("no_of_communities must be greater than 0")
+    
+    if no_of_communities > graph.vcount():
+        raise ValueError("no_of_communities must be fewer than or equal to the number of vertices")
+    
+    # Check if graph is weighted (not supported)
+    if graph.is_weighted():
+        raise ValueError("Weighted graphs are not supported by the fluid communities algorithm")
+    
+    # Handle directed graphs - the algorithm works on undirected graphs
+    # but can accept directed graphs (they are treated as undirected)
+    if graph.is_directed():
+        import warnings
+        warnings.warn(
+            "Directed graphs are treated as undirected in the fluid communities algorithm",
+            UserWarning,
+            stacklevel=2
+        )
+    
+    membership = GraphBase.community_fluid_communities(graph, no_of_communities)
+    return VertexClustering(graph, membership)
+  
+  
 def _modularity(self, membership, weights=None, resolution=1, directed=True):
     """Calculates the modularity score of the graph with respect to a given
     clustering.

tests/test_decomposition.py

@@ -276,6 +276,61 @@ def testEigenvector(self):
         cl = g.community_leading_eigenvector(2)
         self.assertMembershipsEqual(cl, [0, 0, 0, 0, 0, 1, 1, 1, 1, 1])
         self.assertAlmostEqual(cl.q, 0.4523, places=3)
+        
+    def testFluidCommunities(self):
+        # Test with a simple graph: two cliques connected by a single edge
+        g = Graph.Full(5) + Graph.Full(5)
+        g.add_edges([(0, 5)])
+        
+        # Test basic functionality - should find 2 communities
+        cl = g.community_fluid_communities(2)
+        self.assertEqual(len(set(cl.membership)), 2)
+        self.assertMembershipsEqual(cl, [0, 0, 0, 0, 0, 1, 1, 1, 1, 1])
+        
+        # Test with 3 cliques
+        g = Graph.Full(4) + Graph.Full(4) + Graph.Full(4)
+        g += [(0, 4), (4, 8)]  # Connect the cliques
+        cl = g.community_fluid_communities(3)
+        self.assertEqual(len(set(cl.membership)), 3)
+        self.assertMembershipsEqual(cl, [0, 0, 0, 0, 1, 1, 1, 1, 2, 2, 2, 2])
+        
+        # Test error conditions
+        # Number of communities must be positive
+        with self.assertRaises(Exception):
+            g.community_fluid_communities(0)
+        
+        # Number of communities cannot exceed number of vertices
+        with self.assertRaises(Exception):
+            g.community_fluid_communities(g.vcount() + 1)
+        
+        # Test with disconnected graph (should raise error)
+        g_disconnected = Graph.Full(3) + Graph.Full(3)  # No connecting edge
+        with self.assertRaises(Exception):
+            g_disconnected.community_fluid_communities(2)
+        
+        # Test with single vertex (edge case)
+        g_single = Graph(1)
+        cl = g_single.community_fluid_communities(1)
+        self.assertEqual(cl.membership, [0])
+        
+        # Test with small connected graph
+        g_small = Graph([(0, 1), (1, 2), (2, 0)])  # Triangle
+        cl = g_small.community_fluid_communities(1)
+        self.assertEqual(len(set(cl.membership)), 1)
+        self.assertEqual(cl.membership, [0, 0, 0])
+        
+        # Test deterministic behavior on simple structure
+        # Note: Fluid communities can be non-deterministic due to randomization,
+        # but on very simple structures it should be consistent
+        g_path = Graph([(0, 1), (1, 2), (2, 3), (3, 4), (4, 5)])
+        cl = g_path.community_fluid_communities(2)
+        self.assertEqual(len(set(cl.membership)), 2)
+        
+        # Test that it returns a VertexClustering object
+        g = Graph.Full(6)
+        cl = g.community_fluid_communities(2)
+        self.assertIsInstance(cl, VertexClustering)
+        self.assertEqual(len(cl.membership), g.vcount())
 
     def testInfomap(self):
         g = Graph.Famous("zachary")