@woosh/meep-engine 3.16.0 → 3.17.0

package/src/core/model/node-graph/visual/layout/layout_node_graph.js

@@ -24,12 +24,15 @@ import { route_to_spline } from "./route_to_spline.js";
  * not because anything measured how related they are, but because being joined is what put them in
  * neighbouring columns and being joined to the same things is what put them next to each other.
  *
- * **Routing** decides where the wires go, which the placement has deliberately left open. Each wire
- * finds its own way through the space between the boxes, avoiding them and, as far as it can, each
- * other. This is where the drawing stops looking like a diagram of the algorithm and starts looking
- * like something somebody drew: wires that run alongside each other rather than through each other,
- * that go around a node instead of behind it, and that leave and arrive square to the ports they
- * belong to.
+ * **Routing** decides where the wires go, which the placement has left open within the columns it
+ * decided. A wire that crosses a column is taken through the lane the placement reserved for it
+ * there — which is how the placement's crossing-minimised order reaches the drawing — and between
+ * one lane and the next each wire finds its own way, avoiding the boxes and, as far as it can, the
+ * other wires: sharing a line with one costs it something, and so does crossing one. This is where
+ * the drawing stops looking like a diagram of the algorithm and starts looking like something
+ * somebody drew: wires that run alongside each other rather than through each other, that go
+ * around a node instead of behind it, that do not cross what they could as easily have gone round,
+ * and that leave and arrive square to the ports they belong to.
  *
  * The two halves are separate on purpose. Placement can be re-run without re-routing when only the
  * structure changed, and routing can be re-run without re-placing when somebody has dragged a node
@@ -63,7 +66,11 @@ export function layout_node_graph(graph, visual, options = new NodeGraphLayoutOp
 
         const layer_count = layout_assign_layers(boxes, position);
 
-        layout_insert_lanes(boxes);
+        const lane_offset = new Int32Array(boxes.link_count + 1);
+
+        layout_insert_lanes(boxes, lane_offset);
+
+        assign_lanes(problem, lane_offset);
 
         const ordering = layout_order_layers(boxes, layer_count, options.order_sweeps);
 
@@ -91,6 +98,41 @@ export function layout_node_graph(graph, visual, options = new NodeGraphLayoutOp
     return { width, height, crossings };
 }
 
+/**
+ * Hand each connection the lanes its link was given, so that the router can take it through them.
+ *
+ * @param {LayoutProblem} problem mutated: `lane_start` and `lane_box` are written
+ * @param {Int32Array} lane_offset from {@link layout_insert_lanes}, per link as they stood before it
+ * @returns {void}
+ */
+function assign_lanes(problem, lane_offset) {
+    const count = problem.connection_count;
+
+    const lane_start = problem.lane_start;
+
+    for (let i = 0; i < count; i++) {
+        const link = problem.link_of_connection[i];
+
+        lane_start[i + 1] = lane_start[i] + (link === -1 ? 0 : lane_offset[link + 1] - lane_offset[link]);
+    }
+
+    const lane_box = new Int32Array(lane_start[count]);
+
+    for (let i = 0; i < count; i++) {
+        const link = problem.link_of_connection[i];
+
+        if (link === -1) {
+            continue;
+        }
+
+        for (let k = lane_offset[link], at = lane_start[i]; k < lane_offset[link + 1]; k++, at++) {
+            lane_box[at] = k;
+        }
+    }
+
+    problem.lane_box = lane_box;
+}
+
 /**
  * Route the wires of an already placed graph.
  *

package/src/core/model/node-graph/visual/layout/layout_order_layers.d.ts

@@ -3,7 +3,8 @@
  *
  * Two heuristics alternating, then a local fix-up, and the best arrangement any of them reaches is
  * what is kept — a sweep can leave the drawing worse than it found it, and there is no reason to
- * keep the last one rather than the best one.
+ * keep the last one rather than the best one. Best means fewest crossings, and between
+ * arrangements that cross equally often, the one whose links reach least far up and down.
  *
  * - **Sweeps.** Every box moves to the average, or to the median, of where its neighbours in the
  *   adjacent column sit. Median wins where a box's neighbours fall into groups, average where they
@@ -17,6 +18,15 @@
  * that — so the crossing count here is the number of crossings the drawing will actually show,
  * counted rather than estimated.
  *
+ * **Ports are positions, not just boxes.** A link does not meet a box, it meets a port on it, and
+ * a box with three inputs fed by three boxes of the column before is drawn with three wires that
+ * cross each other whenever those three are stacked in the wrong order — an order that looks
+ * perfect to anything comparing boxes alone, since all three links arrive at the same box. So
+ * wherever this compares where a link's far end sits, it uses the box's rank plus how far down the
+ * box the port is, and two links into one box are as in or out of order as the ports they meet.
+ * Two links leaving one port are the exception: they fan out from a single point and cannot cross,
+ * whichever way round their targets are.
+ *
  * @param {LayoutBoxGraph} graph adjacency must be current
  * @param {number} layer_count
  * @param {number} sweeps

package/src/core/model/node-graph/visual/layout/layout_order_layers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"layout_order_layers.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/model/node-graph/visual/layout/layout_order_layers.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wEATW,MAAM,UACN,MAAM;WACI,UAAU;UAAQ,UAAU;iBAAe,UAAU;eAAa,MAAM;EAsI5F"}
+{"version":3,"file":"layout_order_layers.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/model/node-graph/visual/layout/layout_order_layers.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wEATW,MAAM,UACN,MAAM;WACI,UAAU;UAAQ,UAAU;iBAAe,UAAU;eAAa,MAAM;EAyJ5F"}

package/src/core/model/node-graph/visual/layout/layout_order_layers.js

@@ -10,7 +10,8 @@ const EXCHANGE_ROUNDS = 4;
  *
  * Two heuristics alternating, then a local fix-up, and the best arrangement any of them reaches is
  * what is kept — a sweep can leave the drawing worse than it found it, and there is no reason to
- * keep the last one rather than the best one.
+ * keep the last one rather than the best one. Best means fewest crossings, and between
+ * arrangements that cross equally often, the one whose links reach least far up and down.
  *
  * - **Sweeps.** Every box moves to the average, or to the median, of where its neighbours in the
  *   adjacent column sit. Median wins where a box's neighbours fall into groups, average where they
@@ -24,6 +25,15 @@ const EXCHANGE_ROUNDS = 4;
  * that — so the crossing count here is the number of crossings the drawing will actually show,
  * counted rather than estimated.
  *
+ * **Ports are positions, not just boxes.** A link does not meet a box, it meets a port on it, and
+ * a box with three inputs fed by three boxes of the column before is drawn with three wires that
+ * cross each other whenever those three are stacked in the wrong order — an order that looks
+ * perfect to anything comparing boxes alone, since all three links arrive at the same box. So
+ * wherever this compares where a link's far end sits, it uses the box's rank plus how far down the
+ * box the port is, and two links into one box are as in or out of order as the ports they meet.
+ * Two links leaving one port are the exception: they fan out from a single point and cannot cross,
+ * whichever way round their targets are.
+ *
  * @param {LayoutBoxGraph} graph adjacency must be current
  * @param {number} layer_count
  * @param {number} sweeps
@@ -101,11 +111,12 @@ export function layout_order_layers(graph, layer_count, sweeps) {
         }
     }
 
+    // Positions carry a fraction for the port, so nothing here is an integer any more.
     const scratch = {
         weight: new Float64Array(box_count),
-        neighbours: new Int32Array(widest_degree),
-        sequence: new Int32Array(graph.link_count),
-        merge: new Int32Array(graph.link_count)
+        neighbours: new Float64Array(widest_degree),
+        sequence: new Float64Array(graph.link_count),
+        merge: new Float64Array(graph.link_count)
     };
 
     // Sorted by comparator rather than by one of the `array_quick_sort_by_lookup_*` helpers: those
@@ -116,12 +127,15 @@ export function layout_order_layers(graph, layer_count, sweeps) {
     // links across one boundary, in order of where they leave and then of where they arrive
     const by_endpoints = (a, b) =>
         (rank[graph.link_from[a]] - rank[graph.link_from[b]])
-        || (rank[graph.link_to[a]] - rank[graph.link_to[b]]);
+        || (graph.link_from_y[a] - graph.link_from_y[b])
+        || (rank[graph.link_to[a]] - rank[graph.link_to[b]])
+        || (graph.link_to_y[a] - graph.link_to_y[b]);
 
     let best = order.slice();
     let best_cost = count_crossings(graph, rank, layer_count, boundary_start, boundary_link, by_endpoints, scratch);
+    let best_reach = reach(graph, order, layer_start, layer_count, scratch.weight);
 
-    for (let sweep = 0; sweep < sweeps && best_cost > 0; sweep++) {
+    for (let sweep = 0; sweep < sweeps; sweep++) {
         const downward = sweep % 2 === 0;
         const median = (sweep >> 1) % 2 === 0;
 
@@ -146,8 +160,23 @@ export function layout_order_layers(graph, layer_count, sweeps) {
 
         const cost = count_crossings(graph, rank, layer_count, boundary_start, boundary_link, by_endpoints, scratch);
 
-        if (cost < best_cost) {
+        // Fewer crossings wins; the same number of crossings wins if the links reach less far.
+        // The second half matters more than it looks: the order the boxes arrive in has the lanes
+        // after every node, and a sweep that brings each lane up beside the wire it belongs to
+        // regularly crosses exactly as often as leaving it at the bottom of the column did — the
+        // crossings merely move from where the lane meets its wire to where it leaves its port.
+        // Without the tie-break the arrival order is kept, and the wire is drawn to the bottom of
+        // the column and back.
+        if (cost > best_cost) {
+            continue;
+        }
+
+        // the weights are spent by now, so their array can hold the box tops
+        const wander = reach(graph, order, layer_start, layer_count, scratch.weight);
+
+        if (cost < best_cost || wander < best_reach) {
             best_cost = cost;
+            best_reach = wander;
             best.set(order);
         }
     }
@@ -163,9 +192,52 @@ export function layout_order_layers(graph, layer_count, sweeps) {
     return { order, rank, layer_start, crossings: best_cost };
 }
 
+/**
+ * Where a link meets a box, as a position down the column: the box's rank, and then how far down
+ * the box the port is as a fraction of its height.
+ *
+ * A port sits strictly inside its box, so this is strictly less than the rank after. A lane has no
+ * height and no ports, and is simply its rank.
+ *
+ * @param {LayoutBoxGraph} graph
+ * @param {Int32Array} rank
+ * @param {number} box
+ * @param {number} y offset down the box at which the link meets it
+ * @returns {number}
+ */
+function position_of(graph, rank, box, y) {
+    const height = graph.box_h[box];
+
+    return height > 0 ? rank[box] + y / height : rank[box];
+}
+
+/**
+ * Where a link meets its source box, as a position down the column. See {@link position_of}.
+ *
+ * @param {LayoutBoxGraph} graph
+ * @param {Int32Array} rank
+ * @param {number} link
+ * @returns {number}
+ */
+function source_position(graph, rank, link) {
+    return position_of(graph, rank, graph.link_from[link], graph.link_from_y[link]);
+}
+
+/**
+ * @param {LayoutBoxGraph} graph
+ * @param {Int32Array} rank
+ * @param {number} link
+ * @returns {number}
+ */
+function target_position(graph, rank, link) {
+    return position_of(graph, rank, graph.link_to[link], graph.link_to_y[link]);
+}
+
 /**
  * Give every box in one column a position to be sorted by, taken from where its neighbours in the
- * adjacent column sit.
+ * adjacent column sit — where on them, that is: a box fed from the top port of a neighbour belongs
+ * above a box fed from its bottom one, and three boxes feeding one neighbour belong in the order
+ * of the ports they feed.
  *
  * A box with no neighbours on the side being looked at keeps the position it has. Otherwise a
  * source or a sink drifts to the top of its column on every single sweep, having nothing to hold
@@ -202,7 +274,7 @@ function reweigh(graph, order, rank, layer_start, at, downward, median, scratch)
         for (let i = 0; i < count; i++) {
             const link = downward ? graph.in_link[start + i] : graph.out_link[start + i];
 
-            neighbours[i] = rank[downward ? graph.link_from[link] : graph.link_to[link]];
+            neighbours[i] = downward ? source_position(graph, rank, link) : target_position(graph, rank, link);
         }
 
         if (!median) {
@@ -278,6 +350,9 @@ function exchange(graph, order, rank, layer_start, layer_count) {
 /**
  * Crossings between the links of two boxes sharing a column, given `first` sits above `second`.
  *
+ * Only the far ends matter. Where on `first` and `second` their own links attach decides nothing
+ * about whether swapping the two helps, since it is the same either way round.
+ *
  * @param {LayoutBoxGraph} graph
  * @param {Int32Array} rank
  * @param {number} first
@@ -290,7 +365,7 @@ function pair_crossings(graph, rank, first, second) {
     for (let side = 0; side < 2; side++) {
         const offset = side === 0 ? graph.in_offset : graph.out_offset;
         const list = side === 0 ? graph.in_link : graph.out_link;
-        const end_of = side === 0 ? graph.link_from : graph.link_to;
+        const position = side === 0 ? source_position : target_position;
 
         const first_start = offset[first];
         const first_end = offset[first + 1];
@@ -299,10 +374,10 @@ function pair_crossings(graph, rank, first, second) {
         const second_end = offset[second + 1];
 
         for (let i = first_start; i < first_end; i++) {
-            const a = rank[end_of[list[i]]];
+            const a = position(graph, rank, list[i]);
 
             for (let k = second_start; k < second_end; k++) {
-                if (a > rank[end_of[list[k]]]) {
+                if (a > position(graph, rank, list[k])) {
                     total++;
                 }
             }
@@ -315,7 +390,7 @@ function pair_crossings(graph, rank, first, second) {
 /**
  * How many times two links cross, over every column boundary.
  *
- * Links leaving one box are gathered in ascending order of where they arrive, so two of them never
+ * Links leaving one port are gathered in ascending order of where they arrive, so two of them never
  * register as a crossing — they start at the same point and cannot cross. What is left is counted
  * by inversions.
  *
@@ -352,7 +427,7 @@ function count_crossings(graph, rank, layer_count, boundary_start, boundary_link
         window.sort(by_endpoints);
 
         for (let i = 0; i < count; i++) {
-            window[i] = rank[graph.link_to[window[i]]];
+            window[i] = target_position(graph, rank, window[i]);
         }
 
         total += inversions(window, scratch.merge);
@@ -361,11 +436,55 @@ function count_crossings(graph, rank, layer_count, boundary_start, boundary_link
     return total;
 }
 
+/**
+ * How far the links reach up and down the drawing, all told: the sum over every link of the
+ * vertical distance between its two ends, with every column packed tight from the top.
+ *
+ * What separates two arrangements that cross equally often. Crossings are blind to distance — a
+ * dozen wires from one port to a dozen boxes cross the same things whether those boxes are next
+ * to the port or at the far end of the column — and an arrangement that is no better in crossings
+ * but keeps linked boxes together is the one to draw. Heights rather than ranks, because a lane is
+ * a rank like any other and a box is not: three lanes stacked under three boxes are the height of
+ * a wire, and counting them as three more boxes would call a wire to the bottom of that column
+ * and back as short as one to the box beside it.
+ *
+ * @param {LayoutBoxGraph} graph
+ * @param {Int32Array} order
+ * @param {Int32Array} layer_start
+ * @param {number} layer_count
+ * @param {Float64Array} top scratch, one per box: written with where each box's top would be
+ * @returns {number}
+ */
+function reach(graph, order, layer_start, layer_count, top) {
+    for (let layer = 0; layer < layer_count; layer++) {
+        let y = 0;
+
+        for (let k = layer_start[layer]; k < layer_start[layer + 1]; k++) {
+            const box = order[k];
+
+            top[box] = y;
+
+            y += graph.box_h[box];
+        }
+    }
+
+    let total = 0;
+
+    for (let i = 0; i < graph.link_count; i++) {
+        const from = top[graph.link_from[i]] + graph.link_from_y[i];
+        const to = top[graph.link_to[i]] + graph.link_to_y[i];
+
+        total += Math.abs(from - to);
+    }
+
+    return total;
+}
+
 /**
  * Pairs out of order, by merge sort.
  *
- * @param {Int32Array} values consumed; left sorted
- * @param {Int32Array} buffer at least as long as `values`
+ * @param {Float64Array} values consumed; left sorted
+ * @param {Float64Array} buffer at least as long as `values`
  * @returns {number}
  */
 function inversions(values, buffer) {

package/src/core/model/node-graph/visual/layout/route_connections.d.ts

@@ -24,6 +24,35 @@
  * this a graph whose wires nearly all fit spends five further rounds re-deriving the same routes,
  * and the work grows as the square of the graph rather than with the trouble in it.
  *
+ * **The wires leaving one port are one net, and share lines with each other for nothing.** They
+ * are one signal, and they leave the port along one stub whatever anybody does; charging them for
+ * running along the same line after it prices up the one thing they cannot help, every round,
+ * until they are pushed onto whichever line is left and pulled apart there in an order nobody
+ * chose — which is how a fan of six wires came to be drawn crossing itself. Left to share, they
+ * run out of the port as one line and fork where each of them leaves, which is a bus, and is what
+ * a fan of wires from one port looks like in any drawing done by hand. See
+ * {@link RouteGrid#owner_h}.
+ *
+ * **A long wire is routed through its lanes.** The placement gave every wire that crosses a column
+ * a lane in it — a point the ordering stage put where it crosses the fewest other wires and the
+ * coordinate stage lined up with the lanes either side of it — and a wire with lanes is routed as
+ * a chain of short searches, one per lane, each ending where the lane is and going through it
+ * horizontally. That is the placement's crossing-minimised order drawn, rather than left for the
+ * router to rediscover one wire at a time; and it is what makes a wire forty columns long cheap to
+ * route, where one search across the whole drawing floods the grid and gives up. A wire whose
+ * lanes cannot be reached is routed free, as a wire with no lanes always is.
+ *
+ * **Crossings are not an argument, and are settled afterwards.** Sharing a line is something the
+ * negotiation can price up until one wire leaves; crossing is allowed, merely costed, and a wire
+ * that crosses six others may have had no way not to. But the order the wires are first routed in
+ * hides most of the crossings from the wires that make them: a wire routed early sees an empty
+ * grid, takes whichever of its equal routes surfaces first, and is then crossed by everything
+ * routed after it — and since it shares nothing it is never asked again. So once nothing is shared,
+ * every wire something has been done to is asked once more, with all the others present, and moves
+ * only if the route it finds is cheaper than the one it has. That is a descent on the total cost
+ * of the drawing — a crossing costs both wires the same, so a wire making itself cheaper makes the
+ * whole cheaper — and it stops on its own when a round moves nothing.
+ *
  * @see McMurchie, Ebeling — *PathFinder: A Negotiation-Based Performance-Driven Router for FPGAs*
  *      (1995)
  *

package/src/core/model/node-graph/visual/layout/route_connections.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"route_connections.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/model/node-graph/visual/layout/route_connections.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,oFANW,sBAAsB,GACpB,QAAQ,CA4GpB;uCAhJsC,6BAA6B;yBAE3C,eAAe"}
+{"version":3,"file":"route_connections.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/model/node-graph/visual/layout/route_connections.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AACH,oFANW,sBAAsB,GACpB,QAAQ,CA0GpB;uCA3KsC,6BAA6B;yBAE3C,eAAe"}