Version 0.0.3

GradieX — Python Library

The gradiex package wraps the float32 engine and adds a matplotlib plotting layer. Training runs entirely in C++: train() hands the whole dataset to core::Network::train and gets a loss history back.

#Install

From the release directory. A C++20 compiler is required; numpy and matplotlib are pulled in as dependencies.

cd 0.0.3
pip install .

Or build the extension in place, which is what the test scripts and the examples expect:

python3 setup.py build_ext --inplace

#Quick Start

Layers are declared, then built. Nothing is allocated until build(), so an invalid architecture raises a Python exception rather than training incorrectly.

import numpy as np
import gradiex

X = np.array([[0., 0.], [0., 1.], [1., 0.], [1., 1.]])
Y = np.array([[0.], [1.], [1.], [0.]])

gradiex.seed(42)                       # reproducible weight initialisation
net = gradiex.Network(learning_rate=0.5, batch_size=4)
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, plot=True)
print(net.predict([0., 1.]))           # -> array([0.984...], dtype=float32)

plot=True draws the loss curve when training finishes and leaves the figure on net.last_figure. The history is also kept on net.history, so net.plot_loss() works later with no arguments.

#Plots

Every figure below was produced by 0.0.3/examples/two_moons.py, which trains a 2 → 16 → 16 → 1 network on two interleaving moons and reaches 100 % train and test accuracy. Each plot takes an optional ax= and returns its figure, so they compose into larger layouts; nothing calls show() unless you pass show=True. Every one accepts theme="light" or theme="dark" — the figures on this page follow the site theme, and each is a genuinely different rendering rather than an inverted image.

Loss curve

The headline: train(plot=True), or net.plot_loss() at any time afterwards.

Once a model is fitting well the linear axis flattens out. log=True is usually the more informative view:

Architecture

Decision boundary

For a network with input_size == 2. A single output is read as a probability and shaded with a diverging ramp about 0.5; several outputs are read as classes by argmax.

Loss landscape

Two random directions are drawn through the trained weights and filter-normalised — each direction row scaled to the norm of the weight row it perturbs — then the loss is measured on a grid of steps along both. The method is from Li et al., Visualizing the Loss Landscape of Neural Nets (2018).

Weights

Predictions

Summary

#Training Runs In The Engine

train() is one call into core::Network::train. There is no per-sample loop in Python, and none in the binding either — the epoch loop, the shuffle, the mini-batching, gradient accumulation and the update rule are all engine code, with the GIL released for the duration.

That is checked rather than asserted. The same 4000-epoch XOR run, same seeds, through both paths:

Bit-identical, and the output activations agree to nine significant figures. Two seeds control it: gradiex.seed(n) for weight initialisation, and train(seed=n) for the shuffle.

Watching a validation split means calling train(epochs=1) in a loop, since the engine owns the epoch loop. Each call is still an engine call:

train_curve, held_out = [], []
for epoch in range(600):
    train_curve.append(net.train(X_train, Y_train, epochs=1, shuffle=True, seed=epoch)[0])
    held_out.append(net.evaluate(X_test, Y_test))

gradiex.plot_loss(train_curve, val_history=held_out, labels=("train", "held-out"))

#API Reference

Construction

Training and evaluation

Gradient primitives

One method per engine call, for a hand-rolled loop. backward(y) is the convenience form: zero, accumulate, apply.

Introspection

Plotting

Each is both a module function taking a network and a method on it. All accept ax=, theme=, title=, figsize= and show=.

gradiex.THEMES holds the two palettes. matplotlib is imported lazily, on the first plot, so import gradiex does not pay for it.

Names

gradiex.activations(), gradiex.losses() and gradiex.initializers() return these lists at runtime.

#What The Python Layer Guarantees

The C++ API can reach states that crash or train silently wrong. The binding collects layer specs first and constructs core::Network only in build(), so none of them are reachable from Python.

#Tests

python3 python/test_bindings.py    # engine bindings, guards, C++/Python parity
python3 python/test_plotting.py    # every diagram, headless (Agg)

test_bindings.py covers the engine surface and 23 guard cases — each must raise rather than crash. test_plotting.py asserts that every diagram builds a figure with the axes and artists it claims, that the loss-landscape sweep restores the weights exactly (including after a failure mid-sweep), that the directions really are filter-normalised, and that 15 guards raise. It does not assert on pixels; rendering is checked by eye.

The C++ suite is at tests/ — 91 checks, passing under AddressSanitizer and UBSan.