Menu
Version 0.0.2
GradieX Documentation
A feedforward neural network engine written from scratch in C++20 — no BLAS, no Eigen, no external dependencies — with Python bindings via pybind11.
v0.0.2 is the middle release: an architecture rewrite that made the engine fast and, deliberately, much smaller. Most of what it lists as missing was present in v0.0.1 — mini-batching, dropout, L2, a validation split, seeded runs, multi-class softmax and model save/load — and v0.0.3 has since restored mini-batching and moved the engine to float. Of the three, this is the only release whose Python bindings build. See the version comparison.
Getting Started
The engine is header-only, so the C++ side needs no build step of its own:
#include "core/network.h"Then compile as a single translation unit:
clang++ -std=c++20 -O2 main.cpp -o mainFor Python, build the extension module from the repository root:
pip install .Then use it from Python:
import numpy as np, gradiex
net = gradiex.Network(learning_rate=0.5)
net.add_hidden(8, input_size=2, activation="tanh", init="xavier")
net.add_output(1, activation="sigmoid", loss="mse")
net.build()
history = net.train(X, Y, epochs=4000, shuffle=True, seed=42)Reference
- The C++ Library
- The header-only engine in
core/. Namespaces, the function pointer types, theLayerhierarchy,Network, and the activation, initializer and loss catalogues. Sixteen sections, plus a list of known bugs. - The Python Library
- The
gradiexextension module. Installation, theNetworkclass, array conventions, and the guarantees the binding adds on top of the engine. Twelve sections, plus troubleshooting.
If you are looking for something specific:
- Building the C++ library
- Installing the Python module
- Activation function catalogue
- Loss function catalogue
- How weights are stored
- Errors the Python binding raises
- Troubleshooting
- Known bugs and limitations
At a Glance
| Item | Value |
|---|---|
| Language | C++20 |
| Scalar type | double throughout |
| Dependencies | None (C++ standard library only) |
| Python binding | pybind11, Python 3.9 or later |
| Layout | Header-only; core/ compiles into the caller |
| Training | Per-sample stochastic gradient descent |
| Activations | sigmoid, relu, leaky_relu, tanh, swish, gelu |
| Losses | mse, mae, huber, binary cross entropy, cross entropy |
| Initializers | zeros, xavier, he |
| License | MIT |
Project State
This is the second engine, a rewrite of
v0.0.1 (which descends from
GradieX v1). The object
hierarchy was flattened from Network → Layer → Neuron down to
Network → Layer → vectors, and the weights were flattened into
one contiguous array per layer to avoid per-neuron heap allocation.
It is not a superset of v0.0.1. Several features present there have not been carried across yet: model save and load, mini-batching, L2 weight decay, dropout, a train/validation split, seeded reproducibility, and a trainable softmax output. See Not Supported for the full list, and Known Bugs for defects that are documented rather than fixed.
The test suite under tests/ deliberately reports several failures.
Those tests are executable specifications for the bugs above, each explaining
the defect and the fix through FAIL_WITH_NOTE.
Performance work is tracked separately in TODO.md, ordered by measured payoff.