recfold 1.0.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
recfold/__init__.py ADDED
File without changes
recfold/analyzer.py ADDED
@@ -0,0 +1,160 @@
1
+ """Pure-Python tree-to-DAG folding and call statistics for recfold."""
2
+
3
+ from typing import Any, Dict, List, Optional, Tuple
4
+
5
+ from recfold.models import CallNode, DagEdge, DagNode, TraceAnalysis, TraceSession
6
+ from recfold.snapshot import safe_repr
7
+
8
+ # Used when building fold keys: long values must not be cut, or two different
9
+ # calls could look the same and be merged by mistake.
10
+ _FULL_REPR = 10**9
11
+
12
+
13
+ def args_signature(args: Tuple[Any, ...], kwargs: Dict[str, Any], max_len: int = 80) -> str:
14
+ """Return a short text label for a call's arguments, e.g. "(3,)" or "(1, k=2)".
15
+
16
+ Positional values come first, then keyword values sorted by name. A single
17
+ positional argument keeps the trailing comma, like Python's tuple repr.
18
+ Each value is shortened with safe_repr(max_len).
19
+ """
20
+ parts = [safe_repr(a, max_len) for a in args]
21
+ parts += [f"{name}={safe_repr(kwargs[name], max_len)}" for name in sorted(kwargs)]
22
+ if len(args) == 1 and not kwargs:
23
+ return f"({parts[0]},)"
24
+ return "(" + ", ".join(parts) + ")"
25
+
26
+ def compute_subtree_keys(nodes: Dict[str, CallNode], root_id: Optional[str]) -> Dict[str, int]:
27
+ """Return a number for every node reachable from root_id; equal numbers mean equal subtrees.
28
+
29
+ Two calls share a key only if they have the same function name, arguments,
30
+ result, error, and children in the same order with equal keys. So a
31
+ memoizable call such as fib(2) gets one key wherever it appears, while an
32
+ impure call that returned something different does not. Children ids that
33
+ are missing from nodes are skipped. Works without recursion, so very deep
34
+ trees are fine.
35
+ """
36
+ if root_id is None or root_id not in nodes:
37
+ return {}
38
+ table: Dict[Tuple[Any, ...], int] = {}
39
+ keys: Dict[str, int] = {}
40
+ stack = [(root_id, False)]
41
+ while stack:
42
+ node_id, children_done = stack.pop()
43
+ node = nodes[node_id]
44
+ kids = [c for c in node.children_ids if c in nodes]
45
+ if not children_done:
46
+ stack.append((node_id, True))
47
+ stack.extend((c, False) for c in reversed(kids) if c not in keys)
48
+ continue
49
+ if node_id in keys:
50
+ continue
51
+ content = (
52
+ node.func_name,
53
+ args_signature(node.args, node.kwargs, max_len=_FULL_REPR),
54
+ safe_repr(node.result, _FULL_REPR),
55
+ node.exit_snapshot.get("error"),
56
+ tuple(keys[c] for c in kids),
57
+ )
58
+ keys[node_id] = table.setdefault(content, len(table))
59
+ return keys
60
+
61
+ def fold_tree(
62
+ nodes: Dict[str, CallNode],
63
+ root_id: Optional[str],
64
+ max_len: int = 80,
65
+ ) -> Tuple[Dict[str, DagNode], List[DagEdge], Dict[str, str]]:
66
+ """Fold a call tree into a DAG where each distinct subtree appears once.
67
+
68
+ Returns (dag_nodes, dag_edges, node_to_dag):
69
+ - dag_nodes maps a dag id ("d1", "d2", ...) to its DagNode; ids follow the
70
+ order in which calls are first met in a top-down, left-to-right walk,
71
+ so the root is always "d1". call_count says how many tree calls were
72
+ folded into the node.
73
+ - dag_edges has one edge per (caller, callee) pair. If one call makes the
74
+ same sub-call n > 1 times, its edge gets the label "xn".
75
+ - node_to_dag maps every tree node id to the dag id it was folded into.
76
+ The result never has a cycle, because a subtree can't contain itself.
77
+ """
78
+ keys = compute_subtree_keys(nodes, root_id)
79
+ if not keys:
80
+ return {}, [], {}
81
+
82
+ dag_nodes: Dict[str, DagNode] = {}
83
+ dag_of_key: Dict[int, str] = {}
84
+ node_to_dag: Dict[str, str] = {}
85
+ first_of_dag: List[str] = []
86
+ stack = [root_id]
87
+ while stack:
88
+ node_id = stack.pop()
89
+ node = nodes[node_id]
90
+ key = keys[node_id]
91
+ if key not in dag_of_key:
92
+ dag_id = f"d{len(dag_nodes) + 1}"
93
+ dag_of_key[key] = dag_id
94
+ dag_nodes[dag_id] = DagNode(
95
+ dag_id=dag_id,
96
+ func_name=node.func_name,
97
+ args_sig=args_signature(node.args, node.kwargs, max_len),
98
+ call_count=0,
99
+ )
100
+ first_of_dag.append(node_id)
101
+ dag_id = dag_of_key[key]
102
+ dag_nodes[dag_id].call_count += 1
103
+ node_to_dag[node_id] = dag_id
104
+ stack.extend(c for c in reversed(node.children_ids) if c in keys)
105
+
106
+ dag_edges: List[DagEdge] = []
107
+ for node_id in first_of_dag:
108
+ source = node_to_dag[node_id]
109
+ counts: Dict[str, int] = {}
110
+ for child_id in nodes[node_id].children_ids:
111
+ if child_id in keys:
112
+ target = dag_of_key[keys[child_id]]
113
+ counts[target] = counts.get(target, 0) + 1
114
+ for target, count in counts.items():
115
+ edge = DagEdge(source, target, f"x{count}" if count > 1 else None)
116
+ dag_edges.append(edge)
117
+ dag_nodes[source].outgoing_edges.append(edge)
118
+ dag_nodes[target].incoming_edges.append(edge)
119
+ return dag_nodes, dag_edges, node_to_dag
120
+
121
+ def compute_max_depth(nodes: Dict[str, CallNode]) -> int:
122
+ """Return how many levels the deepest call sits below the top call (0 if empty).
123
+
124
+ Uses CallNode.depth, measured from the shallowest call, so a trace that
125
+ started at depth 5 still reports depth counted from its own root.
126
+ """
127
+ if not nodes:
128
+ return 0
129
+ depths = [node.depth for node in nodes.values()]
130
+ return max(depths) - min(depths)
131
+
132
+ def compute_stats(nodes: Dict[str, CallNode], dag_nodes: Dict[str, Any]) -> TraceAnalysis:
133
+ """Return call statistics for a traced tree and its folded DAG.
134
+
135
+ total_calls is the number of tree calls, unique_calls the number of DAG
136
+ nodes, and redundancy_ratio the share of calls that were repeats:
137
+ (total - unique) / total, so 0.0 means nothing was recomputed.
138
+ """
139
+ total = len(nodes)
140
+ unique = len(dag_nodes)
141
+ ratio = (total - unique) / total if total else 0.0
142
+ return TraceAnalysis(
143
+ total_calls=total,
144
+ unique_calls=unique,
145
+ max_depth=compute_max_depth(nodes),
146
+ redundancy_ratio=ratio,
147
+ )
148
+
149
+ def analyze_session(session: TraceSession, max_len: int = 80) -> TraceSession:
150
+ """Fold session's call tree into a DAG and compute its statistics, in place.
151
+
152
+ Fills session.dag_nodes, session.dag_edges and session.analysis (replacing
153
+ any earlier values) and returns the same session, ready for layout.py.
154
+ The raw call tree in session.nodes is left unchanged.
155
+ """
156
+ dag_nodes, dag_edges, _ = fold_tree(session.nodes, session.root_id, max_len)
157
+ session.dag_nodes = dag_nodes
158
+ session.dag_edges = dag_edges
159
+ session.analysis = compute_stats(session.nodes, dag_nodes)
160
+ return session
recfold/layout.py ADDED
@@ -0,0 +1,254 @@
1
+ """Pure-Python 2D layout for recfold DAGs: assigns (x, y) pixel coordinates."""
2
+
3
+ from collections import deque
4
+ from dataclasses import dataclass, field
5
+ from typing import Dict, Iterable, List, Tuple
6
+
7
+ from recfold.models import DagEdge, DagNode, TraceSession
8
+
9
+
10
+ def compute_levels(dag_nodes: Dict[str, DagNode], dag_edges: Iterable[DagEdge]) -> Dict[str, int]:
11
+ """Return the row (level) of every node: roots are 0, others sit below all parents.
12
+
13
+ A node's level is the length of the longest path from any root to it, so a
14
+ shared child always appears below every caller. Edges that mention unknown
15
+ node ids are ignored. Raises ValueError if the edges contain a cycle.
16
+ """
17
+ children: Dict[str, List[str]] = {node_id: [] for node_id in dag_nodes}
18
+ indegree: Dict[str, int] = {node_id: 0 for node_id in dag_nodes}
19
+ for edge in dag_edges:
20
+ if edge.source_id in dag_nodes and edge.target_id in dag_nodes:
21
+ children[edge.source_id].append(edge.target_id)
22
+ indegree[edge.target_id] += 1
23
+
24
+ levels = {node_id: 0 for node_id in dag_nodes}
25
+ queue = deque(sorted(n for n, d in indegree.items() if d == 0))
26
+ visited = 0
27
+ while queue:
28
+ current = queue.popleft()
29
+ visited += 1
30
+ for child in children[current]:
31
+ levels[child] = max(levels[child], levels[current] + 1)
32
+ indegree[child] -= 1
33
+ if indegree[child] == 0:
34
+ queue.append(child)
35
+
36
+ if visited != len(dag_nodes):
37
+ raise ValueError("DAG contains a cycle")
38
+ return levels
39
+
40
+
41
+ def _count_crossings(layers: List[List[str]], dag_edges: Iterable[DagEdge]) -> int:
42
+ """Count edge crossings between each pair of neighbouring rows."""
43
+ position = {n: i for row in layers for i, n in enumerate(row)}
44
+ row_of = {n: r for r, row in enumerate(layers) for n in row}
45
+ pairs: List[Tuple[int, int, int]] = []
46
+ for edge in dag_edges:
47
+ s, t = edge.source_id, edge.target_id
48
+ if s in row_of and t in row_of and row_of[t] == row_of[s] + 1:
49
+ pairs.append((row_of[s], position[s], position[t]))
50
+ crossings = 0
51
+ for i, (r1, s1, t1) in enumerate(pairs):
52
+ for r2, s2, t2 in pairs[i + 1:]:
53
+ if r1 == r2 and (s1 - s2) * (t1 - t2) < 0:
54
+ crossings += 1
55
+ return crossings
56
+
57
+
58
+ def _reorder_row(row: List[str], neighbours: Dict[str, List[str]], reference: List[str]) -> List[str]:
59
+ """Sort a row by the average position of each node's neighbours in reference row."""
60
+ ref_pos = {n: i for i, n in enumerate(reference)}
61
+ current = {n: i for i, n in enumerate(row)}
62
+
63
+ def barycenter(node: str) -> float:
64
+ spots = [ref_pos[m] for m in neighbours.get(node, []) if m in ref_pos]
65
+ return sum(spots) / len(spots) if spots else float(current[node])
66
+
67
+ return sorted(row, key=lambda n: (barycenter(n), current[n], n))
68
+
69
+
70
+ def order_within_levels(
71
+ levels: Dict[str, int],
72
+ dag_edges: Iterable[DagEdge],
73
+ sweeps: int = 4,
74
+ ) -> List[List[str]]:
75
+ """Return rows of node ids (top to bottom), ordered left to right to cut crossings.
76
+
77
+ Rows start sorted by id, then barycenter sweeps (down, then up) move each
78
+ node toward the average position of its neighbours. The ordering with the
79
+ fewest crossings is returned; ties keep the earliest one, so the result is
80
+ deterministic.
81
+ """
82
+ if not levels:
83
+ return []
84
+ edge_list = list(dag_edges)
85
+ layers: List[List[str]] = [[] for _ in range(max(levels.values()) + 1)]
86
+ for node_id in sorted(levels):
87
+ layers[levels[node_id]].append(node_id)
88
+
89
+ parents: Dict[str, List[str]] = {}
90
+ kids: Dict[str, List[str]] = {}
91
+ for edge in edge_list:
92
+ if edge.source_id in levels and edge.target_id in levels:
93
+ parents.setdefault(edge.target_id, []).append(edge.source_id)
94
+ kids.setdefault(edge.source_id, []).append(edge.target_id)
95
+
96
+ best = [list(row) for row in layers]
97
+ best_score = _count_crossings(best, edge_list)
98
+ for _ in range(sweeps):
99
+ for r in range(1, len(layers)):
100
+ layers[r] = _reorder_row(layers[r], parents, layers[r - 1])
101
+ for r in range(len(layers) - 2, -1, -1):
102
+ layers[r] = _reorder_row(layers[r], kids, layers[r + 1])
103
+ score = _count_crossings(layers, edge_list)
104
+ if score < best_score:
105
+ best, best_score = [list(row) for row in layers], score
106
+ return best
107
+
108
+
109
+ def assign_coordinates(
110
+ layers: List[List[str]],
111
+ node_width: float = 140,
112
+ node_height: float = 48,
113
+ h_gap: float = 40,
114
+ v_gap: float = 70,
115
+ margin: float = 20,
116
+ ) -> Dict[str, Tuple[float, float]]:
117
+ """Return the (x, y) centre of every node, in pixels (y grows downward).
118
+
119
+ Row r sits at the same height for all its nodes; each row is centred on the
120
+ widest row, with h_gap between neighbours and v_gap between rows.
121
+ """
122
+ if not layers:
123
+ return {}
124
+ step = node_width + h_gap
125
+ widest = max(len(row) for row in layers) * step - h_gap
126
+ positions: Dict[str, Tuple[float, float]] = {}
127
+ for level, row in enumerate(layers):
128
+ row_width = len(row) * step - h_gap
129
+ start_x = margin + (widest - row_width) / 2
130
+ y = margin + level * (node_height + v_gap) + node_height / 2
131
+ for index, node_id in enumerate(row):
132
+ positions[node_id] = (start_x + index * step + node_width / 2, float(y))
133
+ return positions
134
+
135
+
136
+ def center_over_children(
137
+ layers: List[List[str]],
138
+ positions: Dict[str, Tuple[float, float]],
139
+ dag_edges: Iterable[DagEdge],
140
+ min_step: float,
141
+ ) -> Dict[str, Tuple[float, float]]:
142
+ """Return new positions with each parent shifted over the mean x of its children.
143
+
144
+ Rows are processed from the bottom up. Nodes without children keep their x.
145
+ Left-to-right order is kept, and neighbours in a row stay at least min_step
146
+ apart (distance between centres), so nothing overlaps. y values and the
147
+ input dict are never changed.
148
+ """
149
+ result = dict(positions)
150
+ kids: Dict[str, List[str]] = {}
151
+ for edge in dag_edges:
152
+ if edge.source_id in positions and edge.target_id in positions:
153
+ kids.setdefault(edge.source_id, []).append(edge.target_id)
154
+
155
+ for row in reversed(layers[:-1]):
156
+ previous_x = None
157
+ for node_id in row:
158
+ x, y = result[node_id]
159
+ children = kids.get(node_id)
160
+ if children:
161
+ x = sum(result[c][0] for c in children) / len(children)
162
+ if previous_x is not None and x < previous_x + min_step:
163
+ x = previous_x + min_step
164
+ result[node_id] = (x, y)
165
+ previous_x = x
166
+ return result
167
+
168
+
169
+ def compute_canvas_size(
170
+ positions: Dict[str, Tuple[float, float]],
171
+ node_width: float = 140,
172
+ node_height: float = 48,
173
+ margin: float = 20,
174
+ ) -> Tuple[float, float]:
175
+ """Return (width, height) of the drawing area that fits every node plus margin."""
176
+ if not positions:
177
+ return (2.0 * margin, 2.0 * margin)
178
+ width = max(x for x, _ in positions.values()) + node_width / 2 + margin
179
+ height = max(y for _, y in positions.values()) + node_height / 2 + margin
180
+ return (float(width), float(height))
181
+
182
+
183
+ def edge_segments(
184
+ positions: Dict[str, Tuple[float, float]],
185
+ dag_edges: Iterable[DagEdge],
186
+ node_height: float = 48,
187
+ ) -> List[Tuple[str, str, float, float, float, float]]:
188
+ """Return one (source_id, target_id, x1, y1, x2, y2) line per edge.
189
+
190
+ Each line starts at the bottom-centre of the source node and ends at the
191
+ top-centre of the target node. Edges naming unknown nodes are skipped; the
192
+ order of dag_edges is kept.
193
+ """
194
+ half = node_height / 2
195
+ segments = []
196
+ for edge in dag_edges:
197
+ if edge.source_id in positions and edge.target_id in positions:
198
+ x1, y1 = positions[edge.source_id]
199
+ x2, y2 = positions[edge.target_id]
200
+ segments.append((edge.source_id, edge.target_id, x1, y1 + half, x2, y2 - half))
201
+ return segments
202
+
203
+
204
+ @dataclass
205
+ class LayoutResult:
206
+ """Everything the renderer needs to draw a DAG. Units are pixels, y grows downward.
207
+
208
+ positions maps node id to the (x, y) centre of its box; segments are the
209
+ (source_id, target_id, x1, y1, x2, y2) edge lines; width and height are the
210
+ drawing area; node_width and node_height are the box size used.
211
+ """
212
+
213
+ positions: Dict[str, Tuple[float, float]] = field(default_factory=dict)
214
+ levels: Dict[str, int] = field(default_factory=dict)
215
+ segments: List[Tuple[str, str, float, float, float, float]] = field(default_factory=list)
216
+ width: float = 0.0
217
+ height: float = 0.0
218
+ node_width: float = 140
219
+ node_height: float = 48
220
+
221
+
222
+ def layout_dag(
223
+ dag_nodes: Dict[str, DagNode],
224
+ dag_edges: Iterable[DagEdge],
225
+ node_width: float = 140,
226
+ node_height: float = 48,
227
+ h_gap: float = 40,
228
+ v_gap: float = 70,
229
+ margin: float = 20,
230
+ ) -> LayoutResult:
231
+ """Lay out a DAG: levels, left-to-right order, coordinates, canvas and edge lines.
232
+
233
+ Raises ValueError if the edges contain a cycle.
234
+ """
235
+ edge_list = list(dag_edges)
236
+ levels = compute_levels(dag_nodes, edge_list)
237
+ layers = order_within_levels(levels, edge_list)
238
+ positions = assign_coordinates(layers, node_width, node_height, h_gap, v_gap, margin)
239
+ positions = center_over_children(layers, positions, edge_list, node_width + h_gap)
240
+ width, height = compute_canvas_size(positions, node_width, node_height, margin)
241
+ return LayoutResult(
242
+ positions=positions,
243
+ levels=levels,
244
+ segments=edge_segments(positions, edge_list, node_height),
245
+ width=width,
246
+ height=height,
247
+ node_width=node_width,
248
+ node_height=node_height,
249
+ )
250
+
251
+
252
+ def layout_session(session: TraceSession, **options: float) -> LayoutResult:
253
+ """Lay out the DAG stored on a TraceSession; options are passed to layout_dag."""
254
+ return layout_dag(session.dag_nodes, session.dag_edges, **options)
recfold/models.py ADDED
@@ -0,0 +1,51 @@
1
+ from dataclasses import dataclass, field
2
+ from typing import Any, Dict, List, Optional, Tuple
3
+
4
+
5
+ @dataclass
6
+ class CallNode:
7
+ node_id: str
8
+ func_name: str
9
+ args: Tuple[Any, ...] = field(default_factory=tuple)
10
+ kwargs: Dict[str, Any] = field(default_factory=dict)
11
+ result: Any = None
12
+ depth: int = 0
13
+ parent_id: Optional[str] = None
14
+ children_ids: List[str] = field(default_factory=list)
15
+ entry_snapshot: Dict[str, Any] = field(default_factory=dict)
16
+ exit_snapshot: Dict[str, Any] = field(default_factory=dict)
17
+
18
+
19
+ @dataclass
20
+ class DagEdge:
21
+ source_id: str
22
+ target_id: str
23
+ label: Optional[str] = None
24
+
25
+
26
+ @dataclass
27
+ class DagNode:
28
+ dag_id: str
29
+ func_name: str
30
+ args_sig: str
31
+ call_count: int = 1
32
+ incoming_edges: List[DagEdge] = field(default_factory=list)
33
+ outgoing_edges: List[DagEdge] = field(default_factory=list)
34
+
35
+
36
+ @dataclass
37
+ class TraceAnalysis:
38
+ total_calls: int = 0
39
+ unique_calls: int = 0
40
+ max_depth: int = 0
41
+ redundancy_ratio: float = 0.0
42
+
43
+
44
+ @dataclass
45
+ class TraceSession:
46
+ func_name: str
47
+ nodes: Dict[str, CallNode] = field(default_factory=dict)
48
+ root_id: Optional[str] = None
49
+ dag_nodes: Dict[str, DagNode] = field(default_factory=dict)
50
+ dag_edges: List[DagEdge] = field(default_factory=list)
51
+ analysis: Optional[TraceAnalysis] = None