Psi language reference#

Psi is the language OpenDMD's Formulas are written in. A formula is a few lines of arithmetic, worked out for every pixel of the 128 × 32 panel every frame. Its last line is a colour.

This page lists every name the language knows and what it does. Then come how a formula runs, its limits, some recipes and the language in full. The error codes are on a separate page. To learn Psi, start with Make a Formula in the guide. To try it, open the demo's Formulas.

On the site, the search box filters the built-ins (press /), and Cheat sheet shows only the tables.

Every name#

The name rule. A formula's names win over the built-ins.

• Any built-in value's, function's or drawing call's name may be set as a value of the formula's (t = 0.5, sin = 0.25, line = 3). From the line that sets it, the name reads as the formula's value wherever a value is read (setting x or y moves px py i cx cy r angle with it, as in a function). A call name(…) is still the built-in function, and since, was, under and ink(n) work the same way as sin.
• The keywords (E204), the palettes (E208) and sun, moon and replay (E216) are not names.
• A fn, table, sprite or palette of the formula's needs a name of its own. None may take the name of a value the formula has set (E203), and a fn may not take a built-in function's name either (E215).
• since(k) and was(k) read the built-in inputs only. On a name the formula has set they are refused (E217), so a name is not read two ways on one line.
• A built-in added later is read only where a formula has not set its name, so a formula saved before it means what it meant.

What each does#

These rows are the editor's cheat sheet. Each has a small example. On the site the example is drawn as the panel draws it, with a link to try it in the editor.

Values#

Functions and statements#

Drawing#

Colours#

Declarations#

How a formula runs#

• Levels. Each value is worked out only as often as what it reads changes. Constants are worked out once. Values of the time, the clock and the controls are worked out once a frame, values of y, py and cy once a row, and the rest once a pixel. This changes the cost, not the result.
• Layers (layer [blend] [rate N] { … }) are drawn bottom to top. Each has its own names and colour, and goes onto what is below with its blend (over, add, multiply, screen, max, min). A colour's last value says how much of the pixel it covers.
• Functions (fn p(a, b) = … or fn p(a, b) { … }) are written out where they are called. A function gives a value, a colour, or lines that draw. Inside a function whose values are x, y, the names px py i cx cy r angle follow them, so it draws at another place.
• draw { } runs once a frame, before the pixels. Its loops (for k < n), lines and dots go into a canvas, which the pixels read back as ink.
• Time. t is the frame's time, in seconds into the loop (loop N, 8 when left out). Which instants get drawn is the display's: the panel draws a frame on its scan's refresh (about 8 ms; 100 to 125 a second, by panel), every 2nd refresh unless the formula asks for every refresh (smooth), and fewer when frames take too long; the browser's preview draws at about the same times, and a saved GIF at 20 or 40 ms. So motion is a function of t, never a count of frames. On the panel, racing its scan, t wraps at exactly the loop's length (from OpenDMD 1.1), as in the preview; a saved GIF, and the panel when it can't follow its scan (a rate layer, the glow), play whole 20 ms (or 40 ms) frames, so a loop that isn't a whole number of them comes out up to a frame short there (such a frame, the first of a play among them, that falls in the loop's last part frame draws t at 0). The time past the loop's end carries into the next, so t keeps the clock's pace across the wrap. loop N is also the least time the formula plays for in a playlist, and the length of a GIF saved from it. phase is where the frame is in the loop, 0 to 1: t divided by the loop's length as its line writes it, the very division, so sin(phase) and sin(t/8) in an 8-second loop draw the same frames, and a change of the loop's length needs no other edit. With loop forever, t is seconds since the formula started and grows without end (and there is no phase: E908). phase and smooth are OpenDMD 1.1's: a panel before it says the name is unknown, and needs an update.
• Built-in inputs (daylight, sun.alt, moon.phase, season, yearday, night, bright, replay.playing, replay.platform, replay.game) are read by name. Each is the same for every pixel of a frame and is held to its range. When the panel has no value for one, the input reads its default; thumbnails, the gallery and psi check draw at the defaults, and the editor's preview does until its inputs panel moves them. since(KEY) says when one last changed and was(KEY) what it was before ("Numbers" gives their ends). A formula has no memory between frames.

Limits#

A formula's cost is an estimate in milliseconds a frame. Up to 5 ms is light, up to 8 ms medium, and past that heavy. The panel refuses a formula past 40 ms a frame by the plain VM estimate, or past 12 ms for a look drawn over every GIF. A smooth one past 32 ms, the most it can keep every refresh, is drawn every 2nd refresh instead (from OpenDMD 1.1; earlier panels refuse it). That is the VM's figure with no still cache even where the JIT or the cache would draw it faster, because the panel may have to draw it that way (the JIT switched off, short of memory, or failing its self-check). The light, medium and heavy ratings count the JIT's estimate where it draws, so a Formula can rate light and still be refused: the editor and psi check say so. The gallery takes a formula of 10 ms or less by the rating, and none the panel refuses.

Recipes#

Each recipe is a complete formula. Open one in the editor and change it. Three of them are Formulas from the gallery, word for word.

Scrolling text#

A message is a table of character codes (a character in single quotes is its code). Each pixel works out which character of the message it is in, and where in that character. glyph says whether the font has a pixel there. The message moves a whole number of characters a loop, so it wraps without a jump.

name "Scrolling text"
about "A message scrolling across in the panel's font, twice its size"
loop 6
-- the message: a character in quotes is its code ('A' is 65)
table msg = 'H', 'E', 'L', 'L', 'O', ' ', 'P', 'A', 'N', 'E', 'L', ' '
-- a character is 6 cells (5 and a gap), a cell 2 pixels; the 12 go by
-- once a loop: 72 cells in 6 s
u = floor(px/2 + t*12)
k = floor(u/6) % 12
row = floor((py - 9)/2)
hsv(x/2 + phase, 0.6, glyph(msg[k], u % 6, row))

A palette cycle#

The 1990s trick: the picture never moves, only its palette turns. cycle(P, v, s) reads palette P at v, turned by s. With s = phase (where the frame is in the loop, 0 to 1) it turns once a loop. wave reads only the pixel's position, so the panel works it out once and keeps it, and the formula is very light.

name "Cycled plasma"
about "Plasma the 1992 way: the picture holds still and only its palette turns"
loop 8
smooth
palette glow = #002, #208, #80f, #f0c, #f60, #ff0, #fff, #ff0, #f60, #f0c, #80f, #208
-- three waves that never move (worked out once, then kept)
wave = sin(x*2) + sin((1 - y) * 1.5) + sin(x*1.5 + (1 - y))
-- the palette turned once round in the loop
cycle(glow, wave/6, phase)

A clock face#

hour and minute are the panel's clock. The hands' angles change once a minute, so they are worked out once a frame, not for every pixel. Each hand is a thin box turned by its angle. The dial is a ring where the distance from the middle is close to 15.

name "Clock"
about "A clock face with hour and minute hands"
-- Hands on a round dial; dx, dy: pixels from the middle
dx = px - 63.5
dy = 15.5 - py
hours = (hour%12 + minute/60) / 12
mins = minute/60
hour_hand = step(max(abs(dx*cos(hours) - dy*sin(hours)), abs(dx*sin(hours) + dy*cos(hours) - 4) - 3), 1)
minute_hand = step(max(abs(dx*cos(mins) - dy*sin(mins)), abs(dx*sin(mins) + dy*cos(mins) - 6.5) - 5.5), 0.8)
dial = step(abs(dx*dx + dy*dy - 218), 22)
pal(ice, dial*0.6 + hour_hand + minute_hand)

Drawing over a GIF#

A formula with a look line can be the panel's look, drawn over whatever GIF plays. ur, ug and ub are the colour of the GIF under each pixel and ul its brightness, so the formula can recolour it. Here the GIF turns sepia, by as much as the control says.

name "Old photo"
about "The GIF in warm sepia tones"
control amount = 0.8 "How much" -- 0: the GIF as it is
look
mix(rgb(ur, ug, ub), rgb(ul*1.1 + 0.08, ul*0.92 + 0.04, ul*0.65), amount)

A slow background with rate#

Noise is one of the heavier steps. A bottom layer marked rate 4 is redrawn every 4th frame, a band of rows each frame. The layers above it are drawn every frame, so something small can move smoothly over a heavy background.

name "Slow clouds"
about "Clouds redrawn every 4th frame, with a spark racing over them every frame"
loop 8
-- the bottom layer: heavy noise, worked out every 4th frame
layer rate 4 {
  pal(ocean, noise(x*6 + t/2, y*2, t/4)*0.9)
}
-- the layer above is drawn every frame
layer {
  rgb(1, 0.8, 0.3, len((x - phase)*4, cy) < 0.12)
}

A starfield: a draw loop#

draw { } runs once a frame, before the pixels, and puts lines and dots into the frame's ink. The colour line reads it back as ink. A for loop draws one streak a star. hash(k, …) gives each star a direction and a start, the same every frame. The gallery's Starfield is the full version.

name "Warp stars"
about "64 stars streaking out from the middle: lines drawn once a frame"
loop 2
smooth
draw {
  for k < 64 {
    dir = hash(k, 1)         -- its direction, in turns
    near = frac(phase + hash(k, 2)) -- 0 far away, 1 here
    d = near*near*80         -- how far out it is, in pixels
    tail = d*0.8             -- where it was a moment ago
    line(64 + cos(dir)*tail, 16 + sin(dir)*tail*0.4, 64 + cos(dir)*d, 16 + sin(dir)*d*0.4, 0, near)
  }
}
pal(ice, ink)

Reading slider controls#

A control line makes a slider in the editor, the gallery and the panel's settings. With words instead of a range it makes a row of buttons. It names its value, which reads like any other value. A formula has three controls at most. With a whole-number speed the loop doesn't jump.

name "Sliders"
about "A bar to steer: its speed, its width and its colour are controls"
control speed 0..4 = 1 "Speed"
control width 0.05..0.5 = 0.2 "Width"
control tone = warm, cold
loop 8
-- a control is a value like any other, read once a frame
pos = frac(t*speed/8)
bar = abs(x - pos) < width/2
hsv(pick(tone, 0.06, 0.55), 0.9, bar*(0.3 + y*0.7))

The language in full#

This part is for implementers, tools and the gallery's checker. It covers the version promise, the text and grammar, the numbers, what stays the same between versions, how a formula travels, and the psi command.

Versions#

This page describes Psi 1. A formula may begin with psi 1. It doesn't need to, because a formula without the line is version 1. The editor does not write the line yet; it will once there is a version 2.

The promise starts at OpenDMD 1.0.0. Psi 1 is the language as OpenDMD 1.0.0 ships it. Through the betas it changed without a new version: y turned to count down, part blocks and frame { } went, and / became exact at every level. part stays a reserved word: a formula can't use it as a name, and one that still writes a part block is told to write a function instead. From 1.0.0:

• Within version 1, new built-in names may be added under the name rule ("Every name"). A name a formula sets is that formula's, even where a later release made it a built-in. A formula saved before a name existed means what it meant.
• A change that would alter the pixels of a formula that compiled under version 1, or refuse one, is a new version. "What stays the same" lists what that covers. The tests hold every example and gallery formula to the same frames.
• The compiled form has its own number. A compiled Formula (.psb) carries a program format number, the ABI (3 at 1.0.0). The ABI defines the steps the panel runs and what each means. It is not the language and may change at any release. A panel that meets another ABI's bytes says so, and the web app prepares the Formula again from its text. A new ABI is never a new Psi version, and a new Psi version need not be a new ABI.
• A formula written for a later version than the panel has (psi 2 on a version 1 panel) is refused (E601).

Text#

• A formula is text, at most 32,768 bytes (of UTF-8), comments included.
• Lines. Each statement is a line; ; ends a statement too (a = 1; b = 2). Inside ( ) and [ ] a line end is a space. After an operator or a , the statement continues on the next line.
• Comments run from -- or // to the end of the line.
• Numbers are digits with at most one point, no sign and no exponent: 12, 0.5, .5. A minus sign is an operator.
• Characters in single quotes are numbers: 'A' is 65, one printable ASCII character at a time. There are no strings as values; only print("…", …) in draw { } takes text.
• Colours are # and 3 or 6 hex digits: #f80 is #ff8800.
• Names are a letter or _, then letters, digits and _.
• Text in quotes ("…") goes only on name, about and control lines and in print("…", …) inside draw { }, on one line, without ", <, >, \, tabs, control characters or characters that hide or reorder text.
• A sprite starts with sprite NAME { on a line of its own, then a key line and rows of characters, and ends with } alone. Its rows are read as written, a line at a time.

Grammar#

formula   = { sep } { decl sep } { stmt sep } colourline { sep }   -- or layers instead of colourline
decl      = "psi" NUMBER                      -- the language version, first line only; never needed (unversioned is 1)
          | "name" TEXT                       -- what the formula is called (60 characters)
          | "about" TEXT                      -- one line about it (120 characters)
          | "control" NAME [ NUM ".." NUM ] [ "=" NUM ] [ TEXT ]   -- a slider: range (0..1), default (the low end), label
          | "control" NAME "=" WORD "," WORD { "," WORD } [ TEXT ] -- 2-6 words: buttons; the value is the word's number
          | "look" [ BLEND ] [ NUMBER ]       -- it may be the panel's look: blend (over), amount 0..100 (100)
stmt      = "loop" NUMBER                     -- 0.1..3600 s, once, default 8
          | "loop" "forever"                  -- no loop: t grows without end (section 11)
          | "smooth"                          -- drawn every refresh, not every 2nd: once (a formula's own `smooth` aside)
          | "fps" NUMBER                      -- the older spelling: 100 (smooth), 50 (the default) or 25 (every 4th)
          | NAME "=" expr                     -- may set a name again: a read sees the latest
          | "layer" [BLEND] ["rate" NUMBER] "{" { assign | fn } colourline "}"   -- rate 2..200; fn: a "fn" line as below
          | "fn" NAME "(" [ NAME { "," NAME } ] ")" "=" expr-or-colourline   -- a function (section 9)
          | "fn" NAME "(" [ NAME { "," NAME } ] ")" "{" { assign | dstmt } last "}"
          | "draw" "{" { dstmt sep } "}"      -- once a frame, before the pixels: one per formula
          | "table" NAME "=" ["-"] NUMBER { "," ["-"] NUMBER }   -- constants; a "," may end a line
          | "palette" NAME "=" [ NAME ] COLOUR { "," [ NAME ] COLOUR }   -- 1..32 colours (section 6)
          | "palette" NAME "=" tween [ "," tween ]   -- mixed once a frame; two: the halves (section 6)
          | "scene" NAME "when" e "{" { NAME "=" expr sep } "}"   -- e once a frame or a row; its names 0 while e is 0 (section 13)
tween     = "tween" "(" psrc "," psrc "," e ")"   -- e once a frame, held to 0..1
psrc      = PALETTE | tween                    -- yours, a built-in (not gray), or another tween
dstmt     = NAME "=" expr                     -- the same for every pixel (no x, y, px, py, i, ur…, ink)
          | "for" NAME "<" NUMBER "{" { dstmt sep } "}"   -- NAME = 0 … NUMBER−1; 1..1024, two deep
          | "line" "(" e "," e "," e "," e [ "," e [ "," e ] ] ")"   -- x0, y0, x1, y1 [, v0 [, v1]]
          | "dot" "(" e "," e [ "," e ] ")"                            -- x, y [, v]
          | "print" "(" ( TEXT | e ) "," e "," e "," e [ "," FONT [ "," e ] ] ")"   -- text (32 characters) or a number, x, y, colour [, font [, digits]]
colourline= "rgb" "(" e "," e "," e [ "," cover ] ")"
          | "rgb" "(" ce [ "," cover ] ")"       -- a colour, maybe covering less
          | "hsv" "(" e "," e "," e [ "," cover ] ")"
          | "pal" "(" PALETTE "," e [ "," cover ] ")"
          | "gray" "(" e [ "," cover ] ")"
          | FN "(" args ")"                    -- a function whose last line is a colour
          | ce                                 -- a colour expression (see 6)
          | e                                  -- a bare value: gray(e)
ce        = an expr with a COLOUR or an "rgb(" e "," e "," e ")" in it, read
            once a channel
expr      = or [ "?" expr ":" expr ]           -- both arms are always evaluated
or        = and { ("or" | "||") and }
and       = not { ("and" | "&&") not }
not       = ("not" | "!") not | cmp
cmp       = sum [ ("<" | "<=" | ">" | ">=" | "==" | "!=") sum ]   -- one: E218
sum       = term { ("+" | "-") term }
term      = unary { ("*" | "/" | "%") unary }
unary     = ("-" | "+") unary | atom
atom      = NUMBER | CHAR | COLOUR | NAME | FUNC "(" args ")" | FN "(" args ")"
          | TABLE "[" expr "]" | SPRITE "[" e "," e "]" | "(" expr ")"
args      = e { "," e }                        -- digit/glyph: e "," e "," e [ "," FONT ]
                                               -- pick: e "," e { "," e }
sep       = newline | ";"                      -- newlines inside ( ) and [ ] are spaces
NUMBER    = digits [ "." digits ] | "." digits -- no sign, no exponent
CHAR      = "'" one printable ASCII character "'"   -- its code: 'A' is 65
COLOUR    = "#" 6 hex digits | "#" 3 hex digits   -- #ff8800, #f80 (each digit twice); colour lines only
TEXT      = '"' characters '"'                -- on name/about/control lines and in print only; no " < > \ or tabs inside; label 24 characters
NUM       = [ "-" ] NUMBER
WORD      = NAME
FONT      = "normal" | "small" | "bold"      -- bold: digit only
NAME      = [A-Za-z_][A-Za-z0-9_]*
comment   = "--" or "//" to the end of the line

The header comes first: the declarations (decl), each once (control up to three times), and the loop and smooth (or fps) lines, in any order among themselves, before every other line (a declaration below another line is E951). loop and smooth may also come later among the formula's own lines, outside layers. The colour line is the last line of the formula, of a function and of a layer. With layers, every colour line is inside a layer.

Numbers#

Every value is a fixed-point number from −32,768 to 32,767.99998, in steps of 1/65,536 (Q16.16). Arithmetic saturates rather than wrapping.

• a / b is the exact quotient, truncated towards zero to a step and held to the ends. Half of the step below zero is 0.
• a / 0 is the largest number of a's sign, and 0 / 0 is 0.
• a % 0 is 0. % is floored, so -1 % 3 is 2.
• Comparisons and and, or, not give 1 or 0. Any number but 0 is true.
• Comparisons don't chain. 0 < x < 0.5 is refused (E218); write 0 < x and x < 0.5.
• Both sides of ? : are worked out.
• A division per pixel by a constant, or by a frame's or a row's value, gives the same bits as the same division done once a frame. The panel divides a row of pixels by one divisor exactly, with multiplies.

since(KEY) is the seconds since a built-in input last changed. It is held at 32766 (about 9 hours), and reads 32767 when the input has never changed, so since(k) < 32767 means "it has changed". was(KEY) is the input's value before that change. A built-in input the panel has no value for reads its default. That is the case with no location set, the clock not set, or RePlayOS not followed.

Where a function is defined by a table (sin, sqrt, atan2, the palettes, the fonts), the table is the definition; noise and hash are defined by their integer arithmetic. A formula gives the same bytes on the panel, in the browser and on a computer.

What stays the same#

Each item below shows in a formula's pixels or in whether it compiles. From OpenDMD 1.0.0, changing any of it makes a Psi 2 (see "Versions").

Machinery that gives the same bytes is not on the list and may change at any release. It includes the .psb ABI, the steps and their narrowed and fused forms, the JIT, keeping values that never change from frame to frame, the column run, the cost model and its tiers, and the error sentences. A formula refused as too heavy meets a product limit, not the language. Error codes are only ever added, and a retired code is not used again.

• Syntax and acceptance. The keywords, the palette names and the dotted inputs' groups (sun, moon, replay) are not names; the name rule ("Every name"); the header first (its lines in any order); psi N on the first line only; { on the line that opens it; ; as a separator; -- and // comments; a line going on after an operator or ,; literal counts for for, ink(n) and look; comparisons don't chain; the colour grammar (what is a channel expression, what is a whole colour, pal(P, k) * e the one scaled whole colour, coverage on the outermost colour only). Grammar that is refused today may be accepted later (else if).
• Limits only grow. A formula that fits keeps fitting (see "Limits").
• Numbers. Q16.16 with + - *, negation and abs saturating; * rounding down; / truncating towards zero, exact at every level; / 0, 0 / 0, % 0; floored %; floor and frac of negatives; sqrt of 0 and below is 0; abs of the lowest number is the highest.
• Tables and fixed arithmetic are definitions: sin/cos (256 entries, interpolated), sqrt, atan2, noise, hash, the three fonts, the hsv conversion, ul's weights, the blends and coverage in 8-bit channels, cycle's turn, tweens' rounding, and the palettes' colours. In particular:
• pal(P, k) reads the one of the palette's 32 entries whose band holds k (entry floor(k × 32), 31 at k = 1), with no blending between them. A three-colour palette bands rather than ramps. An interpolated read would be a new name.
• rainbow is black at 0 and dark at 1, its hues between;
• ocean is the same table as ice (one palette, two names).
• Inputs. x and y across and down, cx cy r angle as defined, angle clockwise with a quarter down, t the frame's time in seconds (which instants are drawn is the display's, not the language's), loop 8 when left out, phase as t over it, smooth as fps 100 and fps 25, 50 or 100 only, the controls' ranges and defaults, each built-in input's range and default, since's 32766 for a change and 32767 for never, hour minute second whole.
• Reads outside their range give 0: pick past its choices, T[k] past a table, S[u, v] outside a sprite, digit and glyph outside the cell.
• The draw stage: ink keeps the brighter value, paint is painter's order over the colour line, line and dot with no ink draw 1, the caps skip the rest the same way on every panel.
• Scenes, rates and layers: a scene's names read 0 while it is off, the rate bands' schedule, layers blended bottom to top, a look ignored when the formula plays alone; loop forever's growing t, its seed per play, and the growing-value forms it accepts (more may be accepted later, never fewer).

How a formula travels#

• Links carry names, not formula text. A gallery Formula travels by name: https://opendmd.dev/f/#gallery=<name>, or #gallery=<name> to a panel's web app. A formula changed on the site goes to the panel's web app by postMessage from the page that opened it. To share a formula, submit it to the gallery.
• On the panel a playlist line or the look names a bundled Formula (@formula:<name>) or one saved on the panel. A saved one is a .psi file, played from the compiled .psb the web app writes beside it. A formula sent to show at once goes compiled, on one line (@formula?psb=…, base64url). That line is 6,144 bytes at most, or 2,048 for a look set that way. The panel compiles only the .psi files on its card whose .psb is missing, older or of another ABI (a card filled on a computer, or after an update), in the background once the card is mounted; everything else it plays already compiled.
• In the gallery a formula is a file of two comment lines (-- author: … and -- licence: CC0-1.0 or CC-BY-4.0) followed by the formula. The formula is at most 32,768 bytes and 4,500 bytes once compiled; the file is at most 36 KB.

Tools#

The psi command checks and formats formulas on a computer. Install it from the source with cargo install --path opendmd-psi-cli, or with make psi.

$ psi check storm-front.psi --out -
ok: 39 of 768 steps (per frame 11, draw 0, per row 5, per pixel 23), 2 layers, 3 of 12 registers, 38 of 241 values
name: Storm front
never repeats (loop forever), drawn every 2nd refresh; reads t
panel: ~5.5 ms a frame with the JIT, ~6.8 without: medium (light ≤ 5 ms, medium ≤ 8 ms; the panel takes ≤ 40 ms on the VM, a look ≤ 12)
JIT: yes, ~5.5 ms a frame compiled (what the tier and the gallery's limit count; ~6.8 ms without the JIT)
length: 563 B as written (32,768 at most), 355 B compiled (489 B as a path, @formula?psb=…: 6,144 to show it, 2,048 for an inline look); compiled 355 B of the gallery's 4,500
note: line 14: `d` is worked out for every pixel each frame (~666 ns a pixel): it would be kept in the still cache but it reads `fall`, which changes from frame to frame
heaviest lines (their share of the work a frame; make these lighter first):
  line 8 (74%): cl = noise(x*3 - t*0.15, (1 - y) * 2, 0)*0.7 + noise(x*7 …
  line 14 (12%): d = hash(px, floor(py/4 + hash(px, 1)*8 - fall))
  line 9 (9%): pal(ice, cl*0.8 + (1 - y)*0.3) * (0.35 + cl*0.5)

$ psi check broken.psi
error[E202]: line 3, column 6: unknown function `sine` — did you mean `sin`?
  gray(sine(v))
       ^^^^

psi check also writes a PNG contact sheet of frames across one loop (--out, --frames, --a/--b/--c, --clock, --set KEY=V, --since KEY=S and --was KEY=V for the built-in inputs, --hash, --listing). It says whether the panel's JIT takes the formula, and why not. It also prints the compiler's notes, each with its line number:

• a pick worked out per pixel because one of its arms is;
• a sum or product that brackets better: px - 64 - X works - X out for every pixel, px - (64 + X) once a frame;
• which values are worked out once and kept, and which once a column;
• the heaviest value that could not be kept, and the value that kept it out;
• a draw loop run as lanes (32 turns or more, costed for the next multiple of 128 turns).

--levels lists every value with how often it is worked out and the chain that makes it so (beam per pixel: readsoff(line 3) ←px``).

--same-as other.psi checks a rewrite. It reports whether the two are the same program, and passes when they give the same frames. The frames are three seeds × 120 frames over a loop, or a loop forever formula's first 5 minutes, with the clock moving and the sliders at 0 and at 1. --seeds and --frames change the counts. It exits 1 at the first frame that differs.

psi fmt FILE prints the formula in the canonical layout. --write rewrites the file, and --check names the files that aren't in it. The layout is one statement a line, two spaces inside { }, and spaces round =, comparisons and + -. *, / and % close up where they bind tighter (x*3 + t/8). Comments stay where they are. It changes only the spacing between the formula's words (a ; becomes a line end, a { } block is opened out onto lines), and checks that the result is the same program before it writes.

psi builtins --json and psi errors --json give this page's tables as data. The name tables, the limits and the error codes are generated from the compiler, and the tests fail when they drift. The tests compile every example and recipe, and hold the panel, the browser and a computer to the same frames.