frobenius decomposition v1

Author: statusfailed

src/lax/mod.rs

@@ -76,10 +76,12 @@ pub mod functor;
 pub mod hypergraph;
 pub mod mut_category;
 pub mod open_hypergraph;
+pub mod spider;
 
 pub use crate::category::*;
 pub use hypergraph::*;
 pub use open_hypergraph::*;
+pub use spider::*;
 
 pub mod optic;
 pub mod var;

src/lax/spider.rs

@@ -0,0 +1,146 @@
+//! Make the Frobenius structure of an open hypergraph explicit.
+
+use super::{Hyperedge, NodeId, OpenHypergraph};
+use crate::strict::vec::FiniteFunction;
+
+/// An operation from `A`, or an explicitly represented spider.
+///
+/// A spider records its number of sources and targets. Its incident nodes still
+/// carry the object labels, just like those of an ordinary operation.
+#[derive(Debug, Clone, PartialEq, Eq)]
+#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
+pub enum WithSpider<A> {
+    Operation(A),
+    Spider { sources: usize, targets: usize },
+}
+
+impl<O: Clone + PartialEq, A: Clone> OpenHypergraph<O, A> {
+    /// Replace implicit wiring with explicit spider operations.
+    ///
+    /// The result is strict (has no pending quotient), monogamous, and
+    /// acyclic. Each original operation is retained as
+    /// [`WithSpider::Operation`].
+    ///
+    /// For every original node, the construction inserts two spiders:
+    ///
+    /// - `0 -> 1 + m`, where `m` is the number of occurrences as an operation
+    ///   source or global target;
+    /// - `1 + n -> 0`, where `n` is the number of occurrences as an operation
+    ///   target or global source.
+    ///
+    /// The extra leg connects the two spiders. Every other occurrence gets a
+    /// distinct node, making every node occur exactly once as a source and
+    /// exactly once as a target (counting the global interfaces).
+    ///
+    /// Pending identifications in the lax quotient are applied first. An error
+    /// means that the quotient attempted to identify nodes with different
+    /// labels; the returned finite function is the quotient witness, as for
+    /// [`OpenHypergraph::quotient`].
+    pub fn spiderize(mut self) -> Result<OpenHypergraph<O, WithSpider<A>>, FiniteFunction> {
+        self.quotient()?;
+
+        let OpenHypergraph {
+            sources,
+            targets,
+            hypergraph,
+        } = self;
+
+        assert_eq!(
+            hypergraph.edges.len(),
+            hypergraph.adjacency.len(),
+            "malformed hypergraph: edges and adjacency lengths differ"
+        );
+
+        let mut result = OpenHypergraph::empty();
+
+        // Keeping these first and in the original order makes forgetting the
+        // spiders recover the original node ordering after quotienting.
+        let central: Vec<NodeId> = hypergraph
+            .nodes
+            .iter()
+            .cloned()
+            .map(|label| result.new_node(label))
+            .collect();
+
+        let mut splitter_targets: Vec<Vec<NodeId>> =
+            central.iter().copied().map(|node| vec![node]).collect();
+        let mut merger_sources: Vec<Vec<NodeId>> =
+            central.iter().copied().map(|node| vec![node]).collect();
+
+        for (operation, adjacency) in hypergraph.edges.into_iter().zip(hypergraph.adjacency) {
+            let operation_sources = adjacency
+                .sources
+                .into_iter()
+                .map(|node| {
+                    let occurrence = result.new_node(hypergraph.nodes[node.0].clone());
+                    splitter_targets[node.0].push(occurrence);
+                    occurrence
+                })
+                .collect();
+
+            let operation_targets = adjacency
+                .targets
+                .into_iter()
+                .map(|node| {
+                    let occurrence = result.new_node(hypergraph.nodes[node.0].clone());
+                    merger_sources[node.0].push(occurrence);
+                    occurrence
+                })
+                .collect();
+
+            result.new_edge(
+                WithSpider::Operation(operation),
+                Hyperedge {
+                    sources: operation_sources,
+                    targets: operation_targets,
+                },
+            );
+        }
+
+        result.sources = sources
+            .into_iter()
+            .map(|node| {
+                let occurrence = result.new_node(hypergraph.nodes[node.0].clone());
+                merger_sources[node.0].push(occurrence);
+                occurrence
+            })
+            .collect();
+
+        result.targets = targets
+            .into_iter()
+            .map(|node| {
+                let occurrence = result.new_node(hypergraph.nodes[node.0].clone());
+                splitter_targets[node.0].push(occurrence);
+                occurrence
+            })
+            .collect();
+
+        for (splitter, merger) in splitter_targets.into_iter().zip(merger_sources) {
+            let splitter_outputs = splitter.len();
+            result.new_edge(
+                WithSpider::Spider {
+                    sources: 0,
+                    targets: splitter_outputs,
+                },
+                Hyperedge {
+                    sources: vec![],
+                    targets: splitter,
+                },
+            );
+
+            let merger_inputs = merger.len();
+            result.new_edge(
+                WithSpider::Spider {
+                    sources: merger_inputs,
+                    targets: 0,
+                },
+                Hyperedge {
+                    sources: merger,
+                    targets: vec![],
+                },
+            );
+        }
+
+        Ok(result)
+    }
+}

tests/lax/mod.rs

@@ -2,3 +2,4 @@ pub mod eval;
 pub mod functor;
 pub mod hypergraph;
 pub mod open_hypergraph;
+pub mod spider;

tests/lax/spider.rs

@@ -0,0 +1,157 @@
+use open_hypergraphs::lax::{Hyperedge, Hypergraph, NodeId, OpenHypergraph, WithSpider};
+use proptest::proptest;
+
+use crate::theory::meaningless::{arb_open_hypergraph, Arr, Obj};
+
+fn forget_spiders<O: Clone + PartialEq, A: Clone>(
+    f: OpenHypergraph<O, WithSpider<A>>,
+) -> OpenHypergraph<O, A> {
+    let OpenHypergraph {
+        sources,
+        targets,
+        hypergraph,
+    } = f;
+
+    let mut result = OpenHypergraph {
+        sources,
+        targets,
+        hypergraph: Hypergraph {
+            nodes: hypergraph.nodes,
+            edges: vec![],
+            adjacency: vec![],
+            quotient: hypergraph.quotient,
+        },
+    };
+
+    for (operation, adjacency) in hypergraph.edges.into_iter().zip(hypergraph.adjacency) {
+        match operation {
+            WithSpider::Operation(operation) => {
+                result.hypergraph.edges.push(operation);
+                result.hypergraph.adjacency.push(adjacency);
+            }
+            WithSpider::Spider { sources, targets } => {
+                assert_eq!(sources, adjacency.sources.len());
+                assert_eq!(targets, adjacency.targets.len());
+
+                let mut incident = adjacency.sources.into_iter().chain(adjacency.targets);
+                if let Some(first) = incident.next() {
+                    for node in incident {
+                        result.unify(first, node);
+                    }
+                }
+            }
+        }
+    }
+
+    result.quotient().expect("spider legs have equal labels");
+    result
+}
+
+#[test]
+fn spiderize_makes_a_cyclic_non_monogamous_hypergraph_syntactic() {
+    let mut f = OpenHypergraph::empty();
+    let x = f.new_node(());
+    let y = f.new_node(());
+
+    f.new_edge("forward", ([x], [y]));
+    f.new_edge("backward", ([y], [x]));
+    f.sources = vec![x, x];
+    f.targets = vec![y, y];
+
+    let spiderized = f.spiderize().unwrap();
+    let strict = spiderized.clone().to_strict();
+
+    assert!(strict.is_monogamous());
+    assert!(strict.is_acyclic());
+    assert!(spiderized.hypergraph.is_strict());
+    assert_eq!(spiderized.hypergraph.edges.len(), 2 + 2 * 2);
+}
+
+#[test]
+fn spider_arities_count_all_occurrences() {
+    let mut f = OpenHypergraph::empty();
+    let node = f.new_node(());
+    f.new_edge("op", ([node, node], [node]));
+    f.sources = vec![node, node];
+    f.targets = vec![node];
+
+    let spiderized = f.spiderize().unwrap();
+
+    assert_eq!(
+        spiderized.hypergraph.edges,
+        vec![
+            WithSpider::Operation("op"),
+            WithSpider::Spider {
+                sources: 0,
+                targets: 4,
+            },
+            WithSpider::Spider {
+                sources: 4,
+                targets: 0,
+            },
+        ]
+    );
+
+    assert_eq!(spiderized.sources.len(), 2);
+    assert_ne!(spiderized.sources[0], spiderized.sources[1]);
+}
+
+#[test]
+fn spiderize_applies_pending_quotients() {
+    let mut f = OpenHypergraph::empty();
+    let x = f.new_node(());
+    let y = f.new_node(());
+    f.new_edge("loop", ([x], [y]));
+    f.unify(x, y);
+
+    let spiderized = f.spiderize().unwrap();
+
+    assert_eq!(spiderized.hypergraph.edges.len(), 1 + 2);
+    assert!(spiderized.clone().to_strict().is_acyclic());
+    assert_eq!(
+        forget_spiders(spiderized),
+        OpenHypergraph {
+            sources: vec![],
+            targets: vec![],
+            hypergraph: Hypergraph {
+                nodes: vec![()],
+                edges: vec!["loop"],
+                adjacency: vec![Hyperedge {
+                    sources: vec![NodeId(0)],
+                    targets: vec![NodeId(0)],
+                }],
+                quotient: (vec![], vec![]),
+            },
+        }
+    );
+}
+
+#[test]
+fn spiderize_rejects_inconsistent_quotients() {
+    let mut f = OpenHypergraph::<_, ()>::identity(vec!["a", "b"]);
+    f.unify(NodeId(0), NodeId(1));
+
+    assert!(f.spiderize().is_err());
+}
+
+proptest! {
+    #[test]
+    fn spiderize_is_acyclic_monogamous_and_forgetful(
+        strict_input in arb_open_hypergraph()
+    ) {
+        let input: OpenHypergraph<Obj, Arr> =
+            OpenHypergraph::from_strict(strict_input);
+        let input_node_count = input.hypergraph.nodes.len();
+        let input_operation_count = input.hypergraph.edges.len();
+        let spiderized = input.clone().spiderize().unwrap();
+        let strict_spiderized = spiderized.clone().to_strict();
+
+        assert!(strict_spiderized.is_monogamous());
+        assert!(strict_spiderized.is_acyclic());
+        assert_eq!(
+            spiderized.hypergraph.edges.len(),
+            input_operation_count + 2 * input_node_count
+        );
+        assert_eq!(forget_spiders(spiderized), input);
+    }
+}