@woosh/meep-engine 3.15.0 → 3.17.0

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

@@ -0,0 +1,716 @@
+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.
+ *
+ * **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)
+ *
+ * @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 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 wires = new WireSet(problem, grid, options, { port_x, port_y, escape_x, escape_y });
+
+    routes.net = wires.net;
+
+    // Routes as they currently stand, 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.
+    /** @type {(WireRoute|null)[]} */
+    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) {
+                wires.occupy(i, held[i], -1);
+            }
+
+            held[i] = wires.route(search, i, working);
+
+            if (held[i] !== null) {
+                wires.occupy(i, held[i], 1);
+            }
+        }
+
+        if (mark_contested(grid, held, wires.net, contested) === 0) {
+            break;
+        }
+
+        remember(grid, options.history_rate);
+
+        working.present_cost *= options.present_growth;
+    }
+
+    // Sharing is priced at what the negotiation would have charged had it run out of rounds: an
+    // improvement is not allowed to buy a route with a line the negotiation had already priced a
+    // wire off, and the wires still sharing something pay the same price for it as everyone else.
+    working.present_cost = options.present_cost * options.present_growth ** options.congestion_iterations;
+
+    for (let round = 0; round < options.improvement_rounds; round++) {
+        if (improve(search, wires, held, working) === 0) {
+            break;
+        }
+    }
+
+    for (let i = 0; i < count; i++) {
+        routes.begin(i);
+
+        routes.push(port_x[i * 2], port_y[i * 2]);
+
+        const route = held[i];
+
+        if (route !== null) {
+            const path = route.path;
+
+            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;
+}
+
+/**
+ * One wire's route: its vertices, where each leg of it begins, and what it cost when it was chosen.
+ *
+ * A leg is one search — from the start to the first lane, from lane to lane, from the last lane to
+ * the goal — and the legs share their end points, so `leg[k]` is the index into `path` of the
+ * vertex leg `k` begins at, which is the vertex leg `k - 1` ended at. A wire with no lanes is one
+ * leg.
+ */
+class WireRoute {
+
+    /**
+     * @type {Int32Array}
+     */
+    path;
+
+    /**
+     * Length `legs + 1`; the last entry is `path.length - 1`.
+     * @type {Int32Array}
+     */
+    leg;
+
+    /**
+     * What each wire believed its route cost when it chose it. A wire whose route has since come
+     * to cost more has had something done to it — crossed, or joined on a line — and is the one
+     * worth asking whether it would now rather be elsewhere.
+     * @type {number}
+     */
+    cost;
+
+    /**
+     * @param {Int32Array} path
+     * @param {Int32Array} leg
+     * @param {number} cost
+     */
+    constructor(path, leg, cost) {
+        this.path = path;
+        this.leg = leg;
+        this.cost = cost;
+    }
+}
+
+/**
+ * Every wire's terminals and waypoints, on the grid, and the two things done with them: finding a
+ * wire a route, and putting one on the grid or taking it off.
+ */
+class WireSet {
+
+    /**
+     * @type {RouteGrid}
+     */
+    grid;
+
+    /**
+     * @type {Int32Array}
+     */
+    start_vertex;
+
+    /**
+     * @type {Uint8Array}
+     */
+    start_axis;
+
+    /**
+     * @type {Int32Array}
+     */
+    goal_vertex;
+
+    /**
+     * @type {Uint8Array}
+     */
+    goal_axis;
+
+    /**
+     * Net of each wire: the wires leaving one port share a number. See {@link RouteGrid#owner_h}.
+     * @type {Int32Array}
+     */
+    net;
+
+    /**
+     * Where each wire's waypoints begin in {@link waypoint}. Length `count + 1`.
+     * @type {Int32Array}
+     */
+    waypoint_start;
+
+    /**
+     * Grid vertex of every lane, grouped by wire in the order the wire goes through them.
+     * @type {Int32Array}
+     */
+    waypoint;
+
+    /**
+     * @param {LayoutProblem} problem
+     * @param {RouteGrid} grid
+     * @param {NodeGraphLayoutOptions} options
+     * @param {{port_x: Float64Array, port_y: Float64Array, escape_x: Float64Array, escape_y: Float64Array}} terminal
+     *        written, two entries per connection
+     */
+    constructor(problem, grid, options, terminal) {
+        const count = problem.connection_count;
+
+        this.grid = grid;
+
+        this.start_vertex = new Int32Array(count);
+        this.start_axis = new Uint8Array(count);
+        this.goal_vertex = new Int32Array(count);
+        this.goal_axis = new Uint8Array(count);
+
+        for (let i = 0; i < count; i++) {
+            write_terminal(problem, grid, options, i, true, this.start_vertex, this.start_axis, terminal);
+            write_terminal(problem, grid, options, i, false, this.goal_vertex, this.goal_axis, terminal);
+        }
+
+        // one net per port wires leave from, numbered in the order the ports are first met
+        this.net = new Int32Array(count);
+
+        const net_of_port = new Map();
+
+        for (let i = 0; i < count; i++) {
+            const key = `${problem.from_box[i]}:${problem.from_dx[i]}:${problem.from_dy[i]}`;
+
+            let net = net_of_port.get(key);
+
+            if (net === undefined) {
+                net = net_of_port.size;
+
+                net_of_port.set(key, net);
+            }
+
+            this.net[i] = net;
+        }
+
+        // a problem built by hand, or before placement, has no lanes at all
+        const lane_box = problem.lane_box ?? new Int32Array(0);
+
+        this.waypoint_start = problem.lane_start ?? new Int32Array(count + 1);
+
+        const lane_count = lane_box.length;
+
+        this.waypoint = new Int32Array(lane_count);
+
+        const boxes = problem.boxes;
+
+        for (let k = 0; k < lane_count; k++) {
+            const lane = lane_box[k];
+
+            this.waypoint[k] = grid.nearest_x(boxes.box_x[lane]) + grid.nearest_y(boxes.box_y[lane]) * grid.nx;
+        }
+    }
+
+    /**
+     * Find a wire its route: through its lanes if it has any and they can be reached, free
+     * otherwise.
+     *
+     * @param {RouteSearch} search
+     * @param {number} index wire
+     * @param {NodeGraphLayoutOptions} options
+     * @returns {WireRoute|null} null when no route was found
+     */
+    route(search, index, options) {
+        const first = this.waypoint_start[index];
+        const last = this.waypoint_start[index + 1];
+
+        if (last > first) {
+            const through = this.__route_legs(search, index, options, first, last);
+
+            if (through !== null) {
+                return through;
+            }
+        }
+
+        return this.__route_legs(search, index, options, 0, 0);
+    }
+
+    /**
+     * What a route costs under the grid as it stands, leg by leg. See {@link RouteSearch#cost_of}.
+     *
+     * @param {RouteSearch} search
+     * @param {number} index wire
+     * @param {WireRoute} route its own occupancy must be off the grid
+     * @param {NodeGraphLayoutOptions} options
+     * @returns {number}
+     */
+    cost_of(search, index, route, options) {
+        const path = route.path;
+        const leg = route.leg;
+
+        const legs = leg.length - 1;
+
+        let cost = 0;
+
+        for (let k = 0; k < legs; k++) {
+            const from = leg[k];
+            const to = leg[k + 1];
+
+            cost += search.cost_of(
+                path.subarray(from, to + 1),
+                to + 1 - from,
+                k === 0 ? this.start_axis[index] : ROUTE_AXIS_H,
+                k === legs - 1 ? this.goal_axis[index] : ROUTE_AXIS_H,
+                options,
+                k === legs - 1,
+                this.net[index]
+            );
+        }
+
+        return cost;
+    }
+
+    /**
+     * Claim, or give back, every line a route runs along, and every vertex it goes straight
+     * through.
+     *
+     * 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. The stub does say which way the wire arrives
+     * at the grid, though, and that is what decides whether it goes straight through the vertex
+     * where it meets it — see {@link RouteGrid#through_h}.
+     *
+     * @param {number} index wire
+     * @param {WireRoute} route
+     * @param {number} delta 1 to claim, -1 to give back
+     * @returns {void}
+     */
+    occupy(index, route, delta) {
+        const grid = this.grid;
+
+        const nx = grid.nx;
+
+        const path = route.path;
+
+        const last = path.length - 1;
+
+        const net = this.net[index];
+
+        // the axis the route is on as it arrives at each vertex, beginning with the stub's
+        let arriving = this.start_axis[index];
+
+        for (let i = 0; i <= last; i++) {
+            const a = path[i];
+
+            let leaving;
+
+            if (i === last) {
+                leaving = this.goal_axis[index];
+            } else {
+                const b = path[i + 1];
+
+                if (b === a + 1) {
+                    leaving = ROUTE_AXIS_H;
+                    grid.claim_h(a, net, delta);
+                } else if (a === b + 1) {
+                    leaving = ROUTE_AXIS_H;
+                    grid.claim_h(b, net, delta);
+                } else if (b === a + nx) {
+                    leaving = ROUTE_AXIS_V;
+                    grid.claim_v(a, net, delta);
+                } else {
+                    leaving = ROUTE_AXIS_V;
+                    grid.claim_v(b, net, delta);
+                }
+            }
+
+            if (leaving === arriving) {
+                if (leaving === ROUTE_AXIS_H) {
+                    grid.through_h[a] += delta;
+                } else {
+                    grid.through_v[a] += delta;
+                }
+            }
+
+            arriving = leaving;
+        }
+    }
+
+    /**
+     * Route a wire as a chain of searches through the given waypoints, of which there may be none.
+     *
+     * @param {RouteSearch} search
+     * @param {number} index wire
+     * @param {NodeGraphLayoutOptions} options
+     * @param {number} first index into {@link waypoint}
+     * @param {number} last exclusive
+     * @returns {WireRoute|null}
+     * @private
+     */
+    __route_legs(search, index, options, first, last) {
+        const legs = last - first + 1;
+
+        const leg = new Int32Array(legs + 1);
+
+        let path = null;
+        let length = 0;
+        let cost = 0;
+
+        let at = this.start_vertex[index];
+        let axis = this.start_axis[index];
+
+        for (let k = 0; k < legs; k++) {
+            const final = k === legs - 1;
+
+            const goal = final ? this.goal_vertex[index] : this.waypoint[first + k];
+            const goal_axis = final ? this.goal_axis[index] : ROUTE_AXIS_H;
+
+            if (!search.find(at, axis, goal, goal_axis, options, final, this.net[index])) {
+                return null;
+            }
+
+            const found = search.path;
+            const found_length = search.path_length;
+
+            if (path === null) {
+                path = found.slice(0, found_length);
+                length = found_length;
+            } else {
+                // the leg begins where the last one ended, and that vertex is already in
+                const grown = new Int32Array(length + found_length - 1);
+
+                grown.set(path.subarray(0, length));
+                grown.set(found.subarray(1, found_length), length);
+
+                path = grown;
+                length = grown.length;
+            }
+
+            leg[k + 1] = length - 1;
+
+            cost += search.cost;
+
+            at = goal;
+            axis = ROUTE_AXIS_H;
+        }
+
+        return new WireRoute(path, leg, cost);
+    }
+}
+
+/**
+ * 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;
+}
+
+/**
+ * One round of asking every wire whether it would rather be somewhere else, now that everything
+ * else is routed.
+ *
+ * Each wire is taken off the grid, asked for its cheapest route through what is left, and put back
+ * — on the new route if that is cheaper than the old one under the same grid, on the old one
+ * otherwise. The search is exact, so the new route is never dearer; it is refused when it is merely
+ * no cheaper, which is what keeps the round from moving wires between routes that tie for ever.
+ *
+ * Only the wires something has happened to are asked. A wire's route costs what it did when the
+ * wire chose it until some other wire comes to cross it or to share a line with it, and a wire
+ * whose route still costs what it believed has nothing new to consider: it already took the best
+ * route through the grid it was shown, and that grid has not changed along it. What this misses is
+ * a wire whose surroundings became *cheaper* — a neighbour that moved away — and the round after a
+ * neighbour moves is not the place to chase that; a search is the size of the grid and a wire it
+ * would be spent on is one that was already content. Asking everyone once was tried, and moved
+ * nothing worth the searches.
+ *
+ * A wire that has no route at all is asked again too: the grid it failed on is not the one it is
+ * being offered now.
+ *
+ * @param {RouteSearch} search
+ * @param {WireSet} wires
+ * @param {(WireRoute|null)[]} held current routes, mutated where a wire moves
+ * @param {NodeGraphLayoutOptions} options with the present cost to price sharing at
+ * @returns {number} how many wires moved
+ */
+function improve(search, wires, held, options) {
+    let moved = 0;
+
+    for (let i = 0; i < held.length; i++) {
+        const old = held[i];
+
+        let old_cost = Infinity;
+
+        if (old !== null) {
+            wires.occupy(i, old, -1);
+
+            old_cost = wires.cost_of(search, i, old, options);
+
+            if (old_cost <= old.cost) {
+                // nothing has been done to it since it chose this route
+                wires.occupy(i, old, 1);
+
+                continue;
+            }
+        }
+
+        const found = wires.route(search, i, options);
+
+        if (found !== null && found.cost < old_cost) {
+            held[i] = found;
+
+            moved++;
+        } else if (old !== null) {
+            // what it has is the best it can do here; remember that, so it is not asked again
+            // until something changes
+            old.cost = old_cost;
+        }
+
+        if (held[i] !== null) {
+            wires.occupy(i, held[i], 1);
+        }
+    }
+
+    return moved;
+}
+
+/**
+ * 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 — shared with
+ * a wire of another net; its own net is welcome. 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 {(WireRoute|null)[]} held
+ * @param {Int32Array} net of each wire
+ * @param {Uint8Array} contested written
+ * @returns {number} wires still sharing a line
+ */
+function mark_contested(grid, held, net, contested) {
+    const nx = grid.nx;
+
+    let total = 0;
+
+    for (let i = 0; i < held.length; i++) {
+        const route = held[i];
+
+        if (route === 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;
+
+        const path = route.path;
+
+        for (let k = 0; k + 1 < path.length; k++) {
+            const a = path[k];
+            const b = path[k + 1];
+
+            const shared = b === a + 1 ? grid.foreign_h(a, net[i]) > 0
+                : a === b + 1 ? grid.foreign_h(b, net[i]) > 0
+                    : b === a + nx ? grid.foreign_v(a, net[i]) > 0
+                        : grid.foreign_v(b, net[i]) > 0;
+
+            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++) {
+        // a line is fought over when it holds wires beyond those of the net that holds it
+        const own_h = Math.max(grid.owned_h[i], 1);
+        const own_v = Math.max(grid.owned_v[i], 1);
+
+        if (grid.use_h[i] > own_h) {
+            grid.history_h[i] += rate * (grid.use_h[i] - own_h);
+        }
+
+        if (grid.use_v[i] > own_v) {
+            grid.history_v[i] += rate * (grid.use_v[i] - own_v);
+        }
+    }
+}