Browse the docs · Apsi 1.10.0
Apsi 1.10.0 — everything on one page
This page is the whole language in one place: every piece of syntax with a short example, then every built-in function, every standard module and every member, and every command of Apsi 1.10.0, generated from the runtime itself so nothing is missing. Read it top to bottom once, then use it with your browser's search (Ctrl+F). The long-form explanations live in the language reference.
How a program looks
use physics.constants # modules: use NAME / use NAME as n
import "helpers.apsi" as h # another file of yours
# comments start with #
let g = 9.81[m/s^2] # let = constant, units in [ ] or after a number: 2kg, 3.5s
var t = 0s # var = variable
fn fall(h: Length) -> Time = sqrt(2 * h / g) # one-line function with unit-checked types
print(f"10 m takes {fall(10m):.3f}") # f-strings with format specs
Blocks are indented (4 spaces), like Python. Lines may continue inside ( ), [ ], { }.
Values
| Write | Type | Notes |
|---|---|---|
42, 1_000_000, -7 |
Int |
any size |
3.14, 6.02e23, inf, nan |
Float |
64-bit IEEE |
2kg, 9.81[m/s^2], 1.5[kWh] |
quantity | number + SI unit; wrong units are an error before running |
3.0 ± 0.1, x +/- dx |
uncertain | errors propagate through every formula |
exact("1/3") |
exact | rational numbers without rounding |
true, false, none |
Bool, none |
|
"text", f"x = {x:.2f}" |
Str |
+, *, slicing, .upper() .split() .replace() .strip() .find() … |
[1, 2], (1, 2), {"k": 1} |
List, Tuple, Dict |
Python methods: .append .pop .get .items .keys … |
0..10, 0..=10, 0s..5s |
Range |
end excluded / included; ranges with units |
tensor([[1, 2], [3, 4]]), zeros(3, 3), randn(64) |
Tensor |
NumPy-style arrays, may carry a unit; @ is matrix product |
record(W=w, b=b) |
Record |
named fields, no declaration |
fn(x) => x * 2 |
Fn |
functions are values |
Variables and operators
let a = 1 # cannot be reassigned
var b = 2 # can: b = 3, b += 1 (also -= *= /= //= %= **= @=)
let x, y = (1, 2) # unpacking
a + b a - b a * b a / b a // b a % b a ** b a @ b # arithmetic, matrix product
a == b a != b a < b a <= b a ~= b # ~= approximately equal (also checks units)
a and b a or b not a x in xs # logic, membership
a if cond else b data |> normalize |> train # conditional, pipe
xs[0] xs[-1] xs[1:3] xs[::2] A[:, 0] A[A > 0] # indexing and slicing
Control flow
if x > 0:
print("positive")
elif x == 0:
print("zero")
else:
print("negative")
while n > 1:
n //= 2
for i in 0..10: # also lists, strings, dict keys, tensors, files, channels
if i == 3:
continue
if i == 7:
break
for i, item in enumerate(items):
pass
assert total > 0, "total must be positive"
let squares = [x * x for x in 0..10 if x % 2 == 0]
let pairs = [(i, j) for i in 0..3 for j in 0..3 if i != j]
Errors
error("message") stops the program with a RuntimeError; assert stops with an AssertionError.
Apsi 1.10.0 has no try/except — that arrived in 2.0.0.
Functions
fn area(w, h = 1.0) = w * h # one expression
fn stats(xs: List) -> Tuple: # a block
let m = mean(xs)
return m, std(xs)
area(2.0, h=3.0) # keyword arguments
let double = fn(x) => x * 2 # lambda
fn attention[B, T, D](q: Tensor[B, T, D], k: Tensor[B, T, D]) -> Tensor[B, T, T]:
return q @ transpose(k, (0, 2, 1)) / sqrt(D) # shapes are checked at every call
Decorators: @memo (cache results), @precision(f32) / @precision(exact).
Structs (your own types)
struct Particle:
pos: Tensor[3, Length]
vel: Tensor[3, Velocity]
mass: Mass = 1kg
fn kinetic(self) -> Energy = 0.5 * self.mass * dot(self.vel, self.vel)
let p = Particle(tensor([0.0, 0, 0]) * u.m, tensor([1.0, 0, 0]) * u.m / u.s)
print(p.kinetic()) # 0.5 J
Physical units
2kg, 3.5[m/s], 9.81[m/s^2], 1[kWh], 90deg — every SI unit and prefix. Adding a length to a time, or
passing a mass where a Length is declared, is reported before the program runs. d as [km] converts
for display; magnitude(x) gives the plain number in SI units; unit(x) and dim(x) describe it. Type names such as
Length, Mass, Time, Velocity, Force, Energy, Power, Pressure are used in annotations.
Differential equations (evolve)
var x = 1m
var v = 0[m/s]
evolve x, v over t in 0[s]..10[s] step 1[ms] using rk4 record every 10 into traj:
x' = v
v' = -4[N/m] / 1kg * x
Methods: euler, midpoint, rk4, rk45 (adaptive, tol 1e-10), symplectic, verlet.
Gradients
grad(f)(x), value_and_grad(f)(x), hessian(f), jacobian(f), derivative(f, x) — on numbers, tensors,
quantities (the gradient has the right units) and parameter trees (records, structs, lists, dicts).
Tests
test "falling takes longer from higher":
assert fall(20m) > fall(10m)
apsi test runs every test block of a file, folder or project.
Permissions
Programs run sandboxed. Files, network, environment variables and Python need explicit flags:
--allow-read[=DIRS], --allow-write[=DIRS], --allow-net[=HOSTS], --allow-env, --allow-python[=safe|all],
or --allow-all. apsi audit app.apsi prints exactly the flags a program needs.
Built-in functions and values (201)
Available everywhere without use. Grouped by first letter; the signature shows parameters (=… means optional).
A
| Name | What it is |
|---|---|
abs(x) |
absolute value (element-wise for tensors; keeps units) |
acos(x) |
inverse cosine, radians |
all(iterable, /) |
Return True if bool(x) is True for all values x in the iterable. |
any(iterable, /) |
Return True if bool(x) is True for any x in the iterable. |
approx(a, b, rel=1e-06, atol=1e-12) |
true when a and b are equal within a relative and absolute tolerance (also a ~= b) |
arange(start, stop=None, step=1) |
evenly spaced values in [start, stop) with a step, as a tensor |
argmax(x, axis=None) |
index of the largest value (along an axis) |
argmin(x, axis=None) |
index of the smallest value (along an axis) |
args() |
Command-line arguments after the program name: apsi run app.apsi a b -> ["a", "b"]. |
asin(x) |
inverse sine, radians |
atan(x) |
inverse tangent, radians |
atan2(y, x) |
angle of the point (x, y), radians |
B
| Name | What it is |
|---|---|
bf16 |
value |
bf8 |
value |
bin(number, /) |
Return the binary representation of an integer. |
bool(/, *args, **kwargs) |
true/false of a value |
C
| Name | What it is |
|---|---|
callable(obj, /) |
Return whether the object is callable (i.e., some kind of function). |
cbrt(x) |
cube root |
ceil(x) |
round up to an integer |
chars(s) |
the characters of a string as a list |
chr(i, /) |
Return a Unicode string of one character with ordinal i; 0 <= i <= 0x10ffff. |
clip(x, lo, hi) |
limit values to [lo, hi] |
cload(path) |
load a C library (needs --allow-ffi) |
clock() |
time since the program started, in seconds (a Quantity) |
concat(items, axis=0) |
join tensors along an axis |
cos(x) |
cosine (radians or an angle quantity) |
cosh(x) |
hyperbolic cosine |
cross(a, b) |
cross product of 3-vectors |
cstr |
value |
cumsum(x, axis=None) |
running sum |
D
| Name | What it is |
|---|---|
dequantize(q) |
turn a quantized tensor back into floats |
derivative(f, x) |
numerical derivative of a function at a point |
dict(/, *args, **kwargs) |
make a dictionary |
dim(x) |
the physical dimension of a value (length, time …) |
divmod(x, y, /) |
Return the tuple (x//y, x%y). Invariant: div*y + mod == x. |
dot(a, b) |
dot product |
E
| Name | What it is |
|---|---|
e |
constant |
e4m3 |
value |
e5m2 |
value |
einsum(spec, *operands) |
Einstein summation, e.g. einsum("bij,bjk->bik", A, B). Units multiply; differentiable. |
enumerate(xs, start=0) |
pairs (index, item) |
error(msg) |
stop the program with an error message |
exact(x) |
switch to exact rational arithmetic in a block or for a value |
exists(path) |
true when a file exists (needs read permission) |
exit(code=0) |
Stop the program with an exit status (0 = success). |
exp(x) |
e to the power x |
eye(n) |
identity matrix |
F
| Name | What it is |
|---|---|
f16 |
value |
f32 |
value |
f64 |
value |
filter(f, xs) |
items of a list for which a function returns true |
flatten(x) |
tensor as one dimension |
float(x) |
convert to a floating-point number |
floor(x) |
round down to an integer |
format(value, format_spec='', /) |
Return type(value).format(value, format_spec) |
format_info(fmt) |
details of a number format (f16, bf16, f32 …) |
fp16 |
value |
fp32 |
value |
fp4 |
value |
fp4_e2m1 |
value |
fp6 |
value |
fp64 |
value |
fp6_e2m3 |
value |
fp6_e3m2 |
value |
fp8 |
value |
fp8_e4m3 |
value |
fp8_e5m2 |
value |
from_py(x) |
Python/JSON value -> Apsi value ({value, unit} dicts become Quantities). |
from_torch(t) |
turn a PyTorch tensor into an Apsi tensor |
fsum(x) |
Correctly rounded sum (no accumulated rounding error), for lists and tensors of any size. |
full(shape, value) |
tensor filled with one value |
G
| Name | What it is |
|---|---|
gelu(x) |
function |
getattr(obj, name, *default) |
getattr(obj, "field"[, default]); names starting with _ are never reachable. |
getenv(name, default=None) |
Read an environment variable (needs --allow-env); the place for secrets like API keys. |
grad(f, wrt=0) |
gradient of a function (automatic differentiation) |
H
| Name | What it is |
|---|---|
hasattr(obj, name) |
true when a value has a field or method |
hessian(f) |
hessian(f)(x) -> matrix of second derivatives of a scalar f. |
hex(number, /) |
Return the hexadecimal representation of an integer. |
http_get(url, timeout=30) |
download a URL (needs --allow-net) |
http_post_json(url, data, timeout=30) |
POST JSON to a URL (needs --allow-net) |
I
| Name | What it is |
|---|---|
i32 |
value |
i64 |
value |
inf |
constant |
input(prompt='') |
Read one line from standard input (without the newline); returns none at end of input. |
int(x) |
convert to an integer |
int4 |
value |
int8 |
value |
iter(…) |
iter(iterable) -> iterator iter(callable, sentinel) -> iterator |
J
| Name | What it is |
|---|---|
jacobian(f) |
jacobian(f)(x) -> d f_i / d x_j (f: Tensor[M] -> Tensor[M], x: Tensor[N]) as Tensor[M, N]. |
join(xs, sep='') |
join strings with a separator |
json_parse(text) |
parse JSON text into lists, dicts, numbers and strings |
json_str(value) |
turn a value into JSON text (indent, sort_keys …) |
K
| Name | What it is |
|---|---|
keys(d) |
keys of a dict as a list |
L
| Name | What it is |
|---|---|
laplace(f) |
laplace(f)(x) -> Σ ∂²f/∂x_i² (trace of the Hessian), e.g. for PDE residuals. |
len(x) |
number of items |
library_path(path) |
The actual file cload() would load (e.g. vecmath -> vecmath.dll on Windows). |
linspace(start, stop, n=50) |
n evenly spaced values from start to stop |
list(x=()) |
make a list from any sequence |
load_csv(path, skip_header=0) |
read a CSV file into columns/rows |
load_json(path) |
read a JSON file |
log(x) |
natural logarithm |
log10(x) |
base-10 logarithm |
log2(x) |
base-2 logarithm |
log_softmax(x, axis=-1) |
log of softmax, numerically stable |
M
| Name | What it is |
|---|---|
magnitude(x) |
the number without its unit (in SI base units) |
map(f, xs) |
apply a function to every item |
matmul(a, b) |
matrix product (also a @ b) |
max(*args, axis=None, keepdims=False) |
largest value (of a list/tensor, or of the arguments) |
mean(x, axis=None, keepdims=False) |
average |
measure(value, sigma) |
value ± sigma -> an independent measurement with standard uncertainty sigma. |
memo(fn) |
cache a function's results (@memo) |
meshgrid(x, y) |
coordinate grids from 1-D axes |
min(*args, axis=None, keepdims=False) |
smallest value |
N
| Name | What it is |
|---|---|
nan |
constant |
nbytes(x) |
memory a tensor uses, in bytes |
ndim(x) |
number of tensor dimensions |
next(…) |
next(iterator[, default]) |
nominal(x) |
central value of an uncertain quantity |
norm(x, axis=None) |
Euclidean (or other) norm |
O
| Name | What it is |
|---|---|
oct(number, /) |
Return the octal representation of an integer. |
ones(*shape, dtype=None) |
tensor of ones |
ones_like(x) |
ones with the shape of another tensor |
ord(character, /) |
Return the ordinal value of a character. |
outer(a, b) |
outer product |
P
| Name | What it is |
|---|---|
param_count(tree) |
number of trainable numbers in a model |
permissions() |
the permissions the program runs with |
permutation(n, seed=None) |
random permutation of 0..n |
pi |
constant |
platform() |
"windows", "linux" or "macos". |
pmap(f, xs, workers=None) |
Parallel map on a thread pool (numpy/BLAS work releases the GIL). |
pow(base, exp, mod=None) |
Equivalent to baseexp with 2 arguments or baseexp % mod with 3 arguments |
precision(dtype) |
@precision(f32) / @precision(exact): numeric precision of a function. |
print(*args, sep=' ', end='\n') |
write values to the output, separated by spaces |
prod(x, axis=None) |
product of all values |
ptr_f32 |
value |
ptr_f64 |
value |
ptr_i32 |
value |
ptr_i64 |
value |
pyimport(name) |
use a Python module (pure ones like collections need no permission) |
Q
| Name | What it is |
|---|---|
qmatmul(a, b) |
Matrix multiply with quantised operands: decode to FP32, multiply, accumulate in FP32 (the same numerics as low-precision tensor-core GEMMs). |
quant_error(x, fmt, axis=None) |
Relative RMS error introduced by storing x in fmt. |
quantize(x, fmt, scale='auto', axis=None) |
Quantise a tensor. scale="auto" maps max|x| to the format's largest value (per tensor, or per channel along axis); scale=1.0 keeps raw values (no scaling). |
R
| Name | What it is |
|---|---|
rand(*shape, seed=None) |
uniform random numbers in [0, 1) |
randint(lo, hi, *shape, seed=None) |
random integers |
randn(*shape, seed=None) |
normally distributed random numbers |
range(a, b=None, step=1) |
integers start..stop with a step (like Python) |
read_text(path) |
read a text file |
record(**kw) |
a lightweight object with named fields |
relative_uncertainty(x) |
uncertainty divided by the value |
relu(x) |
max(x, 0) |
repr(x) |
text form of a value as code would write it |
reshape(x, *shp) |
same data, new shape |
reversed(xs) |
items in reverse order |
roll(x, shift, axis=None) |
shift values cyclically |
round(x, digits=0) |
round to n digits |
round_to(x, fmt, scale='auto', axis=None) |
Round x to what the format can represent and return it as a normal tensor ("fake quantisation"). Gradients pass straight through, so this works inside training. |
S
| Name | What it is |
|---|---|
save_csv(path, data, header='') |
write rows to a CSV file |
save_json(path, value) |
write a value as a JSON file |
security_policy() |
the active security profile |
seed(n) |
make random numbers reproducible |
set(/, *args, **kwargs) |
a set: unique items, fast in |
shape(x) |
shape of a tensor |
sigma(x) |
standard uncertainty of a value |
sigmoid(x) |
1 / (1 + e^-x) |
sin(x) |
sine (radians or an angle quantity) |
sinh(x) |
hyperbolic sine |
softmax(x, axis=-1) |
normalised exponentials (probabilities) |
softplus(x) |
log(1 + e^x) |
sort(x) |
sorted copy of a tensor |
sorted(xs, key=None, reverse=False) |
sorted copy of a list (key=, reverse=) |
sqrt(x) |
square root (units become their square root) |
stack(items, axis=0) |
stack tensors along a new axis |
std(x, axis=None) |
standard deviation |
stop_gradient(x) |
use a value without differentiating through it |
str(x) |
text form of a value |
sum(x, axis=None, keepdims=False) |
sum of all values (or along an axis) |
T
| Name | What it is |
|---|---|
tan(x) |
tangent |
tanh(x) |
hyperbolic tangent |
tau |
constant |
tensor(x, dtype=None) |
make a tensor from numbers or nested lists (dtype=…) |
testing() |
true while apsi test runs |
timed(fn) |
@timed: print how long each call takes. |
to_float(x) |
plain float from a quantity or 1-element tensor |
to_py(x) |
Apsi value -> plain Python/JSON-friendly value (units become {value, unit}). |
to_torch(x, device=None) |
turn an Apsi tensor into a PyTorch tensor (needs --allow-python) |
transpose(x, axes=None) |
swap tensor axes |
tree_map(f, *trees) |
apply a function to every leaf of nested lists/dicts/records |
tuple(/, *args, **kwargs) |
make a tuple |
type(v) |
type name of a value ("Int", "Tensor" …) |
U
| Name | What it is |
|---|---|
u |
u.km, u.eV ... -> one of that unit as a Quantity. |
uint8 |
value |
unique(xs) |
distinct values |
unit(x) |
the unit of a quantity |
V
| Name | What it is |
|---|---|
value_and_grad(f, wrt=0) |
value and gradient of a function (automatic differentiation) |
var(x, axis=None) |
variance |
void |
value |
W
| Name | What it is |
|---|---|
where(cond, a, b) |
choose element-wise: where(cond, a, b) |
write_text(path, text) |
write a text file (needs write permission) |
Z
| Name | What it is |
|---|---|
zeros(*shape, dtype=None) |
tensor of zeros |
zeros_like(x) |
zeros with the shape of another tensor |
zip(*xs) |
pairs items of several lists |
Standard modules (22)
Load a module with use NAME (all its names) or use NAME as n (then n.member).
use crypto — 11 names
| Name | What it is |
|---|---|
b64decode(text) |
function |
b64encode(text) |
function |
hash(data, algo='sha256') |
function |
hmac_sign(key, message, algo='sha256') |
function |
hmac_verify(key, message, signature, algo='sha256') |
function |
password_hash(password, n=16384, r=8, p=1) |
Salted password hash to store in a database. |
password_verify(password, stored) |
function |
random_hex(nbytes=32) |
function |
random_token(nbytes=32) |
function |
secure_equal(a, b) |
Constant-time comparison (prevents timing attacks). |
secure_randint(lo, hi) |
Uniform integer in [lo, hi) from the OS CSPRNG. |
use data — 28 names
| Name | What it is |
|---|---|
batch(p, size, drop_last=False) |
function |
cache(p, directory=None, shard=4096) |
Cache a pipeline. directory=none -> RAM; otherwise memory-mapped shards on disk. |
disk_cache(directory='cache') |
@disk_cache("cache"): memoise a function's results on disk across runs. |
filter(p, f) |
function |
flush(x) |
function |
from_csv(path, skip_header=0, chunk=10000, delimiter=',') |
function |
from_files(pattern) |
function |
from_generator(f) |
f() is called at the start of every epoch and must return an iterable. |
from_jsonl(path) |
function |
from_list(xs) |
function |
from_npy(path) |
function |
from_parquet(path, columns=None, rows=65536) |
Stream a Parquet file in record batches: each item is a dict of column -> tensor. |
from_range(n) |
function |
from_tensors(*arrays, batch=None, shuffle=False, seed=None, drop_last=False) |
Rows of one or more equal-length tensors: from_tensors(X, y) yields (x_i, y_i). |
interleave(pipelines, cycle=True) |
Alternate items from several pipelines (round robin) until all are exhausted. |
load_tensor(path, mmap=False) |
function |
map(p, f, workers=None, ordered=True) |
Apply f to every item; workers > 1 runs f in parallel (numpy work releases the GIL). |
open_tensor(path, shape, dtype='f32', mode='w+') |
A memory-mapped tensor on disk (SSD): larger than RAM, written/read lazily. |
prefetch(p, n=2) |
Produce up to n items ahead on a background thread (overlaps loading and compute). |
repeat(p, times=None) |
function |
save_tensor(path, x) |
function |
shard(p, count, index) |
Every count-th item starting at index — split one dataset across workers or machines. |
shuffle(p, buffer=1024, seed=None) |
Streaming shuffle with a bounded buffer (a full shuffle when buffer >= dataset size). |
skip(p, n) |
function |
take(p, n) |
function |
throughput(p, limit=None) |
Measure items per second of a pipeline (optionally only the first limit items). |
unbatch(p) |
function |
window(p, size, shift=1, drop_last=True) |
Sliding windows over a stream: each item is a tensor of size consecutive items (time series). |
use ffi — 6 names
| Name | What it is |
|---|---|
cload(path) |
function |
ptr_f32 |
value |
ptr_f64 |
value |
ptr_i32 |
value |
ptr_i64 |
value |
void |
value |
use gpu — 8 names
| Name | What it is |
|---|---|
cpu_threads() |
function |
device() |
"cuda:0" when a GPU meeting Apsi's target tier is usable through CuPy, otherwise "cpu". |
gpu_available() |
function |
gpu_info() |
function |
hardware() |
function |
to_cpu(x) |
function |
to_device(x, dev=None) |
function |
to_gpu(x) |
function |
use io — 9 names
| Name | What it is |
|---|---|
exists(path) |
function |
json_parse(text) |
function |
json_str(value) |
function |
load_csv(path, skip_header=0) |
function |
load_json(path) |
function |
read_text(path) |
function |
save_csv(path, data, header='') |
function |
save_json(path, value) |
function |
write_text(path, text) |
function |
use layers — 67 names
| Name | What it is |
|---|---|
activation(fn) |
function |
add() |
function |
autoencoder(d_in, latent, hidden=(64,), act='relu') |
Returns a DAG with outputs [reconstruction, code]. |
avg_pool(k=2) |
type |
batch_norm_layer(d, eps=1e-05) |
Normalises over the batch (and spatial) axes with the current batch's statistics. |
bilinear(n1, n2, n_out) |
type |
check_torch(*a, **k) |
Compare every layer type on NumPy and PyTorch (outputs and gradients, float64). |
cnn(in_channels, classes, image=28, channels=(16, 32), dense_width=64) |
Small convolutional classifier for images shaped [N, C, H, W]. |
concatenate() |
function |
conv2d_layer(c_in, c_out, k=3, stride=1, padding='same') |
type |
count_params(params) |
function |
dag(nodes, inputs=('x',), output=None) |
function |
dense(n_in, n_out, act=None) |
function |
devices() |
The compute devices available: NumPy, and PyTorch CPU / CUDA / ROCm / MPS / XPU when installed. |
dropout_layer(p=0.1) |
type |
embedding(vocab, d) |
type |
fit(model, params, X, y=None, backend='numpy', **kw) |
Train model. Returns record(params, history, val_history, device). |
flatten_layer(/, *args, **kwargs) |
type |
gat(n_in, n_out, heads=4, concat=True, slope=0.2) |
Graph attention (Veličković et al.) with several heads; heads are concatenated (or averaged). |
gat_net(n_in, hidden, classes, heads=4, dropout=0.3) |
function |
gather(x, ids) |
Rows of x at ids (differentiable). |
gcn(n_in, n_out, bias=True) |
Graph convolution (Kipf & Welling): h_i = Σ_j x_j W / sqrt(deg_i deg_j). |
gcn_net(n_in, hidden, classes, layers=2, dropout=0.5) |
function |
gin(n_in, n_out, hidden=None) |
Graph isomorphism network layer: MLP((1 + eps) x_i + Σ_j x_j). |
gin_net(n_in, hidden, classes, layers=3, pool='sum') |
Graph-level classifier: GIN layers, pooling per graph, linear head. |
global_avg_pool(/, *args, **kwargs) |
type |
graph(edges=None, n=None, src=None, dst=None, self_loops=True, undirected=False, batch=None) |
graph(edges=[[0, 1], [1, 2]], n=3) or graph(src=tensor, dst=tensor, n=…). batch assigns nodes to separate graphs for graph-level tasks (used by graph_pool). |
graph_pool(how='mean') |
Node features -> one vector per graph (mean, sum or max over each graph's nodes). |
gru_layer(n_in, n_hidden, return_sequences=True) |
type |
identity(/, *args, **kwargs) |
type |
lambda_layer(fn, name='lambda', torch_fn=None) |
type |
last_step(/, *args, **kwargs) |
type |
layer_norm_layer(d, eps=1e-05) |
type |
linear(n_in, n_out, bias=True, init='he') |
function |
lstm_classifier(n_in, hidden, classes, layers=1) |
function |
lstm_layer(n_in, n_hidden, return_sequences=True) |
type |
max_pool(k=2) |
type |
mean_pool(axis=1) |
Mean over one axis, e.g. over time: [B, T, D] -> [B, D]. |
mlp(sizes, act='relu', dropout=0.0, norm=False, out_act=None) |
Multilayer perceptron, e.g. mlp([2, 64, 64, 3]). |
multi_head_attention(d, heads=4, causal=False) |
type |
multiply() |
function |
parallel(branches, combine='concat') |
function |
params_from_torch(*a, **k) |
Parameters of a module made by torch_module (after training it in Python) as an Apsi parameter tree. |
positional_encoding(max_len, d, learned=False) |
type |
predict(model, params, X, backend='numpy', **kw) |
function |
reshape_layer(*shape) |
type |
residual(inner, pre_norm=None) |
function |
resnet_mlp(d_in, d_out, width=64, blocks=3, act='gelu') |
Deep MLP with residual blocks and layer norm — trains stably at any depth. |
rms_norm_layer(d, eps=1e-06) |
type |
sage(n_in, n_out, aggregate='mean') |
GraphSAGE: h_i = x_i W_self + mean_{j→i} x_j W_neigh. |
scale(d, shift=True) |
A learnable per-feature scale (and shift). |
segment_count(ids, n) |
function |
segment_max(data, ids, n) |
Per-segment maximum (no gradient through the choice of maximum). |
segment_mean(data, ids, n) |
function |
segment_softmax(scores, ids, n) |
Softmax of scores within each segment (e.g. over the incoming edges of every node). |
segment_sum(data, ids, n) |
out[k] = sum of data[i] where ids[i] == k (k < n). Differentiable in data. |
select(i) |
Pick one element of a list/tuple input (e.g. the output of parallel). |
sequential(layers) |
function |
siamese(encoder, combine='concat', head=None) |
Shared encoder applied to [a, b]; the outputs are combined (concat/add/mul/list) and optionally fed to head. |
summary(model, params=None) |
A table of the model's layers and parameter counts (printed, and returned as a string). |
torch_module(*a, **k) |
The model with its parameters as a torch.nn.Module: module(x) / module(x, graph=g). |
transformer_block(d, heads=4, ff=None, causal=False, dropout=0.0, activation='gelu') |
Pre-norm transformer block: x + attention(norm(x)), then x + MLP(norm(x)). |
transformer_classifier(vocab, classes, d=64, heads=4, layers=2, context=128) |
Encoder for sequences of token ids [B, T] -> class logits [B, classes] (mean pooling). |
transformer_encoder(d, heads=4, layers=2, ff=None, causal=False, dropout=0.0) |
function |
transformer_lm(vocab, d=64, heads=4, layers=2, context=128, dropout=0.0) |
Decoder-only (GPT-style) language model: token ids [B, T] -> logits [B, T, vocab]. |
vae(d_in, latent, hidden=(64,), act='relu') |
Variational autoencoder. Returns [reconstruction, mu, logvar]; train with vae_loss. |
vae_loss(outputs, x, beta=1.0) |
function |
use linalg — 8 names
| Name | What it is |
|---|---|
det(a) |
function |
eig(a) |
function |
eigh(a) |
function |
inv(a) |
function |
norm(x, axis=None) |
function |
solve(a, b) |
function |
svd(a) |
function |
trace(a) |
function |
use math — 25 names
| Name | What it is |
|---|---|
abs(x) |
function |
acos(x) |
function |
asin(x) |
function |
atan(x) |
function |
atan2(y, x) |
function |
cbrt(x) |
function |
ceil(x) |
function |
cos(x) |
function |
cosh(x) |
function |
e |
constant |
exp(x) |
function |
floor(x) |
function |
inf |
constant |
log(x) |
function |
log10(x) |
function |
log2(x) |
function |
nan |
constant |
pi |
constant |
round(x, digits=0) |
function |
sin(x) |
function |
sinh(x) |
function |
sqrt(x) |
function |
tan(x) |
function |
tanh(x) |
function |
tau |
constant |
use models — 10 names
| Name | What it is |
|---|---|
dequantize_model(params) |
function |
hf_pipeline(task, model=None, device=None, **kw) |
A Hugging Face transformers pipeline: classify = hf_pipeline("sentiment-analysis"). |
load_safetensors(path, dtype=None, names=None, nested=True) |
function |
model_size(params) |
Bytes used by all tensors in a parameter tree (counts compact formats at their real size). |
onnx_model(path, providers=None) |
Run an ONNX model with onnxruntime: m = onnx_model("net.onnx"); m({"input": x}). |
qlinear(x, W, b=None) |
x @ W (+ b) where W may be a QTensor — decodes, multiplies and accumulates in FP32. |
quantize_model(params, dtype=None, min_size=1024) |
Store every weight matrix (>= min_size elements) in a compact format; others stay as-is. |
safetensors_info(path) |
function |
save_safetensors(path, params, metadata=None) |
function |
torch_load(path, map_location='cpu') |
function |
use net — 2 names
| Name | What it is |
|---|---|
http_get(url, timeout=30) |
function |
http_post_json(url, data, timeout=30) |
function |
use nn — 51 names
| Name | What it is |
|---|---|
accuracy(logits, labels) |
function |
adagrad(lr=0.01, eps=1e-10) |
function |
adam(lr=0.001, b1=0.9, b2=0.999, eps=1e-08) |
function |
adamw(lr=0.001, b1=0.9, b2=0.999, eps=1e-08, weight_decay=0.01) |
function |
attention(q, k, v, mask=None) |
Scaled dot-product attention over the last two axes. |
batch_norm(x, gamma=None, beta=None, eps=1e-05, axis=0) |
Batch normalisation over axis (training-mode statistics). |
batches(X, y, size, seed=None) |
function |
causal_mask(T) |
function |
clip_grad_norm(grads, max_norm=1.0) |
function |
conv2d(x, w, b=None, stride=1, padding=0) |
function |
conv_init(c_in, c_out, k=3, seed=None) |
function |
cosine_lr(step, total, base=0.001, warmup=0, minimum=0.0) |
function |
cross_entropy(logits, labels) |
function |
dense(n_in, n_out, seed=None, scale=None) |
A dense layer's parameters: record(W, b) with He initialisation. |
dropout(x, p=0.1, train=True, seed=None) |
function |
embedding_init(vocab, d, seed=None) |
function |
gelu(x) |
function |
global_norm(grads) |
function |
gru(p, xs) |
function |
gru_cell(p, x, h) |
function |
gru_init(n_in, n_hidden, seed=None) |
function |
layer_norm(x, gamma=None, beta=None, eps=1e-05) |
function |
linear_warmup(step, base=0.001, warmup=100) |
function |
load_params(path, like) |
function |
log_softmax(x, axis=-1) |
function |
lstm(p, xs) |
Run an LSTM over a sequence xs: [B, T, n_in] -> outputs [B, T, n_hidden]. |
lstm_cell(p, x, h, c) |
One LSTM step: returns (h, c). x: [B, n_in], h, c: [B, n_hidden]. |
lstm_init(n_in, n_hidden, seed=None) |
LSTM parameters: one fused weight for the 4 gates (input, forget, cell, output). |
make_blobs(n=300, centers=3, dim=2, spread=0.5, seed=0) |
function |
make_moons(n=200, noise=0.1, seed=0) |
function |
make_regression(n=100, features=3, noise=0.1, seed=0) |
function |
max_pool2d(x, k=2) |
function |
mlp_init(sizes, seed=0) |
function |
mse(pred, target) |
function |
norm_init(d) |
function |
numeric_grad(f, x, eps=1e-06) |
Finite-difference gradient (for checking autodiff). |
one_hot(labels, k) |
function |
relu(x) |
function |
rms_norm(x, gamma=None, eps=1e-06) |
function |
rmsprop(lr=0.001, decay=0.9, eps=1e-08) |
function |
save_params(path, params) |
function |
set_lr(opt, lr) |
function |
sgd(lr=0.01, momentum=0.0) |
function |
sigmoid(x) |
function |
softmax(x, axis=-1) |
function |
spiral_data(n_per_class=100, classes=3, noise=0.2, seed=0) |
Classic spiral toy dataset -> (X: Tensor[N, 2], y: Tensor[N] of class ids). |
standardize(X, axis=0) |
Return (X_scaled, mean, std) so new data can be scaled the same way. |
step_lr(step, base=0.001, every=100, factor=0.5) |
function |
tanh(x) |
function |
train(loss_fn, params, data, opt, epochs=10, batch_size=None, seed=0, verbose=True, clip=None, schedule=None, …) |
Generic training loop. |
train_test_split(X, y, test=0.2, seed=0) |
function |
use parallel — 12 names
| Name | What it is |
|---|---|
atomic(value=0) |
function |
bench(f, repeat=5, warmup=1) |
Time f() -> record(best, mean, runs) in seconds (as Time quantities). |
channel(capacity=0) |
function |
cpu_count() |
function |
lock() |
function |
parallel_for(items, f, workers=None) |
Call f(item) for every item on a thread pool; returns when all are done. |
parallel_reduce(items, f, combine, init, workers=None) |
Map f over items in parallel, then fold the results with combine(acc, x). |
set_threads(n) |
Limit compute threads (BLAS and Apsi's worker pool). Returns the active setting. |
sleep(t) |
function |
spawn(f, *args, **kwargs) |
Run f(*args) concurrently; returns a Task (use task.wait() for the result). |
wait_all(tasks, timeout=None) |
function |
wait_any(tasks, timeout=None) |
Return (index, result) of the first task to finish. |
use physics — 24 names
| Name | What it is |
|---|---|
a_0 |
constant |
alpha_fs |
constant |
AU |
constant |
c |
constant |
epsilon_0 |
constant |
G |
constant |
g0 |
constant |
gradient(u, dx, axis=0) |
Central-difference derivative of a field along one axis (periodic). |
h |
constant |
hbar |
constant |
k_B |
constant |
laplacian(u, dx, boundary='periodic') |
Discrete Laplacian (∇²u) on a regular grid with spacing dx. |
m_e |
constant |
M_earth |
constant |
m_n |
constant |
m_p |
constant |
M_sun |
constant |
meshgrid(x, y) |
function |
mu_0 |
constant |
N_A |
constant |
q_e |
constant |
R_earth |
constant |
R_gas |
constant |
sigma_SB |
constant |
use physics.constants — 21 names
| Name | What it is |
|---|---|
a_0 |
constant |
alpha_fs |
constant |
AU |
constant |
c |
constant |
epsilon_0 |
constant |
G |
constant |
g0 |
constant |
h |
constant |
hbar |
constant |
k_B |
constant |
m_e |
constant |
M_earth |
constant |
m_n |
constant |
m_p |
constant |
M_sun |
constant |
mu_0 |
constant |
N_A |
constant |
q_e |
constant |
R_earth |
constant |
R_gas |
constant |
sigma_SB |
constant |
use physics.fields — 3 names
| Name | What it is |
|---|---|
gradient(u, dx, axis=0) |
Central-difference derivative of a field along one axis (periodic). |
laplacian(u, dx, boundary='periodic') |
Discrete Laplacian (∇²u) on a regular grid with spacing dx. |
meshgrid(x, y) |
function |
use physics.units — 0 names
| Name | What it is |
|---|
use precision — 28 names
| Name | What it is |
|---|---|
bf16 |
value |
bf8 |
value |
dequantize(q) |
function |
e4m3 |
value |
e5m2 |
value |
f16 |
value |
f32 |
value |
f64 |
value |
format_info(fmt) |
function |
fp16 |
value |
fp32 |
value |
fp4 |
value |
fp4_e2m1 |
value |
fp6 |
value |
fp64 |
value |
fp6_e2m3 |
value |
fp6_e3m2 |
value |
fp8 |
value |
fp8_e4m3 |
value |
fp8_e5m2 |
value |
int4 |
value |
int8 |
value |
nbytes(x) |
function |
qmatmul(a, b) |
Matrix multiply with quantised operands: decode to FP32, multiply, accumulate in FP32 (the same numerics as low-precision tensor-core GEMMs). |
quant_error(x, fmt, axis=None) |
Relative RMS error introduced by storing x in fmt. |
quantize(x, fmt, scale='auto', axis=None) |
Quantise a tensor. scale="auto" maps max|x| to the format's largest value (per tensor, or per channel along axis); scale=1.0 keeps raw values (no scaling). |
round_to(x, fmt, scale='auto', axis=None) |
Round x to what the format can represent and return it as a normal tensor ("fake quantisation"). Gradients pass straight through, so this works inside training. |
uint8 |
value |
use python — 5 names
| Name | What it is |
|---|---|
from_py(x) |
Python/JSON value -> Apsi value ({value, unit} dicts become Quantities). |
from_torch(t) |
function |
pyimport(name) |
function |
to_py(x) |
Apsi value -> plain Python/JSON-friendly value (units become {value, unit}). |
to_torch(x, device=None) |
function |
use random — 5 names
| Name | What it is |
|---|---|
permutation(n, seed=None) |
function |
rand(*shape, seed=None) |
function |
randint(lo, hi, *shape, seed=None) |
function |
randn(*shape, seed=None) |
function |
seed(n) |
function |
use sci — 20 names
| Name | What it is |
|---|---|
bisect(f, a, b, tol=1e-12, max_iter=200) |
function |
conj(x) |
function |
cumtrapz(y, x) |
function |
curve_fit(model, x, y, p0, sigma=None, max_iter=200, tol=1e-12) |
Levenberg–Marquardt least squares with an exact autodiff Jacobian. |
einsum(spec, *operands) |
Einstein summation, e.g. einsum("bij,bjk->bik", A, B). Units multiply; differentiable. |
fft(x, axis=-1) |
function |
fftfreq(n, d=1.0) |
function |
find_root(f, x0, tol=1e-12, max_iter=100) |
Newton's method with the exact derivative from autodiff (unit-aware). |
ifft(x, axis=-1) |
function |
imag(x) |
function |
integrate(f, a, b, points=64) |
∫_a^b f(x) dx by Gauss–Legendre quadrature. f receives a tensor of points. Exact for polynomials up to degree 2·points−1; units are [f]·[x]. |
interp(x, xp, fp) |
Piecewise-linear interpolation (units of xp and x must match). |
irfft(x, n=None, axis=-1) |
function |
minimize(f, x0, method='lbfgs', steps=500, tol=1e-10, lr=0.01, history=10, verbose=False) |
Minimise a scalar function of a parameter tree using exact gradients. |
power_spectrum(x, d=1.0) |
One-sided power spectrum |rfft|² with matching frequencies -> (freqs, power). |
real(x) |
function |
rfft(x, axis=-1) |
function |
rfftfreq(n, d=1.0) |
function |
solve_ivp(f, t_span, y0, method='bdf', rtol=1e-06, atol=1e-09, t_eval=None, first_step=None, max_steps=200000) |
Solve y' = f(t, y) from t_span[0] to t_span[1]. |
trapz(y, x=None, dx=None) |
Trapezoidal integral of samples y over x (or uniform spacing dx). Units: [y]·[x]. |
use sys — 8 names
| Name | What it is |
|---|---|
cpu_threads() |
function |
device() |
"cuda:0" when a GPU meeting Apsi's target tier is usable through CuPy, otherwise "cpu". |
gpu_available() |
function |
gpu_info() |
function |
hardware() |
function |
to_cpu(x) |
function |
to_device(x, dev=None) |
function |
to_gpu(x) |
function |
use web — 9 names
| Name | What it is |
|---|---|
abort(status, message='error') |
Abort the current request with an HTTP error: abort(404, "no such user"). |
bearer_token(req) |
function |
jwt_sign(claims, secret, expires_in=3600) |
Create an HS256 JSON Web Token. expires_in: seconds (number or Time quantity). |
jwt_verify(token, secret, leeway=30) |
Return the claims of a valid token, or none if the signature/expiry/algorithm is wrong. |
redirect(location, status=302) |
function |
require_api_key(keys, header='x-api-key', exempt=()) |
A before-hook accepting any of the given API keys (constant-time comparison). |
require_jwt(secret, exempt=()) |
A before-hook: rejects requests without a valid Bearer JWT; sets req.user to its claims. |
response(body='', status=200, headers=None, type=None) |
Build a response explicitly: response("created", status=201, headers={"X-A": "1"}). |
server(name='apsi', max_body=1048576, workers=None, max_connections=10000, log=True, handler_timeout=60.0, head…) |
function |
Command line (38 commands)
Every command takes --help (apsi help run works too).
| Command | What it does |
|---|---|
apsi run |
run a .apsi program (default: the project's main file) |
apsi check |
statically check files or folders without running them |
apsi test |
run test blocks in files or folders |
apsi repl |
interactive prompt |
apsi fmt |
format .apsi files in place (safe: syntax tree must stay identical) |
apsi audit |
list the capabilities a program uses and the minimal flags it needs |
apsi scan |
scan programs, folders and companion files for malware patterns |
apsi verify |
check the installed runtime against its release manifest |
apsi config |
show or change settings (security profile) |
apsi lsp |
run the language server (stdio) for editors |
apsi doctor |
check this machine against Apsi's hardware targets |
apsi serve |
expose a program's functions as a JSON HTTP API |
apsi ast |
print the syntax tree of a file |
apsi tokens |
print the tokens of a file |
apsi pkg |
install, list, remove and lock Python libraries (GPU, ONNX, PyTorch, …) |
apsi install |
install Apsi libraries (.apsil) from the registry or a file |
apsi uninstall |
remove installed Apsi libraries |
apsi pack |
check a library and build dist/NAME-VERSION.apsil |
apsi publish |
upload an .apsil library to the registry |
apsi search |
search the library registry |
apsi lib |
libraries: list, info, registry, login, logout |
apsi yank |
hide a version of your library from new installs (--undo to show it again) |
apsi unpublish |
delete a version of your library from the registry |
apsi release |
upload, list or delete Apsi release files and benchmark results on the website |
apsi editors |
install Apsi support into VS Code, Cursor, Windsurf, Sublime, Vim/Neovim, … |
apsi convert |
translate Python files or folders into Apsi (numpy, math, torch, … mapped) |
apsi version |
print the version |
apsi new |
create a new project folder (apsi new NAME --template app|lib|physics|ai|server) |
apsi init |
turn the current (or given) folder into an Apsi project |
apsi task |
list or run the [tasks] of apsi.toml |
apsi eval |
evaluate code from the command line and print the result |
apsi watch |
re-run a program, tests or the checker whenever files change |
apsi bench |
time a program over several runs (output suppressed) |
apsi doc |
documentation for built-ins and modules (apsi doc nn, apsi doc sqrt) |
apsi completion |
print a shell completion script (bash, zsh, fish, powershell) |
apsi help |
show help for a command (apsi help run) |
apsi build |
make an executable from a program (app.exe on Windows) |
apsi compile |
parse, check and compile programs now so later runs start from the cache |
Found a mistake? Report it · Markdown source