spization 1.0.0__tar.gz

spization-1.0.0/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: spization
+Version: 1.0.0
+Summary: Package for Graph Series-Parallel-ization
+Author-email: Marsella8 <pietromax.marsella@gmail.com>
+License: GPL-3.0-or-later
+Project-URL: Homepage, https://github.com/Marsella8/spization
+Project-URL: Repository, https://github.com/Marsella8/spization
+Project-URL: Issues, https://github.com/Marsella8/spization/issues
+Keywords: graph,series-parallel,dag,modular-decomposition,algorithms
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: <3.14,>=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: networkx<4,>=3.3
+Requires-Dist: multimethod<2,>=1.12
+Requires-Dist: loguru<1,>=0.7.2
+Requires-Dist: icecream<3,>=2.1.3
+Requires-Dist: numpy<3,>=2.1.0
+Requires-Dist: rich<14,>=13.8.0
+Requires-Dist: multiset<4,>=3.2.0
+Requires-Dist: bidict<1,>=0.23.1
+Requires-Dist: passagemath-graphs<11,>=10.5.43
+Dynamic: license-file
+
+## SP-ization
+
+A simple Python package for Graph Series-Parallel-ization.
+
+
+<!-- ## Notes:
+
+Your SP: no sync nodes, can be dups
+- Does not have sync nodes, can only have nodes as int. If coming from a graph with dupes, the nodes are simply deduplicated (so from NodeDup to int).
+Technically, SP can only hold NODEs, but for simplicity we'll have Node.
+
+Your graph: sync nodes, cannot be dups
+- Can have sync nodes or not (and can freely switch between one another)
+- Can either have no duplicates (so all the nodes are simply int) or have duplicates (in which case they are NodeDups). You can frely switch between graph and SP.
+
+- Algorithms must take in a DAG that is made up of ints and that is TTSP, and return an SPD of only ints.
+- In general: all graph utilities should apply to SPG, all SP utilities should apply to SPD. -->
+
+## Instructions
+
+Install dependencies: `uv sync --group dev`
+
+To enter the venv: `source .venv/bin/activate`
+
+For testing: `uv run pytest`
+
+For Nix build verification: `nix build .#spization --no-link`
+
+For codecov: `uv run pytest --cov=spization --cov-report=term-missing:skip-covered`
+
+For linting: `uv run ruff check --fix` / `uv run ruff format`
+
+For type checking: `uv run ty check`
+
+To run benchmarking: `uv run benchmark`

spization-1.0.0/README.md

@@ -0,0 +1,35 @@
+## SP-ization
+
+A simple Python package for Graph Series-Parallel-ization.
+
+
+<!-- ## Notes:
+
+Your SP: no sync nodes, can be dups
+- Does not have sync nodes, can only have nodes as int. If coming from a graph with dupes, the nodes are simply deduplicated (so from NodeDup to int).
+Technically, SP can only hold NODEs, but for simplicity we'll have Node.
+
+Your graph: sync nodes, cannot be dups
+- Can have sync nodes or not (and can freely switch between one another)
+- Can either have no duplicates (so all the nodes are simply int) or have duplicates (in which case they are NodeDups). You can frely switch between graph and SP.
+
+- Algorithms must take in a DAG that is made up of ints and that is TTSP, and return an SPD of only ints.
+- In general: all graph utilities should apply to SPG, all SP utilities should apply to SPD. -->
+
+## Instructions
+
+Install dependencies: `uv sync --group dev`
+
+To enter the venv: `source .venv/bin/activate`
+
+For testing: `uv run pytest`
+
+For Nix build verification: `nix build .#spization --no-link`
+
+For codecov: `uv run pytest --cov=spization --cov-report=term-missing:skip-covered`
+
+For linting: `uv run ruff check --fix` / `uv run ruff format`
+
+For type checking: `uv run ty check`
+
+To run benchmarking: `uv run benchmark`

spization-1.0.0/pyproject.toml

@@ -0,0 +1,70 @@
+[project]
+name = "spization"
+version = "1.0.0"
+description = "Package for Graph Series-Parallel-ization"
+readme = "README.md"
+requires-python = ">=3.12,<3.14"
+license = { text = "GPL-3.0-or-later" }
+authors = [{ name = "Marsella8", email = "pietromax.marsella@gmail.com" }]
+keywords = ["graph", "series-parallel", "dag", "modular-decomposition", "algorithms"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Mathematics",
+]
+dependencies = [
+    "networkx>=3.3,<4",
+    "multimethod>=1.12,<2",
+    "loguru>=0.7.2,<1",
+    "icecream>=2.1.3,<3",
+    "numpy>=2.1.0,<3",
+    "rich>=13.8.0,<14",
+    "multiset>=3.2.0,<4",
+    "bidict>=0.23.1,<1",
+    "passagemath-graphs>=10.5.43,<11",
+]
+
+[project.urls]
+Homepage = "https://github.com/Marsella8/spization"
+Repository = "https://github.com/Marsella8/spization"
+Issues = "https://github.com/Marsella8/spization/issues"
+
+[dependency-groups]
+dev = [
+    "build>=1.2.2.post1,<2",
+    "pytest>=8.3.2,<9",
+    "pytest-xdist>=3.8.0,<4",
+    "pytest-cov>=5.0.0,<6",
+    "ruff>=0.6.3,<1",
+    "twine>=6.1.0,<7",
+    "ty>=0.0.1",
+]
+
+[project.scripts]
+benchmark = "spization.benchmarking.benchmarking:main"
+
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+license-files = ["LICENSE"]
+
+[tool.setuptools.packages.find]
+include = ["spization*"]
+namespaces = false
+
+[tool.ty.src]
+include = ["spization"]
+
+[tool.ruff]
+lint.ignore = ["F811", "F821"]
+lint.extend-select = ["I"]
+
+[tool.pytest.ini_options]
+pythonpath = ["."]
+addopts = "-n auto"

spization-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

spization-1.0.0/spization/__init__.py

@@ -0,0 +1,3 @@
+from spization import algorithms, modular_decomposition, objects, utils
+
+__all__ = ["algorithms", "objects", "utils", "modular_decomposition"]

spization-1.0.0/spization/__internals/general/__init__.py

@@ -0,0 +1,53 @@
+from functools import reduce
+from itertools import chain
+from typing import Callable, Iterable
+
+
+def get_only[T](container: Iterable[T]) -> T:
+    c = list(container)
+    if len(c) != 1:
+        raise ValueError(f"Container must only have 1 item, has {len(c)}")
+    return c[0]
+
+
+def get_any[T](container: Iterable[T]) -> T:
+    return next(iter(container))
+
+
+def must[T](value: T | None) -> T:
+    if value is None:
+        raise ValueError("Used must() on a None value.")
+    return value
+
+
+def flatmap[T, U](
+    func: Callable[[T], Iterable[U]], iterable: Iterable[T]
+) -> Iterable[U]:
+    return chain.from_iterable(map(func, iterable))
+
+
+def are_all_equal[T](iterable: Iterable[T]) -> bool:
+    iterator = iter(iterable)
+    try:
+        first = next(iterator)
+    except StopIteration:
+        return True
+    return all(first == x for x in iterator)
+
+
+def are_all_disjoint[T](iterable: Iterable[set[T] | frozenset[T]]) -> bool:
+    sets = list(iterable)
+    if not sets:
+        return True
+    union = reduce(lambda x, y: x.union(y), sets)
+    return len(union) == sum(len(s) for s in sets)
+
+
+__all__ = [
+    "get_any",
+    "get_only",
+    "must",
+    "flatmap",
+    "are_all_equal",
+    "are_all_disjoint",
+]

spization-1.0.0/spization/__internals/graph/__init__.py

@@ -0,0 +1,27 @@
+from .add_nodes_and_edges import add_edges, add_node, add_nodes
+from .longest_path_lengths_from_source import longest_path_lengths_from_source
+from .lowest_common_ancestor import lowest_common_ancestor
+from .properties import (
+    is_2_terminal_dag,
+    is_compatible_graph,
+    is_single_sourced,
+    is_transitively_closed_dag,
+)
+from .sinks import sinks
+from .sources import sources
+from .strata_sort import strata_sort
+
+__all__ = [
+    "longest_path_lengths_from_source",
+    "lowest_common_ancestor",
+    "is_2_terminal_dag",
+    "is_compatible_graph",
+    "is_single_sourced",
+    "is_transitively_closed_dag",
+    "sinks",
+    "sources",
+    "strata_sort",
+    "add_edges",
+    "add_node",
+    "add_nodes",
+]

spization-1.0.0/spization/__internals/graph/add_nodes_and_edges.py

@@ -0,0 +1,20 @@
+from typing import Iterable
+
+from networkx import DiGraph
+
+from spization.objects import DiEdge, Node
+
+
+def add_node(g: DiGraph) -> Node:
+    n = max(g.nodes(), default=-1) + 1
+    g.add_node(n)
+    return n
+
+
+def add_nodes(g: DiGraph, n: int) -> list[Node]:
+    return [add_node(g) for _ in range(n)]
+
+
+def add_edges(g: DiGraph, edges: Iterable[DiEdge]) -> None:
+    for edge in edges:
+        g.add_edge(edge[0], edge[1])

spization-1.0.0/spization/__internals/graph/longest_path_lengths_from_source.py

@@ -0,0 +1,39 @@
+import networkx as nx
+from multimethod import multimethod
+from networkx import DiGraph
+
+from spization.__internals.general import get_only
+from spization.objects import Node
+
+from .properties import is_single_sourced
+from .sources import sources
+
+
+@multimethod
+def longest_path_lengths_from_source(g: DiGraph) -> dict[Node, int]:
+    assert is_single_sourced(g)
+    dist: dict[Node, int] = dict.fromkeys(g.nodes, -1)
+    root: Node = get_only(sources(g))
+    dist[root] = 0
+    topo_order = nx.topological_sort(g)
+    for n in topo_order:
+        if n == root:
+            continue
+        dist[n] = 1 + max(dist[p] for p in g.predecessors(n))
+    return dist
+
+
+@multimethod
+def longest_path_lengths_from_source(
+    g: DiGraph, cost_map: dict[Node, int | float]
+) -> dict[Node, int | float]:
+    assert is_single_sourced(g)
+    dist: dict[Node, int | float] = dict.fromkeys(g.nodes, -1)
+    root: Node = get_only(sources(g))
+    dist[root] = cost_map[root]
+    topo_order = nx.topological_sort(g)
+    for n in topo_order:
+        if n == root:
+            continue
+        dist[n] = cost_map[n] + max(dist[p] for p in g.predecessors(n))
+    return dist

spization-1.0.0/spization/__internals/graph/lowest_common_ancestor.py

@@ -0,0 +1,17 @@
+from typing import Optional
+
+import networkx as nx
+from networkx import DiGraph
+
+from spization.__internals.general import get_any
+from spization.objects import Node
+
+
+def lowest_common_ancestor(g: DiGraph, nodes: set[Node]) -> Optional[Node]:
+    assert all(n in g.nodes() for n in nodes)
+    lca: Optional[Node] = get_any(nodes)
+    for n in nodes:
+        lca = nx.lowest_common_ancestor(g, lca, n)
+        if lca is None:
+            return lca
+    return lca

spization-1.0.0/spization/__internals/graph/properties.py

@@ -0,0 +1,34 @@
+import networkx as nx
+from networkx import DiGraph
+
+from spization.objects import Node
+
+from .sinks import sinks
+from .sources import sources
+
+
+def is_2_terminal_dag(g: DiGraph) -> bool:
+    if not nx.is_directed_acyclic_graph(g):
+        return False
+
+    return len(sources(g)) == 1 and len(sinks(g)) == 1
+
+
+def is_compatible_graph(g: DiGraph) -> bool:
+    return all(isinstance(node, Node) for node in g.nodes())
+
+
+def is_single_sourced(g: DiGraph) -> bool:
+    return len(sources(g)) == 1
+
+
+def is_transitively_closed(g: DiGraph) -> bool:
+    for node in g.nodes():
+        for descendant in nx.descendants(g, node):
+            if not g.has_edge(node, descendant):
+                return False
+    return True
+
+
+def is_transitively_closed_dag(g: DiGraph) -> bool:
+    return nx.is_directed_acyclic_graph(g) and is_transitively_closed(g)

spization-1.0.0/spization/__internals/graph/sinks.py

@@ -0,0 +1,7 @@
+from networkx import DiGraph
+
+from spization.objects import Node
+
+
+def sinks(g: DiGraph) -> set[Node]:
+    return {node for node, out_degree in g.out_degree() if out_degree == 0}

spization-1.0.0/spization/__internals/graph/sources.py

@@ -0,0 +1,7 @@
+from networkx import DiGraph
+
+from spization.objects import Node
+
+
+def sources(g: DiGraph) -> set[Node]:
+    return {node for node, in_degree in g.in_degree() if in_degree == 0}

spization-1.0.0/spization/__internals/graph/strata_sort.py

@@ -0,0 +1,10 @@
+from networkx import DiGraph
+
+from spization.objects import Node
+
+from .longest_path_lengths_from_source import longest_path_lengths_from_source
+
+
+def strata_sort(g: DiGraph) -> list[Node]:
+    depth_map: dict[Node, int] = longest_path_lengths_from_source(g)
+    return sorted(depth_map.keys(), key=lambda node: depth_map[node])

spization-1.0.0/spization/__internals/sp/__init__.py

@@ -0,0 +1,14 @@
+from .cbc_decomposition import (
+    BipartiteComponent,
+    CompleteBipartiteCompositeDecomposition,
+    cbc_decomposition,
+)
+from .inverse_line_graph import InverseLineGraphResult, inverse_line_graph
+
+__all__ = [
+    "inverse_line_graph",
+    "InverseLineGraphResult",
+    "cbc_decomposition",
+    "CompleteBipartiteCompositeDecomposition",
+    "BipartiteComponent",
+]

spization-1.0.0/spization/__internals/sp/cbc_decomposition.py

@@ -0,0 +1,93 @@
+from collections import deque
+from dataclasses import dataclass
+from typing import Optional
+
+from networkx import DiGraph
+
+from spization.__internals.general import get_only
+from spization.__internals.graph import sinks, sources
+from spization.objects import DiEdge, Node
+
+
+@dataclass(frozen=True)
+class BipartiteComponent:
+    head_nodes: frozenset[Node]
+    tail_nodes: frozenset[Node]
+
+
+CompleteBipartiteCompositeDecomposition = set[BipartiteComponent]
+
+
+def is_complete_bipartite_digraph(g: DiGraph, head: frozenset[Node]) -> bool:
+    sinks = set(g.nodes) - head
+    for source in head:
+        for sink in sinks:
+            if not g.has_edge(source, sink):
+                return False
+    return True
+
+
+def cbc_decomposition(g: DiGraph) -> Optional[CompleteBipartiteCompositeDecomposition]:
+    edges_to_process = deque(sorted(g.edges()))
+
+    already_in_a_head: set[Node] = set()
+    already_in_a_tail: set[Node] = set()
+    already_processed: set[DiEdge] = set()
+    result: CompleteBipartiteCompositeDecomposition = set()
+
+    while edges_to_process:
+        e = edges_to_process.pop()
+        if e in already_processed:
+            continue
+
+        head = frozenset(g.predecessors(e[1]))
+        tail = frozenset(g.successors(e[0]))
+
+        if head & tail:
+            return None
+
+        from_head_to_tail = {(u, v) for u in head for v in tail if g.has_edge(u, v)}
+
+        subgraph = g.subgraph(head | tail)
+
+        if not is_complete_bipartite_digraph(subgraph, head):
+            return None
+
+        for u, v in subgraph.edges():
+            if (u, v) not in from_head_to_tail:
+                return None
+
+        out_edges = {(u, v) for u in head for v in g.successors(u)}
+        if out_edges != from_head_to_tail:
+            return None
+
+        in_edges = {(u, v) for v in tail for u in g.predecessors(v)}
+        if in_edges != from_head_to_tail:
+            return None
+
+        result.add(BipartiteComponent(head, tail))
+
+        already_processed |= from_head_to_tail
+        already_in_a_head.update(head)
+        already_in_a_tail.update(tail)
+
+    assert already_in_a_head == set(g.nodes) - sinks(g)
+    assert already_in_a_tail == set(g.nodes) - sources(g)
+
+    return result
+
+
+def get_component_containing_node_in_head(
+    cbc: CompleteBipartiteCompositeDecomposition, n: Node
+) -> Optional[BipartiteComponent]:
+    found: set[BipartiteComponent] = set(filter(lambda bc: n in bc.head_nodes, cbc))
+    assert len(found) <= 1
+    return get_only(found) if found else None
+
+
+def get_component_containing_node_in_tail(
+    cbc: CompleteBipartiteCompositeDecomposition, n: Node
+) -> Optional[BipartiteComponent]:
+    found: set[BipartiteComponent] = set(filter(lambda bc: n in bc.tail_nodes, cbc))
+    assert len(found) <= 1
+    return get_only(found) if found else None

spization-1.0.0/spization/__internals/sp/inverse_line_graph.py

@@ -0,0 +1,63 @@
+from dataclasses import dataclass
+from typing import Optional
+
+from bidict import bidict
+from networkx import DiGraph, MultiDiGraph
+
+from spization.__internals.graph import add_node, sinks, sources
+from spization.__internals.sp.cbc_decomposition import (
+    BipartiteComponent,
+    cbc_decomposition,
+    get_component_containing_node_in_head,
+    get_component_containing_node_in_tail,
+)
+from spization.objects import MultiDiEdge, Node, SerialParallelDecomposition
+
+
+@dataclass
+class InverseLineGraphResult:
+    graph: MultiDiGraph
+    inverse_edge_to_line_node_map: bidict[MultiDiEdge, SerialParallelDecomposition]
+
+
+def inverse_line_graph(g: DiGraph) -> Optional[InverseLineGraphResult]:
+    cbc_decomp = cbc_decomposition(g)
+    if cbc_decomp is None:
+        return None
+
+    result_graph = MultiDiGraph()
+    alpha: Node = add_node(result_graph)
+    omega: Node = add_node(result_graph)
+
+    component_nodes = bidict(
+        {bi_comp: add_node(result_graph) for bi_comp in cbc_decomp}
+    )
+
+    def h(n: Node) -> BipartiteComponent:
+        cmp = get_component_containing_node_in_head(cbc_decomp, n)
+        assert cmp is not None
+        return cmp
+
+    def t(n: Node) -> BipartiteComponent:
+        cmp = get_component_containing_node_in_tail(cbc_decomp, n)
+        assert cmp is not None
+        return cmp
+
+    srcs = sources(g)
+    snks = sinks(g)
+
+    def src_for_node(v: Node) -> Node:
+        return alpha if v in srcs else component_nodes[t(v)]
+
+    def dst_for_node(v: Node) -> Node:
+        return omega if v in snks else component_nodes[h(v)]
+
+    inverse_edge_to_line_node: bidict[MultiDiEdge, SerialParallelDecomposition] = bidict()
+
+    for v in g.nodes:
+        src, dst = src_for_node(v), dst_for_node(v)
+        idx = result_graph.add_edge(src, dst)
+        edge: MultiDiEdge = (src, dst, idx)
+        inverse_edge_to_line_node[edge] = v
+
+    return InverseLineGraphResult(result_graph, inverse_edge_to_line_node)

spization-1.0.0/spization/algorithms/__init__.py

@@ -0,0 +1,12 @@
+from .flexible_sync import flexible_sync
+from .naive_strata_sync import naive_strata_sync
+from .pure_node_dup import pure_node_dup, tree_pure_node_dup
+from .spanish_strata_sync import spanish_strata_sync
+
+__all__ = [
+    "naive_strata_sync",
+    "pure_node_dup",
+    "tree_pure_node_dup",
+    "spanish_strata_sync",
+    "flexible_sync",
+]