@woosh/meep-engine 3.15.0 → 3.16.0

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

@@ -0,0 +1,309 @@
+import { LAYOUT_SIDE_BOTTOM, LAYOUT_SIDE_LEFT, LAYOUT_SIDE_RIGHT, LAYOUT_SIDE_TOP } from "./LayoutProblem.js";
+import { NodeGraphLayoutOptions } from "./NodeGraphLayoutOptions.js";
+import { ROUTE_AXIS_H, ROUTE_AXIS_V, RouteSearch } from "./RouteSearch.js";
+import { RouteSet } from "./RouteSet.js";
+
+/**
+ * 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, grid, options) {
+    const count = problem.connection_count;
+
+    const routes = new RouteSet(count);
+
+    if (count === 0) {
+        return routes;
+    }
+
+    const search = new RouteSearch(grid);
+
+    // present cost rises between rounds, and the caller's options are not ours to change
+    const working = NodeGraphLayoutOptions.from(options);
+
+    const start_vertex = new Int32Array(count);
+    const start_axis = new Uint8Array(count);
+    const goal_vertex = new Int32Array(count);
+    const goal_axis = new Uint8Array(count);
+
+    const port_x = new Float64Array(count * 2);
+    const port_y = new Float64Array(count * 2);
+
+    const escape_x = new Float64Array(count * 2);
+    const escape_y = new Float64Array(count * 2);
+
+    const terminal = { port_x, port_y, escape_x, escape_y };
+
+    for (let i = 0; i < count; i++) {
+        write_terminal(problem, grid, options, i, true, start_vertex, start_axis, terminal);
+        write_terminal(problem, grid, options, i, false, goal_vertex, goal_axis, terminal);
+    }
+
+    // Grid vertices of each route as it currently stands, so that a wire can be taken off the grid
+    // before being routed again. Corner points alone are not enough for that — what has to be given
+    // back is every line the wire occupies.
+    const held = [];
+
+    for (let i = 0; i < count; i++) {
+        held.push(null);
+    }
+
+    // Which wires are worth asking again. Everything, to begin with, because nothing is routed yet.
+    const contested = new Uint8Array(count).fill(1);
+
+    for (let round = 0; round < options.congestion_iterations; round++) {
+        for (let i = 0; i < count; i++) {
+            if (contested[i] === 0) {
+                continue;
+            }
+
+            if (held[i] !== null) {
+                occupy(grid, held[i], -1);
+            }
+
+            const found = search.find(start_vertex[i], start_axis[i], goal_vertex[i], goal_axis[i], working);
+
+            if (!found) {
+                held[i] = null;
+
+                continue;
+            }
+
+            const path = search.path.slice(0, search.path_length);
+
+            held[i] = path;
+
+            occupy(grid, path, 1);
+        }
+
+        if (mark_contested(grid, held, contested) === 0) {
+            break;
+        }
+
+        remember(grid, options.history_rate);
+
+        working.present_cost *= options.present_growth;
+    }
+
+    for (let i = 0; i < count; i++) {
+        routes.begin(i);
+
+        routes.push(port_x[i * 2], port_y[i * 2]);
+
+        const path = held[i];
+
+        if (path !== null) {
+            for (let k = 0; k < path.length; k++) {
+                routes.push(grid.xs[path[k] % grid.nx], grid.ys[(path[k] / grid.nx) | 0]);
+            }
+        } else {
+            // Nothing was found — the wire is boxed in, or the search ran out of room to look. It
+            // still has to be drawn, and going out of one port and into the other the way every
+            // other wire does is a better failure than a line through the middle of a node.
+            routes.push(escape_x[i * 2], escape_y[i * 2]);
+            routes.push(escape_x[i * 2 + 1], escape_y[i * 2 + 1]);
+        }
+
+        routes.push(port_x[i * 2 + 1], port_y[i * 2 + 1]);
+
+        routes.end(i);
+    }
+
+    return routes;
+}
+
+/**
+ * Work out where one end of a wire meets the grid.
+ *
+ * A wire does not start at its port, it starts a clearance away from the box on the side the port
+ * is on — the piece between the two is a straight stub, which is what makes it obvious which port
+ * the wire belongs to. That stub is also where the wire's direction comes from: a port on the right
+ * of a box is left horizontally, whatever the wire does afterwards.
+ *
+ * @param {LayoutProblem} problem
+ * @param {RouteGrid} grid
+ * @param {NodeGraphLayoutOptions} options
+ * @param {number} index connection
+ * @param {boolean} leaving
+ * @param {Int32Array} vertex written
+ * @param {Uint8Array} axis written
+ * @param {{port_x: Float64Array, port_y: Float64Array, escape_x: Float64Array, escape_y: Float64Array}} terminal
+ *        written, two entries per connection
+ * @returns {void}
+ */
+function write_terminal(problem, grid, options, index, leaving, vertex, axis, terminal) {
+    const boxes = problem.boxes;
+
+    const box = leaving ? problem.from_box[index] : problem.to_box[index];
+    const side = leaving ? problem.from_side[index] : problem.to_side[index];
+
+    const x = boxes.box_x[box] + (leaving ? problem.from_dx[index] : problem.to_dx[index]);
+    const y = boxes.box_y[box] + (leaving ? problem.from_dy[index] : problem.to_dy[index]);
+
+    const at = index * 2 + (leaving ? 0 : 1);
+
+    terminal.port_x[at] = x;
+    terminal.port_y[at] = y;
+
+    const clearance = options.clearance;
+
+    let escape_x = x;
+    let escape_y = y;
+
+    switch (side) {
+        case LAYOUT_SIDE_LEFT:
+            escape_x = boxes.box_x[box] - clearance;
+            break;
+        case LAYOUT_SIDE_RIGHT:
+            escape_x = boxes.box_x[box] + boxes.box_w[box] + clearance;
+            break;
+        case LAYOUT_SIDE_TOP:
+            escape_y = boxes.box_y[box] - clearance;
+            break;
+        case LAYOUT_SIDE_BOTTOM:
+            escape_y = boxes.box_y[box] + boxes.box_h[box] + clearance;
+            break;
+    }
+
+    terminal.escape_x[at] = escape_x;
+    terminal.escape_y[at] = escape_y;
+
+    vertex[index] = grid.nearest_x(escape_x) + grid.nearest_y(escape_y) * grid.nx;
+
+    axis[index] = side === LAYOUT_SIDE_TOP || side === LAYOUT_SIDE_BOTTOM ? ROUTE_AXIS_V : ROUTE_AXIS_H;
+}
+
+/**
+ * Claim, or give back, every line a route runs along.
+ *
+ * Only what is on the grid is claimed. The stub between a port and the grid is not on it and is
+ * never charged, which is what lets several wires leave one port: they share that stub whatever it
+ * would cost, having no say in where their own port is, and they are only asked to separate once
+ * they are somewhere they could have chosen.
+ *
+ * @param {RouteGrid} grid
+ * @param {Int32Array} path grid vertices
+ * @param {number} delta 1 to claim, -1 to give back
+ * @returns {void}
+ */
+function occupy(grid, path, delta) {
+    const nx = grid.nx;
+
+    for (let i = 0; i + 1 < path.length; i++) {
+        const a = path[i];
+        const b = path[i + 1];
+
+        if (b === a + 1) {
+            grid.use_h[a] += delta;
+        } else if (a === b + 1) {
+            grid.use_h[b] += delta;
+        } else if (b === a + nx) {
+            grid.use_v[a] += delta;
+        } else {
+            grid.use_v[b] += delta;
+        }
+    }
+}
+
+/**
+ * Say which wires are still sharing a line with somebody, and how many wires that is.
+ *
+ * A wire is asked to look again only when some part of its own route is contested. One that is
+ * clear of everybody has already found what it wanted, and re-deriving it costs a full search to
+ * arrive back where it started.
+ *
+ * @param {RouteGrid} grid
+ * @param {(Int32Array|null)[]} held
+ * @param {Uint8Array} contested written
+ * @returns {number} wires still sharing a line
+ */
+function mark_contested(grid, held, contested) {
+    const nx = grid.nx;
+
+    let total = 0;
+
+    for (let i = 0; i < held.length; i++) {
+        const path = held[i];
+
+        if (path === null) {
+            // No route was found for it. Congestion is not what it is waiting for, but the grid it
+            // failed on is not the grid the next round presents, so it gets asked again rather than
+            // being written off on the strength of one attempt.
+            contested[i] = 1;
+
+            continue;
+        }
+
+        contested[i] = 0;
+
+        for (let k = 0; k + 1 < path.length; k++) {
+            const a = path[k];
+            const b = path[k + 1];
+
+            const shared = b === a + 1 ? grid.use_h[a] > 1
+                : a === b + 1 ? grid.use_h[b] > 1
+                    : b === a + nx ? grid.use_v[a] > 1
+                        : grid.use_v[b] > 1;
+
+            if (shared) {
+                contested[i] = 1;
+
+                total++;
+
+                break;
+            }
+        }
+    }
+
+    return total;
+}
+
+/**
+ * @param {RouteGrid} grid
+ * @param {number} rate
+ * @returns {void}
+ */
+function remember(grid, rate) {
+    for (let i = 0; i < grid.vertex_count; i++) {
+        if (grid.use_h[i] > 1) {
+            grid.history_h[i] += rate * (grid.use_h[i] - 1);
+        }
+
+        if (grid.use_v[i] > 1) {
+            grid.history_v[i] += rate * (grid.use_v[i] - 1);
+        }
+    }
+}

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

@@ -0,0 +1,33 @@
+/**
+ * Work out which lines wires are allowed to travel along, and mark the boxes solid.
+ *
+ * The lines come from four places, and each of them answers a different question:
+ *
+ * - **Around every box**, a line a clearance outside each of its four edges. This is how a wire
+ *   gets past a box, and how it runs alongside one without appearing to touch it.
+ * - **At every port**, a line at the height it sits at. This is what lets a wire arrive at a port
+ *   horizontally instead of sloping into it, and it is most of the reason the grid is as tall as
+ *   it is.
+ * - **At every lane** the layout reserved. A wire crossing a column it does not stop at was
+ *   promised empty space there; this is the line running through it.
+ * - **Across every channel**, a few evenly spaced tracks. Without them the only places a wire can
+ *   turn in a channel are the box edges either side of it, so every wire turning in that channel
+ *   turns in the same place and they are drawn on top of each other.
+ *
+ * Plus a margin all the way round, which is where a wire running against the flow goes to get past
+ * everything in its way.
+ *
+ * When all of that comes to more grid than the budget allows, the port lines are the ones dropped:
+ * they are the most numerous by far, and losing them costs a short sloped approach at each end
+ * rather than a route that cannot be found.
+ *
+ * @param {LayoutProblem} problem
+ * @param {NodeGraphLayoutOptions} options
+ * @returns {RouteGrid}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function route_grid_build(problem: LayoutProblem, options: NodeGraphLayoutOptions): RouteGrid;
+import { RouteGrid } from "./RouteGrid.js";
+//# sourceMappingURL=route_grid_build.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"route_grid_build.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/model/node-graph/visual/layout/route_grid_build.js"],"names":[],"mappings":"AAeA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,2FALa,SAAS,CA6GrB;0BAlJyB,gBAAgB"}

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

@@ -0,0 +1,237 @@
+import { LAYOUT_BOX_LANE } from "./LayoutBoxGraph.js";
+import { number_compare_ascending } from "../../../../primitives/numbers/number_compare_ascending.js";
+import { LAYOUT_SIDE_BOTTOM, LAYOUT_SIDE_TOP } from "./LayoutProblem.js";
+import { RouteGrid } from "./RouteGrid.js";
+
+/**
+ * Coordinates nearer than this to one already collected are the same coordinate.
+ *
+ * Two lines a fraction of a unit apart are one line to anybody looking at the drawing, and keeping
+ * both of them costs a whole row or column of the grid.
+ *
+ * @type {number}
+ */
+const COORDINATE_EPSILON = 0.5;
+
+/**
+ * Work out which lines wires are allowed to travel along, and mark the boxes solid.
+ *
+ * The lines come from four places, and each of them answers a different question:
+ *
+ * - **Around every box**, a line a clearance outside each of its four edges. This is how a wire
+ *   gets past a box, and how it runs alongside one without appearing to touch it.
+ * - **At every port**, a line at the height it sits at. This is what lets a wire arrive at a port
+ *   horizontally instead of sloping into it, and it is most of the reason the grid is as tall as
+ *   it is.
+ * - **At every lane** the layout reserved. A wire crossing a column it does not stop at was
+ *   promised empty space there; this is the line running through it.
+ * - **Across every channel**, a few evenly spaced tracks. Without them the only places a wire can
+ *   turn in a channel are the box edges either side of it, so every wire turning in that channel
+ *   turns in the same place and they are drawn on top of each other.
+ *
+ * Plus a margin all the way round, which is where a wire running against the flow goes to get past
+ * everything in its way.
+ *
+ * When all of that comes to more grid than the budget allows, the port lines are the ones dropped:
+ * they are the most numerous by far, and losing them costs a short sloped approach at each end
+ * rather than a route that cannot be found.
+ *
+ * @param {LayoutProblem} problem
+ * @param {NodeGraphLayoutOptions} options
+ * @returns {RouteGrid}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function route_grid_build(problem, options) {
+    const boxes = problem.boxes;
+
+    const clearance = options.clearance;
+
+    const xs = [];
+    const ys = [];
+
+    let min_x = Infinity;
+    let min_y = Infinity;
+    let max_x = -Infinity;
+    let max_y = -Infinity;
+
+    for (let box = 0; box < boxes.box_count; box++) {
+        const x0 = boxes.box_x[box];
+        const y0 = boxes.box_y[box];
+        const x1 = x0 + boxes.box_w[box];
+        const y1 = y0 + boxes.box_h[box];
+
+        if (x0 < min_x) {
+            min_x = x0;
+        }
+
+        if (y0 < min_y) {
+            min_y = y0;
+        }
+
+        if (x1 > max_x) {
+            max_x = x1;
+        }
+
+        if (y1 > max_y) {
+            max_y = y1;
+        }
+
+        if (boxes.box_kind[box] === LAYOUT_BOX_LANE) {
+            // A lane is a point, not an obstacle: it is the promise of empty space, so all it
+            // contributes is the line through it.
+            ys.push(y0);
+
+            continue;
+        }
+
+        xs.push(x0 - clearance, x1 + clearance);
+        ys.push(y0 - clearance, y1 + clearance);
+    }
+
+    if (boxes.box_count === 0) {
+        min_x = 0;
+        min_y = 0;
+        max_x = 0;
+        max_y = 0;
+    }
+
+    const margin_x = options.layer_gap;
+    const margin_y = options.node_gap + options.wire_gap;
+
+    xs.push(min_x - margin_x, max_x + margin_x);
+    ys.push(min_y - margin_y, max_y + margin_y);
+
+    add_channel_tracks(xs, boxes, options);
+
+    const port_ys = [];
+
+    for (let i = 0; i < problem.connection_count; i++) {
+        port_ys.push(boxes.box_y[problem.from_box[i]] + problem.from_dy[i]);
+        port_ys.push(boxes.box_y[problem.to_box[i]] + problem.to_dy[i]);
+
+        // A port on the top or bottom edge is left going up or down, so what it needs is a line
+        // along its x rather than its y. There are few of these — a node's inputs and outputs are
+        // on its sides — so they go in unconditionally.
+        if (problem.from_side[i] === LAYOUT_SIDE_TOP || problem.from_side[i] === LAYOUT_SIDE_BOTTOM) {
+            xs.push(boxes.box_x[problem.from_box[i]] + problem.from_dx[i]);
+        }
+
+        if (problem.to_side[i] === LAYOUT_SIDE_TOP || problem.to_side[i] === LAYOUT_SIDE_BOTTOM) {
+            xs.push(boxes.box_x[problem.to_box[i]] + problem.to_dx[i]);
+        }
+    }
+
+    const x_axis = sorted_unique(xs);
+
+    let y_axis = sorted_unique(ys.concat(port_ys));
+
+    if (x_axis.length * y_axis.length > options.max_grid_vertices) {
+        y_axis = sorted_unique(ys);
+    }
+
+    const grid = new RouteGrid(x_axis, y_axis);
+
+    for (let box = 0; box < boxes.box_count; box++) {
+        if (boxes.box_kind[box] === LAYOUT_BOX_LANE) {
+            continue;
+        }
+
+        grid.block_rectangle(
+            boxes.box_x[box] - clearance,
+            boxes.box_y[box] - clearance,
+            boxes.box_x[box] + boxes.box_w[box] + clearance,
+            boxes.box_y[box] + boxes.box_h[box] + clearance
+        );
+    }
+
+    return grid;
+}
+
+/**
+ * Put a few evenly spaced vertical lines in the gap between each pair of neighbouring columns.
+ *
+ * The gap is measured from the boxes rather than taken from the options, because a column is as
+ * wide as its widest box and the narrow ones in it leave more room than the gap alone suggests.
+ *
+ * @param {number[]} xs appended to
+ * @param {LayoutBoxGraph} boxes
+ * @param {NodeGraphLayoutOptions} options
+ * @returns {void}
+ */
+function add_channel_tracks(xs, boxes, options) {
+    let layer_count = 0;
+
+    for (let box = 0; box < boxes.box_count; box++) {
+        if (boxes.box_layer[box] + 1 > layer_count) {
+            layer_count = boxes.box_layer[box] + 1;
+        }
+    }
+
+    if (layer_count < 2) {
+        return;
+    }
+
+    const left = new Float64Array(layer_count).fill(Infinity);
+    const right = new Float64Array(layer_count).fill(-Infinity);
+
+    for (let box = 0; box < boxes.box_count; box++) {
+        if (boxes.box_kind[box] === LAYOUT_BOX_LANE) {
+            continue;
+        }
+
+        const layer = boxes.box_layer[box];
+
+        if (boxes.box_x[box] < left[layer]) {
+            left[layer] = boxes.box_x[box];
+        }
+
+        const edge = boxes.box_x[box] + boxes.box_w[box];
+
+        if (edge > right[layer]) {
+            right[layer] = edge;
+        }
+    }
+
+    const tracks = options.channel_tracks;
+
+    for (let i = 0; i + 1 < layer_count; i++) {
+        const start = right[i];
+        const end = left[i + 1];
+
+        if (!(start < end)) {
+            // a column with no real boxes in it, or columns that touch; nothing to divide
+            continue;
+        }
+
+        for (let k = 1; k <= tracks; k++) {
+            xs.push(start + (end - start) * k / (tracks + 1));
+        }
+    }
+}
+
+/**
+ * @param {number[]} values
+ * @returns {Float64Array}
+ */
+function sorted_unique(values) {
+    values.sort(number_compare_ascending);
+
+    const packed = new Float64Array(values.length);
+
+    let count = 0;
+
+    for (let i = 0; i < values.length; i++) {
+        const value = values[i];
+
+        if (count > 0 && value - packed[count - 1] < COORDINATE_EPSILON) {
+            continue;
+        }
+
+        packed[count++] = value;
+    }
+
+    // a copy rather than a view, so that the room the duplicates took is given back
+    return packed.slice(0, count);
+}

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

@@ -0,0 +1,25 @@
+/**
+ * Pull apart wires that ended up drawn on top of each other.
+ *
+ * The router does most of this itself — negotiating over the lines is exactly the business of not
+ * sharing them — but it cannot always finish. Two wires that genuinely have one route between them
+ * both take it, and what the drawing then shows is one wire where there are two. Congestion has no
+ * answer to that, because there is no second route to move to; the answer is to stop insisting they
+ * are on a line at all and spread them a few units either side of it.
+ *
+ * **Which one goes on which side** is not a free choice. Wires arriving at a shared run from above
+ * and leaving it above have to stay above, or the two of them cross twice for nothing — once to
+ * swap and once to swap back. So a group is ordered by where its members come from and where they
+ * go, and gets spread in that order.
+ *
+ * Only the middle of a wire moves. The two ends meet ports, and a port is where it is.
+ *
+ * @param {RouteSet} routes mutated in place
+ * @param {NodeGraphLayoutOptions} options
+ * @returns {number} how many runs were moved
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function route_nudge(routes: RouteSet, options: NodeGraphLayoutOptions): number;
+//# sourceMappingURL=route_nudge.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"route_nudge.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/model/node-graph/visual/layout/route_nudge.js"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,gFALa,MAAM,CAiElB"}