Maths functions¶
These apply to every value of every column:
| Function | Kinds |
|---|---|
-collection, collection.abs() |
Floats and ints |
collection.sqrt(), collection.exp(), collection.log(), ** |
Floats |
zk.min(a, b), zk.max(a, b) |
Floats, ints and dates |
zk.clamp(values, lower, upper), collection.clamp(lower, upper) |
Floats, ints and dates |
trended = gross * inflation**years
squared = gross**2 # a whole-number exponent up to 16 multiplies; 0.5 takes the square root
log_returns = (gross / gross.sum()).log()
bounded = zk.clamp(gross, 0.0, 50_000.0) # the same as gross.clamp(0.0, 50_000.0)
smaller = zk.min(gross, trended) # elementwise, unlike gross.min(), which reduces across rows
log gives -inf at 0 and NaN below it. clamp(lower, upper) is min(upper, max(lower, values)),
and leaves NaN as NaN. Its bounds can be scalars or collections, which are aligned by dimension as
any operand is.
Accuracy and speed¶
exp, log and pow are zeki's own, written so the engine runs them on four values at once with
AVX2 and FMA, where a platform's maths library takes one value per call. Against the standard
library, exp and log are within 1 unit in the last place (ulp), and pow within 2 ulp for
exponents up to 10 in size (14 ulp at 100). sqrt is the processor's own square root, which is
exact.
| Function | zeki, ns per value | Standard library, ns per value |
|---|---|---|
exp |
1.3 | 2.9 |
log |
1.8 | 2.6 |
pow |
3.5 to 5.2 | 8.6 |
Timings are on one core.
A whole-number exponent up to 16 multiplies rather than calling pow, and an exponent of 0.5 takes
the square root.
What zeki knows about values¶
zeki tracks, for each float value, whether every value is free of NaN, finite, non-negative or
positive. Inputs are checked as they're added, and each operation keeps only what it can guarantee:
abs makes values non-negative, as does zk.max(x, 0.0), but a product of positive values is only
non-negative, since it can underflow to 0.
Where an operand is known to be positive and finite, log and pow skip their special cases
(zeros, negatives, infinities and NaN), and pow runs about 25% faster. The fast routes give the
same bits as the general ones, so a result never depends on what zeki knew.