Modify docs and add minor changes

Author: jonasspinner

Cargo.toml

@@ -18,6 +18,7 @@ edition = "2021"
 license = "MIT"
 authors = ["Jonas Spinner"]
 repository = "https://github.com/jonasspinner/modular-decomposition"
+homepage = "https://github.com/jonasspinner/modular-decomposition"
 
 [workspace.dependencies]
 clap = { version = "4.4.7", features = ["derive"] }

README.md

@@ -2,18 +2,36 @@
 
 This project implements several algorithm to compute the [modular decomposition](https://en.wikipedia.org/wiki/Modular_decomposition) of a graph.
 
-+ `fracture`
-  + A $O(n + m \log n)$ algorithm based on [[HPV99]](https://doi.org/10.1142/S0129054199000125) and [[CHM02]](https://doi.org/10.46298/dmtcs.298).
-  + First sketch based on a Julia implementation [[Kar19]](https://github.com/StefanKarpinski/GraphModularDecomposition.jl), but now heavily modified.
-+ `skeleton`
-  + A $O(n + m \log n)$ algorithm based on [[MS00]](https://doi.org/10.46298/dmtcs.274).
-+ `linear (ref)`
-  + A $O(n + m)$ algorithm based on [[TCHP08]](https://doi.org/10.1007/978-3-540-70575-8_52).
-  + A wrapper for the C++ implementation of [[Miz23]](https://github.com/mogproject/modular-decomposition).
-+ `linear`
-  + A $O(n + m)$ algorithm based on [[TCHP08]](https://doi.org/10.1007/978-3-540-70575-8_52).
-  + A port of the C++ implementation of [[Miz23]](https://github.com/mogproject/modular-decomposition) to Rust.
-  + Some additional modifications.
+The project is structures as follows.
+
+**Library**
++ `crates/modular-decomposition` A package providing the `fracture` algorithm based on [[HPV99]](https://doi.org/10.1142/S0129054199000125) and [[CHM02]](https://doi.org/10.46298/dmtcs.298) as a library.
+
+**Algorithms**
++ `crates/linear-ref-sys`/`crates/linear-ref` Bindings and wrapper to reference C++ implementation [[Miz23]](https://github.com/mogproject/modular-decomposition) based on [[TCHP08]](https://doi.org/10.1007/978-3-540-70575-8_52).
++ `crates/linear` Rust port of [[Miz23]](https://github.com/mogproject/modular-decomposition) based on [[TCHP08]](https://doi.org/10.1007/978-3-540-70575-8_52).
++ `crates/skeleton` Based on [[MS00]](https://doi.org/10.46298/dmtcs.274).
++ `crates/fracture` Based on [[HPV99]](https://doi.org/10.1142/S0129054199000125) and [[CHM02]](https://doi.org/10.46298/dmtcs.298). Uses the implementation in `crates/modular-decomposition`.
+
+**Others**
++ `crates/common` Common utilities shared by the algorithm crate
++ `crates/playground` A crate to experiment with related algorithms and data structures.
++ `crates/evaluation` Evaluation of the algorithms on real-world and generated data.
+
+## Usage
+
+The crate `crates/modular-decomposition` provides an API to compute the modular decomposition.
+
+```rust
+use petgraph::graph::UnGraph;
+use modular_decomposition::{ModuleKind, modular_decomposition};
+
+let graph = UnGraph::<(), ()>::from_edges([(0, 1), (1, 2), (2, 3)]);
+let md = modular_decomposition(&graph).unwrap();
+
+assert_eq!(md.module_kind(md.root()), Some(&ModuleKind::Prime));
+```
+
 
 ## Evaluation
 
@@ -22,16 +40,7 @@ This project implements several algorithm to compute the [modular decomposition]
 This figure shows the algorithm performance for some datasets.
 The time for multiple runs is averaged for each instance and algorithm. The time for each algorithm is divided by the best time and the distribution is plotted.
 The `fracture` algorithm performs best for most instances.
-
-## As a library
-
-The crates implementing the algorithms provide a API for the modular decompostion.
-```
-pub fn modular_decomposition<N, E>(graph: &Graph<N, E, Undirected>) -> DiGraph<MDNodeKind, ()>
-{
-    prepare(graph).compute().finalize()
-}
-```
+The evaluation code can be found in `crates/evaluation`.
 
 ## References
 

crates/fracture/src/lib.rs

@@ -45,7 +45,7 @@ impl Computed {
                 ModuleKind::Prime => MDNodeKind::Prime,
                 ModuleKind::Series => MDNodeKind::Series,
                 ModuleKind::Parallel => MDNodeKind::Parallel,
-                ModuleKind::Vertex(v) => MDNodeKind::Vertex(v.index()),
+                ModuleKind::Node(v) => MDNodeKind::Vertex(v.index()),
             },
             |_, _| (),
         )

crates/modular-decomposition/Cargo.toml

@@ -1,11 +1,13 @@
 [package]
 name = "modular-decomposition"
 version.workspace = true
-authors.workspace = true
 edition.workspace = true
 license.workspace = true
+authors.workspace = true
 repository.workspace = true
+homepage.workspace = true
 readme = "README.md"
+description = "A library for computing the modular decomposition of a graph"
 categories = ["science", "algorithms"]
 keywords = ["graph", "modular", "decomposition"]
 

crates/modular-decomposition/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Jonas Spinner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

crates/modular-decomposition/README.md

@@ -1,19 +1,55 @@
 # Modular Decomposition
 
-A $O(n + m \log n)$ algorithm based on [[HPV99]](https://doi.org/10.1142/S0129054199000125) and [[CHM02]](https://doi.org/10.46298/dmtcs.298).
+This is a library to compute the [modular decomposition](https://en.wikipedia.org/wiki/Modular_decomposition) of a
+simple, undirected graph.
 
-## Evaluation
+A node set *M* is a *module* if every node has the same neighborhood outside *M*. The set of all nodes *V* and the sets
+with a single node *{u}* are
+trivial modules.
 
-![](../../evaluation.png)
+The modular decomposition algorithm in this library has a O(n + m log n) running time and is based
+on [[HPV99]](https://doi.org/10.1142/S0129054199000125) and [[CHM02]](https://doi.org/10.46298/dmtcs.298). Although
+linear time algorithms exists, they perform worse in comparison.
+
+## Examples
+
+The smallest prime graph is the path graph on 4 nodes.
+
+```rust
+use petgraph::graph::UnGraph;
+use modular_decomposition::{ModuleKind, modular_decomposition};
+
+// a path graph with 4 nodes
+let graph = UnGraph::<(), ()>::from_edges([(0, 1), (1, 2), (2, 3)]);
+let md = modular_decomposition(&graph).unwrap();
+
+assert_eq!(md.module_kind(md.root()), Some(&ModuleKind::Prime));
+```
+
+Determining whether a graph is a [cograph](https://en.wikipedia.org/wiki/Cograph).
 
-This figure shows the algorithm performance for some datasets.
-The time for multiple runs is averaged for each instance and algorithm. The time for each algorithm is divided by the best time and the distribution is plotted.
-The `fracture` algorithm performs best for most instances.
+```rust
+use petgraph::graph::UnGraph;
+use modular_decomposition::{ModuleKind, modular_decomposition};
 
-## References
+// a complete graph with 3 nodes
+let graph = UnGraph::<(), ()>::from_edges([(0, 1), (0, 2), (1, 2)]);
+let md = modular_decomposition(&graph).unwrap();
+
+// a graph is a cograph exactly if none of its modules is prime
+let is_cograph = md.module_kinds().all(|kind| *kind != ModuleKind::Prime);
+assert!(is_cograph);
+```
+
+## Generics
+
+The algorithm is implemented for structs that implement the `petgraph`
+traits `NodeCompactIndexable`, `IntoNeighbors`, and `GraphProp<EdgeType = Undirected>`.
+
+## Evaluation
+
+![](../../evaluation.png)
 
-+ [HPV99] Michel Habib, Christophe Paul, and Laurent Viennot. “Partition Refinement Techniques: An Interesting Algorithmic Tool Kit”. https://doi.org/10.1142/S0129054199000125.
-+ [CHM02] Christian Capelle, Michel Habib, and Fabien Montgolfier. “Graph Decompositions and Factorizing Permutations”. https://doi.org/10.46298/dmtcs.298
-+ [MS00] Ross M. Mcconnell and Jeremy P. Spinrad. “Ordered Vertex Partitioning”. https://doi.org/10.46298/dmtcs.274
-+ [TCHP08] Marc Tedder, Derek Corneil, Michel Habib, and Christophe Paul. “Simpler Linear-Time Modular Decomposition Via Recursive Factorizing Permutations”. https://doi.org/10.1007/978-3-540-70575-8_52.
-+ [Miz23] https://github.com/mogproject/modular-decomposition
+As part of a thesis, we evaluated four implementations of modular decomposition algorithms.
+The `fracture` algorithm performs best and is provided in this library. For more information see
+the [repository](https://github.com/jonasspinner/modular-decomposition/).

crates/modular-decomposition/examples/adj_vector_graph.rs

@@ -1,6 +1,8 @@
-use modular_decomposition::modular_decomposition;
-use petgraph::visit::{GraphBase, GraphProp, IntoNeighbors, NodeCompactIndexable, NodeCount, NodeIndexable};
-use petgraph::Undirected;
+use modular_decomposition::{modular_decomposition, ModuleKind};
+use petgraph::dot::Config::EdgeNoLabel;
+use petgraph::dot::Dot;
+use petgraph::visit::{Dfs, GraphBase, GraphProp, IntoNeighbors, NodeCompactIndexable, NodeCount, NodeIndexable};
+use petgraph::{Incoming, Undirected};
 
 struct Graph(Vec<Vec<usize>>);
 
@@ -69,5 +71,17 @@ impl NodeCompactIndexable for Graph {}
 
 fn main() {
     let graph = Graph::from_edges([(0, 1), (1, 2), (2, 3)]);
-    let _tree = modular_decomposition(&graph);
+    let tree = modular_decomposition(&graph).map(|tree| tree.into_digraph()).unwrap_or_default();
+    println!("{:?}", Dot::with_config(&tree, &[EdgeNoLabel]));
+
+    let mut factorizing_permutation = Vec::new();
+    let root = tree.externals(Incoming).next().unwrap();
+    let mut dfs = Dfs::new(&tree, root);
+    while let Some(node) = dfs.next(&tree) {
+        if let ModuleKind::Node(u) = tree[node] {
+            factorizing_permutation.push(u);
+        }
+    }
+    let factorizing_permutation: Vec<_> = factorizing_permutation.iter().map(|u| u.index()).collect();
+    println!("{:?}", factorizing_permutation);
 }

crates/modular-decomposition/src/fracture/mod.rs

@@ -1,26 +1,30 @@
 mod factorizing_permutation;
 
 use crate::fracture::factorizing_permutation::{factorizing_permutation, Permutation};
-use crate::md_tree::{MDTree, ModuleKind, NodeIndex, NullGraph};
+use crate::md_tree::{MDTree, ModuleKind, NodeIndex, NullGraphError};
 use crate::segmented_stack::SegmentedStack;
 use petgraph::graph::DiGraph;
 use petgraph::visit::{GraphProp, IntoNeighbors, NodeCompactIndexable};
 use petgraph::Undirected;
 use tracing::{info, instrument};
 
-/// Computes the modular decomposition.
+/// Computes the modular decomposition of the graph.
+///
+/// # Errors
+///
+/// Returns a `NullGraphError` if the input graph does not contain any nodes or edges.
 #[instrument(skip_all)]
-pub fn modular_decomposition<G>(graph: G) -> Result<MDTree, NullGraph>
+pub fn modular_decomposition<G>(graph: G) -> Result<MDTree, NullGraphError>
 where
     G: NodeCompactIndexable + IntoNeighbors + GraphProp<EdgeType = Undirected>,
 {
     let n = graph.node_bound();
     if n == 0 {
-        return Err(NullGraph);
+        return Err(NullGraphError);
     }
     if n == 1 {
         let mut tree = DiGraph::new();
-        tree.add_node(ModuleKind::Vertex(NodeIndex::new(0)));
+        tree.add_node(ModuleKind::Node(NodeIndex::new(0)));
         return MDTree::from_digraph(tree);
     }
 
@@ -141,7 +145,7 @@ pub(crate) fn build_parenthesizing<G>(
 
 #[instrument(skip_all)]
 pub(crate) fn remove_non_module_dummy_nodes(op: &mut [u32], cl: &mut [u32], lc: &[u32], uc: &[u32]) {
-    #[derive(Clone)]
+    #[derive(Clone, Debug)]
     struct Info {
         first_vertex: u32,
         last_vertex: u32,
@@ -216,36 +220,40 @@ pub(crate) fn remove_non_module_dummy_nodes(op: &mut [u32], cl: &mut [u32], lc:
 
 #[instrument(skip_all)]
 pub(crate) fn create_consecutive_twin_nodes(op: &mut [u32], cl: &mut [u32], lc: &[u32], uc: &[u32]) {
-    let n = op.len();
-    let mut s = Vec::with_capacity(n);
-    let mut l = 0;
-    for k in 0..n {
-        s.push((k, l));
-        l = k;
-        s.extend(std::iter::repeat((k, k)).take(op[k] as _));
-        for c in (0..cl[k] + 1).rev() {
-            let (j, i) = s.pop().unwrap();
-
-            l = i;
-            if i >= j {
-                continue;
+    let handle_inner_node = |op: &mut [u32], cl: &mut [u32], nodes: &[(u32, u32)]| -> (u32, u32) {
+        if nodes.len() == 1 {
+            return nodes[0];
+        }
+        let mut add_brackets = |start: &mut Option<u32>, end: u32| {
+            if let Some(start) = start.take() {
+                op[start as usize] += 1;
+                cl[end as usize] += 1;
             }
-            let (a, b) = (lc[j - 1] as usize, uc[j - 1] as usize);
-            if i <= a && a < b && b <= k {
-                if c > 0 {
-                    op[i] += 1;
-                    cl[k] += 1;
-                    l = k + 1;
-                }
+        };
+        let mut start = None;
+        for (&(first_vertex, end), &(_, last_vertex)) in nodes.iter().zip(nodes.iter().skip(1)) {
+            if first_vertex <= lc[end as usize] && uc[end as usize] <= last_vertex {
+                start = start.or(Some(first_vertex));
             } else {
-                if i < j - 1 {
-                    op[i] += 1;
-                    cl[j - 1] += 1;
-                }
-                l = j;
+                add_brackets(&mut start, end)
             }
         }
+        let ((first_vertex, _), (_, last_vertex)) = (nodes[0], nodes[nodes.len() - 1]);
+        add_brackets(&mut start, last_vertex);
+        (first_vertex, last_vertex)
+    };
+
+    let mut s = SegmentedStack::with_capacity(op.len());
+    for j in 0..op.len() {
+        s.extend(op[j] as _);
+        s.add((j as u32, j as u32));
+        for _ in 0..cl[j] {
+            let info = handle_inner_node(op, cl, s.pop());
+            s.add(info);
+        }
     }
+    assert!(s.is_empty());
+    debug_assert_eq!(op.iter().sum::<u32>(), cl.iter().sum());
 }
 
 #[instrument(skip_all)]
@@ -263,7 +271,7 @@ where
 
     let handle_vertex_node = |t: &mut DiGraph<ModuleKind, ()>,
                               x: NodeIndex|
-     -> (NodeIndex, petgraph::graph::NodeIndex) { (x, t.add_node(ModuleKind::Vertex(x))) };
+     -> (NodeIndex, petgraph::graph::NodeIndex) { (x, t.add_node(ModuleKind::Node(x))) };
 
     let mut marked = vec![0; n];
     let mut gen = 0;
@@ -334,6 +342,7 @@ where
         if nodes.len() == 1 {
             return nodes[0];
         }
+        assert!(nodes.len() > 1);
         let (y, kind) = determine_node_kind(t, nodes);
         let idx = t.add_node(kind);
         for (_, u) in nodes {
@@ -370,7 +379,7 @@ mod test {
         remove_non_module_dummy_nodes,
     };
     use petgraph::dot::{Config, Dot};
-    use petgraph::graph::{DiGraph, UnGraph};
+    use petgraph::graph::UnGraph;
     use petgraph::visit::NodeIndexable;
 
     fn print_parenthesis(op: &[u32], cl: &[u32], permutation: &Permutation) {