Shape Recognizer

Repository

I built this shape-recognizing neural network from scratch in Rust to gain a deep, foundational understanding of machine learning algorithms without relying on external deep learning frameworks. The project features a custom forward and backpropagation pipeline, parallelized batch training using Rayon to maximize multi-core execution, and Gzip-compressed binary serialization for ultra-fast model loading and compact storage.

Parallel Batch Training with Rayon

To achieve high throughput when training across millions of samples, I implemented a parallel mini-batch architecture powered by Rayon. The train_batch method delegates sample gradient calculations across available CPU threads using par_iter(). The partial gradients are synthesized concurrently with a custom map-reduce pattern using zero_gradients and accumulate_gradients, eliminating data races before applying the batch adjustments to the primary weights.

1pub fn train_batch(&mut self, batch: &[(&[f32], usize)], learning_rate: f32) {
2    if batch.is_empty() {
3        return;
4    }
5
6    let batch_size = batch.len() as f32;
7    let accum = batch
8        .par_iter()
9        .map(|&(input, target_class)| self.compute_sample_gradients(input, target_class))
10        .reduce(|| self.zero_gradients(), Self::accumulate_gradients);
11
12    self.apply_batch_gradients(accum, batch_size, learning_rate);
13}

Manual Backpropagation & Gradient Descent

Rather than relying on automatic differentiation libraries, I manually implemented backpropagation to directly update layer weights and biases. The train function executes a full forward pass, calculates output deltas against target classes, and propagates error signals backward through the hidden layer. It computes the activation derivative using ReLU and scales updates by the defined learning rate, maintaining complete mathematical transparency throughout the network.

1pub fn train(&mut self, input: &[f32], target_class: usize, learning_rate: f32) {
2    let (output, hidden_raw, hidden_activated) = self.forward_pass_internal(input);
3    let d_output = self.compute_output_gradient(&output, target_class);
4
5    let mut d_hidden = vec![0.0; self.hidden_size];
6    for o in 0..self.output_size {
7        for h in 0..self.hidden_size {
8            d_hidden[h] += d_output[o] * self.weight2[o][h];
9            self.weight2[o][h] -= learning_rate * d_output[o] * hidden_activated[h];
10        }
11        self.bias2[o] -= learning_rate * d_output[o];
12    }
13
14    for h in 0..self.hidden_size {
15        let d_h_activated = d_hidden[h] * Self::relu_derivative(hidden_raw[h]);
16        for i in 0..self.input_size {
17            self.weight1[h][i] -= learning_rate * d_h_activated * input[i];
18        }
19        self.bias1[h] -= learning_rate * d_h_activated;
20    }
21}

Compressed Binary Model Persistence

To maintain a minimal disk footprint and eliminate slow textual parsing (such as JSON or CSV), I built a custom binary serialization format using flate2. Floating-point weight matrices are converted to little-endian byte arrays (to_le_bytes) and streamed into a Gzip encoder. Upon initialization, load_weights_compressed decodes the stream directly back into f32 primitives using slice conversions, ensuring rapid boot times even with large weight matrices.

1fn load_weights_compressed(path: &str, rows: usize, cols: usize) -> Vec<Vec<f32>> {
2    let file = File::open(path).expect("Failed to open compressed weight file");
3    let mut decoder = GzDecoder::new(file);
4    let mut buffer = Vec::new();
5    decoder
6        .read_to_end(&mut buffer)
7        .expect("Failed to decompress file");
8
9    let mut matrix = vec![vec![0.0; cols]; rows];
10    let mut offset = 0;
11
12    for r in 0..rows {
13        for c in 0..cols {
14            let bytes: [u8; 4] = buffer[offset..offset + 4]
15                .try_into()
16                .expect("Corrupted binary slice");
17            matrix[r][c] = f32::from_le_bytes(bytes);
18            offset += 4;
19        }
20    }
21
22    matrix
23}

Technical Architecture & Performance

By eliminating heavy machine learning frameworks, this implementation delivers exceptional efficiency, consuming negligible memory overhead during execution. Training on generated shape datasets demonstrates how low-level memory control in Rust—paired with parallel CPU concurrency—enables high-performance AI training loops directly on standard hardware.

Try It Out

Download

If you want to try this app out for yourself, click on the download button and install rust-neural-network.rar from GitHub, extract the .rar file and run the rust-neural-network executable. It comes pretrained on a generated 6 Million shapes. If you want to train it yourself, delete the weights1_v6.bin.gz and weights2_v6.bin.gz files.

Video Demonstration

External Media Required

This video requires third-party cookies from YouTube to be displayed. Accepting will enable all external media across the site.