Upload 24 files

app.py

@@ -0,0 +1,323 @@
+"""
+Hugging Face / local Gradio app for exploring Collatz structures.
+
+Row 1:
+  - Inverse tree controls
+  - Minimal subtree controls
+  - Statistics for the currently displayed graph
+
+Row 2:
+  - Image display area (Zoom & Scroll or Fit to Width)
+"""
+
+from __future__ import annotations
+import io
+import matplotlib.pyplot as plt
+
+from typing import Any
+from pathlib import Path
+import base64
+
+import gradio as gr
+
+from src.utils import (
+    build_and_render_collatz_tree,
+    build_and_render_minimal_subtree,
+    safe_int,
+)
+from src.collatz.metrics import compute_basic_graph_stats, format_stats_markdown
+
+
+# ============================================================
+# Helpers
+# ============================================================
+
+def image_file_to_html(
+    path: str,
+    mode: str = "Zoom & Scroll",
+    box_height: int = 650,
+) -> str:
+    """
+    Convert an image file into an HTML block.
+
+    Modes:
+      - "Zoom & Scroll": full resolution inside fixed-height scroll-box
+      - "Fit to Width" : scaled to column width, whole graph visible
+    """
+    img_path = Path(path)
+    if not img_path.is_file():
+        return "<p style='color:red;'>Error: image file not found.</p>"
+
+    data = img_path.read_bytes()
+    encoded = base64.b64encode(data).decode("ascii")
+
+    if mode == "Fit to Width":
+        # Show whole graph scaled to container width
+        html = f"""
+        <div style="
+            border:1px solid #ddd;
+            border-radius:6px;
+            padding:4px;
+            background-color:#fafafa;
+        ">
+          <img src="data:image/png;base64,{encoded}"
+               style="display:block; max-width:100%; height:auto; margin:0 auto;" />
+        </div>
+        """
+    else:
+        # Zoom & scroll (full resolution)
+        html = f"""
+        <div style="
+            display:flex;
+            justify-content:center;
+            width:100%;
+        ">
+            <div style="
+                height:{box_height}px;
+                overflow:auto;
+                border:1px solid #ddd;
+                border-radius:6px;
+                padding:4px;
+                background-color:#fafafa;
+                width:fit-content;
+                max-width:100%;
+            ">
+              <img src="data:image/png;base64,{encoded}"
+                   style="display:block; max-width:none; max-height:none;" />
+            </div>
+        </div>
+        """
+
+    return html
+
+def parity_histogram_html(stats: dict) -> str:
+    """
+    Create a small odd vs even histogram as an embedded PNG <img> tag.
+    """
+    num_odd = stats.get("num_odd", 0)
+    num_even = stats.get("num_even", 0)
+
+    # If no nodes, nothing to plot
+    if num_odd == 0 and num_even == 0:
+        return "<p>_No nodes to plot._</p>"
+
+    labels = ["Odd", "Even"]
+    values = [num_odd, num_even]
+
+    fig, ax = plt.subplots(figsize=(3.5, 2.5))
+    ax.bar(labels, values)
+    ax.set_ylabel("Count")
+    ax.set_title("Odd vs Even Nodes")
+    fig.tight_layout()
+
+    buf = io.BytesIO()
+    fig.savefig(buf, format="png")
+    plt.close(fig)
+    encoded = base64.b64encode(buf.getvalue()).decode("ascii")
+
+    return f'<img src="data:image/png;base64,{encoded}" style="max-width:100%; height:auto;" />'
+
+# ============================================================
+# Callbacks
+# ============================================================
+
+def inverse_tree_callback(
+    backbone_length: Any,
+    branch_length: Any,
+    max_depth: Any,
+    view_mode: str,
+):
+    """
+    Generate the inverse structural tree and return (image_html, stats_md).
+    """
+
+    b_len = safe_int(backbone_length, default=8)
+    r_len = safe_int(branch_length, default=4)
+    depth = safe_int(max_depth, default=2)
+
+    # clamp for demo
+    b_len = max(4, min(b_len, 10))
+    r_len = max(1, min(r_len, 7))
+    depth = max(0, min(depth, 4))
+
+    image_path, df_edges = build_and_render_collatz_tree(
+        backbone_length=b_len,
+        branch_length=r_len,
+        max_depth=depth,
+        return_edges=True,
+    )
+
+    html_block = image_file_to_html(image_path, view_mode, 650)
+
+    stats = compute_basic_graph_stats(df_edges)
+    stats_md = format_stats_markdown(stats)
+
+    hist_html = parity_histogram_html(stats)
+
+    return html_block, stats_md, hist_html
+
+
+def minimal_subtree_callback(
+    N: Any,
+    view_mode: str,
+):
+    """
+    Generate the minimal subtree up to N and return (image_html, stats_md).
+    """
+
+    N = safe_int(N, default=7)
+    # Cap N for demo to prevent huge graphs
+    N = max(1, min(N, 2000))
+
+    image_path, df_edges = build_and_render_minimal_subtree(
+        N,
+        return_edges=True,
+        filename=f"minimal_subtree",
+    )
+
+    html_block = image_file_to_html(image_path, view_mode, 650)
+
+    stats = compute_basic_graph_stats(df_edges)
+    stats_md = format_stats_markdown(stats)
+    hist_html = parity_histogram_html(stats)
+
+    return html_block, stats_md, hist_html
+
+
+# ============================================================
+# Build UI
+# ============================================================
+
+def build_demo() -> gr.Blocks:
+
+    with gr.Blocks(title="Collatz Explorer") as demo:
+
+        gr.Markdown(
+            """ 
+<h1 style="text-align:center; margin-bottom:20px;">
+    🔷 <span style="font-weight:700;">Collatz Structural Explorer</span> 🔷
+</h1>
+
+<div style="text-align:justify;">
+
+<div style="margin-left:20px; margin-bottom:15px;">
+The <em>Collatz Structural Explorer</em> accompanies the research article 
+<a href="https://www.tandfonline.com/doi/full/10.1080/27684830.2025.2542052" target="_blank" style="color:#1a73e8; text-decoration:none; font-weight:600;">
+Unfolding the Collatz Tree: An Indirect Structural Proof of the Collatz Conjecture
+</a>, published in the <em>Journal of Experimental Mathematics</em> (Taylor and Francis). 
+This interactive demonstration is intended to visually illustrate key structural ideas from the paper using a dynamic inverse-tree perspective.
+</div>
+
+<div style="margin-left:20px;">
+It highlights how the inverse Collatz map, structural branch rules, and the minimal subtree containing all natural numbers up to a chosen bound N collectively reconstruct the forward Collatz dynamics in an organized and interpretable way. 
+Through real-time visualization and graph statistics, readers can explore the hierarchical structure of the Collatz process and gain an intuitive understanding of the theoretical insights developed in the publication.
+</div>
+
+</div>
+<div style="height:50px;"></div>
+            """
+            )
+
+        # ============================
+        # Row 1: controls + stats
+        # ============================
+        with gr.Row():
+            # Inverse tree controls
+            with gr.Column(scale=1, min_width=260):
+                gr.Markdown("### Inverse Collatz Tree")
+
+                backbone_input = gr.Slider(
+                    4, 10, value=8, step=1,
+                    label="Backbone length (powers of 2)",
+                )
+                branch_input = gr.Slider(
+                    1, 7, value=4, step=1,
+                    label="Branch length",
+                )
+                depth_input = gr.Slider(
+                    0, 4, value=2, step=1,
+                    label="Branch recursion depth",
+                )
+
+                view_mode_inverse = gr.Radio(
+                    ["Zoom & Scroll", "Fit to Width"],
+                    value="Zoom & Scroll",
+                    label="View mode for inverse tree",
+                )
+
+                gen_inverse = gr.Button("Generate Inverse Tree")
+
+            # Minimal subtree controls
+            with gr.Column(scale=1, min_width=260):
+                gr.Markdown("### Minimal Subtree up to N")
+
+                N_input = gr.Number(
+                    value=7, precision=0,
+                    label="Upper bound N (includes all 1..N)",
+                    info="Demo max = 2000",
+                )
+
+                view_mode_minimal = gr.Radio(
+                    ["Zoom & Scroll", "Fit to Width"],
+                    value="Zoom & Scroll",
+                    label="View mode for minimal subtree",
+                )
+
+                gen_minimal = gr.Button("Generate Minimal Subtree")
+
+            # Stats panel
+            # Stats + histogram (side by side)
+            with gr.Column(scale=1):
+                gr.Markdown("### Current Graph Statistics")
+
+                with gr.Row():
+                    # Column for text statistics
+                    with gr.Column(scale=2, min_width=140):
+                        stats_output = gr.Markdown(
+                            value="_No graph generated yet._"
+                        )
+
+                    # Column for histogram (right side)
+                    with gr.Column(scale=2, min_width=140):
+                        hist_output = gr.HTML(
+                            value="",
+                            label="Odd vs Even Histogram",
+                        )
+
+        # ============================
+        # Row 2: image display area
+        # ============================
+        with gr.Row():
+            with gr.Column():
+                image_output = gr.HTML(
+                    label="Current Collatz Graph",
+                )
+                gr.Markdown(
+                    """
+                    **Display tips:**  
+                    - In **Zoom & Scroll** mode, use the scrollbars to explore large graphs.  
+                    - In **Fit to Width** mode, the graph is scaled to the available width.  
+                    - You can right-click the image to open it in a new tab or save it.
+                    """
+                )
+
+        # Wire buttons: both update the same image + stats
+        gen_inverse.click(
+            fn=inverse_tree_callback,
+            inputs=[backbone_input, branch_input, depth_input, view_mode_inverse],
+            outputs=[image_output, stats_output, hist_output],
+        )
+
+        gen_minimal.click(
+            fn=minimal_subtree_callback,
+            inputs=[N_input, view_mode_minimal],
+            outputs=[image_output, stats_output, hist_output],
+        )
+
+    return demo
+
+
+demo = build_demo()
+
+if __name__ == "__main__":
+    demo.launch()

requirements.txt

@@ -0,0 +1,17 @@
+# Core numerical & data utilities
+pandas
+numpy
+
+# Graph algorithms & rendering
+graphviz
+networkx
+
+# Visualizations
+matplotlib
+
+# HF Space interface
+gradio
+
+# System utilities (optional but requested)
+psutil
+matplotlib

src/collatz/inverse_tree.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+from typing import List, Tuple
+
+import pandas as pd
+
+
+def generate_collatz_tree(
+    backbone_length: int = 11,
+    branch_length: int = 5,
+    max_depth: int = 3,
+) -> pd.DataFrame:
+    """
+    Generate an inverse Collatz tree structure starting from 1, with controlled
+    depth and branch expansion, based on the reverse Collatz rule:
+
+        If (n - 1) % 3 == 0 and n is even, then (n - 1) / 3 is a valid preimage.
+
+    The construction uses:
+      - a "backbone" of powers of 2 starting at 1,
+      - branches that grow from specific backbone nodes and from later branch nodes,
+      - recursive expansion up to exactly `max_depth` levels.
+
+    Parameters
+    ----------
+    backbone_length : int, default=11
+        Length of the backbone (powers of 2).
+        Backbone nodes are exactly: 1, 2, 4, ..., 2^(backbone_length - 1).
+    branch_length : int, default=5
+        Length of each branch created from valid reverse steps.
+        Branch nodes are formed by repeated doubling from the branch root.
+        Branches always have exactly `branch_length` nodes.
+    max_depth : int, default=3
+        Number of recursive branch-expansion levels.
+
+    Returns
+    -------
+    pd.DataFrame
+        DataFrame with two columns:
+            - "Source": child node (preimage under the Collatz map),
+            - "Target": parent node (image under the Collatz map).
+
+        These edges define a directed tree (or forest) rooted at 1.
+    """
+
+    if backbone_length < 2:
+        raise ValueError("backbone_length must be at least 2.")
+
+    if branch_length < 1:
+        raise ValueError("branch_length must be at least 1.")
+
+    if max_depth < 0:
+        raise ValueError("max_depth must be non-negative.")
+
+    # Backbone nodes: 1, 2, 4, ..., 2^(backbone_length - 1)
+    branches: List[List[int]] = [[2 ** i for i in range(backbone_length)]] 
+
+    # Backbone edges: 2 -> 1, 4 -> 2, 8 -> 4, ...
+    edges: List[Tuple[int, int]] = [(2 ** i, 2 ** (i - 1)) for i in range(1, backbone_length)] + [(1,4)]
+
+    # Backbone nodes that will create branches: 2^4, 2^6, 2^8, ...
+    branch_creating_numbers: List[int] = [
+        2 ** i for i in range(4, backbone_length, 2)
+    ]
+
+    # Recursive branch expansion with EXACT branch_length and max_depth
+    for _ in range(max_depth):
+        next_level_branch_creators: List[int] = []
+
+        for branch_num in branch_creating_numbers:
+            # Reverse Collatz: (branch_num - 1) / 3
+            parent = (branch_num - 1) // 3
+            edges.append((parent, branch_num))
+
+            # Create a branch of EXACT length = branch_length via repeated doubling
+            new_branch = [parent * (2 ** i) for i in range(branch_length)]
+            branches.append(new_branch)
+
+            # Link within the branch (2a -> a, 4a -> 2a, ...)
+            edges.extend(
+                (new_branch[i + 1], new_branch[i])
+                for i in range(len(new_branch) - 1)
+            )
+
+            # Candidates for further branching on next level
+            next_level_branch_creators.extend(
+                n for n in new_branch[1:] if (n - 1) % 3 == 0
+            )
+
+        branch_creating_numbers = next_level_branch_creators
+
+    df_edges = pd.DataFrame(edges, columns=["Source", "Target"]).drop_duplicates()
+
+    return df_edges

src/collatz/metrics.py

@@ -0,0 +1,101 @@
+"""
+Metrics and basic statistics for Collatz graphs.
+"""
+
+from __future__ import annotations
+
+from typing import Dict, Any, Iterable
+
+import pandas as pd
+
+
+def _to_int_nodes(nodes: Iterable[Any]) -> list[int]:
+    """
+    Safely convert an iterable of node labels to a list of integers.
+    Non-convertible labels are skipped.
+    """
+    int_nodes: list[int] = []
+    for n in nodes:
+        try:
+            int_nodes.append(int(n))
+        except Exception:
+            continue
+    return int_nodes
+
+
+def compute_basic_graph_stats(df_edges: pd.DataFrame) -> Dict[str, Any]:
+    """
+    Compute basic statistics for a Collatz graph represented
+    as a DataFrame of edges with columns ["Source", "Target"].
+
+    Returns a dictionary with:
+        - num_nodes: total number of distinct nodes
+        - num_edges: total number of edges
+        - num_odd:   number of odd-valued nodes
+        - num_even:  number of even-valued nodes
+        - min_node:  minimum node value (if any)
+        - max_node:  maximum node value (if any)
+        - num_cycles: number of cycles (here always 1: the trivial 1–2–4–1 cycle)
+    """
+    if not {"Source", "Target"}.issubset(df_edges.columns):
+        raise ValueError("df_edges must contain 'Source' and 'Target' columns.")
+
+    raw_nodes = set(df_edges["Source"]).union(set(df_edges["Target"]))
+    nodes = _to_int_nodes(raw_nodes)
+
+    num_nodes = len(nodes)
+    num_edges = len(df_edges)
+
+    num_odd = sum(1 for n in nodes if n % 2 == 1)
+    num_even = sum(1 for n in nodes if n % 2 == 0)
+
+    min_node = min(nodes) if nodes else None
+    max_node = max(nodes) if nodes else None
+
+    # By construction, your graphs contain only the trivial 1–2–4–1 cycle.
+    num_cycles = 1 if num_nodes > 0 else 0
+
+    return {
+        "num_nodes": num_nodes,
+        "num_edges": num_edges,
+        "num_odd": num_odd,
+        "num_even": num_even,
+        "min_node": min_node,
+        "max_node": max_node,
+        "num_cycles": num_cycles,
+    }
+
+
+def format_stats_markdown(stats: Dict[str, Any]) -> str:
+    """
+    Format the statistics dictionary returned by compute_basic_graph_stats
+    into a human-readable Markdown string for display in the UI.
+    """
+    if not stats:
+        return "_No statistics available._"
+
+    num_nodes = stats.get("num_nodes", 0)
+    num_edges = stats.get("num_edges", 0)
+    num_odd = stats.get("num_odd", 0)
+    num_even = stats.get("num_even", 0)
+    min_node = stats.get("min_node", None)
+    max_node = stats.get("max_node", None)
+    num_cycles = stats.get("num_cycles", 0)
+
+    lines = [
+        "### Graph Statistics",
+        "",
+        f"- **Nodes:** {num_nodes}",
+        f"- **Edges:** {num_edges}",
+        f"- **Odd nodes:** {num_odd}",
+        f"- **Even nodes:** {num_even}",
+    ]
+
+    if min_node is not None and max_node is not None:
+        lines.append(f"- **Node value range:** {min_node} to {max_node}")
+
+    # Trivial cycle information
+    if num_cycles:
+        lines.append(f"- **Cycles:** {num_cycles} (trivial cycle 1 → 2 → 4 → 1)")
+
+    return "\n".join(lines)

src/collatz/minimal_subtree.py

@@ -0,0 +1,253 @@
+"""
+Minimal Collatz subtree construction up to N, using the structural
+branch algorithm from the paper.
+
+This file implements:
+
+  - Algorithm 5: GenerateCollatzBranches
+  - Algorithm 6: BuildCollatzSubtreeEdges
+
+The combined effect is to construct the minimal Collatz subtree
+(containing all natural numbers 1..N, plus necessary ancestors)
+as a directed graph with edges (child -> parent) following the
+forward Collatz map:
+
+    T(n) = n/2       if n is even
+           3n + 1    if n is odd
+
+Edges are of the form (n, T(n)), including the structural edge (1, 4).
+"""
+
+from __future__ import annotations
+
+from typing import Dict, List, Tuple
+
+import pandas as pd
+
+
+# ============================================================
+# Algorithm 5: GenerateCollatzBranches
+# ============================================================
+
+def generate_collatz_branches(N: int) -> Dict[int, List[int]]:
+    """
+    Implement Algorithm 5: GenerateCollatzBranches.
+
+    Parameters
+    ----------
+    N : int
+        Natural number N (upper bound for starting odd numbers).
+
+    Returns
+    -------
+    Dict[int, List[int]]
+        Dictionary `Tree` mapping each odd root y to an increasing list
+        of values of the form y * 2^m. Initially, each odd x ≤ N is mapped
+        to its doubling sequence up to N, then extended as needed when
+        exploring Collatz branches from all odd x in [3, N].
+
+    Notes
+    -----
+    Structural summary:
+
+      1) For each odd x ≤ N, create the base branch:
+            Tree[x] = [x, 2x, 4x, ..., 2^k x] (all ≤ N).
+
+      2) For each odd x from 3 to N, repeatedly perform:
+            b = 3x + 1
+            m = b & (-b)     # largest power of 2 dividing b
+            y = b // m       # odd part of b
+
+         and extend the branch for y so that it contains b (and any
+         intermediate doublings) if needed. Then set x <- y and repeat
+         until x = 1 or we break due to an already-covered b.
+    """
+
+    if N < 1:
+        raise ValueError("N must be a positive integer.")
+
+    Tree: Dict[int, List[int]] = {}
+
+    # ------------------------------------------------------------
+    # Lines 2–7: For all odd numbers x ≤ N, initialize base branches
+    # ------------------------------------------------------------
+    for x in range(1, N + 1, 2):  # odd x: 1, 3, 5, ...
+        seq: List[int] = []
+        power = 1  # corresponds to 2^0, 2^1, 2^2, ...
+        while x * power <= N:
+            seq.append(x * power)
+            power *= 2
+        Tree[x] = seq
+
+    # ------------------------------------------------------------
+    # Lines 8–33: Extend branches using the 3x+1 structure
+    # ------------------------------------------------------------
+    for start_x in range(3, N + 1, 2):  # x from 3 to N, odd
+        x = start_x
+
+        # while x ≠ 1 do
+        while x != 1:
+            # b ← 3x + 1
+            b = 3 * x + 1
+
+            # m ← b ∧ (−b)  (least significant 1 bit, largest power of 2 dividing b)
+            m = b & -b
+
+            # y ← b / m  (odd part)
+            y = b // m
+
+            # if y ∈ Tree then
+            if y in Tree:
+                # if b ∉ Tree[y] then
+                if b not in Tree[y]:
+                    # power ← 2^{len(Tree[y])}
+                    power = 1 << len(Tree[y])
+
+                    # while y · power ≤ b do
+                    while y * power <= b:
+                        # Append y · power to Tree[y]
+                        Tree[y].append(y * power)
+                        # power ← power · 2
+                        power *= 2
+                else:
+                    # else break
+                    break
+            else:
+                # else:
+                #     power ← 1, seq ← []
+                power = 1
+                seq: List[int] = []
+
+                #     while y · power ≤ b do
+                while y * power <= b:
+                    #         Append y · power to seq
+                    seq.append(y * power)
+                    #         power ← power · 2
+                    power *= 2
+
+                #     Tree[y] ← seq
+                Tree[y] = seq
+
+            # x ← y
+            x = y
+
+    # Line 34: return Tree
+    return Tree
+
+
+# ============================================================
+# Algorithm 6: BuildCollatzSubtreeEdges
+# ============================================================
+
+def build_collatz_subtree_edges(N: int, Tree: Dict[int, List[int]]) -> pd.DataFrame:
+    """
+    Implement Algorithm 6: BuildCollatzSubtreeEdges.
+
+    Parameters
+    ----------
+    N : int
+        Upper bound N (not explicitly used inside, but kept for interface
+        consistency with the paper).
+    Tree : Dict[int, List[int]]
+        Dictionary produced by generate_collatz_branches(N).
+
+    Returns
+    -------
+    pd.DataFrame
+        DataFrame with columns ["Source", "Target"], encoding directed
+        edges (child -> parent) of a connected minimal Collatz subtree
+        containing all integers up to N.
+
+    The pseudocode is followed line by line:
+
+      1) For each branch list S in Tree, add edges S[i] -> S[i-1].
+      2) For each odd root x > 1, compute:
+            b = 3x + 1
+            m = b & (-b)
+            y = b / m
+         find the index t of b in Tree[y], and add edge:
+            Tree[x][0] -> Tree[y][t]
+         which corresponds structurally to x -> 3x + 1.
+      3) Finally, add the structural edge (1, 4).
+    """
+
+    edges: List[Tuple[int, int]] = []
+
+    # ------------------------------------------------------------
+    # Lines 2–6: For all branches (r, S) in Tree
+    # ------------------------------------------------------------
+    for _, S in Tree.items():
+        # S = [r, 2r, 4r, ...]; add edges S[i] -> S[i-1] for i = 1..|S|-1
+        for i in range(1, len(S)):
+            child = S[i]
+            parent = S[i - 1]
+            edges.append((child, parent))
+
+    # ------------------------------------------------------------
+    # Lines 7–13: Link branches via the 3x+1 structure
+    # ------------------------------------------------------------
+    for x in sorted(Tree.keys()):
+        if x > 1:  # only odd roots greater than 1
+            # b = 3x + 1
+            b = 3 * x + 1
+
+            # m = b ∧ (-b)
+            m = b & -b
+
+            # y = b / m
+            y = b // m
+
+            # Let i ← index of b in Tree[y]
+            if y not in Tree:
+                # If Tree[y] does not exist, structure is inconsistent; skip.
+                continue
+
+            try:
+                t = Tree[y].index(b)
+            except ValueError:
+                # If b is not present in Tree[y], skip this link.
+                continue
+
+            # Add edge (Tree[x][0], Tree[y][i]) to edges
+            root_x = Tree[x][0]       # odd root x
+            match_y = Tree[y][t]      # this is b itself
+            edges.append((root_x, match_y))
+
+    # ------------------------------------------------------------
+    # Line 14: Add edge (1, 4)
+    # ------------------------------------------------------------
+    edges.append((1, 4))
+
+    # ------------------------------------------------------------
+    # Line 15: return edges as DataFrame
+    # ------------------------------------------------------------
+    df = pd.DataFrame(edges, columns=["Source", "Target"]).drop_duplicates()
+    return df
+
+
+# ============================================================
+# Convenience wrapper: minimal subtree edges up to N
+# ============================================================
+
+def generate_minimal_collatz_subtree_edges(N: int) -> pd.DataFrame:
+    """
+    High-level helper that runs Algorithm 5 and Algorithm 6:
+
+        Tree  = GenerateCollatzBranches(N)
+        edges = BuildCollatzSubtreeEdges(N, Tree)
+
+    and returns the resulting edge DataFrame.
+
+    Parameters
+    ----------
+    N : int
+        Upper bound on the natural numbers to be included (1..N).
+
+    Returns
+    -------
+    pd.DataFrame
+        Edge list with columns ["Source", "Target"].
+    """
+    Tree = generate_collatz_branches(N)
+    df_edges = build_collatz_subtree_edges(N, Tree)
+    return df_edges

src/utils.py

@@ -0,0 +1,121 @@
+"""
+High-level utilities for Collatz operations.
+
+This module provides glue functions used by the web interface (app.py),
+combining steps such as:
+
+  - generating an inverse Collatz tree,
+  - generating the minimal subtree up to N,
+  - computing basic statistics,
+  - rendering graphs to Graphviz PNG images.
+"""
+
+from __future__ import annotations
+
+from typing import Optional, Tuple
+from pathlib import Path
+
+import pandas as pd
+
+from src.collatz.inverse_tree import generate_collatz_tree
+from src.collatz.minimal_subtree import generate_minimal_collatz_subtree_edges
+from src.visual.render import render_collatz_tree_graphviz
+from src.collatz.metrics import compute_basic_graph_stats
+
+
+def build_and_render_collatz_tree(
+    backbone_length: int,
+    branch_length: int,
+    max_depth: int,
+    *,
+    filename: str = "collatz_tree",
+    output_dir: Optional[str] = "outputs",
+    return_edges: bool = False,
+) -> Tuple[str, Optional[pd.DataFrame]]:
+    """
+    Generate an inverse Collatz tree, render it as a PNG image, and optionally
+    return the underlying edge DataFrame.
+    """
+
+    output_path = Path(output_dir)
+    output_path.mkdir(parents=True, exist_ok=True)
+
+    df_edges: pd.DataFrame = generate_collatz_tree(
+        backbone_length=backbone_length,
+        branch_length=branch_length,
+        max_depth=max_depth,
+    )
+
+    image_path = render_collatz_tree_graphviz(
+        df_edges=df_edges,
+        filename=filename,
+        directory=output_path,
+        image_format="png",
+    )
+
+    if return_edges:
+        return image_path, df_edges
+
+    return image_path, None
+
+
+def build_and_render_minimal_subtree(
+    N: int,
+    *,
+    filename: str = "collatz_minimal_subtree",
+    output_dir: Optional[str] = "outputs",
+    return_edges: bool = False,
+) -> Tuple[str, Optional[pd.DataFrame]]:
+    """
+    Generate the minimal Collatz subtree containing all integers 1..N,
+    render it as a PNG image, and optionally return the underlying
+    edge DataFrame.
+
+    This uses the structural branch construction (Algorithms 5 and 6)
+    implemented in `generate_minimal_collatz_subtree_edges`.
+    """
+
+    output_path = Path(output_dir)
+    output_path.mkdir(parents=True, exist_ok=True)
+
+    df_edges: pd.DataFrame = generate_minimal_collatz_subtree_edges(N)
+
+    image_path = render_collatz_tree_graphviz(
+        df_edges=df_edges,
+        filename=filename,
+        directory=output_path,
+        image_format="png",
+    )
+
+    if return_edges:
+        return image_path, df_edges
+
+    return image_path, None
+
+
+def compute_collatz_tree_stats(
+    backbone_length: int,
+    branch_length: int,
+    max_depth: int,
+) -> dict:
+    """
+    Convenience helper: generate the inverse Collatz tree and return
+    basic graph stats (number of nodes, edges, parity counts, etc.).
+    """
+    df_edges = generate_collatz_tree(
+        backbone_length=backbone_length,
+        branch_length=branch_length,
+        max_depth=max_depth,
+    )
+    return compute_basic_graph_stats(df_edges)
+
+
+def safe_int(x, default: int = 1) -> int:
+    """
+    Convert a value to int safely.
+    This protects the Gradio app from crashing when users type invalid input.
+    """
+    try:
+        return int(x)
+    except Exception:
+        return default

src/visual/render.py

@@ -0,0 +1,210 @@
+"""
+Graph rendering utilities for Collatz trees using Graphviz.
+
+Main entry point:
+
+    render_collatz_tree_graphviz(df_edges, ...)
+
+It takes a DataFrame of edges with columns ["Source", "Target"]
+and renders a PNG image using Graphviz. The function returns the
+absolute path to the generated image file, which is convenient
+for Gradio's image components.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional, Union
+
+import pandas as pd
+from graphviz import Digraph
+
+
+PathLike = Union[str, Path]
+
+
+def render_collatz_tree_graphviz(
+    df_edges: pd.DataFrame,
+    filename: str = "collatz_tree",
+    directory: Optional[PathLike] = None,
+    *,
+    font_size: int = 12,
+    node_size: float = 0.05,
+    arrow_size: float = 0.5,
+    nodesep: float = 0.2,
+    ranksep: float = 0.15,
+    dpi: int = 100,
+    image_format: str = "png",
+) -> str:
+    """
+    Render a Collatz inverse tree from a DataFrame of directed edges using Graphviz,
+    and save it as a single image file.
+
+    Parameters
+    ----------
+    df_edges : pd.DataFrame
+        DataFrame with at least two columns: "Source" and "Target".
+        Each row defines a directed edge: Source -> Target.
+    filename : str, default="collatz_tree"
+        Base file name (without extension) for the generated image.
+    directory : str or Path, optional
+        Directory where the image will be written. If None, uses the current
+        working directory.
+    font_size : int, default=11
+        Fixed font size used for node labels. This stays constant.
+    node_size : float, default=0.40
+        Minimum diameter of node circles in inches. Nodes will grow
+        automatically if labels are larger.
+    arrow_size : float, default=0.5
+        Arrowhead size.
+    nodesep : float, default=0.2
+        Minimum space between nodes on the same rank/level.
+    ranksep : float, default=0.15
+        Minimum space between different ranks/levels in the tree.
+    dpi : int, default=200
+        Render resolution in dots-per-inch.
+    image_format : str, default="png"
+        Output image format supported by Graphviz (e.g. "png", "svg").
+
+    Returns
+    -------
+    str
+        Absolute filesystem path to the generated image file.
+
+    Notes
+    -----
+    - Layout direction is Bottom-to-Top ("BT"), so the root (1) appears near
+      the bottom and branches extend upwards.
+    - Font size is fixed; node circles automatically expand when labels
+      require more space, because fixedsize="false".
+    """
+
+    required_columns = {"Source", "Target"}
+    if not required_columns.issubset(df_edges.columns):
+        missing = required_columns.difference(df_edges.columns)
+        raise ValueError(
+            f"df_edges must contain columns {required_columns}, missing: {missing}"
+        )
+
+    # Output directory
+    if directory is None:
+        directory_path = Path(".").resolve()
+    else:
+        directory_path = Path(directory).resolve()
+
+    directory_path.mkdir(parents=True, exist_ok=True)
+
+    dot = Digraph(
+        comment="Collatz Inverse Tree",
+        format=image_format,
+    )
+
+    # Collect labels (just to ensure clean string formatting)
+    raw_nodes = set(df_edges["Source"]).union(set(df_edges["Target"]))
+    labels = []
+    for node in raw_nodes:
+        if isinstance(node, (int, float)) and int(node) == node:
+            label = str(int(node))
+        else:
+            label = str(node)
+        labels.append(label)
+
+    # Global graph layout: Bottom-to-Top tree
+    dot.attr(
+        rankdir="BT",
+        dpi=str(dpi),
+        nodesep=str(nodesep),
+        ranksep=str(ranksep),
+    )
+
+    # Node style:
+    # - fontsize is fixed (for consistent readability),
+    # - width/height is the *minimum* size,
+    # - fixedsize="false" lets Graphviz enlarge nodes as needed to fit labels.
+    dot.attr(
+        "node",
+        shape="circle",
+        fontsize=str(font_size),
+        width=str(node_size),
+        height=str(node_size),
+        fixedsize="false",
+    )
+
+    # Edge style
+    dot.attr("edge", arrowsize=str(arrow_size))
+    dot.attr(splines="true")
+
+    # Add nodes with parity-based coloring and special styling for 1, 2, 4
+    for label in labels:
+        attrs = {}
+
+        # Try to interpret the label as an integer to check parity
+        try:
+            n = int(label)
+            is_int = True
+        except Exception:
+            n = None
+            is_int = False
+
+        if is_int:
+            # Base colors by parity
+            if n % 2 == 0:
+                # Even nodes: light blue
+                attrs.update(style="filled", fillcolor="#ddeeff")
+            else:
+                # Odd nodes: light orange
+                attrs.update(style="filled", fillcolor="#ffe5cc")
+
+            # Special highlight for the trivial cycle 1 → 2 → 4 → 1
+            if n == 1:
+                attrs.update(
+                    style="filled,bold",
+                    fillcolor="#fff2cc",  # brighter yellow
+                    penwidth="2",
+                )
+            elif n in (2, 4):
+                attrs.update(
+                    style="filled",
+                    fillcolor="#d0e3ff",  # slightly stronger blue
+                )
+        else:
+            # Non-integer labels, if any, keep default styling
+            pass
+
+        dot.node(label, **attrs)
+
+    # Add edges
+    for source, target in df_edges[["Source", "Target"]].itertuples(index=False):
+        # Normalize labels to nice integer strings when possible
+        if isinstance(source, (int, float)) and int(source) == source:
+            src_label = str(int(source))
+        else:
+            src_label = str(source)
+
+        if isinstance(target, (int, float)) and int(target) == target:
+            tgt_label = str(int(target))
+        else:
+            tgt_label = str(target)
+
+        # Special case: cycle-closing edge 1 -> 4
+        if src_label == "1" and tgt_label == "4":
+            dot.edge(
+                src_label,
+                tgt_label,
+                constraint="false",   # do not affect layout / ranks
+                color="gray40",
+                penwidth="1.6",
+                style="curved",       # request a curved spline
+                arrowsize="0.8",
+            )
+        else:
+            dot.edge(src_label, tgt_label)
+
+    # Render to file. Graphviz's render() returns the path including extension.
+    output_path = dot.render(
+        filename=filename,
+        directory=str(directory_path),
+        cleanup=True,
+    )
+
+    return str(Path(output_path).resolve())