Gate Learner

A lightweight, high-performance Multilayer Perceptron (MLP) engine written from scratch in Python to train and evaluate $N$-input logic gates (such as OR and XOR).

Overview

gate_learner is a single-threaded neural network engine designed to solve non-linear classification problems (like the XOR parity problem) for arbitrary $N$-input dimensions. It features a manually implemented forward pass, backpropagation, Binary Cross Entropy (BCE) loss, and an Adam Optimizer with L2 regularisation.

To achieve optimal performance in pure Python, the engine utilizes pre-allocated internal buffers for activations, deltas, and gradients, mutating them in-place to avoid repetitive memory allocations during the training loop.

Features

• Custom MLP Engine
  Built entirely from scratch without external machine learning or tensor libraries.
• Adam Optimizer
  Includes momentum, RMSProp-like scaling, bias correction, and L2 regularisation.
• Flexible Activations
  Supports both Sigmoid and ReLU activation functions with appropriate weight initialisation (Xavier/Glorot and He Uniform).
• Dynamic Dataset Generator
  Generates truth tables for $N$-input OR and XOR gates dynamically.
• Early Stopping
  Halts training automatically when the model converges (Loss < 0.01) or stalls (Loss change < 1e-6 over 50 epochs).
• Visualisation
  Optional dual-axis plotting of training loss and accuracy curves using matplotlib.
• Serialisation
  Save and load trained models and training histories to/from JSON.

Installation

Ensure you have Python 3.12 or newer installed. It is highly recommended to use uv for fast dependency management:

# Clone the repository
git clone https://github.com/ios-community/gate-learner.git
cd gate-learner

# Install dependencies and create virtual environment
uv sync

Usage

Command Line Interface (CLI)

Run the CLI application to train an MLP on a specific logic gate. For example, to train a 2-input XOR gate:

uv run gate-learner \
  --gate xor \
  --inputs 2 \
  --epochs 10000 \
  --lr 0.01 \
  --batch-size 4 \
  --hidden-sizes 4 \
  --hidden-activation sigmoid \
  --seed 42

CLI Arguments

• -g, --gate <or|xor>: Logic gate type [default: xor].
• -i, --inputs <INTEGER>: Number of inputs (1 to 19) [default: 2].
• -e, --epochs <INTEGER>: Maximum training epochs [default: 10000].
• -l, --lr <FLOAT>: Learning rate for the Adam Optimizer [default: 0.01].
• -b, --batch-size <INTEGER>: Batch size for training [default: 4].
• --l2 <FLOAT>: L2 regularisation penalty coefficient [default: 0.0001].
• --hidden-sizes <TEXT>: Comma-separated hidden layer sizes [default: 4].
• --hidden-activation <sigmoid|relu>: Hidden layer activation function [default: relu].
• --seed <INTEGER>: Optional seed for reproducible weight initialisation and dataset shuffling.
• --model-out <PATH>: Path to save the trained model JSON [default: model.json].
• --history-out <PATH>: Path to save the training history JSON [default: history.json].
• --plot-out <PATH>: Path to save the training plot PNG [default: plot.png].

Library Usage

You can also use gate_learner as a library in your own Python projects:

from gate_learner.core import ActivationType, MultilayerPerceptron, NetworkConfig

def main() -> None:
    config = NetworkConfig(
        input_size=2,
        hidden_sizes=[4],
        output_size=1,
        hidden_activation=ActivationType.RELU,
    )

    # Initialise the network
    mlp = MultilayerPerceptron(config)

    # Perform a forward pass
    input_data = [1.0, 0.0]
    output_data = [0.0]
    mlp.forward(input_data, output_data)

    print(f"Output: {output_data}")

if __name__ == "__main__":
    main()

Feature Gating

The plotting functionality is optional and can be disabled to run the engine in minimal or headless environments without graphical dependencies.

• visualise (Optional): Pulls in the matplotlib dependency to render PNG plots.

To install the package without plotting support:

uv sync --no-group dev

To install with plotting support:

uv sync --extra visualise

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.