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.
| 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.
# 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:3000z = Σ_i w_i · x_i + b
A standard weighted sum. The hypothesis class is a hyperplane.
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.
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 |
The v2.0 dashboard at http://localhost:3000 provides:
- Dataset picker — 6 datasets (4 synthetic + 2 handwriting), with download status
- Dataset gallery — first 25 sample images rendered as canvases
- Configuration panel — optimizer, learning rate, epochs, batch size, image size, hidden layers, max train/test samples
- Live training charts — train loss + test accuracy, both arithmetics overlaid
- Summary table — final metrics for classical vs micro
- Confusion matrices — side-by-side, color-coded (green = correct, red = errors)
- Per-class accuracy — bar charts showing which digits/letters are hardest
- Sample predictions — 25 test images with predicted vs true label, color-coded green/red
- Weight heatmaps — first 16 neurons of the first hidden layer, visualized as images
- Structured log stream — color-coded, auto-scrolling
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| 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 | 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.
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
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.
MIT — see LICENSE.