Chapter 1: Meeting Zyth
More chapters are on the way; until then the manual covers the whole language.
Every example in this chapter was run with zyth 0.1.0 on Linux, and the output shown is the output it printed. If you see something different, your version of Zyth is probably newer than this book.
1.1 What Zyth is, and why it exists
Zyth is a programming language for AI work. Its goal is that the same short program can train a model, check itself before it runs, use the graphics card, run in a web browser, and be shipped as a single file.
Most AI programs today are written in Python, with libraries such as PyTorch doing the heavy lifting. That works, but it has costs:
- Mistakes in the shape of data (a matrix with 512 columns fed to a layer that expects 256) are found only when the program reaches that line. In a training run, that can be hours in.
- A Python program is not one file. It needs Python, the right versions of many libraries, and often the right GPU drivers on the machine that runs it.
- Python itself is slow for ordinary loops, so the real work has to be pushed into libraries written in other languages.
Zyth's answers are:
- Tensors (the grids of numbers that AI models work with) are part of the language. The checker knows their shapes, element types and devices, and it reports mismatches before the program starts, explaining where each number came from.
- Training is built in: automatic gradients, optimizers, models, training on several GPUs or several machines, and fine-tuning methods such as SFT and DPO.
- One program runs on the CPU, on NVIDIA GPUs (CUDA), on Apple GPUs (Metal), on other GPUs through Vulkan and DirectX, and in the browser (WebAssembly and WebGPU).
- "zyth build" turns a program into one executable file.
- The syntax is meant to be easy to guess. A design rule of the language says: "If a beginner can't guess what a line does, the syntax is wrong."
Zyth is young. Be aware of these limits as you learn:
- The language is version 0.1. Details may change between versions. "zyth migrate" rewrites programs when names change.
- "zyth run" interprets most of a program ("--aot" compiles its functions), and "zyth build --release" compiles the whole program to machine code. Tensor and GPU work is fast either way; code that mostly handles text, lists and maps is fast only when compiled.
- Few programs exist outside Zyth's own tests, so you may find rough edges.
1.2 Getting Zyth running
On Linux or macOS, type this in a terminal:
curl -fsSL https://zyth.io/install.sh | sh
On Windows, in PowerShell:
irm https://zyth.io/install.ps1 | iex
The installer downloads the release for your computer, checks it against the release's published SHA-256 sums, and puts the zyth command in .zyth/bin in your home folder. On Windows it adds that folder to your PATH; on Linux and macOS it tells you the line to add.
Check that it works:
$ zyth --version
zyth 0.1.0
"zyth doctor" tells you what Zyth found on your machine. On a PC with an NVIDIA card it prints something like:
$ zyth doctor
zyth 0.1.0 (linux x86_64)
cpu: 16 threads
gpu: CUDA
gpu(0): NVIDIA GeForce RTX 3090 (SMs 82, 0 MB in use)
python: /usr/bin/python3 (`use python.X`, `zyth add py:`)
...
You do not need a GPU for this chapter. Everything except section 1.15 runs on the CPU.
1.3 Your first program
Create a file called hello.zyth containing one line:
print("Hello, Zyth!")
Run it:
$ zyth run hello.zyth
Hello, Zyth!
There is no "main" function, no imports, and no semicolons. A Zyth file runs from top to bottom, like a script. (You may write "fn main()" if you like; it is optional.)
Zyth source files end in .zyth.
Comments start with // and run to the end of the line. /* ... */ comments can span lines, and /// comments document the item below them.
// This is a comment
print("this runs") // so is this
1.4 The zyth command
Everything you do with Zyth goes through one command. The ones you will use most:
zyth run file.zyth Check the program, then run it.
zyth check file.zyth Check the program without running it.
zyth repl Type Zyth lines and see results at once.
zyth build file.zyth Make one executable file (section 1.16).
zyth test folder/ Run the tests in a folder.
zyth fmt . Lay out every file in the standard way.
zyth explain E0401 Explain an error code in plain words.
zyth doctor Show which GPUs and tools Zyth can use.
"zyth run" always checks the whole program first. If the checker finds an error, nothing runs. That is how Zyth catches mistakes before a long job starts.
1.5 Values and variables
let name = "Ada"
let year: i64 = 2026
var count = 0
count = count + 1
const GREETING = "Welcome"
Zyth has three ways to give a value a name:
let a name whose value does not change
var a name whose value can change
const a value fixed when the program is compiled
Use "let" unless you need to change the value. If you write "let" and then change it, "zyth fmt" will turn it into "var" for you.
Zyth works out the type from the value, so you rarely write types. You may write one after a colon, as in "let year: i64 = 2026".
The basic types are:
i8 i16 i32 i64 whole numbers (signed)
u8 u16 u32 u64 whole numbers (never negative)
f16 bf16 f32 f64 numbers with a fractional part
bool true or false
char one character
str text (UTF-8)
A whole number literal such as 42 is an i64. A literal with a point, such as 3.5, is an f64.
Zyth never converts between types behind your back. "1" + 1 is an error. To convert, write "as":
let x = 41
print("as a float: {x as f64 + 0.5}")
prints:
as a float: 41.5
Arithmetic works as you would expect, with one detail worth remembering: dividing two whole numbers gives a whole number.
print(7 / 2, 7.0 / 2.0, 2 ** 10)
prints:
3 3.5 1024
** is "to the power of".
1.6 Printing and text
print takes any number of values and prints them separated by spaces.
Inside text in double quotes, {name} puts a value into the text. A format after a colon controls how a number looks: {pi:.2f} means "two places after the point".
let name = "Ada"
let year: i64 = 2026
var count = 0
count = count + 1
const GREETING = "Welcome"
print("{GREETING}, {name}! It is {year}, and count is {count}.")
let pi = 3.14159265
print("pi to two places: {pi:.2f}")
prints:
Welcome, Ada! It is 2026, and count is 1.
pi to two places: 3.14
Any expression may go inside the braces, as {x as f64 + 0.5} showed above.
Text that spans several lines goes between triple quotes. Zyth removes the indentation the lines share:
let prompt = """
You are a helpful assistant.
Question: {question}
"""
1.7 Functions
fn add(a: i64, b: i64) -> i64 {
return a + b
}
fn square(x: f64) -> f64 = x * x
fn greet(name: str, excited: bool = false) -> str {
let mark = if excited { "!" } else { "." }
return "Hello, {name}{mark}"
}
print(add(2, 3))
print(square(1.5))
print(greet("Lin"))
print(greet("Lin", excited: true))
print(3.0 |> square)
prints:
5
2.25
Hello, Lin.
Hello, Lin!
9.0
Things to notice:
- "fn" starts a function. Parameters have types, and the type after -> is what the function returns.
- A function that is one expression can be written with "=" instead of a block, as square is.
- A parameter can have a default value (excited: bool = false). A caller may leave it out, or name it: greet("Lin", excited: true). Naming arguments makes calls easier to read.
- "if" gives a value, so it can sit on the right of "let".
- |> is the pipe. "x |> f" means f(x). "x |> f(a)" means f(x, a). Pipes read left to right, which suits chains of steps such as the layers of a model. You will see "x |> self.fc1 |> relu |> self.fc2" in section 1.13.
1.8 Making decisions and repeating work
let temp = 31
if temp > 30 {
print("hot")
} else if temp > 15 {
print("mild")
} else {
print("cold")
}
for i in 0..3 { print("i = {i}") }
for i in 1..=3 { print("up to and including: {i}") }
var n = 10
var steps = 0
while n != 1 {
n = if n % 2 == 0 { n / 2 } else { 3 * n + 1 }
steps += 1
}
print("10 reaches 1 in {steps} steps")
var total = 0
loop {
total += 7
if total > 30 { break }
}
print("total {total}")
prints:
hot
i = 0
i = 1
i = 2
up to and including: 1
up to and including: 2
up to and including: 3
10 reaches 1 in 6 steps
total 35
- 0..3 counts 0, 1, 2: it stops before the end. 1..=3 includes the end.
- "while" repeats while its condition is true.
- "loop" repeats forever until "break".
- % is the remainder after division. += adds to a variable in place.
Conditions need no parentheses, but the braces are always required.
1.9 Lists, maps and tuples
var fruits = ["apple", "banana"]
fruits.push("cherry")
print(fruits, fruits.len(), fruits[0], fruits[-1])
for (i, f) in fruits.enumerate() { print("{i}: {f}") }
let squares = [1, 2, 3, 4].map(|x| x * x)
let evens = [1, 2, 3, 4, 5, 6].filter(|x| x % 2 == 0)
print(squares, evens)
var ages = { "ada": 36, "lin": 29 }
ages["sam"] = 41
print(ages["lin"], ages.len())
print(ages.get("bob") ?? 0)
let pair = (3, "three")
let (num, word) = pair
print(num, word)
prints:
["apple", "banana", "cherry"] 3 apple cherry
0: apple
1: banana
2: cherry
[1, 4, 9, 16] [2, 4, 6]
29 3
0
3 three
- A list is written in square brackets. Its items are counted from 0, and fruits[-1] is the last item.
- enumerate() gives each item with its position.
- |x| x * x is a closure: a small function without a name. map applies one to every item, and filter keeps the items for which it is true.
- A map pairs keys with values, written in braces. ages.get("bob") asks for a key that may be missing; ?? gives the value to use when it is (section 1.11).
- A tuple groups a fixed number of values, possibly of different types. "let (num, word) = pair" unpacks it.
1.10 Your own types: structs and enums
A struct groups named fields. An enum is a value that is one of several kinds, each of which may carry its own data.
struct Point {
x: f64
y: f64
}
impl Point {
fn length(self) -> f64 = (self.x * self.x + self.y * self.y).sqrt()
}
enum Shape {
Circle(radius: f64)
Rect(w: f64, h: f64)
Dot
}
fn area(s: Shape) -> f64 {
return match s {
Circle(r) => 3.14159 * r * r
Rect(w, h) => w * h
Dot => 0.0
}
}
let p = Point { x: 3.0, y: 4.0 }
print(p.x, p.length())
for s in [Circle(1.0), Rect(2.0, 3.0), Dot] {
print(area(s))
}
prints:
3.0 5.0
3.14159
6.0
0.0
- "impl Point" adds methods to Point. A method's first parameter is self.
- "match" picks the branch that fits the value and takes the enum's data out into names (r, w, h). "_ =>" matches anything, so you can use it as the last branch to catch every kind you did not name.
- If you leave a kind out and have no "_" branch, "zyth check" stops before the program runs. Save the example as shapes.zyth, remove the Dot branch from area, and run "zyth check shapes.zyth":
error[E0210]: non-exhaustive match: missing `Dot`
--> shapes.zyth:17:12
|
17 | return match s {
| ^^^^^^^^^
|
= help: add the missing cases or a `_ => ...` arm
When you add a new kind to an enum later, every match that forgot it is
reported at once.
- Zyth has no classes and no inheritance. You build types from structs and enums, and share behaviour through traits, which a later chapter covers.
1.11 When there might be no answer: optionals and results
Zyth has no null and no exceptions. A function that may have no answer returns an optional, written ?T. Its value is Some(x) or None. A function that may fail returns a Result: Ok(value) or Err(problem).
fn find(names: str[], wanted: str) -> ?i64 {
for (i, n) in names.enumerate() {
if n == wanted { return Some(i) }
}
return None
}
let people = ["ada", "lin", "sam"]
print(find(people, "lin") ?? -1)
print(find(people, "bob") ?? -1)
match find(people, "sam") {
Some(i) => print("sam is at {i}")
None => print("no sam")
}
fn parse_age(text: str) -> Result<i64, str> {
let n = text.parse_int() ?? -1
if n < 0 { return Err("not an age: {text}") }
return Ok(n)
}
for t in ["42", "old"] {
match parse_age(t) {
Ok(n) => print("age {n}")
Err(e) => print("error: {e}")
}
}
prints:
1
-1
sam is at 2
age 42
error: not an age: old
- str[] is a list of text. In general, T[] is a list of T.
- "a ?? b" gives a's value if there is one, and b if not.
- "match" handles each case by name.
- Inside a function that itself returns a Result, "x?" means "if x is an error, return that error now". You will use it often when reading files:
let text = fs.read("data.txt")?
1.12 A first look at tensors
A tensor is a grid of numbers: a list of numbers (one dimension), a table (two), a stack of tables (three), and so on. Images, text turned into numbers, and the weights of a neural network are all tensors.
let a = tensor.from([[1.0, 2.0], [3.0, 4.0]])
let b = tensor.ones(2, 2)
print(a)
print(a.shape, a.dtype)
print(a + b)
print(a * 10.0)
print(a @ b)
print(a.sum().item(), a.mean().item())
let r = tensor.randn(3, 4)
print(r.shape, r.T.shape)
prints:
tensor<f32, [2, 2]>
[[1.0, 2.0],
[3.0, 4.0]]
[2, 2] f32
tensor<f32, [2, 2]>
[[2.0, 3.0],
[4.0, 5.0]]
tensor<f32, [2, 2]>
[[10.0, 20.0],
[30.0, 40.0]]
tensor<f32, [2, 2]>
[[3.0, 3.0],
[7.0, 7.0]]
10.0 2.5
[3, 4] [4, 3]
- A tensor's type is written tensor<f32, [2, 2]>: the element type, then the shape. f32 is the usual element type.
- + - * / work element by element. A single number is applied to every element, as in a * 10.0.
- @ is matrix multiplication: rows of the left times columns of the right.
- sum() and mean() reduce a tensor to one number; item() takes that number out as an ordinary f64.
- tensor.randn(3, 4) fills a 3 by 4 tensor with random numbers from the normal distribution. .T swaps the last two dimensions.
Other ways to make tensors include tensor.zeros, tensor.ones, tensor.full, tensor.rand, tensor.arange, tensor.linspace and tensor.eye. Common operations include exp, log, sqrt, tanh, relu, softmax, reshape, concat and transpose.
1.13 Zyth's headline feature: shape errors before the program runs
A neural network is a chain of layers. Each layer takes tensors of one width and gives tensors of another. If two neighbouring layers disagree, the program is wrong.
Here is a small classifier with a deliberate mistake. Linear(784 -> 512) makes a layer that turns 784 numbers into 512. The next layer should therefore take 512, but it says 256:
model Classifier {
fc1 = Linear(784 -> 512)
fc2 = Linear(256 -> 10)
fn forward(self, x: tensor<f32, [B, 784]>) -> tensor<f32, [B, 10]> {
return x |> self.fc1 |> relu |> self.fc2
}
}
print("starting")
let m = Classifier()
print(m(tensor.randn(8, 784)).shape)
Run it:
$ zyth run classifier.zyth
error[E0406]: `self.fc2` expects tensor<f32, [..., 256]>, found tensor<f32, [B, 512]>
--> classifier.zyth:6:16
|
6 | return x |> self.fc1 |> relu |> self.fc2
| ^^^^^^^^^^^^^^^^^^^^^ dimension 1 is 512, expected 256
|
= note: 256 comes from `Linear(256 -> 10)` at classifier.zyth:3
= note: 512 comes from `Linear(784 -> 512)` at classifier.zyth:2
= help: change line 3 to `Linear(512 -> 10)`
error: could not run classifier.zyth: 1 error(s) found before running
Notice that "starting" was never printed. The checker found the mistake before a single line ran. It also says where each conflicting number came from and suggests the fix. In Python with PyTorch, the same mistake is found only when that line runs, which in a real job may be after the data has loaded and training has begun.
Make the change it suggests (Linear(512 -> 10)) and run it again:
starting
[8, 10]
A few new things appeared in this example:
- "model" declares a neural network. Its fields are its layers, and Zyth collects their weights for you.
- B in tensor<f32, [B, 784]> is a symbolic dimension: "some number of rows, the same B wherever it appears". Here it is the batch size. The checker proves that if 8 rows go in, 8 rows come out.
- A model can be called like a function: m(x) runs its forward method.
"zyth check" runs the same checks without running anything. Editors use it to underline mistakes as you type.
1.14 Teaching a model: your first training loop
Training means adjusting a model's weights until its outputs match the examples. The steps are always the same:
- Run the model on the inputs.
- Measure how wrong it is (the "loss").
- Ask for the gradient: which way each weight should move to lower the loss.
- Let an optimizer move the weights a little.
- Repeat.
This program learns the rule y = 3x - 1 from 256 examples:
// learn y = 3x - 1 from examples
use zyth.optim.Adam
seed(1)
let x = tensor.randn(256, 1)
let y = x * 3.0 - 1.0
model Line {
layer = Linear(1 -> 1)
fn forward(self, x: tensor<f32, [B, 1]>) -> tensor<f32, [B, 1]> = self.layer(x)
}
let m = Line()
let opt = Adam(m.params, lr: 0.1)
for step in 0..200 {
let loss = ((m(x) - y) ** 2).mean()
opt.step(grad(loss, wrt: m.params))
if step % 50 == 0 { print("step {step}: loss {loss.item():.4f}") }
}
let w = m.layer.w.item()
let b = m.layer.b.item()
print("learned: y = {w:.3f}x + {b:.3f}")
prints:
step 0: loss 10.2627
step 50: loss 0.0222
step 100: loss 0.0004
step 150: loss 0.0000
learned: y = 3.000x + -1.000
Line by line:
- "use zyth.optim.Adam" brings in the Adam optimizer from the standard library. If you forget a "use" line, the error message tells you which one to add.
- seed(1) makes the random numbers the same every run, so your output matches this book.
- ((m(x) - y) ** 2).mean() is the mean squared error: the average of the squared differences between the model's answers and the right ones.
- grad(loss, wrt: m.params) computes the gradient of the loss with respect to every weight. Zyth records the operations as they happen and works backwards through them. You never write a derivative yourself.
- opt.step(...) moves the weights. lr: 0.1 is the learning rate: how big each step is.
The loss falls from 10.26 to almost zero, and the layer's weight and bias end at 3 and -1: the model found the rule from the examples alone.
Real models are bigger, but the loop is the same. The standard library also has "fit", which runs this loop for you with batching, logging, checkpoints and several GPUs. Later chapters use it.
1.15 Using the GPU
A GPU does thousands of multiplications at once, which is what neural networks need. In Zyth, .to(gpu) moves a tensor to the GPU, and operations on GPU tensors run there:
let a = tensor.randn(2048, 2048).to(gpu)
let b = tensor.randn(2048, 2048).to(gpu)
let c = a @ b
print(c.shape, c.device)
prints:
[2048, 2048] gpu
You can move a whole model the same way: Line().to(gpu). Zyth also knows where each tensor lives. If one operation mixes a CPU tensor and a GPU tensor, "zyth check" reports it before the program runs and tells you which one to move:
let a = tensor.ones(2, 2).to(gpu)
let b = tensor.ones(2, 2)
print(a @ b)
error[E0403]: device mismatch: gpu @ cpu — use b.to(gpu)
--> dev.zyth:3:7
Tensors made with tensor.ones, tensor.randn and the other tensor functions start on the CPU unless you give them device: gpu. The check also catches the mistake on a computer without a GPU, where gpu tensors stay on the CPU and the line would run: the same program would then fail on a computer that has one.
The same program works on an NVIDIA card (CUDA), on an Apple Mac (Metal), and, with the WebGPU build, on other GPUs and in a browser. Without a GPU, gpu tensors stay on the CPU and the program still runs.
1.16 Turning a program into one file you can hand to anyone
$ zyth build hello.zyth -o hello
built hello (10.3 MB, self-contained, with the static zyth-rt-static runtime (no npm, C libraries or GPU); run it with ./hello)
$ ./hello
Hello, Zyth!
The result is one executable. The machine that runs it needs no Zyth, no Python and no libraries. Smaller runtimes are used when a program needs less; the size depends on what your program uses.
Add --aot to compile the program's functions to machine code:
$ zyth build --aot hello.zyth -o hello
aot: compiled 0 of 0 function(s) to native code
built hello (10.3 MB, self-contained, with the static zyth-rt-static runtime (no npm, C libraries or GPU); run it with ./hello)
hello.zyth has no functions, so nothing was compiled here. Results are the same either way, and number-heavy functions get much faster: the manual measures fib(30) at 1.1 s interpreted and 16 ms compiled.
1.17 What you have learned, and what comes next
You can now:
- write, check and run a Zyth program, and make an executable from it;
- use let, var and const, the basic types and "as" conversions;
- put values into text with {name} and {value:.2f};
- write functions with default and named arguments, and use the pipe |>;
- use if, for, while, loop and match;
- use lists, maps, tuples, structs and enums;
- handle missing values and errors with ?T, Result, ?? and ?;
- make tensors, do arithmetic and matrix products on them;
- read a shape error and fix it from its help line;
- write a training loop with grad and an optimizer;
- move work to the GPU.
The chapters that follow go deeper into each part: the type system and traits, tensors and their shape rules, models and the layer library, training with fit, data, the GPU and writing your own GPU kernels, working with Python and npm libraries, running in the browser, and shipping programs.
Two references are worth knowing about:
- the manual, Zyth's language specification: https://zyth.io/manual/
- the compact reference written for AI models, which also suits a quick look-up: https://zyth.io/llms.txt
1.18 Exercises
1. Change hello.zyth to print your name and today's year using {} in the text.
2. Write a function "fn celsius(f: f64) -> f64" that turns Fahrenheit into Celsius ((f - 32) * 5 / 9). Print the result for 32, 212 and 98.6 with one place after the point.
3. Write a loop that prints the numbers from 1 to 20, but prints "fizz" for multiples of 3, "buzz" for multiples of 5, and "fizzbuzz" for multiples of both.
4. Make a map from three city names to their populations. Print each city with its population, then use ?? to print 0 for a city that is not in the map.
5. Add a Triangle(base: f64, height: f64) kind to the Shape enum of section 1.10 and handle it in area (half of base times height). Print the area of Triangle(4.0, 3.0).
6. In the classifier of section 1.13, change Linear(784 -> 512) to Linear(784 -> 300) without changing anything else. Before you run it, predict what the error will say. Then run "zyth check" and compare.
7. Change the training program of section 1.14 to learn y = -2x + 5. Then try lr: 1.0 and lr: 0.001. What happens to the loss, and why?
8. If you have a GPU, add .to(gpu) to x, y and the model in section 1.14 and check that the answer is the same.