README.md

Experiments

Each experiment turns one learning question into runnable code and observable evidence. Reusable implementation belongs in src/; experiment-only data construction, training loops, reporting, and notes stay here.

A useful experiment should make six things clear:

1. the question it asks;
2. the command that runs it;
3. the reusable code it exercises;
4. the metric, prediction, or trace that answers the question;
5. the boundary between what is implemented and what is intentionally omitted;
6. the research or technical reference behind the idea.

Running Experiments

Use nnctl to apply the catalogued optimization and backend defaults:

nnctl list experiments
nnctl run simple-xor
nnctl run quick
nnctl experiments

nnctl run quick runs the short experiments that need no downloaded dataset or saved model. nnctl experiments builds every experiment without running it. The compatibility commands nnctl examples and zig build examples remain available, but new documentation and scripts should use “experiments.”

Every individual command maps to a stable Zig step. For example, nnctl run optimizer-lab maps to zig build run_optimizer_lab -Dgpu=auto. See Getting Started for direct Zig commands and GPU and Backend Notes for backend requirements.

XOR Training, Regression, Binary Classification, Spectral Learning, Optimizer Lab, GPU Benchmark, and Semantic Search also expose structured live evidence in the local browser lab:

mise run lab

Their normal terminal output remains the default. The lab invokes them with --format ndjson; see the learning lab guide for the event contract and extension steps.

Suggested Learning Routes

• Foundations: Simple XOR → XOR Training → Binary Classification → Regression → Gated Network. Read each program beside matrix.zig, layer.zig, and network.zig.
• Spectral methods: Regression → Spectral Learning, then extend the route with periodic activations and two-dimensional coordinate fields. Compare pointwise error with the frequency components recovered by each model.
• Training and runtime: Backend Demo → Backend Training → Optimizer Lab → Padding Masks → GPU Demo. This route exposes storage, transfer, optimizer, and device-residency decisions.
• Vision and audio: CNN → MNIST → Autoencoder → Speech Commands. Compare a readable spatial reference, a real image dataset, representation learning, and an external audio pipeline.
• Language and sequences: Tokenizer Lab → Word2Vec → Text Classifier → Sequence Tagging → Decoding Lab → Seq2Seq → Machine Translation → Semantic Search → ANN Search → CTC Alignment, then compare GRU Sequence, Time Series, Node Classification, and Transformer Encoder before exploring TinyGPT.
• Applied systems: DQN, TurboQuant, GPU Benchmark, Serving, and the TinyGPT OpenAI-compatible server show where learning code meets evaluation, compression, performance, and interfaces.

Foundations

Experiment and run command	Question and evidence	Code to read	Background
Simple XOR — nnctl run simple-xor	What does an untrained forward pass do? Inspect the XOR truth-table predictions.	entrypoint, matrix, layer, network	Neural-network foundations
XOR Training — nnctl run xor-training	Can backpropagation fit XOR? Compare loss and predictions before and after training.	entrypoint, network	Neural-network foundations
Binary Classification — nnctl run binary-classification	Can a small network learn a circular decision boundary? Inspect training loss and classification results.	entrypoint, network	Neural-network foundations
Regression — nnctl run regression	Can the same primitives approximate a nonlinear function? Compare targets with predictions.	entrypoint, network	Neural-network foundations
Gated Network — nnctl run gated-network	How do GLU and SwiGLU paths change a layer’s forward computation? Inspect the gated outputs.	entrypoint, layer, activation	Activations and gating
Network Visualisation — nnctl run network-visualisation	How do several network shapes look before training? Inspect the terminal topology diagrams.	entrypoint, visualiser	Architecture

Spectral Methods

Experiment and run command	Question and evidence	Code to read	Background
Spectral Learning — nnctl run spectral-learning	Why does a coordinate MLP learn broad structure before fine oscillation, and how do Fourier features change that order? Compare raw and encoded prediction curves, amplitude spectra, pointwise loss, and target-harmonic error.	entrypoint, spectral tools, network	Spectral learning

This first experiment establishes reusable Fourier transform, real-signal amplitude, and coordinate-feature primitives. Natural follow-ons are a SIREN experiment that adds periodic activations and initialization, followed by a 2D implicit-image experiment that visualizes spatial frequency recovery.

Training and Runtime

Experiment and run command	Question and evidence	Code to read	Background
Backend Demo — nnctl run backend-demo	Do public matrix operations behave consistently through the backend abstraction? Inspect operation results and selected backend.	entrypoint, backend	GPU and backend work
Backend Training — nnctl run backend-training	Can parameters remain on a backend through a small supervised loop? Inspect loss reduction and explicit synchronization.	entrypoint, backend	GPU and backend work
Optimizer Lab — nnctl run optimizer-lab	How do SGD, momentum, and AdamW behave from identical initialization? Compare loss reduction and held-out accuracy.	entrypoint, modules, training	Optimization
Padding Masks — nnctl run padding-masks	How can variable-length sequences share a batch without learning from filler values? Inspect masked probabilities, loss, and gradients.	entrypoint, tensor, transformer	Transformers
GPU Demo — nnctl run gpu	Which backend is selected, and do basic operations agree with CPU behavior? Inspect backend identity and matrix results.	entrypoint, backend API, GPU notes	GPU and backend work

Vision and Audio

Experiment and run command	Question and evidence	Code to read	Background
CNN — nnctl run cnn	Does convolution learn orientation more directly than flattened features? Inspect held-out pattern accuracy and gradients.	entrypoint, spatial layers	Representations, vision, and audio
MNIST — nnctl run mnist	Can the CPU fundamentals classify handwritten digits? Inspect loss and test accuracy on downloaded MNIST data.	entrypoint, network	Representations, vision, and audio
Autoencoder — nnctl run autoencoder	Can a two-value bottleneck preserve small image families while removing noise? Inspect reconstruction error, pixel accuracy, and latent centers.	entrypoint, modules, training	Representations, vision, and audio
Speech Commands — nnctl run speech-commands	Can log-mel features and a small MLP recognize eight spoken words across speakers? Inspect validation accuracy, confusion counts, and checkpoint compatibility.	entrypoint, notes, audio, training	Representations, vision, and audio

Language, Retrieval, and Sequence Models

Experiment and run command	Question and evidence	Code to read	Background
Tokenizer Lab — nnctl run tokenizer-lab	What does learned BPE trade for a larger vocabulary? Compare merge growth, compression, and exact byte round trips.	entrypoint, text	NLP and retrieval
Word2Vec — nnctl run word2vec	Can a prediction objective turn co-occurrence into geometric neighborhoods? Inspect loss and nearest words.	entrypoint, embeddings	NLP and retrieval
Text Classifier — nnctl run text-classifier	Can masked multi-head attention distinguish contextual sentiment? Inspect held-out accuracy and phrase predictions.	entrypoint, embeddings, transformer	Transformers
Sequence Tagging — nnctl run sequence-tagging	How do independent token scores become a globally valid BIO sequence? Inspect likelihood, marginals, and Viterbi output.	entrypoint, structured prediction	NLP and retrieval
Decoding Lab — nnctl run decoding-lab	How do greedy, top-k, nucleus, temperature, and repetition penalties reshape token choice? Compare seeded outputs.	entrypoint, decoding	NLP and retrieval
Seq2Seq — nnctl run seq2seq	Can decoder queries learn translation and reordering efficiently? Inspect token/exact accuracy, alignment, bucketed padding efficiency, and accumulated microbatches.	entrypoint, transformer, sequence batching	NLP and retrieval
Machine Translation — nnctl run machine-translation	How do teacher forcing and sequence search fit together? Compare greedy and length-normalized beam output, then inspect the masked source alignment.	entrypoint, translation stack, beam search	NLP and retrieval
Semantic Search — nnctl run semantic-search	Can paired encoders learn a shared retrieval space with in-batch negatives? Inspect recall@1, MRR, and cosine rankings.	entrypoint, retrieval, embeddings	NLP and retrieval
ANN Search — nnctl run ann-search	How much exact-retrieval work can an approximate index avoid? Compare IVF probes by recall@5, candidate count, and measured query latency.	entrypoint, retrieval index	NLP and retrieval
CTC Alignment — nnctl run ctc-alignment	How can unsegmented frame scores learn a character target? Inspect blank-aware forward-backward loss, greedy collapse, and prefix-beam decoding.	entrypoint, CTC	NLP and retrieval
GRU Sequence — nnctl run gru-sequence	Can a recurrent state retain one marked bit through distractors? Inspect held-out accuracy and device telemetry.	entrypoint, recurrent	Sequence models and reinforcement learning
Time Series — nnctl run time-series	Can a causal Conv1d beat a persistence forecast? Compare masked rolling-window MSE, inspect the learned kernel, and verify the causal boundary.	entrypoint, causal convolution, masked loss	Sequence models and reinforcement learning
Node Classification — nnctl run node-classification	When does graph structure add signal beyond node features? Compare a feature-only classifier with mean-aggregation graph convolution on the same split.	entrypoint, sparse graphs	Sequence models and reinforcement learning
Transformer Encoder — nnctl run transformer-encoder	Can bidirectional attention retrieve a value from a distant token? Inspect held-out accuracy and training readbacks.	entrypoint, transformer	Transformers
TinyGPT — nnctl run tiny-gpt	How do a decoder-only Transformer, KV cache, training loop, and sampler fit together? Inspect loss and seeded generated text.	entrypoint, notes, model, transformer	Transformers and TinyGPT

Applied Systems

Experiment and run command	Question and evidence	Code to read	Background
DQN — nnctl run dqn	Can replay, exploration, Bellman targets, and a target network solve LineWorld? Inspect greedy success, path length, and learned Q-values.	entrypoint, reinforcement, modules	Sequence models and reinforcement learning
TurboQuant — nnctl run turboquant	How does rotation change scalar-quantization error? Compare reconstruction, inner-product, and compression metrics.	entrypoint, notes, quantization	Quantization
GPU Benchmark — nnctl run gpu-benchmark	When does backend matrix multiplication beat CPU execution, and at what numerical error? Compare timings and sampled error.	entrypoint, backend, benchmark guide	GPU and backend work
Serving — nnctl run serving	What is the smallest useful prediction service around a saved model? Inspect HTTP validation and prediction responses.	entrypoint, notes, inference service	Serving and tooling
TinyGPT OpenAI Server — nnctl run tiny-gpt-openai	How can the local TinyGPT model expose OpenAI-compatible model and chat endpoints? Inspect /v1/models and /v1/chat/completions responses.	entrypoint, notes, model	Serving and tooling

Data and Checkpoints

Most experiments are self-contained. These workflows need local files:

MNIST

nnctl data mnist
nnctl run mnist

Speech Commands

nnctl data speech-commands
nnctl train speech-commands --output speech-commands.bin
nnctl run speech-commands -- --model speech-commands.bin --input clip.wav

The data command downloads the external Mini Speech Commands dataset. Training uses a deterministic speaker-disjoint split; see the experiment notes for labels and input details.

Serving

nnctl run xor-training -- --output=xor_model.bin
nnctl run serving

The server loads xor_model.bin by default. Its local README contains request examples and the response schema.

TinyGPT

The checked-in toy corpus works offline. Optional sourced corpora and a trained checkpoint use:

nnctl data tiny-gpt
nnctl train tiny-gpt --preset coherent-small --output tiny-gpt.bin
nnctl chat --model tiny-gpt.bin

See the TinyGPT notes for presets, corpus selection, checkpoint behavior, and serving commands.

Adding an Experiment

• Start with one precise question and a deterministic small dataset when possible.
• Put reusable operations, modules, and algorithms in src/; keep scenario construction and reporting in the experiment directory.
• Add the executable and acceptance test to build.zig and the command/defaults to the nnctl experiment catalog.
• Print evidence that answers the question: a metric, comparison, prediction, trace, or visualization.
• State important host/device boundaries and anything deliberately left out.
• Link the entrypoint, reusable implementation, and primary reference from this README; add a local README only when setup or interpretation needs more room.