Metadata: discovery tags (collection, languages)

d778433 verified 4 days ago

7.02 kB

	---
	license: agpl-3.0
	tags:
	- snapkitty
	- machine-learning
	- c
	---

	> Source: [github.com/SNAPKITTYWEST/snapkitty-mlc](https://github.com/SNAPKITTYWEST/snapkitty-mlc)

	[![License: BSL-1.1](https://img.shields.io/badge/License-BSL--1.1-blue.svg)](https://opensource.org/licenses/BSL-1.0)
	[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-purple.svg)](https://www.gnu.org/licenses/agpl-3.0)
	[![License: MPL-2.0](https://img.shields.io/badge/License-MPL--2.0-orange.svg)](https://www.mozilla.org/en-US/MPL/2.0/)
	[![C11](https://img.shields.io/badge/C-C11-00599C.svg)](https://en.cppreference.com/w/c/11)
	[![CMake](https://img.shields.io/badge/CMake-%E2%89%A53.16-064F8C.svg)](https://cmake.org/)
	[![FlashAttention](https://img.shields.io/badge/FlashAttention-Dao%202022-green.svg)](https://arxiv.org/abs/2205.14135)
	[![Evidence or Silence](https://img.shields.io/badge/Protocol-Evidence%20or%20Silence-black.svg)](#)

	# snapkitty-mlc

	SnapKitty Machine Learning in C — 機器學習 C 語言核心庫 (مكتبة التعلم الآلي الأساسية بلغة C)

	Minimal autograd library with arena allocator, PCG32 PRNG, and MNIST example. Extracted from [SNAPKITTYAGENT9NOVA/MLC](https://github.com/SNAPKITTYAGENT9NOVA/MLC) and extended with FlashAttention (Dao et al. 2022).

	Authors: Ahmad Ali Parr, Jessica L. Williams (SNAPKITTYWEST)

	---

	## Modules

	\| Module \| Description \| 描述 (الوصف) \|
	\|--------\|-------------\|--------------\|
	\| `sk_arena` \| Virtual-memory arena allocator — Win32 VirtualAlloc + Linux mmap; 2 thread-local scratch pools \| 虛擬記憶體分配器 (مخصص الذاكرة الافتراضية) \|
	\| `sk_random` \| PCG32 (O'Neill 2014) — reentrant `_r` variants, better statistical properties than `rand()` \| 偽隨機數生成器 (مولد الأرقام العشوائية الزائفة) \|
	\| `sk_matrix` \| Row-major f32 matrix — all 4 matmul transpose variants, ReLU/Softmax/CrossEntropy + gradient accumulation \| 矩陣運算 + 梯度累積 (عمليات المصفوفات + تراكم التدرج) \|
	\| `sk_model` \| Computation graph — iterative DFS topological sort, reverse-mode autograd, mini-batch SGD with Fisher-Yates shuffle \| 計算圖 + 自動微分 (الرسم البياني الحسابي + التفاضل التلقائي) \|

	---

	## Repository Structure

	```
	snapkitty-mlc/
	├── include/
	│ ├── sk_defs.h Type aliases (i8/u8/f32…), KiB/MiB/GiB, MIN/MAX
	│ ├── sk_arena.h Virtual-memory arena allocator (Win32 + POSIX)
	│ ├── sk_random.h PCG32 PRNG (O'Neill 2014) — reentrant + global
	│ ├── sk_matrix.h Row-major f32 matrix: create/fill/matmul/relu/softmax/xent
	│ └── sk_model.h Computation graph, autograd, mini-batch SGD
	├── src/
	│ ├── sk_arena.c Arena implementation (VirtualAlloc / mmap)
	│ ├── sk_random.c PCG32 implementation
	│ ├── sk_matrix.c All matrix ops + gradient accumulation
	│ └── sk_model.c Graph build, topological sort, forward/backward, train loop
	├── examples/
	│ ├── mnist.c 784→16 ReLU → 16+skip ReLU → 10 Softmax
	│ ├── flash_attention_golden.py FlashAttention Alg 1 (Dao et al. 2022)
	│ └── data_convert.py MNIST → binary .mat
	└── CMakeLists.txt
	```

	---

	## Build

	```bash
	cmake -S . -B build
	cmake --build build
	# → build/libsk_mlc.a build/mnist
	```

	Requirements: C11 compiler (GCC / Clang / MSVC), CMake ≥ 3.16. No external dependencies.

	---

	## MNIST Example

	```bash
	# 1. Generate data (once)
	pip install tensorflow-datasets numpy
	python examples/data_convert.py

	# 2. Train
	./build/mnist
	```

	Architecture: `784 → 16 (ReLU) → 16+skip (ReLU) → 10 (Softmax+CrossEntropy)`
	Expected: ~97% test accuracy after 10 epochs (SGD lr=0.01, batch=50).

	---

	## FlashAttention Verification

	```bash
	python3 examples/flash_attention_golden.py
	# ALL TESTS PASSED — max error 2×10⁻¹²
	```

	All 4 test configurations pass against Algorithm 1 from Dao et al. 2022.

	---

	## API Reference

	### Arena Allocator (`sk_arena.h`)

	```c
	sk_arena* sk_arena_create(u64 reserve_size, u64 commit_size);
	void sk_arena_destroy(sk_arena* arena);
	void* sk_arena_push(sk_arena* arena, u64 size, b32 non_zero);
	void sk_arena_clear(sk_arena* arena);

	SK_PUSH_STRUCT(arena, T) // allocate one T, zeroed
	SK_PUSH_ARRAY(arena, T, n) // allocate n × T, zeroed
	```

	### PRNG (`sk_random.h`)

	```c
	void sk_prng_seed(u64 initstate, u64 initseq);
	u32 sk_prng_rand(void); // [0, 2^32)
	f32 sk_prng_randf(void); // [0, 1)

	// Reentrant:
	void sk_prng_seed_r(sk_prng* rng, u64 s, u64 seq);
	u32 sk_prng_rand_r(sk_prng* rng);
	f32 sk_prng_randf_r(sk_prng* rng);
	```

	### Matrix (`sk_matrix.h`)

	```c
	sk_matrix* sk_mat_create(sk_arena*, u32 rows, u32 cols);
	b32 sk_mat_mul(out, a, b, zero_out, transpose_a, transpose_b);
	b32 sk_mat_relu(out, in);
	b32 sk_mat_softmax(out, in);
	b32 sk_mat_cross_entropy(out, p, q);
	```

	### Model / Autograd (`sk_model.h`)

	```c
	sk_model* sk_model_create(sk_arena* arena);
	sk_model_var* sk_mv_matmul(arena, model, a, b, flags);
	sk_model_var* sk_mv_relu(arena, model, input, flags);
	sk_model_var* sk_mv_softmax(arena, model, input, flags);
	sk_model_var* sk_mv_cross_entropy(arena, model, p, q, flags);
	void sk_model_compile(arena, model); // topological sort
	void sk_model_train(model, &desc); // SGD training loop
	```

	---

	## Design Principles

	- No malloc in the hot path — all allocation through the arena
	- No external dependencies — libc only (`stdio`, `string`, `math`)
	- PCG32 — better statistical properties than `rand()`, reproducible with seed
	- Iterative DFS topological sort — forward/backward are simple array loops
	- Gradient accumulation — `_add_grad` functions accumulate; caller clears per batch

	---

	## License

	This project is released under a trilicense model. You may choose any one of the following:

	\| License \| SPDX \| Link \|
	\|---------\|------\|------\|
	\| Boost Software License 1.0 \| BSL-1.1 \| [LICENSE-BSL](https://opensource.org/licenses/BSL-1.0) \|
	\| GNU Affero General Public License v3 \| AGPL-3.0 \| [LICENSE-AGPL](https://www.gnu.org/licenses/agpl-3.0) \|
	\| Mozilla Public License 2.0 \| MPL-2.0 \| [LICENSE-MPL](https://www.mozilla.org/en-US/MPL/2.0/) \|

	Unauthorized cloud SaaS redistribution without source disclosure is prohibited under all three licenses.

	---

	SnapKitty West / SNAPKITTYWEST — Evidence or Silence — 2026

	### 💼 Commercial License

	Snapkitty code is free and open under AGPL-3.0 for open-source use. Building a commercial product or service? A proprietary commercial license from Snapkitty Collective LLC lets you ship this code without the AGPL's source-sharing and network-use obligations.

	[→ Get a commercial license](mailto:A.parr@belespritdaccord.uk?subject=Commercial%20license:%20snapkitty-mlc) · A.parr@belespritdaccord.uk