BlyxDocumentation
Browse chapters
Documentation / Practical projects

Train a neural network with BlyxTorch

Train an XOR classifier, inspect a real gradient, then compile a dense network for your own labels and deploy it as a standalone CPU executable.

Learn a nonlinear decision

XOR labels the input pair (0,1) or (1,0) as positive. A single straight-line decision boundary cannot separate both positive points from the two negative points. The default BlyxTorch model uses two inputs, four tanh hidden units and one output logit. Its 17 parameters include all weights and biases.

Start in VS Code or VSCodium

Install the BlyxTorch extension from your editor’s registry. It installs Blyx Language alongside the trainer. Create a file named sensor.blyx, type bt-sensor, accept the completion, and choose Blyx: Run File. Change the final sensor reading and run it again. An offline install uses the two VSIX files linked from the package page.

Train the released classifier

Download and extract the matching archive. From its folder, run the three commands below. Training takes 250 epochs with Adam, a learning rate of 0.03, batches of four and seed 7. The output is a two-line text checkpoint. The prebuilt trainer runs directly. On Windows PowerShell, start commands with .\blyxtorch.exe and save the checkpoint with | Out-File -Encoding ascii xor.bt.

./blyxtorch train fixtures/xor.csv 250 0.03 4 adam 7 > xor.bt
./blyxtorch predict xor.bt fixtures/xor-features.csv
./blyxtorch score xor.bt fixtures/xor.csv

Read the predictions

The mean training loss is about 0.00630 on the four rows. The probabilities below are rounded. To evaluate performance on a real dataset, keep separate labelled observations out of training and run score on those rows. In the browser example, change the second input from [0, 1] to [0, 0]. Its predicted class changes from true to false.

x0x1TargetProbability
0000.00365
0110.99391
1010.99308
1100.00846

Trace a derivative

The browser program uses a dual number with a value and a tangent. For a trainable weight use tangent 1; for a constant use tangent 0. At w = 1, the loss (2w − 5)² is 9. Its derivative is −12, so a gradient step with learning rate 0.125 moves the weight to 2.5 and the loss becomes zero.

Compile a different network

Widths include input and output. This example uses eight and four hidden units for a three-class classifier. Compile the emitted Blyx source with Blyx 0.2.1, Rust 1.85 or later and a host linker. The resulting executable can train and predict on a different machine of the same target platform. For Windows PowerShell, send the emitted source through Out-File -Encoding ascii classifier.blyx and compile to classifier.exe.

./blyxtorch emit 2,8,4,3 softmax relu > classifier.blyx
blyxc build classifier.blyx -o classifier
./classifier --help

Choose a loss and a header

Use mse for continuous targets, binary for one probability, or softmax for a single class index per observation. The input is an unquoted numerical UTF-8 CSV. Training and gradient commands use labelled rows. Prediction takes the feature columns alone.

TaskExample headerModel output
Two regression targetsx0,x1,y0,y1Two real numbers
Binary classificationx0,x1,y0One probability
Three-class classificationx0,x1,classThree probabilities summing to one

Inspect gradients and checkpoints

The gradient command returns a per-row loss followed by one derivative per trainable weight or bias. The compiled backward pass uses the chain rule to traverse the layers in reverse order. Within each layer the output-by-input weight matrix comes first in row-major order, then its bias vector. Loading checks the model's identity and parameter count. The optimizer uses the actual size of the final mini-batch.

./blyxtorch gradient xor.bt fixtures/xor.csv

Train and test on different jobs

Extract the starter and open BlyxTorch.code-workspace. Each row describes pages divided by 100 and waiting jobs divided by 10. Select Terminal → Run Task → BlyxTorch: Evaluate print queue. The model trains on 16 synthetic jobs and evaluates six separate labels. The task reports six rows and mean loss near 0.00234. Edit new-jobs.csv and choose Predict new print jobs to score your inputs. A saved checkpoint and the browser program also run inference without retraining.

blyxtorch train-score print-queue/train.csv print-queue/holdout.csv 180 0.03 4 adam 7
blyxtorch train-predict print-queue/train.csv print-queue/new-jobs.csv 180 0.03 4 adam 7

Choose an appropriate workload

BlyxTorch 0.2.0 runs fixed-shape float64 networks on CPU. It supports up to eight affine layers and 1,024 parameters. The published comparison covers five small networks, CPU PyTorch, and a separate CSV-scoring benchmark. GPU execution, convolution, transformer training and arbitrary-rank tensors are outside this release.

Try the program

Output Ready
Expected output
9
-12
0
Open in the full playground →

Practice

In the worked program, change the learning rate from 0.125 to 0.25. Where does the update put the weight, and what loss do you get?

Hint

The derivative before the update is −12. Compute 1 − 0.25 × (−12), then square the new prediction error.

Worked solution

The weight becomes 4. Its prediction is 8, so the new loss is (8 − 5)² = 9. The larger step crosses the minimum.

Find

0.125 * at(loss, 1)

Replace with

0.25 * at(loss, 1)

Output after the change

9
-12
9