Handwritten Digit Softmax Classifier in C: From 784 Pixels to submission.csv
AI Learning Project
Handwritten Digit Softmax Classifier in C: From 784 Pixels to submission.csv
A practical walkthrough of the C softmax classifier for handwritten digits, including logits, softmax probabilities, gradient updates, and CSV submission export.
AI Learning Project

Handwritten Digit Softmax Classifier in C: From 784 Pixels to submission.csv

Reading info

Level: Practice Reading time: 11 min
  • C
  • Softmax
  • Classification
Open knowledge map

Once the dataset layout is clear, the most useful part of this handwritten digit project is the C implementation itself. It does not rely on a deep learning framework. Instead, it uses a direct multi-class softmax model that maps a 784-dimensional input vector to ten digit classes.

This is a good kind of project for learning how model formulas become code. You can inspect the weight matrix, the softmax probability calculation, the cross-entropy loss accumulation, and the gradient-based parameter updates without a large abstraction layer getting in the way.

1. The model structure is deliberately small

The main parameters are only:

  • W[10][784]: one weight vector of length 784 for each class
  • b[10]: one bias term for each class

For a single input sample x, the classifier first computes one raw score per class:

z[k] = b[k];
for (int j = 0; j < FEATURES; j++) {
    z[k] += W[k][j] * x[j];
}

Those ten values are the logits for the current sample.

2. Softmax turns raw scores into probabilities

Raw linear scores are not directly interpretable as probabilities, so the implementation normalizes them with softmax:

p[i] = exp(z[i] - max_z);
sum += p[i];
...
p[i] /= sum;

The subtraction by max_z is a stability trick. It keeps the exponentials from blowing up numerically. After softmax, the probabilities over the ten classes add up to one, and the predicted label is just the class with the largest probability.

3. What the training loop is actually doing

The current project runs 20 epochs with a learning rate of 0.01. In each epoch, it loops through every training sample and repeats the same sequence:

  1. Compute ten logits
  2. Apply softmax to get a probability distribution
  3. Compare that distribution to the true label
  4. Update the weights and biases with the resulting error

The update rule is written in a very transparent way:

double error = p[k] - (k == y_train[i] ? 1.0 : 0.0);
for (int j = 0; j < FEATURES; j++) {
    W[k][j] -= LEARNING_RATE * error * X_train[i][j];
}
b[k] -= LEARNING_RATE * error;

If you already know logistic regression or linear multi-class classification, this will look familiar. It is essentially softmax regression trained with stochastic gradient descent.

4. Which metrics are worth checking

During training, the program prints epoch loss and training accuracy. After training, it prints the final training accuracy and a confusion matrix. Those are the most useful outputs to read first:

  • Loss: whether optimization is moving in the right direction
  • Accuracy: whether the classification result is improving
  • Confusion matrix: which digits are most often mixed up

If a few classes remain confused with each other, that is usually a sign that the digit shapes are visually close or that the linear model has reached its representational limit.

5. How submission.csv is generated

After training, the program reads test.csv, calls predict_one for each sample, and writes the result back into the required CSV structure:

ImageId,Label
1,7
2,2
3,1
...

That is the final submission.csv. From an engineering perspective, this step matters because it turns the training code into a complete pipeline that can process unseen inputs and export predictions in a reusable format.

6. How to run it locally

The downloads section now includes the source file plus compressed copies of the training and test data. The current implementation expects train.csv and test.csv in the same working directory:

unzip train.csv.zip
unzip test.csv.zip
gcc digit_softmax_classifier.c -lm -O2 -o digit_classifier
./digit_classifier

A normal run should print:

  • the number of training and test samples
  • loss and accuracy for each epoch
  • final training accuracy and the confusion matrix
  • a message confirming that submission.csv was written

7. What this C version does not try to do

The current implementation is already enough for a complete multi-class practice project, but its boundaries are also clear:

  • the model is still linear, not convolutional
  • a strong training accuracy does not automatically mean the best generalization
  • there is no dedicated validation split for tuning
  • there is no mini-batch schedule, regularization, or more advanced optimization

Those are not flaws so much as the next layer of work. A clean, understandable, end-to-end baseline is already valuable.

8. Where to go next

If you want an interactive version before reading more source code, open the handwritten digit tab in the playground. The browser version does not retrain on the full dataset. Instead, it loads a compact pre-trained softmax demo so you can draw digits, inspect probability scores, and try labeled samples directly in the page.

The source code, zipped datasets, sample submission file, generated submission, and browser model bundle are all available on the downloads page. If you have not read the previous post yet, start with the dataset structure article so the arrays and loops in this C file are easier to place in context.

Internal links

Related tutorials

Review foundation Handwritten Digit Dataset Basics

Read train.csv, test.csv, labels, and the flattened 28 by 28 pixel layout before training the classifier.

 Continue next Handwritten Digit Playground Notes

See how the offline classifier was adapted into a browser demo with drawing input and probability output.

 Learning path AI Learning Path

Read AI foundations, machine learning, CNN work, traffic defense, and AI security in order.

 Resources Resource Library

Download companion code, datasets, diagrams, model files, and notes.

 Topic hub Student AI Projects

Connect handwritten digits, browser demos, and CNN projects into a portfolio path.

Search questions

FAQ

Who is this article for?

This article is for readers who want a practice-level guide to Handwritten Digit Softmax in C. It takes about 11 min and focuses on C, Softmax, Classification.

What should I read next?

The recommended next step is Handwritten Digit Playground Notes, so the article connects into a longer learning route instead of ending as an isolated note.

Does this article include runnable code or companion resources?

Yes. Use the run notes, resource cards, and download links on the page to reproduce the example or inspect the companion files.

How does this article fit into the larger site?

It is connected to the article context block, learning routes, resources, and project timeline so readers can move from concept to implementation.

Article context

AI Learning Project

A practical route from AI concepts to machine learning workflow, evaluation, neural networks, Python practice, handwritten digits, a CIFAR-10 CNN, adversarial traffic-defense notes, and AI security.

Level: Practice Reading time: 11 min
  • C
  • Softmax
  • Classification

Your next step

Continue: Handwritten Digit Playground Notes
Review the foundation Open resource
Other language version 用 C 实现手写数字 Softmax 分类器：从 784 维像素到 submission.csv
Share summary Handwritten Digit Softmax in C

Follow the C implementation from logits and softmax probabilities to confusion matrices and submission export.

Download share card Open share center

Companion resources

Leave a Reply

Project timeline

Published posts

  1. AI Basics Learning Roadmap Separate AI, machine learning, and deep learning before going into implementation details.
  2. Machine Learning Workflow Follow the practical path from data and features to training, prediction, and evaluation.
  3. Model Training and Evaluation Understand loss, overfitting, train/test splits, accuracy, recall, and F1.
  4. Neural Network Basics Move from perceptrons to activation, forward propagation, backpropagation, and training loops.
  5. NLP Basics: Understanding Bag of Words and TF-IDF An introduction to the most fundamental text representation methods in NLP: Bag of Words (BoW) and TF-IDF.
  6. RNN Basics: Handling Sequential Data with Memory Understand the core concepts of Recurrent Neural Networks (RNN), the role of hidden states, and their application in NLP.
  7. Transformer Self-Attention Read Q/K/V, scaled dot-product attention, multi-head attention, and positional encoding before exploring LLM internals.
  8. Python AI Mini Practice Run a small scikit-learn classification task and read the experiment output.
  9. Handwritten Digit Dataset Basics Read train.csv, test.csv, labels, and the flattened 28 by 28 pixel layout before training the classifier.
  10. Handwritten Digit Softmax in C Follow the C implementation from logits and softmax probabilities to confusion matrices and submission export.
  11. Handwritten Digit Playground Notes See how the offline classifier was adapted into a browser demo with drawing input and probability output.
  12. CIFAR-10 Tiny CNN Tutorial in C Build and train a small convolutional neural network for CIFAR-10 image classification, then read its loss and accuracy output.
  13. Building a Tiny CIFAR-10 CNN in C: Convolution, Pooling, and Backpropagation A source-based walkthrough of cifar10_tiny_cnn.c, covering CIFAR-10 binary input, 3x3 convolution, ReLU, max pooling, fully connected logits, softmax, backpropagation, and local commands.
  14. High-Entropy Traffic Defense Notes Study encrypted metadata leaks, entropy, traffic classifiers, and a defensive Python chaffing prototype.
  15. AI Security Threat Modeling Build a defense map with NIST adversarial ML, MITRE ATLAS, and OWASP LLM risks.
  16. Adversarial Examples and Robust Evaluation Evaluate clean and perturbed accuracy with an FGSM-style digits experiment.
  17. Data Poisoning and Backdoor Defense Study poison rate, trigger behavior, attack success rate, and training pipeline controls.
  18. Model Privacy and Extraction Defense Measure membership inference signal and surrogate fidelity against a local toy model.
  19. LLM, RAG, and Agent Security Separate instructions from data and enforce tool permissions against indirect prompt injection.

Published resources

  1. Python AI practice code guide The article includes a runnable scikit-learn classification script.
  2. digit_softmax_classifier.c The C source for the handwritten digit softmax classifier.
  3. train.csv.zip Compressed handwritten digit training set with 42000 labeled samples.
  4. test.csv.zip Compressed handwritten digit test set with 28000 unlabeled samples.
  5. sample_submission.csv The official submission format example for checking the final output columns.
  6. submission.csv The prediction file generated by the current C project.
  7. digit-playground-model.json The compact softmax demo model and sample set used by the browser playground.
  8. digit-sample-grid.svg A small handwritten digit preview grid extracted from the training set.
  9. Handwritten digit project bundle Contains the source file, compressed datasets, submission files, browser model, and preview grid.
  10. cifar10_tiny_cnn.c source Single-file C tiny CNN with CIFAR-10 loading, convolution, pooling, softmax, and backpropagation.
  11. model_weights.bin sample weights Model weights generated by one local small-sample run.
  12. test_predictions.csv sample predictions Sample test prediction output from the CIFAR-10 tiny CNN.
  13. CNN project explanation PDF Companion explanation material for the CNN project.
  14. Virtual Mirror redacted code skeleton A redacted mld_chaffing_v2.py control-flow skeleton with secrets, node topology, and target lists removed.
  15. Virtual Mirror stress-test template A redacted CSV template for CPU, memory, peak threads, pulse rate, latency, and error measurements.
  16. Virtual Mirror classifier-evaluation template A CSV template for TP, FN, FP, TN, accuracy, precision, recall, F1, ROC-AUC, entropy, and JS divergence.
  17. Virtual Mirror resource notes Notes explaining why the public resources include only redacted code, test templates, and architecture context.
  18. AI Security Lab README Setup, safety boundaries, and quick-run commands for the AI Security series.
  19. AI Security Lab full bundle Includes safe toy scripts, result CSVs, risk register, attack-defense matrix, and architecture diagram.
  20. AI security risk register CSV risk register template for AI threat modeling and release review.
  21. AI attack-defense matrix Maps attack surface, toy demo, metric, and defensive control into one CSV table.
  22. AI Security Lab architecture diagram Shows threat modeling, robustness, data integrity, model privacy, and RAG guardrails.
  23. FGSM digits robustness script FGSM-style perturbation and accuracy-drop experiment for a local digits classifier.
  24. Data poisoning and backdoor toy script Demonstrates poison rate, trigger behavior, and attack success rate on digits.
  25. Model privacy and extraction toy script Outputs membership AUC, target accuracy, surrogate fidelity, and surrogate accuracy.
  26. RAG prompt injection guard toy script Uses a deterministic toy agent to demonstrate external-data demotion and tool-policy blocking.
  27. Deep Learning topic share card A 1200x630 SVG card for sharing the Deep Learning / CNN topic hub.
  28. Machine Learning From Scratch share card A 1200x630 SVG card for the K-means, Iris, and ML workflow topic hub.
  29. Student AI Projects share card A 1200x630 SVG card for handwritten digits, C classifiers, and browser demos.
  30. CNN convolution scan animation An 8-second Remotion animation showing how a 3x3 convolution kernel scans an input and builds a feature map.

Current route

  1. AI Basics Learning Roadmap Learning path step
  2. Machine Learning Workflow Learning path step
  3. Model Training and Evaluation Learning path step
  4. Neural Network Basics Learning path step
  5. Transformer Self-Attention Learning path step
  6. LLM Visualizer Learning path step
  7. Python AI Mini Practice Learning path step
  8. Handwritten Digit Dataset Basics Learning path step
  9. Handwritten Digit Softmax in C Learning path step
  10. Handwritten Digit Playground Notes Learning path step
  11. CIFAR-10 Tiny CNN Tutorial in C Learning path step
  12. High-Entropy Traffic Defense Notes Learning path step
  13. AI Security Threat Modeling Learning path step
  14. Adversarial Examples and Robust Evaluation Learning path step
  15. Data Poisoning and Backdoor Defense Learning path step
  16. Model Privacy and Extraction Defense Learning path step
  17. LLM, RAG, and Agent Security Learning path step

Next notes

  1. Add more image-classification and error-analysis cases
  2. Turn common metrics into a quick reference
  3. Add more AI security defense experiment notes