@bramas/simulant-ui 0.2.0 → 0.3.0

package/README.md

@@ -45,6 +45,23 @@ Projects can supply a custom drawing function, agent names and aliases for
 older parameter names. Settings outside declared domains produce advisory
 warnings; execution remains available.
 
+Parameter declarations describe model domains, using `in [...]` for exact finite
+sets and `where` for properties. Starting values come from a bounded search,
+with editable typed fallbacks when no match is found. Override them separately
+in the project registry:
+
+```ts
+simProject(model, 'cautiousPair', {
+  defaults: { N: 8, site: 3 },
+  checkSettings: () => [{ N: 5, site: 1 }, { N: 8, site: 3 }],
+});
+```
+
+`checkSettings` supplies finite settings for `check-all` when model domains
+cannot be enumerated. Each setting must include every parameter; settings
+outside the model domains are skipped. Without it, `check-all` enumerates the
+model's finite domains. Defaults never restrict the model or select check settings.
+
 Renderers receive the page's colors in `options.theme` (light or dark): draw
 labels and marks with `theme.foreground` and `theme.muted` so that drawings stay
 readable in both themes. `simulator.css` is the whole stylesheet; the interface

package/dist/SimulatorApp.jsx

@@ -335,7 +335,6 @@ export const SimulatorApp = (props) => {
             return { baseModel, execution: current.execute(baseModel) };
         }
         catch (e) {
-            console.error('Project setup failed:', e);
             setSetupLog(e instanceof Error ? e.message : String(e));
             return { baseModel: null, execution: null };
         }

package/dist/sim/describe.js

@@ -111,10 +111,10 @@ const HOOKS = ['beforeLook', 'beforeMove', 'afterMove'];
 /** Above this many definitions, the algorithm's facts give their number rather than their names. */
 const MANY_DEFS = 6;
 /** Counts the settings of `check-all`, up to `cap`. */
-function countSettings(exp, cap = 10_000) {
+function countSettings(settings, cap = 10_000) {
     let n = 0;
     try {
-        for (const _ of parameterValues(exp))
+        for (const _ of settings())
             if (++n >= cap)
                 return `more than ${cap}`;
     }
@@ -130,7 +130,7 @@ function lineTable(exp) {
         return {};
     return Object.fromEntries(Object.entries(l.cases).flatMap(([pc, e]) => e.e === 'lit' && typeof e.value === 'number' ? [[pc, e.value]] : []));
 }
-export function describeExperiment(exp, sources, revision, lean) {
+export function describeExperiment(exp, sources, revision, lean, checkSettings) {
     const { model, algorithm, task } = exp;
     const key = (kind, name) => `${kind} ${name}`;
     // The declarations as written. Without recorded uses (IR built otherwise), the algorithm alone.
@@ -232,9 +232,9 @@ export function describeExperiment(exp, sources, revision, lean) {
         const i = expItem(new RegExp(`^\\s+param\\s+${p.name}\\b`));
         return {
             label: `param ${p.name}`,
-            value: p.domain ? i?.text ?? 'a domain' : 'no domain (set it in the settings)',
-            code: !!p.domain,
-            note: `of type ${showType(p.type)}`,
+            value: p.domain || p.accepts ? i?.text ?? 'a domain' : `all values of ${showType(p.type)}`,
+            code: !!p.domain || !!p.accepts,
+            note: `of type ${showType(p.type)}${p.accepts ? '; where restricts the domain' : ''}`,
             refs: expRef(i),
         };
     });
@@ -248,7 +248,7 @@ export function describeExperiment(exp, sources, revision, lean) {
                 { label: 'Agents', value: agents?.text ?? 'see the experiment', code: true, refs: expRef(agents) },
                 { label: 'Positions', value: position?.text ?? 'see the experiment', code: true, note: 'Initial position of agent i.', refs: expRef(position) },
                 ...params,
-                { label: 'Settings checked', value: countSettings(exp), note: 'Parameter values enumerated by check-all, from the domains above.' },
+                { label: 'Settings checked', value: countSettings(checkSettings ?? (() => parameterValues(exp))), note: checkSettings ? 'Finite settings supplied by project.ts, filtered through the model domains.' : 'Parameter values enumerated by check-all, from the domains above.' },
                 {
                     label: 'Limits',
                     value: exp.limits ? Object.entries(exp.limits).map(([k, v]) => `${k} ${v}`).join(', ') : 'none',
@@ -379,7 +379,9 @@ export function describeExperiment(exp, sources, revision, lean) {
         library: lean.library.map(l => ({ module: l.module, text: l.text, refs: refTo('component', l.component) })),
     };
     const caveats = [
-        'Checks are bounded: they cover the settings enumerated from the parameter domains, not every ring size.',
+        checkSettings
+            ? 'Checks are bounded: they cover the finite settings supplied by project.ts, not every admissible parameter value.'
+            : 'Checks are bounded: they cover the settings enumerated from the parameter domains, not every ring size.',
         ...(exp.limits ? ['Exploration limits can leave a check incomplete.'] : []),
         ...(algorithm.native ? [`The algorithm's step is native TypeScript (${algorithm.native}): it is not written in .sim and is not translated to Lean.`] : []),
         ...(group.rotations ? ['Symmetry reduction relies on equivariance declarations, which are claims tested on bounded instances.'] : []),

package/dist/sim/project.js

@@ -1,4 +1,4 @@
-import { parameterDomainViolations, parameterValues, System } from "@bramas/simulant-engine/system";
+import { parameterDefaults, 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";
@@ -57,24 +57,15 @@ function fits(value, t) {
         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) {
+export function adjustSettings(exp, settings, defaults = {}) {
     if (!settings)
         return { settings, notes: [] };
-    const first = firstValues(exp) ?? {};
+    const first = parameterDefaults(exp, defaults);
     const notes = [];
     const out = {};
     for (const p of exp.params) {
@@ -129,6 +120,25 @@ export function algorithmSource(exp, sources) {
 }
 export function simProject(module, experiment, opts = {}) {
     const draw = opts.draw ?? drawRing;
+    const defaultsOf = (exp) => Object.fromEntries(exp.params
+        .filter(p => opts.defaults && p.name in opts.defaults)
+        .map(p => [p.name, coerce(opts.defaults[p.name], p.type)]));
+    const coerceSettings = (exp, settings) => Object.fromEntries(exp.params
+        .filter(p => p.name in settings).map(p => [p.name, coerce(settings[p.name], p.type)]));
+    function* settingsFor(exp) {
+        if (!opts.checkSettings) {
+            yield* parameterValues(exp);
+            return;
+        }
+        for (const given of opts.checkSettings(exp)) {
+            const params = coerceSettings(exp, renameSettings(given, opts.aliases));
+            for (const p of exp.params)
+                if (!(p.name in params))
+                    throw new Error(`checkSettings is missing parameter ${p.name}`);
+            if (!parameterDomainViolations(exp, params).length)
+                yield params;
+        }
+    }
     const lazy = (f) => {
         let done = false, value;
         return () => { if (!done) {
@@ -140,7 +150,7 @@ export function simProject(module, experiment, opts = {}) {
         const exp = m.experiments[experiment];
         if (!exp)
             return undefined;
-        const first = lazy(() => firstValues(exp));
+        const first = lazy(() => parameterDefaults(exp, defaultsOf(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;
@@ -148,7 +158,7 @@ export function simProject(module, experiment, opts = {}) {
             // 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])),
+            description: lazy(() => describeExperiment(exp, m.sources ?? {}, m.revision, m.lean?.[experiment], opts.checkSettings && (() => settingsFor(exp)))),
             editorSchema: lazy(() => ({ fields: exp.params.map(p => field(p.name, p.type, first()?.[p.name])) })),
         };
     };
@@ -178,7 +188,7 @@ export function simProject(module, experiment, opts = {}) {
             return;
         }
         else
-            emit({ kind: 'replaced', revision, adjust: settings => adjustSettings(loaded.exp, renameSettings(settings, opts.aliases)) });
+            emit({ kind: 'replaced', revision, adjust: settings => adjustSettings(loaded.exp, renameSettings(settings, opts.aliases), defaultsOf(loaded.exp)) });
     });
     if (isRenderer(draw))
         draw.subscribe(() => emit({ kind: 'redraw' }));
@@ -257,7 +267,7 @@ export function simProject(module, experiment, opts = {}) {
         checkAll: async (o = {}, onProgress) => {
             const rev = revision;
             const { exp } = need();
-            return report(await checkSettings(exp, parameterValues(exp), {
+            return report(await checkSettings(exp, settingsFor(exp), {
                 ...limits(o), shared: !o.perSetting, maxConfigs: o.maxConfigs,
             }, o.signal && { signal: o.signal }, onProgress), rev);
         },
@@ -300,7 +310,7 @@ export function simProject(module, experiment, opts = {}) {
         },
         settingsGenerator: function* () {
             if (current)
-                yield* parameterValues(current.exp);
+                yield* settingsFor(current.exp);
         },
         get editorSchema() {
             return current?.editorSchema() ?? { fields: [] };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bramas/simulant-ui",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "private": false,
   "license": "CECILL-B",
   "type": "module",
@@ -31,11 +31,11 @@
     }
   },
   "dependencies": {
-    "@bramas/simulant-core": "0.2.0",
-    "@bramas/simulant-lang": "0.2.0",
-    "@bramas/simulant-lean-gen": "0.2.0",
-    "@bramas/simulant-engine": "0.2.0",
-    "@bramas/simulant-vite-plugin": "0.2.0"
+    "@bramas/simulant-lang": "0.3.0",
+    "@bramas/simulant-core": "0.3.0",
+    "@bramas/simulant-engine": "0.3.0",
+    "@bramas/simulant-lean-gen": "0.3.0",
+    "@bramas/simulant-vite-plugin": "0.3.0"
   },
   "peerDependencies": {
     "solid-js": "^1.9.3"

package/src/SimulatorApp.tsx

@@ -371,7 +371,6 @@ export const SimulatorApp: Component<SimulatorAppProps> = (props) => {
       setSetupLog('');
       return { baseModel, execution: current.execute(baseModel) };
     } catch (e) {
-      console.error('Project setup failed:', e);
       setSetupLog(e instanceof Error ? e.message : String(e));
       return { baseModel: null, execution: null };
     }

package/src/sim/describe.ts

@@ -115,10 +115,10 @@ const HOOKS = ['beforeLook', 'beforeMove', 'afterMove'] as const;
 const MANY_DEFS = 6;
 
 /** Counts the settings of `check-all`, up to `cap`. */
-function countSettings(exp: Experiment, cap = 10_000): string {
+function countSettings(settings: () => Iterable<unknown>, cap = 10_000): string {
   let n = 0;
   try {
-    for (const _ of parameterValues(exp)) if (++n >= cap) return `more than ${cap}`;
+    for (const _ of settings()) if (++n >= cap) return `more than ${cap}`;
   } catch {
     return 'unknown (a domain cannot be enumerated)';
   }
@@ -132,7 +132,7 @@ function lineTable(exp: Experiment): Record<string, number> {
   return Object.fromEntries(Object.entries(l.cases).flatMap(([pc, e]) => e.e === 'lit' && typeof e.value === 'number' ? [[pc, e.value]] : []));
 }
 
-export function describeExperiment(exp: Experiment, sources: Record<string, string>, revision?: string, lean?: SimLean): ModelDescription {
+export function describeExperiment(exp: Experiment, sources: Record<string, string>, revision?: string, lean?: SimLean, checkSettings?: () => Iterable<unknown>): ModelDescription {
   const { model, algorithm, task } = exp;
   const key = (kind: string, name: string) => `${kind} ${name}`;
 
@@ -235,9 +235,9 @@ export function describeExperiment(exp: Experiment, sources: Record<string, stri
     const i = expItem(new RegExp(`^\\s+param\\s+${p.name}\\b`));
     return {
       label: `param ${p.name}`,
-      value: p.domain ? i?.text ?? 'a domain' : 'no domain (set it in the settings)',
-      code: !!p.domain,
-      note: `of type ${showType(p.type)}`,
+      value: p.domain || p.accepts ? i?.text ?? 'a domain' : `all values of ${showType(p.type)}`,
+      code: !!p.domain || !!p.accepts,
+      note: `of type ${showType(p.type)}${p.accepts ? '; where restricts the domain' : ''}`,
       refs: expRef(i),
     };
   });
@@ -252,7 +252,7 @@ export function describeExperiment(exp: Experiment, sources: Record<string, stri
         { label: 'Agents', value: agents?.text ?? 'see the experiment', code: true, refs: expRef(agents) },
         { label: 'Positions', value: position?.text ?? 'see the experiment', code: true, note: 'Initial position of agent i.', refs: expRef(position) },
         ...params,
-        { label: 'Settings checked', value: countSettings(exp), note: 'Parameter values enumerated by check-all, from the domains above.' },
+        { label: 'Settings checked', value: countSettings(checkSettings ?? (() => parameterValues(exp))), note: checkSettings ? 'Finite settings supplied by project.ts, filtered through the model domains.' : 'Parameter values enumerated by check-all, from the domains above.' },
         {
           label: 'Limits',
           value: exp.limits ? Object.entries(exp.limits).map(([k, v]) => `${k} ${v}`).join(', ') : 'none',
@@ -386,7 +386,9 @@ export function describeExperiment(exp: Experiment, sources: Record<string, stri
   };
 
   const caveats = [
-    'Checks are bounded: they cover the settings enumerated from the parameter domains, not every ring size.',
+    checkSettings
+      ? 'Checks are bounded: they cover the finite settings supplied by project.ts, not every admissible parameter value.'
+      : 'Checks are bounded: they cover the settings enumerated from the parameter domains, not every ring size.',
     ...(exp.limits ? ['Exploration limits can leave a check incomplete.'] : []),
     ...(algorithm.native ? [`The algorithm's step is native TypeScript (${algorithm.native}): it is not written in .sim and is not translated to Lean.`] : []),
     ...(group.rotations ? ['Symmetry reduction relies on equivariance declarations, which are claims tested on bounded instances.'] : []),

package/src/sim/project.ts

@@ -6,7 +6,7 @@
  * `draw`, the algorithm view from the algorithm's source and line table.
  */
 import type { Experiment, Type } from '@bramas/simulant-lang/ir';
-import { parameterDomainViolations, parameterValues, System } from '@bramas/simulant-engine/system';
+import { parameterDefaults, parameterDomainViolations, parameterValues, System } from '@bramas/simulant-engine/system';
 import { checkFirstBranch, checkSetting, checkSettings, stateGraph, type CheckResult } from '@bramas/simulant-engine/check';
 import type { EditorField, EditorSchema } from '@bramas/simulant-core/types/editor-schema';
 import type { AlgorithmSource, CheckOptions, ModelDescription, ProjectType, ProjectUpdate } from '@bramas/simulant-core/types/project';
@@ -41,6 +41,10 @@ export type SimProjectOptions = {
    * `{ BH_node: 'site' }` reads `BH_node` as `site` when `site` is not given.
    */
   aliases?: Record<string, string>;
+  /** Simulator starting values, independent of the model's parameter domains. */
+  defaults?: Record<string, unknown>;
+  /** Finite settings for check-all when the model's domains cannot be enumerated. */
+  checkSettings?: (experiment: Experiment) => Iterable<Record<string, unknown>>;
 };
 
 /** Settings with older parameter names renamed (see `SimProjectOptions.aliases`). */
@@ -86,23 +90,14 @@ function fits(value: unknown, t: Type): boolean {
   }
 }
 
-/** The first parameter values of an experiment's domains (the form's defaults). */
-function firstValues(exp: Experiment): Record<string, unknown> | undefined {
-  try {
-    return parameterValues(exp).next().value as Record<string, unknown> | undefined;
-  } 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: Experiment, settings: Record<string, unknown> | null): { settings: Record<string, unknown> | null; notes: string[] } {
+export function adjustSettings(exp: Experiment, settings: Record<string, unknown> | null, defaults: Record<string, unknown> = {}): { settings: Record<string, unknown> | null; notes: string[] } {
   if (!settings) return { settings, notes: [] };
-  const first = firstValues(exp) ?? {};
+  const first = parameterDefaults(exp, defaults);
   const notes: string[] = [];
   const out: Record<string, unknown> = {};
   for (const p of exp.params) {
@@ -153,12 +148,25 @@ export function algorithmSource(exp: Experiment, sources: Record<string, string>
 
 export function simProject(module: SimSources, experiment: string, opts: SimProjectOptions = {}): ProjectType<any, any> {
   const draw = opts.draw ?? drawRing;
+  const defaultsOf = (exp: Experiment) => Object.fromEntries(exp.params
+    .filter(p => opts.defaults && p.name in opts.defaults)
+    .map(p => [p.name, coerce(opts.defaults![p.name], p.type)]));
+  const coerceSettings = (exp: Experiment, settings: Record<string, unknown>) => Object.fromEntries(exp.params
+    .filter(p => p.name in settings).map(p => [p.name, coerce(settings[p.name], p.type)]));
+  function* settingsFor(exp: Experiment) {
+    if (!opts.checkSettings) { yield* parameterValues(exp); return; }
+    for (const given of opts.checkSettings(exp)) {
+      const params = coerceSettings(exp, renameSettings(given, opts.aliases));
+      for (const p of exp.params) if (!(p.name in params)) throw new Error(`checkSettings is missing parameter ${p.name}`);
+      if (!parameterDomainViolations(exp, params).length) yield params;
+    }
+  }
 
   // What the project runs: the last definition that compiled, replaced on hot updates.
   type Current = {
     exp: Experiment; key: string;
-    /** The defaults, computed when first needed (a domain may take time to enumerate). */
-    first: () => Record<string, unknown> | undefined; editorSchema: () => EditorSchema;
+    /** Defaults are computed lazily; explicit domains may take time to evaluate. */
+    first: () => Record<string, unknown>; editorSchema: () => EditorSchema;
     source: AlgorithmSource;
     description: () => ModelDescription;
   };
@@ -169,7 +177,7 @@ export function simProject(module: SimSources, experiment: string, opts: SimProj
   const load = (m: SimSources): Current | undefined => {
     const exp = m.experiments[experiment];
     if (!exp) return undefined;
-    const first = lazy(() => firstValues(exp));
+    const first = lazy(() => parameterDefaults(exp, defaultsOf(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;
@@ -177,7 +185,7 @@ export function simProject(module: SimSources, experiment: string, opts: SimProj
       // 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])),
+      description: lazy(() => describeExperiment(exp, m.sources ?? {}, m.revision, m.lean?.[experiment], opts.checkSettings && (() => settingsFor(exp)))),
       editorSchema: lazy(() => ({ fields: exp.params.map(p => field(p.name, p.type, first()?.[p.name])) })),
     };
   };
@@ -206,7 +214,7 @@ export function simProject(module: SimSources, experiment: string, opts: SimProj
       emit({ kind: 'redraw' });
       return;
     }
-    else emit({ kind: 'replaced', revision, adjust: settings => adjustSettings(loaded.exp, renameSettings(settings, opts.aliases)) });
+    else emit({ kind: 'replaced', revision, adjust: settings => adjustSettings(loaded.exp, renameSettings(settings, opts.aliases), defaultsOf(loaded.exp)) });
   });
   if (isRenderer(draw)) draw.subscribe(() => emit({ kind: 'redraw' }));
 
@@ -287,7 +295,7 @@ export function simProject(module: SimSources, experiment: string, opts: SimProj
     checkAll: async (o = {}, onProgress) => {
       const rev = revision;
       const { exp } = need();
-      return report(await checkSettings(exp, parameterValues(exp), {
+      return report(await checkSettings(exp, settingsFor(exp), {
         ...limits(o), shared: !o.perSetting, maxConfigs: o.maxConfigs,
       }, o.signal && { signal: o.signal }, onProgress), rev);
     },
@@ -328,7 +336,7 @@ export function simProject(module: SimSources, experiment: string, opts: SimProj
       return v === 'success' && model.system.exp.task.goal !== 'eventually' ? 'inProgress' : v;
     },
     settingsGenerator: function* () {
-      if (current) yield* parameterValues(current.exp);
+      if (current) yield* settingsFor(current.exp);
     },
     get editorSchema() {
       return current?.editorSchema() ?? { fields: [] };