Built-in functions#

46 functions. Zero vendor math.

.vis 0.1 has 46 built-in functions. All of them are Vision’s own, with the same result on every GPU and on the numpy reference; none calls the vendor’s math library.

Precision is the maximum error against the exact result computed in float64, in units in the last place (ULP), for results between 2⁻¹²⁵ and half the largest float. (sample): measured on 1 in every 101 inputs (42 million per function); the others on all 4 294 967 296 inputs.

Outside its domain a function returns the value at the edge of the domain, and an overflow gives ±MAX (±3.4028235e38): every value is finite. Every example below is computed by Vision in the tests.

Exponentials and logarithms#

Function	Meaning	Precision	Examples
`exp(x)`	eˣ	0.99 ULP	`exp(1)` = 2.718282, `exp(100)` = MAX, `exp(-200)` = 0
`exp2(x)`	2ˣ	1.19 ULP (sample)	`exp2(10)` = 1024, `exp2(200)` = MAX
`expm1(x)`	eˣ − 1, accurate near 0	3.31 ULP (sample)	`expm1(0)` = 0, `expm1(100)` = MAX
`log(x)`	natural logarithm	0.83 ULP	`log(1)` = 0, `log(0)` = −MAX, `log(-1)` = −MAX
`log2(x)`	base-2 logarithm, exact on powers of 2	1.31 ULP (sample)	`log2(1024)` = 10, `log2(0)` = −MAX
`log10(x)`	base-10 logarithm	1.68 ULP (sample)	`log10(1000)` = 3, `log10(-5)` = −MAX
`log1p(x)`	ln(1 + x), accurate near 0	2.79 ULP (sample)	`log1p(0)` = 0, `log1p(-1)` = −MAX
`pow(a, b)`	aᵇ (also written a ^ b)	2.13–2.48 ULP (sample)	`pow(2, 10)` = 1024, `pow(0, -1)` = MAX, `pow(0, 0)` = 1, `pow(-2, 3)` = −8, `pow(-2, 0.5)` = 0

log. log of 0 or of a negative number is −MAX.

pow. A negative base works with an integer-valued exponent; with any other exponent the result is 0. x ^ n with an integer literal n up to 16 is an exact product and keeps the type of x.

Roots#

Function	Meaning	Precision	Examples
`sqrt(x)`	√x	0.75 ULP	`sqrt(16)` = 4, `sqrt(-1)` = 0
`cbrt(x)`	∛x, defined for negative numbers	0.92 ULP (sample)	`cbrt(27)` = 3, `cbrt(-8)` = −2
`hypot(a, b)`	√(a² + b²) without premature overflow	2.39 ULP (sample)	`hypot(3, 4)` = 5, `hypot(3e38, 3e38)` = MAX

Trigonometric#

Function	Meaning	Precision	Examples
`sin(x)`	sine, accurate for every float32 argument	1.59 ULP	`sin(0)` = 0, `sin(1.5707964)` = 1
`cos(x)`	cosine	1.58 ULP	`cos(0)` = 1
`tan(x)`	tangent	3.24 ULP	`tan(0)` = 0, `tan(1.5707964)` = −22877332
`asin(x)`	arcsine	2.08 ULP (sample)	`asin(1)` = 1.570796, `asin(2)` = 1.570796
`acos(x)`	arccosine	1.33 ULP (sample)	`acos(1)` = 0, `acos(2)` = 0, `acos(-3)` = 3.141593
`atan(x)`	arctangent	1.75 ULP	`atan(1)` = 0.7853982
`atan2(y, x)`	the angle of the point (x, y)	1.94 ULP	`atan2(1, 1)` = 0.7853982, `atan2(0, 0)` = 0, `atan2(0, -1)` = 3.141593

Hyperbolic#

Function	Meaning	Precision	Examples
`sinh(x)`	hyperbolic sine	1.66 ULP (sample)	`sinh(0)` = 0, `sinh(100)` = MAX
`cosh(x)`	hyperbolic cosine	1.66 ULP (sample)	`cosh(0)` = 1, `cosh(-100)` = MAX
`tanh(x)`	hyperbolic tangent	1.62 ULP	`tanh(0)` = 0, `tanh(20)` = 1
`asinh(x)`	inverse hyperbolic sine	4.14 ULP (sample)	`asinh(0)` = 0
`acosh(x)`	inverse hyperbolic cosine	2.21 ULP (sample)	`acosh(1)` = 0, `acosh(0.5)` = 0
`atanh(x)`	inverse hyperbolic tangent	1.58 ULP (sample)	`atanh(0)` = 0, `atanh(1)` = MAX, `atanh(-2)` = −MAX

Probability and random numbers#

Function	Meaning	Precision	Examples
`erf(x)`	error function	2.40 ULP (sample)	`erf(0)` = 0, `erf(10)` = 1
`erfc(x)`	1 − erf(x), accurate in the tail	4.62 ULP (sample)	`erfc(0)` = 1, `erfc(-10)` = 2
`normcdf(x)`	cumulative standard normal distribution	4.60 ULP (sample)	`normcdf(0)` = 0.5, `normcdf(-40)` = 0
`rand(ix, iy, seed)`	a uniform pseudo-random number in [0, 1) from three integers; the same arguments always give the same number	exact	`rand(0, 0, 1)` = 0.1384287

rand. rand has no hidden state: for a new draw at every step, pass a step counter (an i32 channel) as an argument. Not rand(x, y, 7) in a kernel run 100 times but rand(x, y, clock) with clock += 1 in the kernel: the same arguments give the same number at every step.

Rounding#

Function	Meaning	Precision	Examples
`floor(x)`	the largest integer ≤ x	exact	`floor(-2.5)` = −3
`ceil(x)`	the smallest integer ≥ x	exact	`ceil(2.1)` = 3
`round(x)`	the nearest integer, ties to even	exact	`round(2.5)` = 2, `round(-0.5)` = 0
`trunc(x)`	the integer part	exact	`trunc(-2.7)` = −2
`fract(x)`	x − floor(x)	exact	`fract(-1.25)` = 0.75

Comparison and blending#

Function	Meaning	Precision	Examples
`abs(x)`	absolute value; keeps int	exact	`abs(-3)` = 3
`sign(x)`	−1, 0 or 1; keeps int	exact	`sign(-3.5)` = −1, `sign(0)` = 0
`min(a, b)`	the smaller of two numbers; int when both are	exact	`min(1, 2.5)` = 1
`max(a, b)`	the larger of two numbers; int when both are	exact	`max(1, 2.5)` = 2.5
`clamp(v, lo, hi)`	min(max(v, lo), hi)	exact	`clamp(5, 0, 3)` = 3
`mix(a, b, t)`	a·(1 − t) + b·t	exact	`mix(10, 20, 0.25)` = 12.5
`step(edge, v)`	1 if edge ≤ v, else 0	exact	`step(0.5, 0.2)` = 0, `step(0.5, 0.7)` = 1
`smoothstep(lo, hi, v)`	a smooth Hermite step from 0 to 1	exact	`smoothstep(0, 1, 0.5)` = 0.5
`select(cond, a, b)`	a where cond is true, b elsewhere	exact	`select(true, 1, 2)` = 1, `select(3 > 4, 1, 2)` = 2

min. Inside a kernel min and max take two numbers; the minimum over a whole canvas is a measure. Not min(t) in a kernel but measure lowest = min(t) on c: the reduction over the canvas is a measure.

select. cond is a condition: to test a number, compare it. Not select(n, 1, 0) but select(n == 1, 1, 0): the first argument is true or false, not a number.

Conversion and integer transfers#

Function	Meaning	Precision	Examples
`float(v)`	the value as a float; true is 1 and false is 0	exact	`float(3)` = 3
`int(v)`	the value as an int, truncating towards zero and saturating	exact	`int(-2.7)` = −2, `int(1e20)` = 2147483647
`flux(d, s)`	d / 2^s rounded half away from zero, s from 0 to 30; flux(-d, s) = -flux(d, s), so what a cell gives a neighbour is exactly what the neighbour receives and integer totals are conserved	exact	`flux(13, 3)` = 2, `flux(-13, 3)` = −2
`rgb(r, g, b)`	the integer r·65536 + g·256 + b: the value a colour pixel of a PNG loads as	exact	`rgb(30, 150, 60)` = 2004540

Reductions#

sum, mean, min, max and count reduce a whole canvas; they appear only in a measure (see Vocabulary). Inside a kernel, min and max are the two-argument functions above.