Docs 2.0.0 · 9 min read

From Python to Apsi (apsi convert)

apsi convert translates Python files — or whole folders — into Apsi, maps the libraries you use onto Apsi's own built-ins, checks the result and tells you exactly which lines need a human look.

apsi convert script.py                 # writes script.apsi next to it, then checks it
apsi convert script.py --run           # convert, check and run
apsi convert src/ -o apsi_src/         # a whole project, keeping the folder layout
apsi convert script.py --stdout        # print the Apsi code

In VS Code, Cursor and the other VS Code-family editors: right-click a .py file (or a folder) → Apsi: Convert Python File to Apsi — the result opens beside the Python file.

Typical output:

✓ demo.py → demo.apsi  (2 notes)
    line 48: generator squares(): values are collected into a list
    line 92: try/except: Apsi stops with a clear error message instead of raising exceptions; …

What is translated

Libraries

PyTorch programs → native Apsi

A PyTorch training script becomes an Apsi program that runs without Python and without PyTorch. The converter targets use torch, Apsi's own implementation of the PyTorch API: the same layer names, constructor arguments, parameter names (fc1.weight stored as [out, in]), buffers, losses, optimizers and learning-rate schedulers, implemented natively on Apsi's automatic differentiation. Nothing is approximated and nothing is left for you to finish by hand.

import torch
import torch.nn as nn
import torch.nn.functional as F

class MLP(nn.Module):
    def __init__(self, d_in, hidden, d_out):
        super().__init__()
        self.fc1 = nn.Linear(d_in, hidden)
        self.bn = nn.BatchNorm1d(hidden)
        self.out = nn.Linear(hidden, d_out)
        self.drop = nn.Dropout(0.1)

    def forward(self, x):
        return self.out(self.drop(F.relu(self.bn(self.fc1(x)))))

X = torch.randn(256, 4)
y = (X[:, 0] > 0).long()
model = MLP(4, 32, 2)
opt = torch.optim.AdamW(model.parameters(), lr=1e-2)
sched = torch.optim.lr_scheduler.CosineAnnealingLR(opt, T_max=200)
loss_fn = nn.CrossEntropyLoss(label_smoothing=0.1)
for epoch in range(200):
    opt.zero_grad()
    logits = model(X)
    loss = loss_fn(logits, y)
    loss.backward()
    torch.nn.utils.clip_grad_norm_(model.parameters(), 1.0)
    opt.step()
    sched.step()
model.eval()
print(loss.item())
torch.save(model.state_dict(), "mlp.safetensors")

apsi convert mlp.py writes:

# Converted from mlp.py by `apsi convert`.
use models as models
use torch as torch

var _aux3 = none
var _grads2 = none
var _loss_of1 = none
var loss = none

fn MLP(d_in, hidden, d_out):
    let fc1 = torch.Linear(d_in, hidden)
    let bn = torch.BatchNorm1d(hidden)
    let out = torch.Linear(hidden, d_out)
    let drop = torch.Dropout(0.1)
    fn init_(seed = 0) = record(fc1=fc1.init(seed=seed * 1009 + 1), bn=bn.init(seed=seed * 1009 + 2), out=out.init(seed=seed * 1009 + 3), drop=drop.init(seed=seed * 1009 + 4))
    fn forward_(p, x, train = false) = out(p.out, drop(p.drop, torch.relu(bn(p.bn, fc1(p.fc1, x, train=train), train=train)), train=train), train=train)
    return torch.Module(init_, forward_, "MLP", record(fc1=fc1, bn=bn, out=out, drop=drop))
let X = randn(256, 4)
let y = tensor(X[:, 0] > 0, dtype=i64)
let model = MLP(4, 32, 2)
var model_params = model.init(seed=0)
let opt = torch.AdamW(lr=0.01)
let sched = torch.CosineAnnealingLR(opt, T_max=200)
let loss_fn = torch.CrossEntropyLoss(label_smoothing=0.1)
for epoch in 0..200:
    fn _loss_of1(_p):
        let logits = model(_p, X)
        let loss = loss_fn(logits, y)
        return loss
    loss, _aux3, _grads2 = torch.value_and_grad_aux(_loss_of1)(model_params)
    _grads2 = torch.clip_grad_norm(_grads2, 1.0)
    model_params = opt.step(model_params, _grads2)
    sched.step()
model.eval()
print(loss)
models.save_safetensors("mlp.safetensors", torch.state_dict(model, model_params))

The saved file is a standard safetensors file with PyTorch's names (bn.running_mean, fc1.weight, …): model.load_state_dict(load_file("mlp.safetensors"), strict=True) in PyTorch accepts it unchanged, and the other direction works the same way.

What is converted exactly

Verified exactness. The test suite (tests/test_convert_torch.py, tests/test_torch_compat.py) runs every layer, loss, optimizer and scheduler above next to real PyTorch with identical weights and compares outputs, gradients and learning-rate sequences. A complete training run — convolution, BatchNorm, LSTM, multi-head attention, AdamW, cosine annealing, gradient clipping and label smoothing — ends with the same weights as PyTorch to within 1e-9.

Random initialisation uses Apsi's generator, so a model trained from scratch starts from different random weights than in PyTorch. To reproduce a PyTorch run exactly, load its initial state_dict.

Memory

• torch.checkpoint_layer(layer, params, x) or torch.checkpoint(fn, x) stores only the block inputs and recomputes the rest during the backward pass: about a third of the peak memory for about twice the compute.
• Create parameters with dtype=f32 (or fit(…, precision="fp32")); gradients and Adam state then stay float32.
• DataLoader builds one batch at a time, so datasets larger than memory can be streamed from a Dataset class.

Checked with real programs

tests/pycompat/ holds Python programs that use classes with inheritance and operator methods, dataclasses, custom exceptions, try/except/else/finally, generators (also endless ones), closures with nonlocal, *args/**kwargs, collections, heapq, itertools, re, json, string formatting (%, .format, f-strings), comprehensions with several for, sets, slicing, sorting with keys and numpy. tests/test_python_compat.py converts each one and checks that the Apsi program prints exactly what Python prints. All of them pass.

What needs a human look

The converter never silently drops behaviour. These general Python constructs have no direct Apsi equivalent and are reported with their line number so that you can check the result:

• match statements (rewrite as if/elif), async/await
• random.shuffle and other in-place random operations
• super().method() other than super().__init__(), metaclasses, __getattr__
• base classes from other modules (classes derived from torch.nn.Module and Dataset are converted, see above)
• decorators that have no Apsi equivalent

After converting, run apsi check file.apsi (done automatically) — and consider adding units to the physics parts: let g = 9.81 → let g = 9.81[m/s^2] turns every later formula into a checked one.

Found a mistake? Report it · Markdown source