cat-dog-asm-cnn - GitLite

KO | EN

gitlite — search

#hacktoberfest #react #ai #typescript #llm #android #machine-learning #deep-learning #macos #java #windows #awesome #cli #pytorch

cat-dog-asm-cnn

(★ 178)

A Convolutional Neural Network implemented entirely from scratch in x86-64 assembly using AVX-512, performing cat vs dog image classification without any ML frameworks or libraries.

파일 탐색기

최종 버전 다운로드 (.zip)

- accuracy.png
- image.jpg
- image2.jpg
- image3.png
- image4.png
- img.jpg
- parameters.raw
.gitignore
_start.asm
activation_functions.asm
backward.asm
buffer.asm
build.sh
convolution.asm
debug_buffer.asm
debug_tools.asm
dense.asm
Dockerfile
dot_product.asm
forward.asm
LICENSE
loader.asm
loss.asm
macros.inc
matrix_ops.asm
maxpool.asm
padding.asm
parameters.asm
print.asm
README.md
update_weights.asm

# 설치 가이드

1. 코드 내려받기

git clone https://github.com/mohammad-ghaderi/cat-dog-asm-cnn

깃허브에서 프로젝트 코드 전체를 내 컴퓨터로 내려받습니다.

cd cat-dog-asm-cnn

방금 내려받은 프로젝트 폴더 안으로 이동합니다.

2. Docker

쉬움 추천

사전 준비물

Git GitHub에서 프로젝트 코드를 내려받으려면 필요합니다.
Docker Desktop 컨테이너를 빌드하고 실행하려면 필요합니다. 설치 후 실행해서 백그라운드에 켜두세요.

docker build -t nasm-assembly .

Dockerfile을 기반으로 실행 가능한 이미지를 빌드합니다.

docker run \

빌드된 이미지를 실제 컨테이너로 실행합니다.

docker exec -it <container_id_or_name> bash

이 명령어를 터미널에 그대로 입력해 실행하세요.

• Runtime: Docker

이 명령어를 터미널에 그대로 입력해 실행하세요.

✅ 터미널에 docker compose ps 를 입력해 컨테이너들이 Up 상태인지 확인하세요. README에 포트 번호가 적혀있다면 브라우저에서 http://localhost:포트번호 로 접속해보세요.

이 레포의 README에 적힌 실제 명령어를 그대로 가져왔습니다.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Convolutional Neural Network in Assembly x86, From Scratch, ~10 times faster

Author: [Mohammad Ghaderi](https://www.linkedin.com/in/mohammad-ghaderi-ba09a8359)

Advisor: [Prof. Saleh Yousefi](https://scholar.google.com/citations?user=ew1vFSsAAAAJ)

#### Overview

This project implements a full Convolutional Neural Network (CNN) entirely in x86-64 **assembly language** for **cat–dog image classification**. The network is built completely from scratch, including convolution, pooling, dense layers, forward pass, and backward pass — with no machine learning frameworks or libraries.

The goal of this project was to gain a deep, low-level understanding of CNNs, focusing on memory layout, data movement, and explicit SIMD-based **parallel computation**. The entire network is implemented in **pure x86-64 assembly**, using AVX-512 vector instructions to **process 16 float32 values in parallel**, exposing all aspects of forward and backward propagation at the instruction level.

The project runs inside a lightweight Debian Slim environment using Docker.

### Performance

This implementation achieves approximately 10× faster performance than an equivalent NumPy-based CNN, even though NumPy itself relies on highly optimized C libraries. However, it does not reach the performance of PyTorch, as the codebase was intentionally designed to be dynamic and scalable, with configurable layers and hyperparameters. In a previous project, where the architecture and execution paths were more specialized and fixed, performance exceeded PyTorch by approximately 1.4×. In contrast, this project prioritizes generality and extensibility over aggressive specialization, resulting in a deliberate trade-off between flexibility and peak performance, while still benefiting significantly from explicit AVX-512 SIMD vectorization.

### Why I Built This

**Sometimes, we think we truly understand something**, until **we try to build it from scratch** When **theory meets practice, every small detail becomes a challenge**.

After implementing a [fully connected neural network in assembly for MNIST](https://github.com/mohammad-ghaderi/mnist-asm-nn), I wanted to go further and tackle a real CNN for **cat-vs-dog classification**. Convolutions, pooling, tensor reshaping, and backpropagation introduce a completely different level of complexity when there are no libraries to rely on.

![projct](https://raw.githubusercontent.com/mohammad-ghaderi/cat-dog-asm-cnn/main/docs/img.jpg)

This project pushed me to understand CNNs not just mathematically, but mechanically: how every multiply, add, load, store, and branch maps directly to CPU instructions.

#### Performance & Optimization

Not only is this a pure assembly implementation, it is also heavily optimized:

• AVX-512 SIMD acceleration using ZMM registers
      – 16 float32 values computed in parallel
      – Used in convolution, dense layers, and ...

• End-to-end vectorized forward and backward passes

• Approximately 10× faster than an equivalent NumPy implementation
      – Both in training and inference
      – NumPy itself relies on optimized C libraries

Implementation Highlights

• Convolution (Conv2D)
    • Max Pooling
    • Fully Connected (Dense) layers
    • Activation functions (ReLU, Sigmoid)
    • Forward propagation
    • Backward propagation (gradients & updates)
    • Data loader
    • Hyperparameter-driven and scalable design

### Dataset

+ Cat vs Dog classification
+ 25,000 RGB images (128 × 128 × 3)
+ Balanced dataset (cats and dogs)

### CNN Architecture

| Layer   | Type                        | Input → Output         |
| ------- | --------------------------- | ---------------------- |
| Conv1   | #32 Conv2D (3×3) + ReLU     | 3×128×128 → 32×128×128 |
| Pool1   | MaxPool (2×2)               | 32×128×128 → 32×64×64  |
| Conv2   | #64 Conv2D (3×3) + ReLU     | 32×64×64 → 64×64×64    |
| Pool2   | MaxPool (2×2)               | 64×64×64 → 64×32×32    |
| Conv3   | #128 Conv2D (3×3) + ReLU  | 64×32×32 → 128×32×32   |
| Pool3   | MaxPool (2×2)               | 128×32×32 → 128×16×16  |
| FC1     | Dense + ReLU                | 32768(128×16×16) → 128 |
| FC2     | Dense + Sigmoid             | 128 → 1                |
+ Epochs: 10
+ Batch size: 16
+ Learning rate: 0.01

The code is written in a way that allows changing some of hyperparameters without rewriting the rest of the implementation.

###### Debugging Challenges

Debugging a CNN written in pure assembly is extremely challenging. Traditional tools like GDB become difficult to use when dealing with large tensors, SIMD registers, and deeply nested computations.

Because of this, I developed my own debugging techniques, including manual tensor validation, controlled test inputs, and custom inspection routines to verify correctness at each stage of the network.

###### Environment

• Architecture: x86-64
    • SIMD: AVX-512
    • OS: Debian Slim
    • Runtime: Docker
    • Assembler: NASM

####  Previous Work
Neural Network in Assembly (MNIST from Scratch)
https://github.com/mohammad-ghaderi/mnist-asm-nn

#### GDB debuggin environment
![Debuggin](https://raw.githubusercontent.com/mohammad-ghaderi/cat-dog-asm-cnn/main/docs/image4.png)

##### Accuracy same as python version (78% for this model) 
![Accuracy](https://raw.githubusercontent.com/mohammad-ghaderi/cat-dog-asm-cnn/main/docs/accuracy.png)
(adding dropout and batchnomalization would boost it)

## Build & Run with Docker
This project can be built and run inside a Docker container with NASM and build tools installed. Follow these steps:

#### Build the Docker image
```bash
docker build -t nasm-assembly .
```

### Run the Docker Container
```
docker run \
  --volume="PATH/TO/PROJECT:/mnt/project" \
  --cpus=4 \
  --memory=4g \
  --memory-swap=4g \
  nasm-assembly
```
Replace `PATH/TO/PROJECT` with your local project folder, e.g.:

- Windows: `C:/Users/YourName/cat-dog-asm-cnn`  
- Linux/Mac: `/home/username/cat-dog-asm-cnn`

#### Enter the Container
```
docker exec -it <container_id_or_name> bash
```

#### Run & build 
This project includes a `build.sh` script to assemble, link, and run the NASM neural network.

```
./build.sh
```
- This will assemble all .asm files, link them, and produce the executable ./model.

Run the neural network model:
```
./model
```

#### Downloading Dataset
+ [Raw files](https://drive.google.com/file/d/11Dc51DLDCyMv-ajI0k4RJNRvjHNTQwWr/view)
+ [Tumbs](https://drive.google.com/file/d/1dbpla8zC1LJeroHVA8w3bLG-jQY7nPp5/view)

+ [Original Dog and Cat dataset](https://www.kaggle.com/datasets/bhavikjikadara/dog-and-cat-classification-dataset)