tin_man

A Rust library implementing the WiSARD family of weightless neural networks, plus thermometer-style feature encoders and full model persistence.

WiSARD (Wilkie, Stonham, and Aleksander's Recognition Device) is a pioneering Weightless Neural Network (WNN) model developed in the 1970s and 1980s by Bruce Wilkie, John Stonham, and Igor Aleksander. Unlike traditional neural networks that store knowledge in synaptic weights, WiSARD uses Random Access Memory (RAM) nodes to store learned patterns directly in lookup tables.

Igor Aleksander is an emeritus professor of Neural Systems Engineering in the Department of Electrical and Electronic Engineering at Imperial College London. He worked in artificial intelligence and neural networks and advised my advisor, Felipe Maia Galvão França, who taught me the simplicity and power of WNNs.

Felipe's PhD dissertation covers two of his research passions: Scheduling by Edge Reversal (SER) and WNNs. He has advised a prolific group of researchers on both themes (BTW, my Master's, for instance, extended SER with hibernation) and has co-authored more than fifty published manuscripts in the WNN research field, reflecting his lasting contribution to it.

This Rust library is named after the Tin Man, also known as the Tin Woodman or Nick Chopper — a fictional character created by L. Frank Baum in his 1900 novel The Wonderful Wizard of Oz. He is a sentient being made entirely of metal who seeks a heart to restore his capacity for emotion. As an engineer, I'd like to remind you: tin never, ever rusts.

Models

Bloom filter variants

For large address_size values, an exact RAM node needs 2^address_size counters — most of which are never visited. The Bloom-filter-backed variants below replace each RAM's exact address table with a compact, multi-hash counting structure, trading a small, tunable false-positive rate for dramatically lower memory use.

Every Bloom model exposes memory_bytes() so you can directly measure the memory savings against an equivalent exact model, and accepts a parallel: bool constructor flag (where applicable) to switch classification between sequential and rayon-parallelized execution.

Encoders

Project layout

tin_man/
├── src/ Core library (models, RAMs, encoders, persistence, Bloom variants)
├── benches/ Criterion throughput benchmarks
├── examples/ Standalone runnable usage examples
├── tests/ Integration tests (cargo test)
├── tin_man_py/ Python bindings (PyO3 + maturin)
├── tin_manR/ R bindings (extendr + rextendr)
├── scripts/ Python visualization utilities (mental images, retina mapping)
└── README.md

benches/

Benchmarks are run with Criterion and measure training and classification/prediction throughput (operations per second) for all models:

Run all benchmarks with:

cargo bench

Criterion prints per-operation timing and throughput (e.g. Kelem/s) directly in the terminal, and generates an interactive HTML report at target/criterion/report/index.html.

examples/

Runnable, self-contained examples demonstrating end-to-end usage of each model and encoder. Run any example with:

cargo run --example <name>

tests/

Integration tests exercising the public API of all models — training, classification/prediction correctness, edge cases (untrained models, input size mismatches), bleaching vs. binary mode consistency, and Bloom-filter false-positive-rate sanity checks. Run with:

cargo test

scripts/

Python utilities (using plotnine) for visualizing trained models as PNGs:

Installation

Add to your Cargo.toml:

[dependencies]
tin_man = { path = "path/to/tin_man" }

Quick example

use tin_man::{Wisard, encoders::LinearThermometer};

fn main() {
    let data = vec![1.2, 3.4, 2.1, 5.6, 4.3];
    let encoder = LinearThermometer::fit(&data, 8);

    let mut w = Wisard::new(8, 4, 0.1, true, false);
    w.train(&encoder.encode(1.2), "low");
    w.train(&encoder.encode(5.6), "high");

    let (label, confidence) = w.classify(&encoder.encode(1.5)).unwrap();
    println!("{label} ({confidence:.2})");
}

Persistence

All models support saving/loading via FileFormat::Json (readable) or FileFormat::Binary (compact):

use tin_man::{FileFormat, Wisard};

let w = Wisard::new(8, 4, 0.1, true, false);
w.save_to_file("model.json", FileFormat::Json).unwrap();
let w2 = Wisard::load_from_file("model.json", FileFormat::Json).unwrap();

Python bindings

See tin_man_py/README.md for installing and using this library from Python via PyO3/maturin.

Generating docs

cargo doc --open --no-deps

License

MIT