Capstone: one problem through five tracks
A three-class softmax classifier written from its formula: notation to NumPy, matrix products, cross-entropy, the gradient, and an honest report.
What it covers7
Why it matters
This capstone puts the course to work on one problem. You write the model from its notation, derive and check its gradient, train it, rebuild it in PyTorch and report it the way an engineer would: on products it never saw, with an interval, a fair comparison and a stability test. Each step uses a lesson of Phase 2, and the loop is the one Phase 3 and Phase 4 repeat on real data.
What you'll be able to do
- Translate a model written in notation, z = xW + b, softmax and cross-entropy, into NumPy
- Check a hand-derived gradient against a numeric one, then against PyTorch's autograd, to four places
- Train by gradient descent and read the loss curve in terms of curvature
- Report held-back accuracy with a Wilson interval, a paired comparison, a stability test and the singular values of W
Show the answer
2 × 3: one row per feature, one column per type
A row x of 2 features times W must give 3 scores, one per type: (1 × 2)(2 × 3) = 1 × 3. For 120 products at once, X is 120 × 2 and XW is 120 × 3.
The brief: tell mugs, tents and pants apart
Purpose. Build one small classifier from scratch, train it, check it against PyTorch and report it with error bars, using every track of this course once.
The practice shop sells mugs, tents and pants. For each product you know two numbers, its weight in kilograms and its price, and you want a model that reads them and says which of the three types it is. A paper would write the model for one product like this:
In plain words: is a 2 × 3 table of weights and three biases. is three scores, one per type. Softmax turns them into chances, and the loss is the average minus log of the chance given to the right type.
Show the answer
9
2 × 3 = 6 weights plus 3 biases is 9 numbers. That is the whole model.
You build it in five steps, each from a lesson of the course:
- The forward pass. One matrix product and a softmax, from the linear layer and softmax.
- The loss. Cross-entropy, from cross-entropy from logits.
- The gradient. and times it, checked against a numeric gradient, from gradients.
- Training. Gradient descent with the rate from curvature, and the same model in PyTorch.
- The report. Accuracy on products the model never saw, with an interval from samples and confidence, and a paired comparison from comparing two models.
The data below is invented: 40 products of each type, with weights and prices around a typical value. It is split 90 and 30, and the features are standardized with the 90 training rows only, so nothing about the held-back 30 leaks in.
The data: 120 products, split 90 and 30
Look at the shapes and the typical weight and price of each type. The setup code at the top builds the data once for every cell.
Setup (runs before every cell) · 41 lines
The lesson runs this once, before its first cell, and every cell, drill and example starts with what it defines. A cell that changes a setup object changes it for the cells after it, until the page reloads.
import math import numpy as np rng = np.random.default_rng(3) types = ["mug", "tent", "pants"] centers = np.array([[0.4, 25.0], [2.5, 180.0], [0.6, 60.0]]) noise = 0.15 * rng.standard_normal((120, 2)) X = np.vstack([centers[k] * (1 + noise[40 * k: 40 * k + 40]) for k in range(3)]) y = np.repeat(np.arange(3), 40) Y = np.eye(3)[y] order = np.random.default_rng(0).permutation(120) tr, te = order[:90], order[90:] mu, sd = X[tr].mean(axis=0), X[tr].std(axis=0) Xn = (X - mu) / sd def softmax(Z): Z = Z - Z.max(axis=1, keepdims=True) e = np.exp(Z) return e / e.sum(axis=1, keepdims=True) def cross_entropy(P, y): return -np.log(P[np.arange(len(y)), y]).mean() def wilson(k, n, z=1.96): center = (k + z ** 2 / 2) / (n + z ** 2) half = z / (n + z ** 2) * math.sqrt(k * (n - k) / n + z ** 2 / 4) return center - half, center + half def train(Xn, Y, steps=200, lr=0.5): W, b = np.zeros((Xn.shape[1], Y.shape[1])), np.zeros(Y.shape[1]) losses = [] for _ in range(steps): P = softmax(Xn @ W + b) losses.append(float(-np.log((P * Y).sum(axis=1)).mean())) G = (P - Y) / len(Xn) W = W - lr * (Xn.T @ G) b = b - lr * G.sum(axis=0) return W, b, losses W, b, losses = train(Xn[tr], Y[tr]) P = softmax(Xn[te] @ W + b)
print("X", X.shape, " y", y.shape, " train", len(tr), " test", len(te)) for k, name in enumerate(types): print(f"{name:6s} mean weight {X[y == k, 0].mean():.2f} kg" f" mean price {X[y == k, 1].mean():.1f}") print("standardized train means:", Xn[tr].mean(axis=0).round(6)) print("first two rows:", Xn[:2].round(2).tolist())
Mugs weigh about 0.4 kg and cost about 24.5, tents about 2.54 kg and 180.3, pants about 0.59 kg and 62.1. The training rows have mean 0 after standardizing, and the first two products are mugs, as the labels say.
The three types form three clouds. Mugs and pants overlap in weight and separate in price; tents stand apart in both:
Uses the setup above, 41 lines.
import matplotlib.pyplot as plt for k, name in enumerate(types): plt.scatter(Xn[y == k, 0], Xn[y == k, 1], label=name) plt.xlabel("weight (standardized)") plt.ylabel("price (standardized)") plt.legend(); plt.show()
import numpy as np print(np.eye(3)[[0, 2]].tolist())
Show the answer
[[1.0, 0.0, 0.0], [0.0, 0.0, 1.0]]
Indexing the identity matrix by the labels picks out row 0 and row 2: a 1 in the labeled column and 0 elsewhere. That matrix Y is what the loss compares P against.
Write a sentence or two, then compare it with a good answer in the lesson.
Build it: forward, backward, train and check
Purpose. Write each step, check it against something independent, then run the same model in PyTorch.
Step 1: the forward pass and the loss
With the 90 training products as rows of , the scores for all of them are one product: , with shapes and the bias added to every row. Softmax turns each row into three chances. With every score is 0 and every chance is 1/3, so the loss must be .
Uses the setup above, 41 lines.
W0, b0 = np.zeros((2, 3)), np.zeros(3) Z = Xn[tr] @ W0 + b0 P = softmax(Z) print("Z shape", Z.shape, " P row 0:", P[0].round(3)) print("loss", round(cross_entropy(P, y[tr]), 4), " ln 3 =", round(math.log(3), 4)) print("entropy of a prediction, bits:", round(-(P[0] * np.log2(P[0])).sum(), 3))
The loss is 1.0986, equal to , and the entropy of one prediction is 1.585 bits, : a model that knows nothing is as unsure as a fair three-way pick.
Show the answer
Every probability is 1/3, so each product contributes −ln(1/3) = ln 3 and the mean is ln 3
With zero weights every score is equal, softmax gives 1/3 everywhere, and −ln(1/3) = ln 3 for every row.
Cross-entropy from probabilities and labels
Write cross_entropy(P, y): P is an n × k array of probabilities (rows sum to 1) and y an array of n integer labels. Return the mean over rows of −log of the probability in the labeled column.
Uses the setup above, 41 lines.
import numpy as np def cross_entropy(P, y): return 0.0 P = np.array([[0.7, 0.2, 0.1], [0.1, 0.1, 0.8]]) print(round(cross_entropy(P, np.array([0, 2])), 4))
Step 2: the gradient, and a check on it
Softmax with cross-entropy has the slope , the chances minus the one-hot truth, divided by for the mean. The chain rule carries it to the parameters:
In plain words: each weight touches every product's score for type with the feature , so the contributions add up over products. That is what times the matrix does. Step through it on three products.
Now check the real gradient on the training data against a central difference of the loss, one weight at a time. A hand gradient that agrees with a numeric one to 8 places is almost certainly right:
Uses the setup above, 41 lines.
def loss_fn(W, b): return cross_entropy(softmax(Xn[tr] @ W + b), y[tr]) Wr = np.random.default_rng(1).normal(size=(2, 3)) * 0.1 G = (softmax(Xn[tr] @ Wr) - Y[tr]) / len(tr) analytic = Xn[tr].T @ G numeric = np.zeros_like(Wr) h = 1e-6 for i in range(2): for j in range(3): E = np.zeros_like(Wr) E[i, j] = h up, down = loss_fn(Wr + E, np.zeros(3)), loss_fn(Wr - E, np.zeros(3)) numeric[i, j] = (up - down) / (2 * h) print(np.abs(analytic - numeric).max() < 1e-8)
One step of gradient descent
Write gradient_step(X, Y, W, b, lr): compute P = softmax(XW + b), the gradient G = (P − Y)/n, and return the updated (W, b) after one descent step: W − lr·XᵀG and b − lr·(column sums of G). Return new arrays; do not change the inputs.
Uses the setup above, 41 lines.
import numpy as np def softmax(Z): Z = Z - Z.max(axis=1, keepdims=True) e = np.exp(Z) return e / e.sum(axis=1, keepdims=True) def gradient_step(X, Y, W, b, lr): return W, b X = np.array([[1.0, -1.0], [0.5, 2.0]]); Y = np.eye(3)[[0, 1]] W2, b2 = gradient_step(X, Y, np.zeros((2, 3)), np.zeros(3), 0.5) print(W2.round(3).tolist(), b2.round(3).tolist())
Step 3: train
Repeat: forward, gradient, step with a rate of 0.5 (the curvature of this loss is gentle, so it is safe) for 200 steps. The train helper in the setup does exactly the loop from the Gradients lesson and records the loss before each step:
Uses the setup above, 41 lines.
W, b, losses = train(Xn[tr], Y[tr]) print([round(losses[i], 4) for i in (0, 49, 99, 199)]) print("W:", W.round(2).tolist()) print("b:", b.round(2).tolist())
The loss starts at 1.0986 and falls to 0.314, 0.2195 and 0.1423. The weights say what the model learned: the first row, for weight, is large and positive for tents (2.59) and negative for mugs (−1.22); the second row, for price, separates pants (1.82) from mugs (−4.31). Plot the curve:
Uses the setup above, 41 lines.
import matplotlib.pyplot as plt W, b, losses = train(Xn[tr], Y[tr]) plt.plot(losses) plt.xlabel("step"); plt.ylabel("training loss"); plt.show()
Show the answer
Forward pass, loss, gradient, update
The loop predicts, scores the prediction, finds the slopes and then moves the weights.
Show the answer
The gentle direction of the loss has low curvature, so the capped step crawls along it
As in the ravine of the curvature lesson, the steep directions settle first and the flat ones take many steps.
Step 4: the same model in PyTorch
nn.Linear(2, 3) holds a weight of shape (3, 2), the transpose of our W. F.cross_entropy takes the logits and class indices. optim.SGD with the same rate 0.5 performs the same update. If the two agree, the hand-built gradient is the one autograd finds:
Uses the setup above, 41 lines.
import torch import torch.nn as nn import torch.nn.functional as F lin = nn.Linear(2, 3) with torch.no_grad(): lin.weight.zero_() lin.bias.zero_() Xt = torch.tensor(Xn[tr].tolist()) yt = torch.tensor(y[tr].tolist()) opt = torch.optim.SGD(lin.parameters(), lr=0.5) tl = [] for step in range(200): opt.zero_grad() loss = F.cross_entropy(lin(Xt), yt) loss.backward() opt.step() tl.append(loss.item()) print([round(tl[i], 4) for i in (0, 49, 99, 199)]) print(max(abs(a - c) for a, c in zip(losses, tl)) < 1e-4)
The PyTorch losses are 1.0986, 0.314, 0.2195 and 0.1423, the same as NumPy's, and the largest gap over all 200 steps is under 0.0001. Same model, same gradient, two implementations. (The browser runs a teaching subset of PyTorch; the same lines run on a real install.)
import torch.nn as nn lin = nn.Linear(2, 3) print(tuple(lin.weight.shape), tuple(lin.bias.shape))
Show the answer
(3, 2) (3,)
nn.Linear(2, 3) stores its weight as (out, in) = (3, 2) and its bias as (out,) = (3,). Our W is the transpose, (2, 3).
Write a sentence or two, then compare it with a good answer in the lesson.
Ship it: report like an engineer
Purpose. Report the model on products it never saw, with an interval, a comparison, a stability test and a look at what it learned.
A report that says "accuracy 1.0 on the training data" says how well the model learned those products, not how it does on new ones. The 30 held-back products play no part in fitting or standardizing. The map shows where each piece of the report sits in a training run.
Held-back accuracy, with an interval
Score the 30 held-back products. Two intervals for a proportion: the normal one, accuracy ± 1.96 standard errors, and the Wilson interval from the sampling lesson. They disagree at the edges, and the edge is where a good model lives:
Uses the setup above, 41 lines.
W, b, losses = train(Xn[tr], Y[tr]) P = softmax(Xn[te] @ W + b) k, n = int((P.argmax(axis=1) == y[te]).sum()), len(te) acc = k / n half = 1.96 * math.sqrt(acc * (1 - acc) / n) low, high = wilson(k, n) print(f"held back: {k} of {n} right = {acc:.3f}") print(f" normal: {acc - half:.3f} to {acc + half:.3f}") print(f" Wilson: {low:.3f} to {high:.3f}")
All 30 are right, so the normal interval has width 0: it claims certainty, which 30 products cannot support. The Wilson interval runs from 0.886 to 1.0: with 30 of 30 right, the true accuracy could plausibly be as low as 0.886.
Show the answer
On new products from this shop, a true accuracy anywhere from about 0.89 to 1.00 fits these 30
The interval says how much 30 products can pin down the true accuracy. A perfect score on 30 is good evidence that the model is good, not proof that it never errs, and the training score can't stand in for it, because the model has already seen those products.
A paired comparison
Is using both features better than using weight alone? Train a second model on weight only and score both on the same 30 products. A paired comparison counts only the products where the two models disagree:
Uses the setup above, 41 lines.
Wb, bb, _ = train(Xn[tr][:, :1], Y[tr]) Pb = softmax(Xn[te][:, :1] @ Wb + bb) a_ok = P.argmax(axis=1) == y[te] b_ok = Pb.argmax(axis=1) == y[te] only_a, only_b = int((a_ok & ~b_ok).sum()), int((~a_ok & b_ok).sum()) m = only_a + only_b tail = sum(math.comb(m, i) for i in range(max(only_a, only_b), m + 1)) / 2 ** m print(int(a_ok.sum()), int(b_ok.sum()), only_a, only_b, round(min(1, 2 * tail), 3))
The two-feature model gets 30 right and the weight-only model 28. They disagree on 2 products, and both go the same way. The exact two-sided test gives a p-value of 0.5. With only 2 disagreements, 30 products cannot separate the models, even though the gap looks clear.
Stability and what it learned
Scale the scores by 1,000, as an unscaled network can, and a naive softmax overflows. The stable one does not. The singular values of W say how many directions the model uses:
Uses the setup above, 41 lines.
Zbig = (Xn[te] @ W + b) * 1000 print("stable:", np.isnan(softmax(Zbig)).any()) with np.errstate(all="ignore"): e = np.exp(Zbig) print("naive:", np.isnan(e / e.sum(axis=1, keepdims=True)).any()) print(np.linalg.svd(W, compute_uv=False).round(3))
The stable softmax has no nan, and the naive one does. The two singular values, 5.648 and 2.5, show both input directions carry real weight: the model uses weight and price, not one of them.
Last, draw what it learned. The picture colors each point of the plane by the type the model predicts, with the training products on top:
Uses the setup above, 41 lines.
import matplotlib.pyplot as plt gx, gy = np.meshgrid(np.linspace(-2, 3, 120), np.linspace(-2, 2, 120)) grid = np.column_stack([gx.ravel(), gy.ravel()]) region = softmax(grid @ W + b).argmax(axis=1).reshape(gx.shape) plt.contourf(gx, gy, region, alpha=0.3) plt.scatter(Xn[tr, 0], Xn[tr, 1], c=y[tr], s=12) plt.xlabel("weight (standardized)"); plt.ylabel("price (standardized)"); plt.show()
Show the answer
No: the Wilson interval says the true accuracy could be as low as about 0.886
A perfect score on a small test set is an estimate with a wide lower end. The interval is the honest way to say it.
A report on a model you built
A shop owner has a model that sorts products into types from their weight and price, and wants to know whether to trust it. They will read one page.
Your task is to build the model, evaluate it on held-back products and report what you found, with its uncertainty, in words a shopkeeper can follow. The hard part is saying what the numbers can and cannot support.
It must
- Generate or load a data set of at least 90 products with two features and three types, and hold back at least 30
- Standardize with the training rows only
- Train a softmax classifier from scratch and show its loss curve
- Check your gradient against a numeric gradient
- Report held-back accuracy with a Wilson interval
- Compare against a simpler model on the same held-back products with a paired count of disagreements
- Say in two or three sentences what the data can and cannot support
Go further
- Add a third feature and see whether the held-back accuracy changes
- Report accuracy for each type
Uses the setup above, 41 lines.
import numpy as np rng = np.random.default_rng(0) # your code: build the data, split it, train, then report
Goes deeper in
- Probability for models: sequence likelihood and what the loss measures.
- Hypothesis testing: when a gap between two numbers is real.
- Machine learning: the same loop on real data sets.
- Deep learning: layers between X and Z.
Write a sentence or two, then compare it with a good answer in the lesson.
Practice what you just read
- 11 code examples you can edit and run
- a practice exercise that checks your code
- a 5-question quiz
- 9 review cards for spaced repetition
Try a quiz question
In Z = XW + b for 120 products with 2 features and 3 types, the shapes are:
Before this lesson
Where this lesson leads.
575 lessons in thirteen phases. 176 are free without an account, and a free account opens the rest. See every lesson.
Phase 2 · about 23 hours of study
Math for ML engineers
The Foundation's formulas at working depth: batches, shapes, autograd, stable arithmetic and error bars
30 lessons 1 free
- Reading a paper's equations, with shapes FreeΣ, subscripts, hats and bars, translated into Python you can run and test.35 min
- Floating point and log spaceGrowth, decay, and why logs turn products into sums.35 min
- Shapes at transformer scaleArrays with more axes: batches, sequences, heads.36 min
- The linear layer as algebraMany dot products at once: what a neural network layer computes.40 min
- Solving and least squaresThe matrix operations you'll see in every formula.36 min
- Projections, orthogonality and rank-1 updatesA matrix stretches, rotates and projects space.34 min
- Eigenvalues of symmetric matricesThe directions a transformation leaves pointing the same way.36 min
- SVD at workCompress data to its most important directions.40 min
- Strange geometry in high dimensionsNear-perpendicular random directions, bunched-up distances, and the curse of dimensionality.38 min
- Derivatives of the functions models usePower, sum and product rules, so you rarely compute from scratch.35 min
- The chain rule with vectorsDerivatives of functions inside functions: the heart of backprop.40 min
- Backprop through a linear layer: gradients with shapesThe slope of the loss through Y = XW + b: dX, dW and db derived from one entry, found again from shapes, and checked against autograd.40 min
- Gradients in matrix form, and how to check themThe vector of all partial derivatives: which way is uphill.35 min
- Why training is fast or slowSecond derivatives, minimum or maximum, why curvature caps the learning rate, convex losses and Newton's method.40 min
- The chain rule of probabilityUpdate beliefs when new evidence arrives.40 min
- Distributions as objectsRandom variables and the shapes their outcomes take.35 min
- Expectation and variance of estimatorsExpected value, variance and standard deviation.35 min
- Gaussians at workThe bell curve, and why it shows up everywhere.35 min
- Covariance matrices and the multivariate normalCovariance and correlation, curves, outliers and common causes, rank correlation, skew and kurtosis.40 min
- Losses are negative log-likelihoodsChoose the parameters that make the data most probable.35 min
- Samples and confidence: error bars for an evalEstimate from a sample and say how sure you are.40 min
- Priors, MAP and regularizationPriors as pseudo-counts, Beta posteriors, shrinkage for small samples, and which of two rates is really higher.40 min
- Markov chainsStates, a table of what comes next, the chance of a path, and where a chain settles.38 min
- Softmax at working depthTurn any list of scores into probabilities.35 min
- Cross-entropy from logitsThe loss function language models are trained on.40 min
- KL divergence at workForward against reverse KL, KL between normals, F.kl_div's argument order, a distillation loss with temperature, and a KL penalty against a base model.36 min
- A/B tests and significance, for prompts and modelsTell a real lift from noise.40 min
- Comparing two models on the same testPaired results, disagreements, a quick z and a bootstrap for the gap between two models.35 min
- Ranking from head-to-head resultsElo updates, Bradley-Terry strengths, and how model leaderboards turn votes into ratings.37 min
- Capstone: one problem through five tracksA three-class softmax classifier written from its formula: notation to NumPy, matrix products, cross-entropy, the gradient, and an honest report.45 min
Never trained an AI? Teach a small one to write, right in your browser. It takes about 20 seconds and needs no account. Teach it to write