setup

setup(options): Promise<{ destroy: () => void; draw: () => void; evolve: () => void; readGrid: () => Promise<number[]>; seed: number; setAutomaton: (__namedParameters) => void; update: () => void; writeCell: (index, elementIndex) => void; writeCellAt: (x, y, elementIndex) => void; writeCells: (start, cells) => void; writeGrid: (grid) => void; }>

Defined in: webgpu/setup.ts:440

Initializes the WebGPU simulation for a given canvas and automaton. The grid is randomly initialized with the defined elements, each equally likely, unless an initialGrid gives the cells or the weights.

Async because the first call initializes WebGPU, which later simulations share. If the device is lost, the next call requests a new one.

Use index found in ElementBlueprint instances to reference elements when building the initialGrid.

Parameters

options

An object containing the canvas element and the compiled automaton.

automaton

Automaton

The compiled automaton produced by vivarium().create().

canvas

HTMLCanvasElement

The HTML canvas element. By default, its width and height define the grid dimensions. The simulation renders to it through a webgpu context, so the canvas must not already have a 2d or webgl context.

height?

number = canvas.height

The number of grid rows, any positive integer. Defaults to canvas.height.

initialGrid?

number[] | { weights: Record<string, number>; } | number[][]

An optional 2d array of element indices to use instead of random initialization. Alternatively, you can pass a flat (1d) array with one index per cell, row-major order. Or pass { weights } to keep random initialization with element names mapped to relative weights: { weights: { empty: 9, tree: 1 } } fills about 90% of the cells with empty and 10% with tree, same as { empty: 90, tree: 10 }. Elements left out are never picked. Prefer taking the names from ElementBlueprint.name, e.g. { weights: { [empty.name]: 9, [tree.name]: 1 } }, so renaming an element can’t break the weights.

onDeviceLost?

(info) => void

Called if the GPU device is lost (e.g. driver crash or reset). The simulation then behaves as after destroy and its grid is gone; call setup again to recreate it on a new device. To resume, pass a grid saved earlier with readGrid as initialGrid.

seed?

number = ...

An integer in [0, 2^32) that makes the run reproducible: the same seed, automaton, options and calls give the same random initial grid and the same chance outcomes at every step, on any device and browser. A new vivarium version may change the outcomes of a seed. Defaults to a random one, readable as seed on the result to replay the run.

width?

number = canvas.width

The number of grid columns, any positive integer. Defaults to canvas.width. width * height can be at most 2^25 (about 5792×5792), and width and height at most 524280 each; larger grids throw. The grid is stretched over the canvas, so a small grid on a large canvas draws each cell as a block of pixels.

Returns

Promise<{ destroy: () => void; draw: () => void; evolve: () => void; readGrid: () => Promise<number[]>; seed: number; setAutomaton: (__namedParameters) => void; update: () => void; writeCell: (index, elementIndex) => void; writeCellAt: (x, y, elementIndex) => void; writeCells: (start, cells) => void; writeGrid: (grid) => void; }>

A promise of an object with:

• update — advances the simulation by one step (synchronous, GPU only).
• draw — renders the latest state to the canvas (synchronous, GPU only).
• evolve — convenience shorthand for update() + draw().
• readGrid — reads the current grid state.
• writeCell — updates a single cell by flat index.
• writeCellAt — updates a single cell by grid coordinates.
• writeCells — updates a span of consecutive cells by flat index, in one upload.
• writeGrid — overwrites the entire grid.
• setAutomaton — replaces the automaton. Cells whose element index the new automaton doesn’t have become element 0.
• destroy — frees the GPU resources; afterwards update, draw and evolve do nothing and the other functions throw.
• seed — the seed of this run, the given one or the random default.

Throws

If the automaton is not one create() could have made, apart from its ids (which only need to be unique) and elements sharing a color. The error names the first bad field, e.g. rules[0].when[1].count[2].