@bramas/simulant-ui 0.0.0-stage → 0.1.1

package/dist/sim/project.js

@@ -0,0 +1,349 @@
+import { parameterDomainViolations, parameterValues, System } from "@bramas/simulant-engine/system";
+import { checkFirstBranch, checkSetting, checkSettings, stateGraph } from "@bramas/simulant-engine/check";
+import { formatDiagnostic } from "@bramas/simulant-vite-plugin/module";
+import { isRenderer } from "../renderers/define.js";
+import { agentColor, drawRing, ringLayout } from "../renderers/ring.js";
+import { describeExperiment } from "./describe.js";
+import { simExecution } from "./execution.js";
+import { Snapshot } from "./snapshot.js";
+/** Settings with older parameter names renamed (see `SimProjectOptions.aliases`). */
+export function renameSettings(settings, aliases = {}) {
+    if (!settings || typeof settings !== 'object')
+        return settings;
+    const out = {};
+    for (const [k, v] of Object.entries(settings)) {
+        const name = aliases[k];
+        if (name === undefined)
+            out[k] = v;
+        else if (!(name in settings))
+            out[name] = v;
+    }
+    return out;
+}
+/** Settings from the editor (or a URL) to parameter values of the right types. */
+function coerce(value, t) {
+    switch (t.k) {
+        case 'nat':
+        case 'int':
+        case 'node': return typeof value === 'string' ? Number(value) : value;
+        case 'bool': return value === true || value === 'true';
+        case 'list':
+        case 'multiset':
+        case 'record':
+        case 'option': return typeof value === 'string' ? JSON.parse(value) : value;
+        default: return value;
+    }
+}
+/** Whether a setting is a value of the declared type (after coercion). */
+function fits(value, t) {
+    let v;
+    try {
+        v = coerce(value, t);
+    }
+    catch {
+        return false;
+    }
+    switch (t.k) {
+        case 'nat':
+        case 'node': return Number.isInteger(v) && v >= 0;
+        case 'int': return Number.isInteger(v);
+        case 'bool': return typeof value === 'boolean' || value === 'true' || value === 'false';
+        case 'enum': return t.ctors.includes(v);
+        case 'string': return typeof v === 'string';
+        case 'list':
+        case 'multiset': return Array.isArray(v);
+        case 'option': return true;
+        case 'record': return typeof v === 'object' && v !== null && !Array.isArray(v);
+        default: return true;
+    }
+}
+/** The first parameter values of an experiment's domains (the form's defaults). */
+function firstValues(exp) {
+    try {
+        return parameterValues(exp).next().value;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Settings for a new definition of the experiment (plan, Section 6.7): values
+ * of parameters that still exist with a compatible type are kept; the others
+ * are reset to their defaults, and each reset is noted.
+ */
+export function adjustSettings(exp, settings) {
+    if (!settings)
+        return { settings, notes: [] };
+    const first = firstValues(exp) ?? {};
+    const notes = [];
+    const out = {};
+    for (const p of exp.params) {
+        if (!(p.name in settings)) {
+            out[p.name] = first[p.name];
+            notes.push(`new parameter ${p.name} = ${JSON.stringify(first[p.name])}`);
+        }
+        else if (fits(settings[p.name], p.type)) {
+            out[p.name] = settings[p.name];
+        }
+        else {
+            out[p.name] = first[p.name];
+            notes.push(`${p.name} reset from ${JSON.stringify(settings[p.name])} to ${JSON.stringify(first[p.name])}`);
+        }
+    }
+    for (const k of Object.keys(settings)) {
+        if (!exp.params.some(p => p.name === k))
+            notes.push(`parameter ${k} no longer exists`);
+    }
+    return { settings: out, notes };
+}
+function field(name, t, value) {
+    switch (t.k) {
+        case 'nat':
+        case 'int':
+        case 'node': return { type: 'number', key: name, label: name, defaultValue: Number(value ?? 0), ...(t.k === 'int' ? {} : { min: 0 }) };
+        case 'bool': return { type: 'boolean', key: name, label: name, defaultValue: !!value };
+        case 'enum': return { type: 'select', key: name, label: name, defaultValue: String(value ?? t.ctors[0]), options: t.ctors.map(c => ({ value: c, label: c })) };
+        default: return { type: 'text', key: name, label: `${name} (JSON)`, defaultValue: JSON.stringify(value ?? null) };
+    }
+}
+/** The algorithm's definition as written in its file (the viewer shows it as is, with its line numbers). */
+export function algorithmSource(exp, sources) {
+    const src = exp.algorithm.source;
+    const text = src && sources[src.file];
+    const linesOf = (file, from, to) => {
+        const all = (sources[file] ?? '').split('\n');
+        const lines = [];
+        for (let n = from; n <= to; n++)
+            lines.push({ number: n, text: (all[n - 1] ?? '').trimEnd() });
+        while (lines.length && !lines[lines.length - 1].text)
+            lines.pop();
+        return lines;
+    };
+    const lines = src && text ? linesOf(src.file, src.line, src.endLine) : [];
+    // The definitions the algorithm uses, in file order.
+    const definitions = (src?.defs ?? [])
+        .filter(d => sources[d.file] !== undefined)
+        .sort((a, b) => a.file === b.file ? a.line - b.line : a.file < b.file ? -1 : 1)
+        .map(d => ({ name: d.name, file: d.file, lines: linesOf(d.file, d.line, d.endLine) }));
+    return { name: exp.algorithm.name, file: src?.file, lines, ...(definitions.length ? { definitions } : {}) };
+}
+export function simProject(module, experiment, opts = {}) {
+    const draw = opts.draw ?? drawRing;
+    const lazy = (f) => {
+        let done = false, value;
+        return () => { if (!done) {
+            value = f();
+            done = true;
+        } return value; };
+    };
+    const load = (m) => {
+        const exp = m.experiments[experiment];
+        if (!exp)
+            return undefined;
+        const first = lazy(() => firstValues(exp));
+        // Line information only affects the algorithm and model views: an edit that only moves lines redraws.
+        const { line: _line, source: _source, ...algorithm } = exp.algorithm;
+        const { source: _expSource, ...rest } = exp;
+        return {
+            // Lines of expressions (`at`) are display only, like the line table.
+            exp, key: JSON.stringify({ ...rest, algorithm }, (k, v) => k === 'at' ? undefined : v), first,
+            source: algorithmSource(exp, m.sources ?? {}),
+            description: lazy(() => describeExperiment(exp, m.sources ?? {}, m.revision, m.lean?.[experiment])),
+            editorSchema: lazy(() => ({ fields: exp.params.map(p => field(p.name, p.type, first()?.[p.name])) })),
+        };
+    };
+    const errors = (m) => {
+        const own = (m.diagnostics ?? []).filter(d => !d.experiment || d.experiment === experiment).map(formatDiagnostic);
+        return own.length ? own : [`no experiment ${experiment} in the module`];
+    };
+    let current = load(module);
+    let initialErrors = current ? [] : errors(module);
+    let revision = module.revision ?? '';
+    const listeners = new Set();
+    const emit = (u) => { for (const l of listeners)
+        l(u); };
+    module.subscribe?.(next => {
+        revision = next.revision ?? revision;
+        const loaded = load(next);
+        if (!loaded) {
+            emit({ kind: 'failed', revision, diagnostics: errors(next) });
+            return;
+        }
+        const before = current;
+        initialErrors = [];
+        current = loaded;
+        // Same semantics (at most lines moved): the execution goes on; the algorithm view takes the new lines.
+        if (before && before.key === loaded.key) {
+            emit({ kind: 'redraw' });
+            return;
+        }
+        else
+            emit({ kind: 'replaced', revision, adjust: settings => adjustSettings(loaded.exp, renameSettings(settings, opts.aliases)) });
+    });
+    if (isRenderer(draw))
+        draw.subscribe(() => emit({ kind: 'redraw' }));
+    const need = () => {
+        if (!current)
+            throw new Error(initialErrors.join('\n'));
+        return current;
+    };
+    const layouts = new WeakMap();
+    // Lines of agents of a system built before a line-only edit, from the current line table.
+    const lineSystems = new Map();
+    const lineOf = (snapshot, index) => {
+        const cur = need();
+        if (snapshot.system.exp === cur.exp)
+            return snapshot.agents[index].line;
+        const key = `${cur.key.length}:${JSON.stringify(snapshot.system.params)}`;
+        let sys = lineSystems.get(key);
+        if (!sys || sys.exp !== cur.exp) {
+            lineSystems.clear();
+            sys = new System(cur.exp, snapshot.system.params);
+            lineSystems.set(key, sys);
+        }
+        return sys.line(snapshot.config.agents[index]);
+    };
+    const inSource = (line) => {
+        const src = need().exp.algorithm.source;
+        return line !== undefined && (!src || (line >= src.line && line <= src.endLine)) ? line : undefined;
+    };
+    const normalizeSettings = (settings) => renameSettings(settings, opts.aliases);
+    const paramsOf = (given) => {
+        const { exp, first } = need();
+        const settings = normalizeSettings(given);
+        return Object.fromEntries(exp.params.map(p => [p.name, coerce(settings?.[p.name] ?? first()?.[p.name], p.type)]));
+    };
+    // Results carry the revision they were computed for, and their traces adapter paths.
+    const report = (r, rev) => ({
+        status: r.status, reason: r.reason, stats: r.stats, revision: rev,
+        ...(typeof r.settings === 'number' ? { settings: r.settings, graphs: r.graphs } : {}),
+        trace: r.trace && {
+            kind: r.trace.kind, settings: r.trace.settings, path: r.trace.path, cycleStart: r.trace.cycleStart,
+            steps: r.trace.steps.map(s => ({ label: s.label, verdict: s.verdict })),
+        },
+    });
+    const limits = (o = {}) => ({ maxDepth: o.maxDepth, maxStates: o.maxStates });
+    const setup = (settings) => {
+        const { exp } = need();
+        const params = paramsOf(settings);
+        const system = new System(exp, params);
+        return {
+            system, params,
+            info: {
+                experiment, algorithm: exp.algorithm.name, size: system.topo.size, params,
+                components: exp.model.components.map(c => c.name),
+            },
+        };
+    };
+    return {
+        setup: setup,
+        execute: (model) => simExecution(model.system),
+        normalizeSettings,
+        settingsWarnings: settings => {
+            const params = paramsOf(settings);
+            return parameterDomainViolations(need().exp, params)
+                .map(name => `${name} = ${JSON.stringify(params[name])} is outside its declared parameter domain.`);
+        },
+        subscribe: listener => {
+            listeners.add(listener);
+            return () => { listeners.delete(listener); };
+        },
+        revision: () => revision,
+        experiment: () => ({ name: experiment, ir: need().exp }),
+        check: async (settings, o = {}) => {
+            const rev = revision;
+            return report(await checkSetting(need().exp, paramsOf(settings), limits(o), o.signal && { signal: o.signal }), rev);
+        },
+        checkAll: async (o = {}, onProgress) => {
+            const rev = revision;
+            const { exp } = need();
+            return report(await checkSettings(exp, parameterValues(exp), {
+                ...limits(o), shared: !o.perSetting, maxConfigs: o.maxConfigs,
+            }, o.signal && { signal: o.signal }, onProgress), rev);
+        },
+        checkFirstBranch: (settings, o = {}) => report(checkFirstBranch(need().exp, paramsOf(settings), limits(o)), revision),
+        stateGraph: (settings, o = {}) => {
+            const { exp } = need();
+            const params = paramsOf(settings);
+            const g = stateGraph(exp, params, limits(o));
+            // States as snapshots, so that `debugConfig` and renderers take them.
+            const system = new System(exp, params);
+            return { ...g, states: g.states.map(s => ({ ...s, config: new Snapshot(s.config, system) })) };
+        },
+        drawConfig: (ctx, snapshot, model, options) => {
+            // The viewer owns the canvas: draw within the given placement, restoring its state.
+            ctx.save();
+            try {
+                const layout = draw(ctx, snapshot, model.info, options);
+                if (layout)
+                    layouts.set(snapshot, layout);
+            }
+            finally {
+                ctx.restore();
+            }
+        },
+        getAgentsRenderInfo: (snapshot, _model, centerX, centerY, radius) => opts.draw ? layouts.get(snapshot)?.agents ?? [] : ringLayout(snapshot, { centerX, centerY, radius }).agents,
+        debugConfig: (snapshot) => {
+            const nodes = Array.from({ length: snapshot.size }, (_, n) => {
+                const here = snapshot.get(n).agents.map(a => `${a.id}${a.correct ? '' : '!'}`);
+                return here.length ? here.join(',') : '.';
+            });
+            return `${nodes.join('|')} ${JSON.stringify(snapshot.world)}`;
+        },
+        // The current UI stops at `success` and `failure`. Only under the goal `eventually` is a
+        // success final; under the other goals, executions go on (the explorer decides them).
+        stateKey: (snapshot) => snapshot.system.key(snapshot.config),
+        verdict: (snapshot, model) => ({ verdict: model.system.verdict(snapshot.config), goal: model.system.exp.task.goal }),
+        executionStatusChecker: (snapshot, model) => {
+            const v = model.system.verdict(snapshot.config);
+            return v === 'success' && model.system.exp.task.goal !== 'eventually' ? 'inProgress' : v;
+        },
+        settingsGenerator: function* () {
+            if (current)
+                yield* parameterValues(current.exp);
+        },
+        get editorSchema() {
+            return current?.editorSchema() ?? { fields: [] };
+        },
+        inspect: (snapshot, model) => ({
+            world: { ...snapshot.world },
+            params: { ...model.params },
+            agents: snapshot.agents
+                .map((a, i) => ({ a, i }))
+                .sort((x, y) => x.a.id - y.a.id)
+                .map(({ a, i }) => ({
+                id: a.id,
+                name: opts.agentName?.(a.id) ?? `a${a.id}`,
+                color: agentColor(a.id),
+                status: !a.present ? 'hidden' : a.correct ? 'correct' : 'faulty',
+                value: {
+                    position: a.pos,
+                    // Outside the algorithm's definition (the idling of a lag), the agent is idle; without a
+                    // line table (no memory), the algorithm view shows where the last step decided.
+                    ...(a.present && lineOf(snapshot, i) !== undefined ? { line: inSource(lineOf(snapshot, i)) ?? 'idle' } : {}),
+                    flags: a.flags,
+                    ...a.fields,
+                    pub: a.pub,
+                    mem: a.mem,
+                },
+            })),
+        }),
+        describe: () => need().description(),
+        getAlgorithmViewInfo: (snapshot) => ({
+            source: need().source,
+            // Hidden agents (such as those the black hole destroyed) run no line; the others by id.
+            agents: snapshot.agents
+                .map((a, i) => ({ a, i }))
+                .filter(({ a }) => a.present)
+                .sort((x, y) => x.a.id - y.a.id)
+                .map(({ a, i }) => ({
+                agentId: opts.agentName?.(a.id) ?? `a${a.id}`,
+                index: i,
+                line: lineOf(snapshot, i) ?? 0,
+                // From the current definition: program-counter values survive an edit that only moves lines.
+                calls: need().exp.algorithm.source?.calls?.[snapshot.config.agents[i].mem?.pc ?? 'start'] ?? [],
+                color: agentColor(a.id),
+            })),
+        }),
+    };
+}

package/dist/sim/snapshot.js

@@ -0,0 +1,29 @@
+export class Snapshot {
+    config;
+    system;
+    agents;
+    world;
+    size;
+    constructor(config, system) {
+        this.config = config;
+        this.system = system;
+        const flagNames = system.lay.flags.map(f => f.name);
+        this.size = system.topo.size;
+        this.world = config.world;
+        this.agents = config.agents.map((a, index) => {
+            const flags = Object.fromEntries(flagNames.map(f => [f, !!a.f[f]]));
+            const id = typeof a.pub?.id === 'number' ? a.pub.id : index;
+            return {
+                index, id, pos: a.pos, flags,
+                fields: Object.fromEntries(Object.entries(a.f).filter(([k]) => !flagNames.includes(k))),
+                pub: a.pub, mem: a.mem, line: system.line(a),
+                correct: system.rt.correct(a), present: system.rt.present(a),
+                _id: id, _pos: a.pos,
+            };
+        });
+    }
+    /** The agents on a node (the former engine's configuration interface, which renderers still use). */
+    get(node) {
+        return { state: null, agents: this.agents.filter(a => a.pos === node) };
+    }
+}

package/dist/sim/types.js

@@ -0,0 +1 @@
+export {};