Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
73 lines (61 loc) · 4.56 KB

ARCHITECTURE.md

File metadata and controls

73 lines (61 loc) · 4.56 KB
Raw

Architecture & Design (Python)

This document describes the high-level architecture of the gate_learner Python package.

Module Overview

The project is structured as a decoupled library with a Typer CLI wrapper. This separation ensures that the core mathematical engine remains independent of I/O, CLI parsing, and plotting logic.

+-----------------------------------------------------------------------+
|                              CLI Module                               |
|                     (gate_learner/cli.py, main)                       |
+-----------------------------------+-----------------------------------+
                                    |
                                    v
+-----------------------------------+-----------------------------------+
|                           Dataset Generator                           |
|                     (gate_learner/dataset.py)                         |
+-----------------------------------+-----------------------------------+
                                    |
                                    v
+-----------------------------------+-----------------------------------+
|                           Core ML Engine                              |
|                     (gate_learner/core.py)                            |
|   +---------------------------------------------------------------+   |
|   |                     MultilayerPerceptron                      |   |
|   |  - Forward Pass (Sigmoid / ReLU Activation)                   |   |
|   |  - Gradient Accumulation (BCE Loss)                           |   |
|   +-------------------------------+-------------------------------+   |
|                                   |                                   |
|                                   v                                   |
|   +---------------------------------------------------------------+   |
|   |                        AdamOptimizer                          |   |
|   |  - Parameter Update (L2 Regularisation & Bias Correction)     |   |
|   +-------------------------------+-------------------------------+   |
+-----------------------------------+-----------------------------------+
                                    |
                                    +-----------------------+
                                    |                       |
                                    v                       v
+-----------------------------------+---+               +---+--------------------+
|            Storage Module             |               |  Plot Module (Feature) |
|       (gate_learner/storage.py)       |               | (gate_learner/plot.py) |
+---------------------------------------+               +------------------------+

1. Core ML Engine (core.py)

Contains the mathematical representation of the neural network.

  • Layer: Represents a single layer containing weights, biases, and an activation function.
  • MultilayerPerceptron: Manages a sequence of layers. It holds pre-allocated internal buffers for activations, deltas, and gradients to avoid list allocations during the training loop.
  • AdamOptimizer: Implements the Adam optimization algorithm. It maintains its own state buffers (first and second moments) matching the network's architecture.

2. Dataset Generator (dataset.py)

Generates truth tables for $N$-input OR and XOR gates. It includes safety checks to prevent memory exhaustion by limiting $N < 20$ (since dataset size scales exponentially as $2^N$).

3. Storage Module (storage.py)

Handles JSON serialisation and deserialisation of the trained model weights and training history.

4. Plot Module (plot.py)

Gated under optional matplotlib import. It renders a dual-axis PNG chart showing the training loss and accuracy curves over epochs.

5. CLI Module (cli.py & main.py)

Parses command-line arguments using typer, coordinates the training loop, manages early stopping, and handles output generation.

Key Architectural Decisions

Memory Management & Allocation

To achieve high performance in pure Python, list allocations are avoided inside the training loop.

  • The MultilayerPerceptron allocates its activation, delta, and gradient buffers once during initialization via ensure_buffers().
  • During the forward and backward passes, these buffers are mutated in-place.

Concurrency & Serialization

The MultilayerPerceptron and Layer classes are designed to be fully picklable (serialisable). This allows the model to be safely transferred across processes using Python's multiprocessing module for parallel hyperparameter grid search.