logigate/app/lib/logic/bench.ts

241 lines
9.0 KiB
TypeScript

// Test benches: a table of tests docked to a placed component. Each row sets
// its inputs, gives it clock ticks if asked, and checks its outputs. The
// component runs on its own (no wires to the circuit around it), from all
// zeros, its state carried from row to row, so a row can test memory, a
// counter, or a whole computer running until it is done.
//
// Pins A0, A1, … make one column A that takes a number. An input cell is a
// number (12, 0x0C, 0b1100), P for a clock pulse, or empty to leave it as
// it was. An output cell is the number it should show, empty for any.
// Ticks: N pulses (the P inputs and the component's own clocks) before the
// check; ≤N gives up to N, checking after each, until the outputs match.
import { compile } from './compile'
import { chipPins, type DefLookup } from './geometry'
import { Simulator } from './sim'
import type { Bench, BenchRow, ComponentDef } from './types'
export interface BenchColumn {
name: string
/** Pin keys, bit 0 first. */
keys: string[]
}
export interface RowResult {
/** True all checks hold, false one does not, null nothing to check. */
ok: boolean | null
/** Outputs after the row, by column. */
got: Record<string, number>
/** Ticks the row ran. */
ticks: number
error?: string
}
export interface BenchResult {
rows: RowResult[]
pass: number
fail: number
error?: string
}
const SETTLE = 2_000_000
/** Ticks a run gives in all, at most (a run in the editor stays short; by hand it may go longer). */
export const AUTO_TICKS = 20_000
export const HAND_TICKS = 500_000
/** Rows "every combination" makes, at most (10 input bits). */
export const MAX_COMBO_BITS = 10
const SERIES = /^(.*?)(\d+)$/
/** Pins as columns: A0…An (numbered from 0, none missing) make one column A, any other pin is its own. */
export function groupPins(pins: { key: string; label: string }[]): BenchColumn[] {
const series = new Map<string, Map<number, string>>()
for (const p of pins) {
const m = SERIES.exec(p.label.trim())
if (!m || !m[1]) continue
const s = series.get(m[1]) ?? new Map<number, string>()
s.set(Number(m[2]), p.key)
series.set(m[1], s)
}
const whole = new Set([...series.entries()].filter(([, s]) => s.size >= 2 && [...s.keys()].every(i => i < s.size)).map(([name]) => name))
const out: BenchColumn[] = []
const done = new Set<string>()
for (const p of pins) {
const m = SERIES.exec(p.label.trim())
const name = m?.[1]
if (name && whole.has(name)) {
if (done.has(name)) continue
done.add(name)
const s = series.get(name)!
out.push({ name, keys: [...s.keys()].sort((a, b) => a - b).map(i => s.get(i)!) })
} else out.push({ name: p.label.trim() || p.key, keys: [p.key] })
}
return out
}
export function benchColumns(def: ComponentDef): { ins: BenchColumn[]; outs: BenchColumn[] } {
const pins = chipPins(def)
return { ins: groupPins(pins.inputs), outs: groupPins(pins.outputs) }
}
/** A cell as a number, P (inputs only), or null when empty or a don't-care. */
export function parseCell(s: string | undefined, bits: number, input: boolean): number | 'P' | null | { error: string } {
const t = (s ?? '').trim()
if (!t || t === '-' || t.toLowerCase() === 'x') return null
if (input && /^(p|↑)$/i.test(t)) return 'P'
let v: number
if (/^\d+$/.test(t)) v = parseInt(t, 10)
else if (/^0x[0-9a-f]+$/i.test(t)) v = parseInt(t.slice(2), 16)
else if (/^0b[01]+$/i.test(t)) v = parseInt(t.slice(2), 2)
else if (/^-\d+$/.test(t)) v = 2 ** bits + parseInt(t, 10)
else return { error: `"${t}" is not a number${input ? ' or P' : ''}` }
if (v < 0 || v >= 2 ** bits) return { error: `${t} does not fit in ${bits} bit${bits === 1 ? '' : 's'}` }
return v
}
/** Ticks of a row: N, or ≤N (also <=N) to wait for the outputs. Empty: one pulse when the row has a P, else none. */
export function parseTicks(s: string | undefined): { n: number; wait: boolean } | null | { error: string } {
const t = (s ?? '').trim()
if (!t) return null
const m = /^(≤|<=|<|max\s*|up\s*to\s*)?\s*(\d+)$/i.exec(t)
if (!m) return { error: `Ticks "${t}": a number, or ≤ and a number` }
const n = parseInt(m[2]!, 10)
if (n > HAND_TICKS) return { error: `Ticks: at most ${HAND_TICKS}` }
return { n, wait: !!m[1] }
}
/** Runs a bench's rows on the component, in order. */
export function runBench(getDef: DefLookup, defId: string, rows: BenchRow[], maxTicks = AUTO_TICKS): BenchResult {
const def = getDef(defId)
const res: BenchResult = { rows: [], pass: 0, fail: 0 }
if (!def) return { ...res, error: 'The component it tests no longer exists' }
const cols = benchColumns(def)
const sim = new Simulator(compile(getDef, defId))
sim.run(SETTLE)
const clocks = sim.nl.clocks.length > 0
let left = maxTicks
const read = (c: BenchColumn) => c.keys.reduce((v, k, i) => v + (sim.output(k) ? 2 ** i : 0), 0)
for (const row of rows) {
const out: RowResult = { ok: null, got: {}, ticks: 0 }
res.rows.push(out)
const fail = (error: string) => {
out.ok = false
out.error = error
res.fail++
}
// Inputs, pulses held low for now.
const pulses: BenchColumn[] = []
let bad = ''
for (const c of cols.ins) {
const v = parseCell(row.set?.[c.name], c.keys.length, true)
if (v && typeof v === 'object') bad ||= `${c.name}: ${v.error}`
else if (v === 'P') {
pulses.push(c)
c.keys.forEach(k => sim.setSource(k, false))
} else if (v !== null) c.keys.forEach((k, i) => sim.setSource(k, Math.floor(v / 2 ** i) % 2 === 1))
}
const checks: { c: BenchColumn; want: number }[] = []
for (const c of cols.outs) {
const v = parseCell(row.expect?.[c.name], c.keys.length, false)
if (v && typeof v === 'object') bad ||= `${c.name}: ${v.error}`
else if (typeof v === 'number') checks.push({ c, want: v })
}
const ticks = parseTicks(row.ticks)
if (ticks && 'error' in ticks) bad ||= ticks.error
if (bad) {
fail(bad)
continue
}
const spec = (ticks as { n: number; wait: boolean } | null) ?? { n: pulses.length ? 1 : 0, wait: false }
if (spec.n && !pulses.length && !clocks) {
fail('Ticks, but nothing to tick: give a clock input P, or a clock inside')
continue
}
if (!sim.run(SETTLE)) {
fail('It oscillates and never settles')
continue
}
const matches = () => checks.every(({ c, want }) => read(c) === want)
const tick = (): boolean => {
for (const c of pulses) c.keys.forEach(k => sim.setSource(k, true))
if (clocks) sim.setClock(1)
if (!sim.run(SETTLE)) return false
for (const c of pulses) c.keys.forEach(k => sim.setSource(k, false))
if (clocks) sim.setClock(0)
return sim.run(SETTLE)
}
let stopped = ''
for (let t = 0; t < spec.n; t++) {
if (spec.wait && checks.length && matches()) break
if (left-- <= 0) {
stopped = `Stopped after ${maxTicks.toLocaleString('en')} ticks in all`
break
}
if (!tick()) {
stopped = 'It oscillates and never settles'
break
}
out.ticks++
}
for (const c of cols.outs) out.got[c.name] = read(c)
if (stopped) {
fail(stopped)
if (left <= 0) {
res.error = stopped
break
}
continue
}
if (!checks.length) continue
out.ok = matches()
if (out.ok) res.pass++
else {
res.fail++
if (spec.wait) out.error = `Not within ${spec.n} ticks`
}
}
return res
}
/** Every combination of the inputs, counting up (the first column the highest), outputs left to fill. */
export function combinationRows(def: ComponentDef): BenchRow[] | { error: string } {
const { ins } = benchColumns(def)
const bits = ins.reduce((n, c) => n + c.keys.length, 0)
if (!ins.length) return { error: 'It has no inputs' }
if (bits > MAX_COMBO_BITS) return { error: `${bits} input bits are ${2 ** bits} combinations: at most ${MAX_COMBO_BITS} bits` }
const rows: BenchRow[] = []
for (let i = 0; i < 2 ** bits; i++) {
let rest = i
const set: Record<string, string> = {}
for (let k = ins.length - 1; k >= 0; k--) {
const c = ins[k]!
const n = 2 ** c.keys.length
set[c.name] = String(rest % n)
rest = Math.floor(rest / n)
}
rows.push({ set })
}
return rows
}
/**
* The rows with what the component shows now in their empty output cells
* (to keep it working the same). Outputs already filled in stay as they are,
* so a row that waits for them waits the same.
*/
export function recordExpected(getDef: DefLookup, defId: string, rows: BenchRow[]): BenchRow[] {
const r = runBench(getDef, defId, rows, HAND_TICKS)
return rows.map((row, i) => {
const got = r.rows[i]?.got
if (!got || (r.rows[i]?.error && r.rows[i]?.ok !== false)) return row
const expect = { ...row.expect }
for (const [k, v] of Object.entries(got)) if (!expect[k]?.trim()) expect[k] = String(v)
return { ...row, expect }
})
}
/** A bench cell's value for a column, by name. */
export const cellOf = (row: BenchRow, side: 'set' | 'expect', name: string) => row[side]?.[name] ?? ''
export type { Bench, BenchRow }