SNNL

**SNNL** is a rewrite of the earlier `BeeDNN` codebase into a cleaner, more modular layout. The goal is to preserve the useful parts of the original project and its broader ambitions while moving toward a structure that is easier to navigate, extend, and target with code generation.

Current Direction

• Keep the lightweight, dependency-free C++ core.
• Preserve the practical layer/data/model surface that made `BeeDNN` useful.
• Move from a flat source tree into grouped domains:

- `src/matrix/`

- `src/layers/`

- `src/data/`

- `src/loss/`

- `src/codegen/`

• Keep the public API simple while moving heavier subsystems into compiled sources.

Inherited Scope From BeeDNN

The rewrite is meant to carry forward the same overall content:

• matrix-first neural-network primitives
• structural, unary, dense, vision, and sequence layers
• training-oriented helpers such as losses and data sources
• dataset utilities for CSV and MNIST
• export/codegen hooks for generated inference modules
• room for bindings, samples, and tests

Current Layout

• `src/Model.h`: high-level model container and codegen export entry point
• `src/matrix/Matrix.h`: tensor shape + lightweight matrix utilities
• `src/layers/`: base layer interface and grouped layer families
• `docs/layers.md`: constructor, requirement, and result reference for factory-registered layers
• `docs/implementing_layers.md`: guide for adding new custom layers to SNNL
• `docs/training_network.md`: guide for training networks with SGD or the evolutionary trainer
• `src/data/`: data loaders, synthetic generators, and source abstractions
• `src/loss/`: loss API, factory singleton, and compiled implementations
• `src/optimizer/`: optimizer API, factory singleton, and compiled implementations
• `src/regularizer/`: regularizer API, factory singleton, and compiled implementations
• `src/training/Common.h`: shared merge/serialization helpers for the training stack
• `src/codegen/`: IR plus target emitters
• `samples/`, `tests/`, `binding_python/`, `binding_java/`, `binding_wasm/`: reserved rewrite structure matching the original project’s breadth

Building

The rewrite now ships with CMake and builds a compiled `snnl` library.

cmake -S . -B build
cmake --build build
ctest --test-dir build --output-on-failure

Available targets:

• `snnl`: compiled static library
• `snnl_sample_minimal`: tiny sample that builds a rewrite-era model and exports Mermaid graph output
• `snnl_sample_sequential_blobs`: rewrite-era `Sequential` + `SupervisedGradientDescent` multiclass toy classifier
• `snnl_sample_serialization_roundtrip`: XOR training sample that preprocesses inputs and verifies save/load parity
• `snnl_sample_factory_codegen`: constructs layers from the factory API and emits Mermaid + C artifacts
• `snnl_sample_rest_hub`: sample REST coordinator for browser-oriented distributed training experiments
• `snnl_sample_tcp_hub`: sample TCP coordinator for native/baremetal distributed training experiments
• `snnl_sample_tcp_worker`: tiny native worker example for the TCP hub
• `snnl_smoke`: smoke test that composes layers, fake data, and a built-in loss
• `snnl_training_stack`: exercises all ported losses, optimizers, regularizers, and save/load round-trips

Distributed Training Hooks

Generated `C`, `CppEigen`, and `WebGPU` runtimes now expose tensor synchronization helpers for trainable weights:

• tensor enumeration and shape metadata
• tensor manifest export
• `receiveMatrix(...)` / `_receive_matrix(...)` EMA-based weight ingestion
• `getUpdatedMatrix(...)` / `_get_updated_matrix(...)` direct weight access

The lightweight distributed helper headers live under `src/distributed/` and the coordinator examples live under `samples/`.

Factory API

The rewrite now exposes singleton registries for both training components and layers:

• `snnl::LayerFactory::instance()`
• `snnl::LossFactory::instance()`
• `snnl::OptimizerFactory::instance()`
• `snnl::RegularizerFactory::instance()`

Each factory supports:

• stream loading via `load(std::istream&)`
• construction via `load(name, stringArgs, floatArgs)`
• implementation registration via `addImpl(...)`
• discovery via `getList()` and `getUsage(name)`

Built-in implementations are registered from `loadAllImpl()` in the corresponding `.cpp` file.

Layer / Codegen Status

• Mermaid export is generated exclusively from `src/codegen/Exporter.h`.
• Layers now export a backend-agnostic generalized math/dataflow IR through `codegen::NodeSpec`.
• Composite layers are lowered through `src/codegen/Lowering.h` before non-Mermaid emitters consume them.
• The rewrite now includes a first wave of BeeDNN-era layers across dense, normalization/noise, vision, and attention families.

Status

This repository is still a rewrite, not a feature-complete drop-in replacement for `BeeDNN`. The current port keeps the new structure, restores a broader amount of the old project’s substance, and leaves the remaining gaps tracked in [`todo.md`](todo.md).