nillanet module

class nillanet.model.NN(input, output, architecture, activation, derivative1, classifier, derivative2, loss, derivative3, learning_rate, dtype=cupy.float32)

Bases: object

Minimal feedforward neural network using CuPy.

This class implements batched SGD with configurable activation, classifier, and loss functions. Inputs/targets are kept on device to avoid host↔device copies.

Parameters:

• input (cupy.ndarray | numpy.ndarray) – Training inputs of shape (n_samples, n_features). If NumPy, it will be moved to device.

• output (cupy.ndarray | numpy.ndarray) – Training targets of shape (n_samples, n_outputs). If NumPy, it will be moved to device.

• architecture (list[int]) – Units per layer, including output layer.

• activation (Callable[[cupy.ndarray], cupy.ndarray]) – Hidden-layer activation function.

• derivative1 (Callable[[cupy.ndarray], cupy.ndarray]) – Derivative of activation evaluated at pre-activations.

• classifier (Callable[[cupy.ndarray], cupy.ndarray]) – Output-layer transfer function (e.g., identity, sigmoid, softmax).

• derivative2 (Callable[[cupy.ndarray], cupy.ndarray]) – Derivative of classifier evaluated at pre-activations.

• loss (Callable[..., cupy.ndarray]) – Loss function that accepts named arguments (e.g., yhat, y) and returns per-sample losses or their average.

• derivative3 (Callable[..., cupy.ndarray]) – Derivative of loss with respect to predictions (same signature as loss).

• learning_rate (float) – SGD step size.

• dtype (cupy.dtype, optional) – Floating point dtype for parameters and data. Defaults to cupy.float32.

X

Training inputs with a prepended bias column, shape (n_samples, n_features + 1).

Type:

cupy.ndarray

Y

Training targets on device.

Type:

cupy.ndarray

W

Layer weight matrices; W[i] has shape (in_features_i, out_features_i).

Type:

list[cupy.ndarray]

architecture

Layer sizes as provided.

Type:

list[int]

learning_rate

SGD step size.

Type:

float

batch(x, y)

Run a single forward/backward/update step.

Parameters:

• x (cupy.ndarray | numpy.ndarray) – Inputs, shape (B, D) or (D,).

• y (cupy.ndarray | numpy.ndarray) – Targets, shape (B, K) or (K,).

Notes

Ensures inputs/targets reside on device and are at least 2D.

predict(input)

Run a forward pass to produce predictions.

Parameters:

input (cupy.ndarray | numpy.ndarray) – Inputs of shape (n_samples, n_features). If NumPy, it will be moved to device.

Returns:

Model outputs of shape (n_samples, n_outputs).

Return type:

cupy.ndarray

summary()

Print layer shapes and total parameter count.

train(epochs=1, batch=0)

Train the model using simple SGD.

Parameters:

• epochs – Number of SGD steps to run.

• batch – One of: - 1: sample a single example per step (pure SGD) - 0: use all samples per step (full batch) - >1 and < len(Y): use that mini-batch size per step

Raises:

SystemExit – If batch is invalid.

class nillanet.activations.Activations

Bases: object

Activation functions for NN class.

linear(x)

linear_derivative(x)

relu(x)

relu_derivative(x)

sigmoid(x)

sigmoid_derivative(x)

softmax(x)

tanh(x)

tanh_derivative(x)

class nillanet.loss.Loss

Bases: object

Loss functions for NN class

binary_crossentropy(y, yhat)

binary_crossentropy_derivative(y, yhat)

mse(yhat, y)

mse_alt(yhat)

mse_alt_derivative(yhat)

mse_derivative(yhat, y)

class nillanet.io.IO

Bases: object

Helper functions for NN class.

load(filename)

Read serialized file

Parameters:

filename – Path to the model pickle file.

save(model, filename)

Serialize the model to disk using pickle.

Parameters:

filename – Path to the output pickle file.

CuPy arrays are picklable

class nillanet.distributions.Distributions

Bases: object

Random training distributions for test modules.

arithmetic_distribution(depth, mode)

predict arithmetic result from distributions of two input values

Parameters:

• depth (int) – The number of rows for the generated matrix of floating point numbers.

• mode (str) – The mode of operation. Accepts either “add”, “subtract”, “multiply”, “divide”, or “zero” (always predict 0).

Returns:

tuple of (generated matrix, expected output)

Raises:

SystemExit – If the provided mode is not “summation” or “one_hot”.

linear_distribution(depth)

linear regression that predicts y from x for x-values on a random line with slope and intercept

Parameters:

depth (int) – The number of x-values to generate.

Returns:

tuple of (generated vector of x-values, vector of expected y-values)

logical_distribution(depth, mode)

boolean logic

Parameters:

• depth (int) – The number of rows for the generated two-column binary matrix.

• mode (str) – Accepts “and”, “or”, “xor”, or “xnor”.

Returns:

tuple of (generated binary matrix, expected output)

sort(rows, cols)

numerical sort

Parameters:

• rows (int) – the number of rows for the generated matrix

• cols (int) – the number of columns for the generated matrix

Returns:

tuple of (generated matrix, sorted matrix)

summation(rows, cols, mode='one_hot')

distributions of binary vectors for testing binary cross entropy (one-hot mode only)

Parameters:

• rows (int) – The number of rows for the generated binary matrix.

• cols (int) – The number of columns for the generated binary matrix.

• mode (str) – The mode of operation. Accepts either “summation” or “one_hot”. - “summation”: Produces a scalar count of the number of ones in each x vector. - “one_hot”: Produces a one-hot encoded representation of the count of ones in each x vector. Defaults to “one_hot”.

Returns:

tuple of (generated binary matrix, expected output)

Raises:

SystemExit if the provided mode is not "summation" or "one_hot". –