conjugate-neuron

v2.0 — An experimental comparison of a classical (degree-0) neuron against a degree (-1) microstate neuron, on synthetic AND real handwriting data (MNIST, EMNIST Letters).

This repository implements, in TypeScript, the experiment proposed in the conversation that originated from the papers A Logarithmic-Exponential Conjugation Principle for Arithmetic Operations and Towards a Conjugate Arithmetic (J. Tapiador García). The central question was:

"Do you think that by displacing arithmetic to degree -1 the speed of computation (inference) would increase, or what would happen?"

v2.0 extends the original single-neuron synthetic comparison to real handwriting recognition: MNIST (digits 0-9) and EMNIST Letters (A-Z), with mini-batch training, confusion matrices, per-class accuracy, sample predictions, and weight heatmaps — all viewable in a live web dashboard.

What's new in v2.0

| Feature | v1.0 | v2.0 | |---------|------|------| | Datasets | 4 synthetic (XOR, spiral, Gaussian mixtures, blobs) | 4 synthetic + 2 handwriting (MNIST, EMNIST Letters) | | Training | Full-batch gradient descent | Mini-batch (configurable batch size) | | Data source | Generated in-memory | Lazy download + on-disk cache (~/.conjugate-neuron/data/) | | Image input | N/A (2D synthetic points) | 28×28 → downsampled to 14×14 or 7×7 | | Dashboard | Loss/accuracy charts + logs | + dataset gallery, confusion matrices, per-class accuracy, sample predictions, weight heatmaps | | Evaluation | Final loss/accuracy | + test-set accuracy, confusion matrix, per-class breakdown |

v1.x synthetic datasets are still available — v2.0 is additive, not breaking.

Quick start

# Install
npm install -g conjugate-neuron
# Or from source:
git clone https://github.com/Justo-Tapiador/conjugate-neuron.git
cd conjugate-neuron
npm install

# Download MNIST (one-time, ~12MB)
npx conjugate-neuron --download mnist

# Run a headless comparison (3 epochs, 2000 train samples)
npx conjugate-neuron --headless --dataset mnist --epochs 3 --max-train 2000

# Or start the dashboard
npx conjugate-neuron
# → open http://localhost:3000

The experiment

Classical neuron (degree 0)

z = Σ_i w_i · x_i + b

A standard weighted sum. The hypothesis class is a hyperplane.

Microstate neuron (degree -1)

z = log( Σ_i e^{w_i + x_i} + e^b )

Under the conjugation principle, multiplication becomes addition and addition becomes LogSumExp. The neuron computes the logarithm of a local partition function — each input x_i is a microstate weight, and the pre-activation z is the corresponding free energy. The gradient is softmax, so the neuron natively computes a probability distribution over its inputs.

What v2.0 measures

For each (dataset, arithmetic) pair:

| Metric | Description | |--------|-------------| | Train accuracy | Per-epoch training-set accuracy | | Train loss | Per-epoch training-set cross-entropy | | Test accuracy | Per-epoch test-set accuracy (held out) | | Test loss | Per-epoch test-set cross-entropy | | Epochs to 90% | First epoch where test accuracy ≥ 0.9 | | Confusion matrix | 10×10 (MNIST) or 26×26 (EMNIST) grid | | Per-class accuracy | Accuracy for each digit/letter | | Sample predictions | First 25 test images with predicted vs true label | | Weight heatmap | First hidden layer weights as images |

Dashboard features

The v2.0 dashboard at http://localhost:3000 provides:

1. Dataset picker — 6 datasets (4 synthetic + 2 handwriting), with download status
2. Dataset gallery — first 25 sample images rendered as canvases
3. Configuration panel — optimizer, learning rate, epochs, batch size, image size, hidden layers, max train/test samples
4. Live training charts — train loss + test accuracy, both arithmetics overlaid
5. Summary table — final metrics for classical vs micro
6. Confusion matrices — side-by-side, color-coded (green = correct, red = errors)
7. Per-class accuracy — bar charts showing which digits/letters are hardest
8. Sample predictions — 25 test images with predicted vs true label, color-coded green/red
9. Weight heatmaps — first 16 neurons of the first hidden layer, visualized as images
10. Structured log stream — color-coded, auto-scrolling

CLI reference

conjugate-neuron                              # start dashboard on :3000
conjugate-neuron --port 4000                  # custom port
conjugate-neuron --headless --dataset mnist   # headless MNIST comparison
conjugate-neuron --download mnist             # download MNIST, then exit
conjugate-neuron --download emnist-letters    # download EMNIST Letters
conjugate-neuron --list                       # list cached datasets
conjugate-neuron --clear-cache                # clear all cached data

Headless flags

| Flag | Default | Description | |------|---------|-------------| | --dataset <id> | xor | xor, spiral, gaussian-mixtures, blobs, mnist, emnist-letters | | --epochs <n> | 5 | Number of training epochs | | --lr <x> | 0.001 | Learning rate (handwriting) / 0.05 (synthetic) | | --batch-size <n> | 32 | Mini-batch size (handwriting only) | | --max-train <n> | 5000 | Max training samples per epoch | | --max-test <n> | 1000 | Max test samples for evaluation |

Dataset details

| Dataset | Classes | Train | Test | Size | Download | |---------|---------|-------|------|------|----------| | XOR | 1 (binary) | 100 | — | 2D | — | | Spiral | 3 | 300 | — | 2D | — | | Gaussian mixtures | 2 | 400 | — | 2D | — | | Blobs | 2 | 200 | — | 2D | — | | MNIST | 10 (0-9) | 60,000 | 10,000 | 28×28 | ~12 MB | | EMNIST Letters | 26 (A-Z) | 124,800 | 20,800 | 28×28 | ~50 MB |

Handwriting datasets are downloaded on first use from public mirrors (OSCI Amazon S3 for MNIST, NIST for EMNIST) and cached under ~/.conjugate-neuron/data/. Override the cache location with CONJUGATE_NEURON_DATA_DIR=/your/path.

Repository structure

conjugate-neuron/
├── src/
│   ├── index.ts                    ← public library entry point
│   ├── main.ts                     ← CLI entry point
│   ├── arithmetic/                 ← Arithmetic interface + 3 impls
│   ├── tensor/                     ← Vector, Matrix, RNG
│   ├── nn/                         ← Parameter, Neuron, Layer, Network (+ mini-batch)
│   ├── activations/                ← Identity, Sigmoid, Tanh, ReLU
│   ├── losses/                     ← MSE, BCE, CrossEntropy
│   ├── optimizers/                 ← SGD, Adam
│   ├── datasets/
│   │   ├── Dataset.ts              ← v1 synthetic datasets
│   │   ├── IDX.ts                  ← IDX binary format parser (NEW)
│   │   ├── ImageUtils.ts           ← downsample, normalize (NEW)
│   │   ├── Downloader.ts           ← lazy download + cache (NEW)
│   │   ├── MNIST.ts                ← MNIST loader (NEW)
│   │   ├── EMNIST.ts               ← EMNIST Letters loader (NEW)
│   │   └── index.ts                ← unified registry
│   ├── experiments/
│   │   ├── ExperimentRunner.ts     ← v1 synthetic experiments
│   │   ├── HandwritingExperiment.ts ← v2 handwriting experiments (NEW)
│   │   ├── runComparison.ts        ← v1 comparison
│   │   └── runHandwritingComparison.ts ← v2 comparison (NEW)
│   └── server/
│       ├── LogBus.ts               ← event bus (+ new event kinds)
│       ├── server.ts               ← Express + WebSocket (+ new endpoints)
│       └── public/                 ← dashboard HTML/CSS/JS (redesigned)
├── tests/
│   └── arithmetic.test.ts          ← 8 unit tests
├── docs/
│   ├── theory.md
│   ├── experiment-design.md
│   └── mnn.png
└── .github/workflows/ci.yml

Mathematical background

The conjugation principle defines an infinite hierarchy of binary operations *_k:

a *_(k+1) b = exp( log(a) *_k log(b) )

Setting *_0 = + gives:

• Degree -1: log(e^a + e^b) = LogSumExp (the microstate neuron's aggregation)
• Degree 0: a + b (ordinary addition)
• Degree 1: a · b (ordinary multiplication)

A degree-(-1) neuron computes z = log(Σ e^{w_i + x_i} + e^b) — the log of a local partition function. See docs/theory.md for the full derivation.

License

MIT — see LICENSE.