@bramas/simulant-engine 0.0.0-stage → 0.1.1

package/dist/explorer.js

@@ -0,0 +1,303 @@
+import { Symmetry } from "./symmetry.js";
+export class Explorer {
+    system;
+    opts;
+    states = [];
+    initial = [];
+    /** A concrete configuration of each initial state, before symmetry reduction, and its index. */
+    concreteInitial = new Map();
+    index = new Map();
+    symmetry;
+    goal;
+    incomplete;
+    edges = 0;
+    constructor(system, opts = {}) {
+        this.system = system;
+        this.opts = opts;
+        this.symmetry = new Symmetry(system, { enabled: opts.symmetry !== false });
+        this.goal = system.exp.task.goal;
+    }
+    add(s, depth, parent) {
+        const rep = this.symmetry.trivial ? s : this.symmetry.canonical(s.config, s.key);
+        const known = this.index.get(rep.key);
+        if (known !== undefined)
+            return known;
+        const id = this.states.length;
+        this.states.push({ id, config: rep.config, key: rep.key, depth, verdict: this.system.verdict(rep.config), parent });
+        this.index.set(rep.key, id);
+        return id;
+    }
+    /** Whether the successors of a state matter for the goal. */
+    shouldExpand(s) {
+        if (s.verdict === 'failure')
+            return false;
+        return !(this.goal === 'eventually' && s.verdict === 'success');
+    }
+    run() {
+        const work = this.work();
+        for (;;) {
+            const r = work.next();
+            if (r.done)
+                return r.value;
+        }
+    }
+    /** As `run`, returning to the event loop regularly, so that work can be cancelled (watch mode). */
+    async runAsync(opts = {}) {
+        const work = this.work();
+        const slice = opts.slice ?? 50;
+        const check = () => { if (opts.signal?.aborted)
+            throw opts.signal.reason ?? new Error('aborted'); };
+        check();
+        for (let start = Date.now();;) {
+            const r = work.next();
+            if (r.done)
+                return r.value;
+            check();
+            if (Date.now() - start >= slice) {
+                await new Promise(resolve => setImmediate(resolve));
+                check();
+                start = Date.now();
+            }
+        }
+    }
+    /** The exploration, yielding every few hundred expanded states. */
+    *work() {
+        const { system, opts } = this;
+        const maxDepth = opts.maxDepth ?? Infinity;
+        const maxStates = opts.maxStates ?? Infinity;
+        (opts.initial ?? system.initial()).forEach((s, index) => {
+            const id = this.add(s, 0);
+            if (!this.concreteInitial.has(id)) {
+                this.initial.push(id);
+                this.concreteInitial.set(id, { config: s.config, index });
+            }
+        });
+        const fairScheduler = system.exp.model.round !== 'fsync';
+        for (let cursor = 0; cursor < this.states.length; cursor++) {
+            if ((cursor & 255) === 255)
+                yield;
+            const s = this.states[cursor];
+            if (s.verdict === 'failure') {
+                return this.result('failure', 'a reachable configuration fails the task', this.counterexample('failure', this.pathIds(s.id)));
+            }
+            if (!this.shouldExpand(s))
+                continue;
+            if (s.depth >= maxDepth) {
+                this.incomplete ??= `depth limit ${maxDepth} reached`;
+                continue;
+            }
+            if (this.states.length >= maxStates) {
+                this.incomplete ??= `state limit ${maxStates} reached`;
+                break;
+            }
+            const succ = [];
+            const act = [];
+            const successorIndex = new Map();
+            for (const t of system.successors(s.config)) {
+                const id = this.add(t, s.depth + 1, s.id);
+                const at = successorIndex.get(id);
+                if (at === undefined) {
+                    successorIndex.set(id, succ.length);
+                    succ.push(id);
+                    act.push(new Set(t.activated));
+                }
+                else if (fairScheduler)
+                    for (const i of t.activated)
+                        act[at].add(i);
+            }
+            s.succ = succ;
+            if (fairScheduler)
+                s.act = act;
+            this.edges += succ.length;
+        }
+        const lasso = this.goal === 'safety' ? undefined : this.findLasso(fairScheduler);
+        if (lasso)
+            return this.result('failure', `an execution never satisfies "${this.goal}"`, lasso);
+        if (this.incomplete)
+            return this.result('incomplete', this.incomplete);
+        return this.result('success', 'every admissible execution satisfies the task');
+    }
+    result(status, reason, counterexample) {
+        return {
+            status, reason, counterexample,
+            stats: {
+                states: this.states.length,
+                expanded: this.states.filter(s => s.succ).length,
+                edges: this.edges,
+                maxDepth: this.states.reduce((m, s) => Math.max(m, s.depth), 0),
+                group: this.symmetry.group.length,
+            },
+        };
+    }
+    /** States that may lie on a bad cycle. */
+    inGraph(s) {
+        if (!s.succ)
+            return false;
+        return this.goal === 'eventually' ? s.verdict !== 'success' : true;
+    }
+    findLasso(fairScheduler) {
+        for (const scc of this.sccs()) {
+            const members = new Set(scc);
+            const inside = (u) => this.states[u].succ.map((v, j) => [v, j]).filter(([v]) => members.has(v));
+            const nontrivial = scc.length > 1 || inside(scc[0]).some(([v]) => v === scc[0]);
+            if (!nontrivial)
+                continue;
+            // The bad state the cycle must visit.
+            const bad = this.goal === 'eventually' ? scc[0] : scc.find(u => this.states[u].verdict !== 'success');
+            if (bad === undefined)
+                continue;
+            // Scheduler fairness: every acting agent is activated on some edge of the component.
+            const needed = [];
+            if (fairScheduler) {
+                const C = this.states[scc[0]].config;
+                const acting = C.agents.flatMap((a, i) => this.system.rt.acts(a) === 'never' ? [] : [i]);
+                let fair = true;
+                for (const agent of acting) {
+                    const edge = scc.flatMap(u => inside(u).filter(([, j]) => this.states[u].act[j].has(agent)).map(([v]) => [u, v]))[0];
+                    if (!edge) {
+                        fair = false;
+                        break;
+                    }
+                    needed.push(edge);
+                }
+                if (!fair)
+                    continue;
+            }
+            return this.lasso(bad, members, needed);
+        }
+    }
+    /** Tarjan's algorithm, iteratively, on the states of `inGraph`. */
+    sccs() {
+        const n = this.states.length;
+        const index = new Int32Array(n).fill(-1);
+        const low = new Int32Array(n);
+        const onStack = new Uint8Array(n);
+        const stack = [];
+        const out = [];
+        let counter = 0;
+        for (const root of this.states) {
+            if (!this.inGraph(root) || index[root.id] >= 0)
+                continue;
+            const work = [[root.id, 0]];
+            index[root.id] = low[root.id] = counter++;
+            stack.push(root.id);
+            onStack[root.id] = 1;
+            while (work.length) {
+                const top = work[work.length - 1];
+                const [u, i] = top;
+                const succ = this.states[u].succ;
+                if (i < succ.length) {
+                    top[1]++;
+                    const v = succ[i];
+                    if (!this.inGraph(this.states[v]))
+                        continue;
+                    if (index[v] < 0) {
+                        index[v] = low[v] = counter++;
+                        stack.push(v);
+                        onStack[v] = 1;
+                        work.push([v, 0]);
+                    }
+                    else if (onStack[v]) {
+                        low[u] = Math.min(low[u], index[v]);
+                    }
+                }
+                else {
+                    work.pop();
+                    if (work.length) {
+                        const p = work[work.length - 1][0];
+                        low[p] = Math.min(low[p], low[u]);
+                    }
+                    if (low[u] === index[u]) {
+                        const scc = [];
+                        let w;
+                        do {
+                            w = stack.pop();
+                            onStack[w] = 0;
+                            scc.push(w);
+                        } while (w !== u);
+                        out.push(scc);
+                    }
+                }
+            }
+        }
+        return out;
+    }
+    /** A shortest path inside `members` from `from` to `to` (at least one step when from === to). */
+    route(from, to, members) {
+        const prev = new Map();
+        const queue = [from];
+        for (let c = 0; c < queue.length; c++) {
+            const u = queue[c];
+            for (const v of this.states[u].succ) {
+                if (!members.has(v) || prev.has(v))
+                    continue;
+                prev.set(v, u);
+                if (v === to) {
+                    const path = [v];
+                    let w = u;
+                    while (w !== from) {
+                        path.push(w);
+                        w = prev.get(w);
+                    }
+                    return path.reverse();
+                }
+                queue.push(v);
+            }
+        }
+        throw new Error('no route inside a strongly connected component');
+    }
+    lasso(bad, members, needed) {
+        const prefix = this.pathIds(bad);
+        const cycle = [];
+        let at = bad;
+        for (const [u, v] of needed) {
+            if (u !== at)
+                cycle.push(...this.route(at, u, members));
+            cycle.push(v);
+            at = v;
+        }
+        if (at !== bad || !cycle.length)
+            cycle.push(...this.route(at, bad, members));
+        // The cycle ends at `bad`, which is the start of the loop.
+        const ids = [...prefix, ...cycle.slice(0, -1)];
+        return { ...this.counterexample('lasso', ids, cycle.length ? bad : undefined), cycleStart: prefix.length - 1 };
+    }
+    counterexample(kind, ids, loopTo) {
+        return { kind, steps: this.steps(ids, loopTo), initialIndex: this.concreteInitial.get(ids[0]).index };
+    }
+    pathIds(id) {
+        const ids = [id];
+        while (this.states[ids[0]].parent !== undefined)
+            ids.unshift(this.states[ids[0]].parent);
+        return ids;
+    }
+    /** The key of the state that stores a configuration (its orbit's representative). */
+    repKey(t) {
+        return this.symmetry.trivial ? t.key : this.symmetry.canonical(t.config, t.key).key;
+    }
+    /**
+     * Steps along stored states, replayed concretely: each configuration is the
+     * successor of the previous concrete one that the stored state represents,
+     * so that a path does not jump around the ring.
+     */
+    steps(ids, loopTo) {
+        let concrete = this.concreteInitial.get(ids[0]).config;
+        const steps = [{ state: ids[0], config: concrete, verdict: this.states[ids[0]].verdict, witness: [] }];
+        const follow = (to) => {
+            const target = this.states[to].key;
+            const t = this.system.successors(concrete).find(t => this.repKey(t) === target);
+            if (!t)
+                throw new Error('edge not found');
+            concrete = t.config;
+            steps.push({ state: to, config: t.config, verdict: this.states[to].verdict, witness: t.witness });
+        };
+        for (const id of ids.slice(1))
+            follow(id);
+        if (loopTo !== undefined)
+            follow(loopTo);
+        return steps;
+    }
+}
+export function explore(system, opts = {}) {
+    return new Explorer(system, opts).run();
+}

package/dist/symmetry.js

@@ -0,0 +1,111 @@
+import { mapper } from "./values.js";
+export function derivedGroup(exp) {
+    const { model, task } = exp;
+    const reasons = [];
+    if (model.symmetries === 'none')
+        return { rotations: false, reflections: false, reasons: ['symmetries := none'] };
+    const pieces = [
+        ...model.components.map(c => ({ what: `component ${c.name}`, eq: c.equivariance })),
+        ...model.sensors.map(s => ({ what: `sensor ${s.name}`, eq: s.equivariance })),
+        ...model.components.flatMap(c => (c.sensors ?? []).map(s => ({ what: `sensor ${s.name}`, eq: s.equivariance }))),
+        { what: `task ${task.name}`, eq: task.equivariance },
+    ];
+    let rotations = true;
+    let reflections = true;
+    for (const p of pieces) {
+        if (!p.eq?.rotations) {
+            rotations = false;
+            reasons.push(`${p.what} is not declared rotation-equivariant`);
+        }
+        if (!p.eq?.reflections) {
+            reflections = false;
+            reasons.push(`${p.what} is not declared reflection-equivariant`);
+        }
+    }
+    if (model.frame.kind === 'common') {
+        reflections = false;
+        reasons.push('common chirality: a mirrored configuration behaves differently');
+    }
+    return { rotations, reflections: rotations && reflections, reasons };
+}
+export class Symmetry {
+    system;
+    group;
+    info;
+    transform;
+    constructor(system, opts = {}) {
+        this.system = system;
+        const info = this.info = opts.enabled === false
+            ? { rotations: false, reflections: false, reasons: ['disabled'] }
+            : derivedGroup(system.exp);
+        const all = system.topo.automorphisms();
+        this.group = all.filter(g => g.reflects ? info.reflections : info.rotations);
+        if (!this.group.length)
+            this.group = [all[0]]; // the identity (rotation 0)
+        this.transform = configMapper(system);
+    }
+    get trivial() {
+        return this.group.length === 1;
+    }
+    apply(C, g) {
+        return this.system.canonical(this.transform(C, g));
+    }
+    /** The representative of the orbit of `C` with the smallest key, and `g` with representative = g·C. */
+    canonical(C, key = this.system.key(C)) {
+        let best = { config: C, key, g: this.group[0] };
+        for (let j = 1; j < this.group.length; j++) {
+            const g = this.group[j];
+            const D = this.apply(C, g);
+            const k = this.system.key(D);
+            if (k < best.key)
+                best = { config: D, key: k, g };
+        }
+        return best;
+    }
+}
+/**
+ * The bounded test of an equivariance claim (plan 3.11): for each
+ * configuration C and group element g, the successors of g·C must be g
+ * applied to the successors of C, and the verdict must not change.
+ * Returns a description of each violation.
+ */
+export function equivarianceViolations(system, configs, group) {
+    const transform = configMapper(system);
+    const act = (C, g) => system.canonical(transform(C, g));
+    const keys = (cs) => [...new Set(cs.map(C => system.key(C)))].sort();
+    const out = [];
+    for (const C of configs) {
+        const succ = system.successors(C).map(t => t.config);
+        for (const g of group) {
+            const D = act(C, g);
+            if (system.verdict(D) !== system.verdict(C))
+                out.push(`${g.label}: verdict of ${system.key(C)} changes`);
+            const expected = keys(succ.map(t => act(t, g)));
+            const actual = keys(system.successors(D).map(t => t.config));
+            if (expected.join('\n') !== actual.join('\n'))
+                out.push(`${g.label}: successors of ${system.key(C)} are not mapped to successors`);
+        }
+    }
+    return out;
+}
+/** How an automorphism acts on whole configurations, derived from the composed types. */
+function configMapper(system) {
+    const { lay } = system;
+    const field = (t) => mapper(t);
+    const agentFields = lay.agentFields.map(f => [f.name, field(f.type)]).filter(([, m]) => m);
+    const pub = field(lay.pub);
+    const mem = field(lay.mem);
+    const world = field(lay.worldType);
+    return (C, g) => ({
+        agents: C.agents.map(a => {
+            let f = a.f;
+            if (agentFields.length) {
+                f = { ...f };
+                for (const [n, m] of agentFields)
+                    f[n] = m(a.f[n], g);
+            }
+            return { pos: g.node(a.pos), pub: pub ? pub(a.pub, g) : a.pub, mem: mem ? mem(a.mem, g) : a.mem, f };
+        }),
+        world: world ? world(C.world, g) : C.world,
+    });
+}