@woosh/meep-engine 3.15.0 → 3.16.0

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

@@ -0,0 +1,415 @@
+/**
+ * Adjacent-pair exchange rounds after each sweep. The pass stops as soon as a round changes
+ * nothing, so this only bounds a pathological case.
+ * @type {number}
+ */
+const EXCHANGE_ROUNDS = 4;
+
+/**
+ * Decide the order of boxes within each column.
+ *
+ * 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.
+ *
+ * - **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
+ *   are spread evenly, and alternating them escapes the local minimum either one alone settles
+ *   into. Exact crossing minimisation is NP-hard and nobody reading a graph is counting crossings.
+ * - **Exchanges.** After each sweep, adjacent pairs swap wherever that removes crossings. A sweep
+ *   moves a box to where its neighbours are on average; an exchange fixes the case where two boxes
+ *   simply want each other's place, which no average will ever tell them.
+ *
+ * Every link spans exactly one column boundary by this point — {@link layout_insert_lanes} saw to
+ * that — so the crossing count here is the number of crossings the drawing will actually show,
+ * counted rather than estimated.
+ *
+ * @param {LayoutBoxGraph} graph adjacency must be current
+ * @param {number} layer_count
+ * @param {number} sweeps
+ * @returns {{order: Int32Array, rank: Int32Array, layer_start: Int32Array, crossings: number}}
+ *          `order` holds box indices grouped by column, `layer_start` where each column begins in
+ *          it, and `rank` where each box sits within its own column.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function layout_order_layers(graph, layer_count, sweeps) {
+    const box_count = graph.box_count;
+
+    const layer_start = new Int32Array(layer_count + 1);
+    const order = new Int32Array(box_count);
+    const rank = new Int32Array(box_count);
+
+    for (let box = 0; box < box_count; box++) {
+        layer_start[graph.box_layer[box] + 1]++;
+    }
+
+    for (let i = 0; i < layer_count; i++) {
+        layer_start[i + 1] += layer_start[i];
+    }
+
+    {
+        const cursor = layer_start.slice(0, layer_count);
+
+        for (let box = 0; box < box_count; box++) {
+            const at = cursor[graph.box_layer[box]]++;
+
+            order[at] = box;
+            rank[box] = at - layer_start[graph.box_layer[box]];
+        }
+    }
+
+    if (layer_count < 2) {
+        return { order, rank, layer_start, crossings: 0 };
+    }
+
+    // links grouped by the boundary they cross, which is the column their source sits in
+    const boundary_start = new Int32Array(layer_count + 1);
+    const boundary_link = new Int32Array(graph.link_count);
+
+    for (let i = 0; i < graph.link_count; i++) {
+        boundary_start[graph.box_layer[graph.link_from[i]] + 1]++;
+    }
+
+    for (let i = 0; i < layer_count; i++) {
+        boundary_start[i + 1] += boundary_start[i];
+    }
+
+    {
+        const cursor = boundary_start.slice(0, layer_count);
+
+        for (let i = 0; i < graph.link_count; i++) {
+            boundary_link[cursor[graph.box_layer[graph.link_from[i]]]++] = i;
+        }
+    }
+
+    // Sized by links rather than by boxes: two ports of one node can both be joined to two ports of
+    // the next, and then a box has more neighbours than the adjacent column has boxes.
+    let widest_degree = 0;
+
+    for (let box = 0; box < box_count; box++) {
+        const in_degree = graph.in_offset[box + 1] - graph.in_offset[box];
+        const out_degree = graph.out_offset[box + 1] - graph.out_offset[box];
+
+        if (in_degree > widest_degree) {
+            widest_degree = in_degree;
+        }
+
+        if (out_degree > widest_degree) {
+            widest_degree = out_degree;
+        }
+    }
+
+    const scratch = {
+        weight: new Float64Array(box_count),
+        neighbours: new Int32Array(widest_degree),
+        sequence: new Int32Array(graph.link_count),
+        merge: new Int32Array(graph.link_count)
+    };
+
+    // Sorted by comparator rather than by one of the `array_quick_sort_by_lookup_*` helpers: those
+    // alias the shared traversal scratch stack, and neither can carry the tie-break, which is what
+    // makes this run give the same answer as the last one.
+    const compare = (a, b) => (scratch.weight[a] - scratch.weight[b]) || (rank[a] - rank[b]);
+
+    // 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]]);
+
+    let best = order.slice();
+    let best_cost = count_crossings(graph, rank, layer_count, boundary_start, boundary_link, by_endpoints, scratch);
+
+    for (let sweep = 0; sweep < sweeps && best_cost > 0; sweep++) {
+        const downward = sweep % 2 === 0;
+        const median = (sweep >> 1) % 2 === 0;
+
+        for (let i = 0; i < layer_count; i++) {
+            // A downward sweep looks at what feeds each box, so it has to visit the columns in the
+            // order they were themselves settled; upward is the mirror of that.
+            const at = downward ? i : layer_count - 1 - i;
+
+            reweigh(graph, order, rank, layer_start, at, downward, median, scratch);
+
+            const start = layer_start[at];
+            const end = layer_start[at + 1];
+
+            order.subarray(start, end).sort(compare);
+
+            for (let k = start; k < end; k++) {
+                rank[order[k]] = k - start;
+            }
+        }
+
+        exchange(graph, order, rank, layer_start, layer_count);
+
+        const cost = count_crossings(graph, rank, layer_count, boundary_start, boundary_link, by_endpoints, scratch);
+
+        if (cost < best_cost) {
+            best_cost = cost;
+            best.set(order);
+        }
+    }
+
+    order.set(best);
+
+    for (let i = 0; i < layer_count; i++) {
+        for (let k = layer_start[i]; k < layer_start[i + 1]; k++) {
+            rank[order[k]] = k - layer_start[i];
+        }
+    }
+
+    return { order, rank, layer_start, crossings: best_cost };
+}
+
+/**
+ * Give every box in one column a position to be sorted by, taken from where its neighbours in the
+ * adjacent column sit.
+ *
+ * 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
+ * it anywhere.
+ *
+ * @param {LayoutBoxGraph} graph
+ * @param {Int32Array} order
+ * @param {Int32Array} rank
+ * @param {Int32Array} layer_start
+ * @param {number} at column index
+ * @param {boolean} downward look at what feeds each box, rather than what it feeds
+ * @param {boolean} median take the median rather than the average
+ * @param {object} scratch
+ * @returns {void}
+ */
+function reweigh(graph, order, rank, layer_start, at, downward, median, scratch) {
+    const weight = scratch.weight;
+    const neighbours = scratch.neighbours;
+
+    for (let k = layer_start[at]; k < layer_start[at + 1]; k++) {
+        const box = order[k];
+
+        const start = downward ? graph.in_offset[box] : graph.out_offset[box];
+        const end = downward ? graph.in_offset[box + 1] : graph.out_offset[box + 1];
+
+        const count = end - start;
+
+        if (count === 0) {
+            weight[box] = rank[box];
+
+            continue;
+        }
+
+        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]];
+        }
+
+        if (!median) {
+            let total = 0;
+
+            for (let i = 0; i < count; i++) {
+                total += neighbours[i];
+            }
+
+            weight[box] = total / count;
+
+            continue;
+        }
+
+        const window = neighbours.subarray(0, count);
+
+        window.sort();
+
+        const middle = count >> 1;
+
+        // Not `computeStatisticalPartialMedian`: that copies the array it is given, and this runs
+        // once per box per sweep. It also takes the lower of the two middles, where what is wanted
+        // here is the point between them — a box with two neighbours belongs between them, not
+        // level with the upper one.
+        weight[box] = count % 2 === 1
+            ? window[middle]
+            : (window[middle - 1] + window[middle]) / 2;
+    }
+}
+
+/**
+ * Swap adjacent boxes wherever it removes crossings.
+ *
+ * @param {LayoutBoxGraph} graph
+ * @param {Int32Array} order
+ * @param {Int32Array} rank
+ * @param {Int32Array} layer_start
+ * @param {number} layer_count
+ * @returns {void}
+ */
+function exchange(graph, order, rank, layer_start, layer_count) {
+    for (let round = 0; round < EXCHANGE_ROUNDS; round++) {
+        let swapped = false;
+
+        for (let at = 0; at < layer_count; at++) {
+            const start = layer_start[at];
+            const end = layer_start[at + 1];
+
+            for (let k = start; k + 1 < end; k++) {
+                const a = order[k];
+                const b = order[k + 1];
+
+                if (pair_crossings(graph, rank, b, a) >= pair_crossings(graph, rank, a, b)) {
+                    continue;
+                }
+
+                order[k] = b;
+                order[k + 1] = a;
+
+                rank[b] = k - start;
+                rank[a] = k + 1 - start;
+
+                swapped = true;
+            }
+        }
+
+        if (!swapped) {
+            return;
+        }
+    }
+}
+
+/**
+ * Crossings between the links of two boxes sharing a column, given `first` sits above `second`.
+ *
+ * @param {LayoutBoxGraph} graph
+ * @param {Int32Array} rank
+ * @param {number} first
+ * @param {number} second
+ * @returns {number}
+ */
+function pair_crossings(graph, rank, first, second) {
+    let total = 0;
+
+    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 first_start = offset[first];
+        const first_end = offset[first + 1];
+
+        const second_start = offset[second];
+        const second_end = offset[second + 1];
+
+        for (let i = first_start; i < first_end; i++) {
+            const a = rank[end_of[list[i]]];
+
+            for (let k = second_start; k < second_end; k++) {
+                if (a > rank[end_of[list[k]]]) {
+                    total++;
+                }
+            }
+        }
+    }
+
+    return total;
+}
+
+/**
+ * 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
+ * register as a crossing — they start at the same point and cannot cross. What is left is counted
+ * by inversions.
+ *
+ * @param {LayoutBoxGraph} graph
+ * @param {Int32Array} rank
+ * @param {number} layer_count
+ * @param {Int32Array} boundary_start
+ * @param {Int32Array} boundary_link
+ * @param {function(number, number): number} by_endpoints
+ * @param {object} scratch
+ * @returns {number}
+ */
+function count_crossings(graph, rank, layer_count, boundary_start, boundary_link, by_endpoints, scratch) {
+    const sequence = scratch.sequence;
+
+    let total = 0;
+
+    for (let boundary = 0; boundary + 1 < layer_count; boundary++) {
+        const start = boundary_start[boundary];
+        const end = boundary_start[boundary + 1];
+
+        const count = end - start;
+
+        if (count < 2) {
+            continue;
+        }
+
+        for (let i = 0; i < count; i++) {
+            sequence[i] = boundary_link[start + i];
+        }
+
+        const window = sequence.subarray(0, count);
+
+        window.sort(by_endpoints);
+
+        for (let i = 0; i < count; i++) {
+            window[i] = rank[graph.link_to[window[i]]];
+        }
+
+        total += inversions(window, scratch.merge);
+    }
+
+    return total;
+}
+
+/**
+ * Pairs out of order, by merge sort.
+ *
+ * @param {Int32Array} values consumed; left sorted
+ * @param {Int32Array} buffer at least as long as `values`
+ * @returns {number}
+ */
+function inversions(values, buffer) {
+    const length = values.length;
+
+    let total = 0;
+
+    for (let width = 1; width < length; width *= 2) {
+        for (let low = 0; low < length; low += width * 2) {
+            const middle = low + width < length ? low + width : length;
+            const high = low + width * 2 < length ? low + width * 2 : length;
+
+            if (middle === high) {
+                continue;
+            }
+
+            let left = low;
+            let right = middle;
+            let at = low;
+
+            while (left < middle && right < high) {
+                if (values[left] <= values[right]) {
+                    buffer[at++] = values[left++];
+                } else {
+                    // everything still waiting on the left is greater than this one
+                    total += middle - left;
+
+                    buffer[at++] = values[right++];
+                }
+            }
+
+            while (left < middle) {
+                buffer[at++] = values[left++];
+            }
+
+            while (right < high) {
+                buffer[at++] = values[right++];
+            }
+
+            for (let i = low; i < high; i++) {
+                values[i] = buffer[i];
+            }
+        }
+    }
+
+    return total;
+}

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

@@ -0,0 +1,21 @@
+/**
+ * Turn every backwards link around, so that what is left is a directed acyclic graph.
+ *
+ * Every stage after this one — layering, ordering, coordinates — is written against a graph that
+ * flows one way, and none of them has a sensible answer for a cycle. Reversing the links the
+ * ordering stage identified as backwards is what makes that assumption true, and it is the whole
+ * reason {@link layout_break_cycles} runs first.
+ *
+ * The reversal is only a placement fiction. Nothing is drawn from the links: a wire is drawn
+ * between the two ports of its connection, which are unchanged, and it simply runs right to left.
+ * Which links were turned is therefore not worth recording — nothing downstream asks.
+ *
+ * @param {LayoutBoxGraph} graph mutated in place; adjacency is invalidated
+ * @param {Int32Array} position from {@link layout_break_cycles}
+ * @returns {number} how many links were turned
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function layout_orient_links(graph: LayoutBoxGraph, position: Int32Array): number;
+//# sourceMappingURL=layout_orient_links.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"layout_orient_links.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/model/node-graph/visual/layout/layout_orient_links.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,qEANW,UAAU,GACR,MAAM,CAkClB"}

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

@@ -0,0 +1,49 @@
+/**
+ * Turn every backwards link around, so that what is left is a directed acyclic graph.
+ *
+ * Every stage after this one — layering, ordering, coordinates — is written against a graph that
+ * flows one way, and none of them has a sensible answer for a cycle. Reversing the links the
+ * ordering stage identified as backwards is what makes that assumption true, and it is the whole
+ * reason {@link layout_break_cycles} runs first.
+ *
+ * The reversal is only a placement fiction. Nothing is drawn from the links: a wire is drawn
+ * between the two ports of its connection, which are unchanged, and it simply runs right to left.
+ * Which links were turned is therefore not worth recording — nothing downstream asks.
+ *
+ * @param {LayoutBoxGraph} graph mutated in place; adjacency is invalidated
+ * @param {Int32Array} position from {@link layout_break_cycles}
+ * @returns {number} how many links were turned
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function layout_orient_links(graph, position) {
+    const link_count = graph.link_count;
+
+    let reversed = 0;
+
+    for (let i = 0; i < link_count; i++) {
+        const from = graph.link_from[i];
+        const to = graph.link_to[i];
+
+        if (position[from] <= position[to]) {
+            continue;
+        }
+
+        graph.link_from[i] = to;
+        graph.link_to[i] = from;
+
+        const from_y = graph.link_from_y[i];
+
+        graph.link_from_y[i] = graph.link_to_y[i];
+        graph.link_to_y[i] = from_y;
+
+        reversed++;
+    }
+
+    if (reversed > 0) {
+        graph.build_adjacency();
+    }
+
+    return reversed;
+}

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

@@ -0,0 +1,41 @@
+/**
+ * Route every wire, letting them argue over the space until they stop.
+ *
+ * This is negotiated congestion routing — PathFinder. Every wire is routed as if the lines other
+ * wires are on merely cost a little extra rather than being forbidden, and then the whole set is
+ * ripped up and routed again with the price raised. A wire that had somewhere else to go moves; a
+ * wire with nowhere else stays and the others give way around it. Repeat until nothing is shared.
+ *
+ * The reason to do it this way rather than routing wires one at a time and forbidding what is
+ * already taken is that forbidding makes the *order* decide the drawing. The first wire routed gets
+ * the straight line through the middle and everything after it detours, whether or not it was the
+ * one that needed it. Negotiation asks each wire how much it wants the space, by seeing which of
+ * them finds an alternative when the price goes up, and that question has an answer that does not
+ * depend on who was asked first.
+ *
+ * **History is what makes it settle.** Charging only for what is currently occupied makes two wires
+ * swap routes every round for ever, each taking the one the other has just left. A line that has
+ * been fought over stays expensive after it is vacated, so the second time round the pair separates
+ * instead of trading.
+ *
+ * **Only the wires in an argument are asked again.** After the first round, a wire whose route
+ * shares nothing with anybody has already got what it wanted and is left alone; the rounds after
+ * the first cost what the remaining conflicts cost rather than what the whole graph costs. Without
+ * 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.
+ *
+ * @see McMurchie, Ebeling — *PathFinder: A Negotiation-Based Performance-Driven Router for FPGAs*
+ *      (1995)
+ *
+ * @param {LayoutProblem} problem placement must be finished
+ * @param {RouteGrid} grid
+ * @param {NodeGraphLayoutOptions} options
+ * @returns {RouteSet}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function route_connections(problem: LayoutProblem, grid: RouteGrid, options: NodeGraphLayoutOptions): RouteSet;
+import { NodeGraphLayoutOptions } from "./NodeGraphLayoutOptions.js";
+import { RouteSet } from "./RouteSet.js";
+//# sourceMappingURL=route_connections.d.ts.map

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

@@ -0,0 +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"}