Skip to main content

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

Model Purpose
Wisard Standard multi-class classification
ClusWisard Classification with multiple clusters per class
RegressionWisard Continuous-value regression
ClusRegressionWisard Regression with multiple clusters per group

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.

Model Purpose Backing structure
BloomWisard Wisard-equivalent classification Counting Bloom filter per RAM (bloom_size counters, num_hashes hash functions)
BloomClusWisard ClusWisard-equivalent, multiple Bloom-backed clusters per class Same as BloomWisard, one filter set per cluster
BloomRegressionWisard RegressionWisard-equivalent continuous-value regression Count-Min-Sketch-style dual sum/count Bloom structure per RAM

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

Encoder Bin placement
LinearThermometer Uniform across [min, max]
GaussianThermometer Concentrated near the mean (normal CDF)
DistributiveThermometer Quantile-based, fit from data
KernelCanvas Variable-length sequences of points into a fixed-size binary canvas via random kernels

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:

File What it measures
wisard_bench.rs Training and classification throughput for Wisard, ClusWisard, RegressionWisard, and ClusRegressionWisard, plus a classification throughput sweep across different address_size values
bloom_wisard_bench.rs Training and classification throughput for BloomWisard, BloomClusWisard, and BloomRegressionWisard, plus a comparison sweep of bloom_size/num_hashes against exact-RAM throughput and memory usage

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>
Example Demonstrates
wisard_basic Training and classifying with Wisard on binary-encoded input
clus_wisard_basic Handling heterogeneous sub-patterns within a class using ClusWisard
regression_wisard_basic Continuous-value prediction with RegressionWisard
clus_regression_wisard_basic Multi-cluster regression with ClusRegressionWisard and grouped predictions
thermometer_encoding Fitting and applying LinearThermometer, GaussianThermometer, and DistributiveThermometer to continuous features
persistence Saving and loading trained models via FileFormat::Json and FileFormat::Binary
kernel_canvas_timeseries Classifying variable-length 2D strokes (diagonal vs. circular) via KernelCanvas + Wisard
bloom_iris Classifying the Iris dataset with BloomWisard and BloomClusWisard, sequentially trained so that classes are discovered incrementally (one class trained initially, two more discovered on the fly)

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:

Script What it renders
tin_man_mental_image.py DRASiW-style "mental image" per class for an exact Wisard model, projecting RAM counter values back onto retina bit positions
tin_man_bloom_mental_image.py Same mental-image visualization for a BloomWisard model, reconstructing estimated per-address counts from the Bloom filter's hashed counters before projecting
tin_man_mapping.py Visualizes the retina-to-RAM mapping, labeling each pixel with its assigned RAM node id and address bit index

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

Metadata

Release files for tin-man-py 0.5.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for tin-man-py 0.5.1
File Size Uploaded Provenance Actions
tin_man_py-0.5.1.tar.gz 48.5 kB Without provenance Details for tin_man_py-0.5.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for tin-man-py 0.5.1
File Interpreter ABI Platform Actions
tin_man_py-0.5.1-cp313-cp313-macosx_11_0_arm64.whl CPython 3.13 CPython 3.13 macOS 11.0+ ARM64 Details for tin_man_py-0.5.1-cp313-cp313-macosx_11_0_arm64.whl

Total release size: 452.4 kB

Release files / tin_man_py-0.5.1.tar.gz

Download URL tin_man_py-0.5.1.tar.gz
Size 48.5 kB
Tags Source
SHA-256 checksum
How to use checksums
bbd0f32b7bfeab29aaae1e080e613c7f5ecf38e3c043ee2e99354f1cec777b39
BLAKE2b-256 checksum
How to use checksums
6dc1ff49c775dd8d548d3e7ee068ac62335e4607304e478e161783cd2c18571d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.14.1

Release files / tin_man_py-0.5.1-cp313-cp313-macosx_11_0_arm64.whl

Download URL tin_man_py-0.5.1-cp313-cp313-macosx_11_0_arm64.whl
Size 403.9 kB
Tags CPython 3.13 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
5d3174a2e88133ee46d0e068e987053aacb909f7fd039b9dc8e80ddd47338756
BLAKE2b-256 checksum
How to use checksums
b734be2a2c35693f2c047f16f59a8a98dcca5a076a3f6ca413e48b92f119bcf6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.14.1

Security for tin-man-py 0.5.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.5.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page