# Builtins

Every builtin function, evaluated at compile time. Tensor operations are in
[tensor operations](https://sexpgpu.041.io/docs/tensors.md); prelude macros and functions written in
Lisp are in [the prelude](https://sexpgpu.041.io/docs/prelude.md). Builtins need no `require` and can
be shadowed.

## Arithmetic and comparison

| names | notes |
|---|---|
| `+` `-` `*` `/` | n-ary; `/` always returns a float, so `(/ 1 2)` is `0.5` and a head dimension is `(floor (/ dim heads))` |
| `mod` `pow` `sqrt` `exp` `log` `floor` | `floor` returns an integer |
| `min` | numbers only |
| `max` | numbers, or the maximum of a tensor |
| `=` `/=` `<` `<=` `>` `>=` | numeric; `/=` requires pairwise distinct arguments |
| `eq` `equal` | identity, and structural equality for data; use `equal` for lists, strings, keywords |
| `not` `truthy` | `(truthy x)` is `true` unless `x` is `nil` or `false` |

`+ - * / pow sqrt exp log max` and the six comparisons are overloaded: the
tensor reading wins when any argument is a tensor. Integer overflow and
division by zero are `E-EVAL-007`.

## Lists and higher order

| builtin | result |
|---|---|
| `(list x...)` | a list |
| `(cons x list)` | a new list with `x` in front; there are no dotted pairs |
| `(first xs)` `(rest xs)` | the first element or `nil`, and the rest as a list |
| `(nth i xs)` | the `i`-th element, `nil` past the end |
| `(length xs)` | elements of a list or vector, characters of a string |
| `(append xs...)` | one list |
| `(reverse xs)` | a list |
| `(vector x...)` | a vector; `[x ...]` is the literal |
| `(vec xs)` `(to-list xs)` | a vector from a list, a list from a vector |
| `(map f xs)` | a list of `(f x)`; one sequence only |
| `(filter f xs)` | the elements where `(f x)` is true |
| `(reduce f init xs)` | a left fold, `(f (f init x0) x1)`... |
| `(repeat n f)` | `(list (f 0) ... (f (- n 1)))` |
| `(range n)` `(range a b)` | integers from 0 or `a` below `n` or `b` |
| `(apply f arg... list)` | see [functions](https://sexpgpu.041.io/docs/functions.md#apply) |

Sequence builtins accept a list or a vector and return a list. `nil` is the
empty list. Lists are immutable.

## Plists

| builtin | result |
|---|---|
| `(plist :k v ...)` | a property list; keys must be keywords and come in pairs |
| `(getf plist key [default])` | the value after the first `equal` key, else `default` or `nil` |

`ctx`, `prepare`'s return value and curriculum observations are plists.

## Multiple values

`values` and `values-list`; the binding forms are special forms, see
[multiple values](https://sexpgpu.041.io/docs/control.md#multiple-values).

## Text and symbols

| builtin | result |
|---|---|
| `(str x...)` | the printed forms concatenated into one string |
| `(format "~a~%" x...)` | a string; understands `~a` and `~%` only |
| `(symbol-name s)` | the printable name of a symbol or keyword, a string |
| `(keyword x)` | a keyword from a symbol, string or keyword |
| `(gensym [prefix])` | a fresh symbol; see [macros](https://sexpgpu.041.io/docs/macros.md) |
| `(symbol-prefix-p "g!" s)` | whether a symbol's name starts with the prefix |

`intern` is a special form; see [macros](https://sexpgpu.041.io/docs/macros.md#the-helpers).

## Predicates

`consp` (a non-empty list), `listp` (a list or `nil`), `vectorp`, `null`,
`numberp`, `keywordp`, `symbolp`, `stringp`, and `functionp` (a function,
builtin, model, model constructor or optimizer definition).

## Errors

`(error message...)` is `E-EVAL-001`; `(assert test [message])` is
`E-EVAL-002`. See [control](https://sexpgpu.041.io/docs/control.md#errors-on-purpose).

## Experiment constructors

Ordinary builtins that build configuration values:

| builtin | page |
|---|---|
| `loader` `stage` `files` `manifest` `field` | [loaders](https://sexpgpu.041.io/docs/data.md) |
| `select` `select-not` `select-and` `group` | [optimizer groups](https://sexpgpu.041.io/docs/optimizer-groups.md) |
| `named` | [models](https://sexpgpu.041.io/docs/models.md#paths) |
| `optimizer-update` | [writing optimizers](https://sexpgpu.041.io/docs/optimizers.md) |
| `metric` `diagnostic` `tap-gradient` `counter` | [metrics](https://sexpgpu.041.io/docs/metrics.md), [writing diagnostics](https://sexpgpu.041.io/docs/writing-diagnostics.md), [loaders](https://sexpgpu.041.io/docs/data.md#counters) |

`field` also reads a batch inside `prepare`: `(field batch :tokens)`.

Related: [the prelude](https://sexpgpu.041.io/docs/prelude.md), [tensor operations](https://sexpgpu.041.io/docs/tensors.md).

---

SexpGPU documentation. Every page: https://sexpgpu.041.io/llms.txt