How youcef3939/cml works
1. What this repo is
- CML is a small machine-learning framework written in pure C.
- It is organized as a layered system: low-level tensor/autograd primitives at the bottom, neural-network modules above that, then training utilities and an example program on top.
2. Top-level runtime flow
- The main execution path is: load CSV data → wrap it as tensors → run a model forward pass → compute loss → call backward/autograd → update parameters with SGD.
- The example in examples/mlp_train.c is the best entry point for understanding how the pieces connect.
3. Tensor subsystem
- tensor/tensor.c, tensor/tensor.h define the core Tensor type.
- This layer is responsible for N-dimensional float32 storage, shape/stride tracking, contiguous layout, views such as reshape/slice without copying, and gradient buffers.
- This is the foundational boundary: everything else in the repo consumes or produces Tensor*.
4. Tensor operations
- tensor/ops.c contains the forward implementations of math primitives such as elementwise arithmetic, matrix multiplication, reduction, and broadcasting behavior.
- These ops are the basic computational units that model code builds from.
5. Autograd / backward pass
- tensor/backward.c and autograd/engine.c implement reverse-mode automatic differentiation.
- The architecture is dynamic graph-based: each tensor can remember its parents and a backward function, and the backward pass walks the graph in reverse topological order.
- Gradients are accumulated explicitly into tensor-owned gradient buffers.
6. Neural network layer boundary
- nn/linear.c, nn/linear.h implement dense layers with explicit weight and bias tensors.
- nn/activations.c, nn/activations.h provide activation functions such as ReLU, sigmoid, and tanh.
- These modules are thin wrappers over tensor ops plus autograd-enabled composition, so they are a higher-level modeling layer rather than a separate runtime.
7. Loss functions
- nn/loss.c, nn/loss.h define training objectives such as MSE and BCE.
- Loss is the bridge between model outputs and backpropagation: the computed scalar loss is what triggers gradient propagation through the graph.
8. Optimizer subsystem
- optim/sgd.c, optim/sgd.h implement stochastic gradient descent.
- This layer reads accumulated parameter gradients and applies in-place parameter updates, forming the “learning” step after backprop.
9. Data ingestion
- data/csv.c, data/csv.h load tabular data from CSV files into the program.
- The included data/train_X.csv and data/train_y.csv are sample training inputs and targets used by the example pipeline.
- This is the only explicit dataset boundary in the repo; there is no broader data pipeline or storage layer.
10. Example application
- examples/mlp_train.c ties all subsystems together into a minimal training loop for an MLP.
- It demonstrates how the repo expects to be used: read data, build tensors, instantiate a model, compute loss, backpropagate, and step the optimizer.
11. Main architectural boundaries
- The repo is intentionally split into four concentric layers:
- Core math/runtime: tensor/ and autograd/
- Modeling primitives: nn/
- Training logic: optim/
- I/O and orchestration: data/ and examples/
- This separation keeps the tensor engine independent from the neural-network and training code.
12. Technology profile
- The project is C-only, with no Python, CUDA, BLAS/LAPACK, or external ML framework dependency.
- Build is done by compiling the C sources directly with gcc and linking the math library (-lm).
- The architecture therefore emphasizes explicit memory management, explicit graph construction, and explicit training control.
13. What an architecture diagram should emphasize
- Put Tensor at the center as the shared data structure.
- Show forward computation flowing from CSV data through tensor ops into linear layers/activations and then loss.
- Show backward computation flowing from loss back through the autograd engine into parameter gradients.
- Show SGD consuming those gradients to mutate the model parameters.
Main entry points: mlp_train.c MLP Train · tensor.c Tensor · csv.c CSV Loader · linear.c Linear
Components 12
Data I/O
CSV ingestion and sample training files.
- CSV Loader · Loads tabular training data into memory for the example pipeline.
data/csv.c - Train X · Example feature matrix used by the training demo.
data/train_X.csv - Train Y · Example target values used by the training demo.
data/train_y.csv
Core Runtime
Tensor storage, math ops, and autograd.
- Tensor · N-D float32 tensors with shape, strides, views, and gradients.
tensor/tensor.c - Ops · Forward tensor math such as elementwise ops, matmul, reduction, and broadcasting.
tensor/ops.c - Backward · Tensor-level backward helpers for reverse-mode autodiff.
tensor/backward.c - Autograd · Walks the dynamic computation graph in reverse topological order and accumulates gradients.
autograd/engine.c
Neural Net
Modeling primitives built on tensors.
- Linear · Fully connected layer with explicit weight and bias tensors.
nn/linear.c - Activations · ReLU, sigmoid, and tanh wrappers built on tensor primitives.
nn/activations.c
Training
Optimization and loss computation.
Example
End-to-end training entry point.
- MLP Train · Minimal end-to-end training loop demonstrating data loading, forward pass, backprop, and optimization.
examples/mlp_train.c
Connections 18
- Train X → CSV Loader: read · Feature data is loaded from CSV.
- Train Y → CSV Loader: read · Target data is loaded from CSV.
- CSV Loader → Tensor: wrap · Parsed values are wrapped as tensors.
- Tensor → Ops: compute · Tensor operations build the forward computation.
- Ops → Linear: feed · Linear layers consume tensor math outputs.
- Linear → Activations: transform · Activations are applied after affine transforms.
- Activations → Losses: score · Model outputs are compared to targets via loss functions.
- Losses → Autograd: backprop · Scalar loss triggers reverse-mode differentiation.
- Autograd → Backward: dispatch · Autograd engine coordinates backward functions.
- Backward → Tensor: accumulate · Gradients are accumulated into tensor-owned buffers.
- Tensor → SGD: params · Parameter tensors with gradients are updated in place.
- SGD → Linear: update · Optimizer mutates layer weights and biases.
- MLP Train → CSV Loader: load · Example starts by loading the CSV dataset.
- MLP Train → Tensor: build · Example converts data into tensors and creates model state.
- MLP Train → Linear: model · Example instantiates and runs the MLP layers.
- MLP Train → Losses: loss · Example computes the training objective.
- MLP Train → Autograd: train · Example invokes backward propagation.
- MLP Train → SGD: step · Example applies optimizer updates after gradients are computed.