Language specification#

One meaning for every program, on every machine.

This is the normative definition of .vis, version 0.1. Where a tutorial explains, this document decides: when the two disagree, this one is right. The vocabulary is listed in Vocabulary, the grammar in Language reference, the functions in Built-in functions and the errors in Errors; those pages are part of this specification.

1. Conformance#

  1. A program is a text that the rules below accept. Any other text is rejected at compile time with an error of Errors.

  2. The result of a program is the final value of every channel and the series of every measure.

  3. Determinism. The result of a program depends only on its text, the values of its params and the contents of the files it loads. It does not depend on the device, the vendor, the driver, the operating system, the number of devices or the time of the run.

  4. Reference. The value of every operation is the one computed by the reference implementation of Vision (--device numpy), bit by bit. An implementation, or a device, conforms when it gives the same bits on every case of the conformance kit (vision conformance, see Conformance kit).

  5. The words must, must not and is state requirements; for example introduces an illustration.

2. Lexical structure#

  1. Encoding. A program is UTF-8 text. It is normalised to Unicode NFC before it is read, so the same visible text is the same program.

  2. Lines. Line breaks have no meaning: a statement ends where the grammar says it ends. ; may separate statements and is never required.

  3. Comments start with // and end at the end of the line.

  4. Names start with a letter (any Unicode letter) or _, followed by letters, digits or _. Names are case sensitive. Keywords (Vocabulary) cannot be names.

  5. Numbers. 42 is an int literal; 4.2, .5, 2. and 1e5 are float literals. A literal has no sign: -3 is the negation of 3. An int literal must not exceed 2147483647 (E0502); a float literal must fit in float32 (E0501).

  6. Strings appear only as file names: "output/map.png". They have no escapes and end on the same line (E0101).

  7. Any other character is an error (E0102).

3. Programs and names#

  1. A program is a sequence of declarations: param, canvas, kernel, measure, in any order, and at most one run block (E0202).

  2. Global names. Params, canvases, kernels and measures share one namespace (E0302, E0303, E0304). Channels belong to their canvas.

  3. Reserved names. Keywords, the names of the functions, x, y, width, height and scenario cannot be declared (E0301). In a program with a 3-D canvas, z and depth are reserved too; in a 2-D program they are ordinary names.

  4. Locals (let, var, the variable of a for) live in their block and the blocks inside it. A local must not repeat a name of the same scope (E0313), a channel of the canvas (E0311) or a name of the program or of the language (E0312).

4. Values and types#

  1. float is a 32-bit binary floating-point number that is always finite. +, - and * are rounded to nearest, ties to even; / is within 1.15 ULP of the exact quotient, with 1 / 0 = MAX, -1 / 0 = −MAX and 0 / 0 = 0. A result smaller in magnitude than 2⁻¹²⁶ is 0; a result beyond the largest float is ±3.4028235e38 (written ±MAX), with the sign of the exact result. There is no infinity and no NaN.

  2. int is a 32-bit two’s-complement integer. +, - and * wrap around.

  3. bool is true or false, the result of comparisons and logical operators. A bool is not a number: it cannot be stored in a channel (E0409) or used in arithmetic (E0421); select(cond, a, b) and float(cond) turn it into a number.

  4. Mixed arithmetic. An operation on an int and a float converts the int to float. / is always real division: 7 / 2 is 3.5. int % int is the remainder with the sign of the dividend (-7 % 3 is -1); x % 0 is 0.

  5. Powers. x ^ n, with an integer literal n from 0 to 16, is the exact repeated product and keeps the type of x. Any other power is pow(x, n), a float.

  6. Conversions. int(v) truncates towards zero and saturates at the limits of int; float(v) is exact for bool and rounded for int.

  7. Functions are defined in Built-in functions, each with its type rule and the values at the edges of its domain. Outside its domain a function returns the value at the edge (for example, sqrt(-1) is 0).

5. Canvases#

  1. canvas name[w, h] edge e { channels } declares a grid of w × h cells; canvas name[w, h, d] a volume of w × h × d cells (d at most 65535, E0508). Sizes are constant positive integers (E0503–E0507): numbers, params and arithmetic on them.

  2. A channel holds one value per cell: f32 (the default) or i32. Every channel starts at 0.

  3. The edge decides what a read outside the canvas gives: clamp (the default) the nearest border cell, wrap the cell on the opposite side, zero the value 0. It applies to every axis.

  4. Cell (0, 0) is the top-left cell; x grows to the right, y downwards, z from the first layer.

6. Kernels#

  1. kernel name on canvas { statements } defines one step of every cell of the canvas.

  2. Execution model. When the run block calls a kernel, its statements run for every cell. Every cell starts from the same state, the state before the kernel. When every cell has finished, the channels the kernel assigned take their new values, all at once; the other channels keep theirs. The order in which the cells run has no effect on the result.

  3. Reading. Inside the kernel:

    • a channel name (t) denotes the value of this cell in this run of the kernel: it starts as the state before the kernel and follows the assignments of the kernel;

    • an indexed read (t[x - 1, y], and also t[x, y]) always reads the state before the kernel;

    • other.u[i, j] reads a channel of another canvas, in the state before the kernel;

    • x, y, z, width, height, depth and scenario are given by the canvas and the run (E0412).

  4. Writing (the pixel rule). A kernel assigns only channels of its own canvas (E0413), by name, and only for its own cell: t[x + 1, y] = … is not a statement (E0210). Hence there are no data races.

  5. Statements. let (immutable, E0407) and var declare locals, which keep the type of their first value (E0408); name = expr and name op= expr assign; if/else if/else run a block where a condition holds (E0404); for i in a to b runs a block for i = a … b, both ends included, with bounds that are the same in every cell (E0405), and i cannot be assigned (E0406).

  6. An i32 channel takes only int values (E0410); a float becomes int only with int(...).

7. Expressions#

  1. Precedence and associativity are those of Vocabulary; parentheses group. Comparisons do not chain (E0213).

  2. Operands are evaluated as values; there are no side effects inside an expression, so the order of evaluation cannot change a result.

  3. rand(ix, iy, seed) is a pure function of its three integers: the same arguments give the same number in every cell, step and run. A new draw at every step needs an argument that changes, such as a step counter.

8. Measures#

  1. measure name = f(value) on canvas [where condition] reduces the canvas to one number with sum, mean, min, max (of a number, E0402) or count (of a condition, E0401). where keeps the cells where its condition holds (E0403).

  2. The value is evaluated for every cell like an expression of a kernel, on the current state.

  3. sum and mean are computed with about 44 bits of precision; every reduction has a fixed order, so its value is part of the deterministic result.

  4. Each call of the measure in the run block appends one value to its series. When no cell is selected the value is none (shown as no pixels).

9. The run block#

  1. The commands run in order: a kernel name runs one step; a measure name appends one value; repeat n { … } runs its commands n times (n ≥ 0, constant, E0509).

  2. scenarios n { … } runs its commands n times (n ≥ 1, E0510), every time from the state at the start of the block, with scenario = 0, 1, …, n − 1 in kernels and measures; outside the block scenario is 0. After the block the state is the one left by the last scenario. The block does not nest (E0511).

  3. load canvas.channel "file" [nodata v] replaces the state of a channel with the data of the file (section 10).

  4. print and save show or write the current state; they do not change it. A measure must have been taken at least once before it is printed or saved (E0601).

  5. A kernel or measure named in the run block must exist (E0316).

10. Data#

  1. load reads .npy, .csv/.txt, .asc (Esri ASCII grid) and .png. Row 0 of a file is row y = 0 of the canvas (the top, the north of a grid). A 3-D .npy is [depth, height, width].

  2. The size of the data must be the size of the canvas (E0710).

  3. Values are made canonical as the device stores them: a magnitude below 2⁻¹²⁶ becomes 0, −0 becomes +0, ±infinity becomes ±MAX. NaN, and the NODATA_value of an .asc, are cells without data: they are an error unless nodata v gives the value that replaces them (E0704).

  4. An i32 channel loads only integers that fit in 32 bits (E0711).

  5. The SHA-256 of every loaded file is part of a receipt of the run.

11. Errors#

  1. Every error of a program is found before it runs, except those of data files (family E07). An error has a stable code (see Errors); a code keeps its meaning across versions, while its message may improve.

  2. A program with an error does not run.

12. Versions and compatibility#

  1. The language has a version MAJOR.MINOR (this document: 0.1), separate from the version of the package.

  2. Before 1.0, a minor version may change the language; every change is listed in the release notes, with the way to update a program.

  3. From 1.0 on:

    • a minor version only adds: every valid program keeps its meaning and its bits;

    • a change that alters the result of a valid program needs a new major version, and is announced one minor version before, with a warning.

  4. Never, in any version:

    • an error code changes meaning;

    • the result of a program changes between devices.

  5. Changes to the language are proposed as a Vision Enhancement Proposal (VEP). A VEP states:

    • the motivation;

    • the exact change to this specification;

    • the new error codes;

    • the conformance cases that check it;

    • its effect on existing programs.

    It is accepted only with its specification text, its tests and its conformance cases.