1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
//! Mermaid flowchart rendering for topologies.
use crate::graph::node::NodeKind;
use crate::graph::topology::{FeatureSplitPolicy, Topology};
/// How a blueprint's feature split names itself in a doc: the policy, when one is recorded, else
/// `rows` (masks present without a policy is a legacy record the load path reconciles; naming them
pub(crate) fn split_policy_name(policy: Option<FeatureSplitPolicy>) -> &'static str {
match policy {
Some(FeatureSplitPolicy::Exclusive) => "exclusive",
Some(FeatureSplitPolicy::Random) => "random",
// PROVENANCE, not a policy: the run's pool can only draw `exclusive` or `random` (`FeatureSplitPolicy::is_drawable`), so calling this `crossover` read like a third…
Some(FeatureSplitPolicy::Inherited) => "inherited",
None => "rows",
}
}
/// The Input node's feature split as one line — `split random · 8p · 392/784 seen` — or `None`
/// the net has none.
pub(crate) fn feature_split_cell(graph: &Topology) -> Option<String> {
let masks = graph.input_feature_masks()?;
let input_dim = graph.options.input_dim.unwrap_or(1).max(1);
let seen = (0..input_dim)
.filter(|f| masks.iter().any(|m| m.get(*f).copied().unwrap_or(0) != 0))
.count();
Some(format!(
"split {} · {}p · {}/{} seen",
split_policy_name(graph.options.feature_split),
masks.len(),
seen,
input_dim
))
}
/// Mermaid flowchart of a [`Topology`] — renders natively in GitHub/GitLab/Notion
/// and can be exported via `mmdc`.
pub fn topology_mermaid(graph: &Topology) -> String {
let mut out = String::new();
out.push_str("```mermaid\n");
// The SAME curve the lineage graph asks for (`lineage.rs`): without an explicit config every viewer picks its own, so one card showed the smooth `Δfit` wires of the birth…
out.push_str("---\nconfig:\n layout: dagre\n flowchart:\n curve: basis\n---\n");
out.push_str("flowchart LR\n");
// Per-net hidden-dim range for edge-thickness normalization (min/max
// interpolate, same spirit as the planned ASCII box sizing).
let dims: Vec<usize> = graph.nodes.iter().filter_map(|n| n.hidden_dim).collect();
let (min_dim, max_dim) = (
dims.iter().min().copied().unwrap_or(1),
dims.iter().max().copied().unwrap_or(1),
);
let dim_range = (max_dim.saturating_sub(min_dim)).max(1);
// Node definitions — COMPACT one-line labels; Mermaid auto-sizes boxes,
// multi-line labels balloon every box.
for node in &graph.nodes {
let label = match node.kind {
NodeKind::Input => {
// The Input box is where the feature split belongs: it is Genome on the INPUT's
// ports, so a reader who wants to know whether this net partitions its columns sees
match feature_split_cell(graph) {
Some(split) => format!(
"n{}[\"in {}<br/>{}\"]",
node.id,
graph.options.input_dim.unwrap_or(1),
split
),
None => format!(
"n{}[\"in {}\"]",
node.id,
graph.options.input_dim.unwrap_or(1)
),
}
}
NodeKind::Hidden => {
let dim = node.hidden_dim.unwrap_or(8);
// Activation moves OFF the label (per-port ops belong
// wire); label = combine + std + dim, kept one line.
let combine = node
.combine_op
.map(|c| c.to_string())
.unwrap_or_else(|| "add".into());
let std = node
.standardize
.map(|s| s.to_string())
.unwrap_or_else(|| "identity".into());
format!("n{}[\"H{} {}·{} {}\"]", node.id, node.id, combine, std, dim)
}
NodeKind::Output => {
// Same combine·std·dim shape, prefixed `out`; activation omitted
// (fixed identity readout).
let combine = node
.combine_op
.map(|c| c.to_string())
.unwrap_or_else(|| "add".into());
let std = node
.standardize
.map(|s| s.to_string())
.unwrap_or_else(|| "identity".into());
format!(
"n{}[\"out {}·{} {}\"]",
node.id,
combine,
std,
graph.options.output_dim.unwrap_or(1)
)
}
};
out.push_str(&format!(" {}\n", label));
}
// Node borders — stroke-width from the node's hidden_dim (per-net
// normalized); one inline `style` line per node.
const MIN_BORDER: f32 = 0.5;
/// Thickest border stroke (widest hidden dim in the net).
const MAX_BORDER: f32 = 5.0;
for node in &graph.nodes {
let dim = node.hidden_dim.unwrap_or(min_dim);
let t = dim.saturating_sub(min_dim) as f32 / dim_range as f32;
let width = MIN_BORDER + (MAX_BORDER - MIN_BORDER) * t.clamp(0.0, 1.0);
out.push_str(&format!(
" style n{} stroke-width:{:.1}px\n",
node.id, width
));
}
// Edges — stroke-width scaled by HOP DISTANCE, so long-range skips render
// as thick trunks; normalized per net.
const MIN_WIDTH: f32 = 0.5;
/// Thickest edge stroke (longest hop in the net).
const MAX_WIDTH: f32 = 5.0;
let max_hop = graph
.connections
.iter()
.map(|c| c.to.node.saturating_sub(c.from.node))
.max()
.unwrap_or(1)
.max(1);
for (idx, conn) in graph.connections.iter().enumerate() {
// Edge label = the SOURCE PORT's activation: the wire carries
// non-linearity, so the signal name belongs on the arrow.
let edge_act = graph.nodes[conn.from.node].port_activation(conn.from.index);
let act = format!("{:#?}", edge_act).to_lowercase();
// No port annotation: dedup guarantees at most one wire per
// (source → target, activation), so parallel wires differ by label.
out.push_str(&format!(
" n{} -- {} --> n{}\n",
conn.from.node, act, conn.to.node
));
let hop = conn.to.node.saturating_sub(conn.from.node).max(1);
let t = (hop - 1) as f32 / (max_hop - 1).max(1) as f32;
let width = MIN_WIDTH + (MAX_WIDTH - MIN_WIDTH) * t.clamp(0.0, 1.0);
out.push_str(&format!(
" linkStyle {} stroke-width:{:.1}px\n",
idx, width
));
}
// Orphaned ports — the mermaid counterpart of the ASCII `*` marks;
// markers styled invisible (bare dashed whiskers).
let mut orphan_idx = graph.connections.len();
let output_id = graph
.nodes
.iter()
.find(|n| n.kind == NodeKind::Output)
.map(|n| n.id);
for node in &graph.nodes {
// The Output node's port always "dangles" by design (it's the exit,
// an unused port) — skip it so mermaid doesn't invent an orphan.
let is_output = Some(node.id) == output_id;
for port in 0..node.num_inputs {
let wired = graph
.connections
.iter()
.any(|c| c.to.node == node.id && c.to.index == port);
if !wired {
let marker = format!("o{}i{}", node.id, port);
// Show WHAT the orphaned port would have applied — the port's
// own activation — so the stub reads like `selu (input)`.
let act = format!("{:#?}", node.port_activation(port)).to_lowercase();
// marker → node: the stub ENTERS the box (input side).
out.push_str(&format!(
" {}(( )) -- {} (input) --> n{}\n",
marker, act, node.id
));
out.push_str(&format!(" style {} fill:none,stroke:none\n", marker));
out.push_str(&format!(
" linkStyle {} stroke-dasharray:3 3\n",
orphan_idx
));
orphan_idx += 1;
}
}
for port in 0..node.num_outputs {
if is_output {
continue; // the net's exit port — never an orphan
}
let wired = graph
.connections
.iter()
.any(|c| c.from.node == node.id && c.from.index == port);
if !wired {
let marker = format!("o{}o{}", node.id, port);
let act = format!("{:#?}", node.port_activation(port)).to_lowercase();
// node → marker: the stub LEAVES the box (output side).
out.push_str(&format!(
" n{} -- {} (orphan) --> {}(( ))\n",
node.id, act, marker
));
out.push_str(&format!(" style {} fill:none,stroke:none\n", marker));
out.push_str(&format!(
" linkStyle {} stroke-dasharray:3 3\n",
orphan_idx
));
orphan_idx += 1;
}
}
}
out.push_str("```\n");
out
}