Docs 2.0.0 · 2 min read

Getting started

This guide takes you from installation to a first program, a first trained model and a first library in about ten minutes.

1. Install

Apsi 2.0.0 runs on Windows 10 or newer and Linux (x86-64) and needs Python 3.12 or newer as its host runtime. The installers check for Python and offer to install it.

• Windows: download the installer from the download page and run it. Details: Install on Windows.
• Linux: unpack the Linux package and run sh install.sh, or install the .deb. Details: Install on Linux.

Check the installation:

apsi version
apsi doctor          # checks Python, the native compiler and your hardware

2. Your first program

apsi new hello
cd hello
apsi run

apsi new creates a project with apsi.toml, src/main.apsi, tests and editor settings. Open src/main.apsi:

fn greet(who: Str) -> Str = f"Hello, {who}!"

let g = 9.81[m/s^2]
let t = 2s
print(greet("Apsi"))
print(f"a stone falls {0.5 * g * t ** 2} in {t}")

Physical units are part of the language. Change t to 2kg and run again: the checker reports the unit error before anything runs.

3. Make it fast

Mark a function @native and it is compiled to machine code for your processor the first time it is called. The machine code is cached on disk, so later runs start immediately.

@native
fn mandel(n: Int, maxit: Int) -> Int:
    var count = 0
    for y in 0..n:
        for x in 0..n:
            let cr = 2.0 * x / n - 1.5
            let ci = 2.0 * y / n - 1.0
            var zr = 0.0
            var zi = 0.0
            var it = 0
            while it < maxit and zr * zr + zi * zi <= 4.0:
                let t = zr * zr - zi * zi + cr
                zi = 2.0 * zr * zi + ci
                zr = t
                it += 1
            if it == maxit:
                count += 1
    return count

print(mandel(1000, 50))

See the native compiler guide for what can be compiled and how to use all cores with parallel for.

4. Train a model

use torch

let model = torch.Sequential(torch.Linear(2, 32), torch.ReLU(), torch.Linear(32, 1))
var params = model.init(0)
let opt = torch.AdamW(lr=1e-2)

let x = randn(256, 2, seed=1)
let y = sum(x * x, axis=1, keepdims=true)

for step in 0..500:
    fn loss_of(p) = torch.mse_loss(model(p, x), y)
    let loss, grads = value_and_grad(loss_of)(params)
    params = opt.step(params, grads)
    if step % 100 == 0:
        print(f"step {step}: loss {loss}")

Already have PyTorch code? Convert it:

apsi convert train.py -o train.apsi
apsi run train.apsi

See From Python and PyTorch.

5. Use and publish libraries

apsi install physics-units        # newest version from the registry

use physics_units

To publish your own, create a library project, build it into dist/ and upload it with an API token:

apsi new my-lib --template lib
cd my-lib
apsi pack
apsi publish --token apsi_…

See Libraries.

6. Where to go next

• Language reference — syntax, types, units, modules.
• AI and machine learning and Reinforcement learning.
• Science, physics and medicine.
• Troubleshooting if something does not work.

Found a mistake? Report it · Markdown source