torchtsetlin 0.1.0__tar.gz

torchtsetlin-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vajira Thambawita
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

torchtsetlin-0.1.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: torchtsetlin
+Version: 0.1.0
+Summary: GPU-enabled, PyTorch-native Tsetlin Machine framework: models, data preparation, training, evaluation, interpretation and visualization.
+Author-email: Vajira Thambawita <vajira@simula.no>
+License: MIT
+Project-URL: Homepage, https://github.com/vlbthambawita/torchtsetlin
+Project-URL: Documentation, https://vlbthambawita.github.io/torchtsetlin/
+Project-URL: Repository, https://github.com/vlbthambawita/torchtsetlin
+Project-URL: Issues, https://github.com/vlbthambawita/torchtsetlin/issues
+Keywords: tsetlin machine,pytorch,interpretable machine learning,logic-based learning,gpu
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch>=2.0
+Requires-Dist: numpy>=1.22
+Provides-Extra: viz
+Requires-Dist: matplotlib>=3.5; extra == "viz"
+Provides-Extra: vision
+Requires-Dist: torchvision>=0.15; extra == "vision"
+Provides-Extra: sklearn
+Requires-Dist: scikit-learn>=1.1; extra == "sklearn"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.5; extra == "docs"
+Requires-Dist: mkdocs-material>=9.4; extra == "docs"
+Requires-Dist: mkdocstrings[python]>=0.24; extra == "docs"
+Requires-Dist: mkdocs-autorefs>=0.5; extra == "docs"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-timeout; extra == "dev"
+Requires-Dist: matplotlib>=3.5; extra == "dev"
+Requires-Dist: scikit-learn>=1.1; extra == "dev"
+Requires-Dist: torchvision>=0.15; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Provides-Extra: all
+Requires-Dist: torchtsetlin[dev,docs,sklearn,vision,viz]; extra == "all"
+Dynamic: license-file
+
+# torchtsetlin
+
+**GPU-enabled, PyTorch-native Tsetlin machines** — models, data preparation, training,
+evaluation, interpretation and visualisation in one package.
+
+[![CI](https://github.com/vlbthambawita/torchtsetlin/actions/workflows/ci.yml/badge.svg)](https://github.com/vlbthambawita/torchtsetlin/actions)
+[![docs](https://img.shields.io/badge/docs-mkdocs--material-blue)](https://vlbthambawita.github.io/torchtsetlin/)
+[![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+A [Tsetlin machine](https://tsetlinmachine.org) learns propositional rules
+(`IF x0 AND NOT x1 THEN class 1`) with teams of learning automata instead of gradients.
+`torchtsetlin` implements the family as ordinary `torch.nn.Module`s: the automata live in
+tensors, so a model moves between CPU and GPU with `.to(device)`, is saved with
+`state_dict()`, and learns from mini-batches with a single `model.update(x, y)` call.
+
+```python
+import torchtsetlin as tt
+
+x_train, y_train = tt.data.make_noisy_xor(5000, noise=0.4)          # Boolean features, int labels
+x_test, y_test = tt.data.make_noisy_xor(2000, noise=0.0, seed=1)
+
+model = tt.TsetlinMachine(n_features=12, n_classes=2, n_clauses=20, T=15, s=3.9).to("cuda")
+
+# PyTorch-style loop: update() is the analogue of loss.backward(); optimizer.step()
+for epoch in range(50):
+    model.train()
+    for i in range(0, 5000, 10):
+        model.update(x_train[i:i+10].cuda(), y_train[i:i+10].cuda())
+    model.eval()
+    acc = (model(x_test.cuda()).argmax(1) == y_test.cuda()).float().mean()
+
+print(model.rules()[:2])   # ['IF x0 AND NOT x1 THEN 1', 'IF x1 AND NOT x0 THEN 1']
+```
+
+Or with the built-in trainer:
+
+```python
+trainer = tt.Trainer(model, batch_size=10, callbacks=[tt.EarlyStopping(patience=20)])
+trainer.fit((x_train, y_train), epochs=100, val_data=(x_test, y_test))
+trainer.evaluate((x_test, y_test))          # {'accuracy': 0.99}
+```
+
+## Features
+
+| | |
+|---|---|
+| **Models** | `TsetlinMachine` (multi-class, optional integer clause weights), `CoalescedTsetlinMachine` (shared clauses; multi-class or multi-label), `RegressionTsetlinMachine`, `ConvTsetlinMachine` / `Conv1dTsetlinMachine` and convolutional coalesced / regression variants |
+| **Learning** | vote margin `T`, specificity `s`, memory depth, boosted true-positive feedback, clause-size constraint, drop-clause / drop-literal, focused negative sampling, **batched** (GPU-friendly) or **exact sequential** feedback |
+| **Data** | thermometer, one-hot, bit-plane, adaptive-threshold, colour-thermometer and hypervector encoders; synthetic datasets; torchvision helpers |
+| **Training** | `Trainer` for tensors / `Dataset` / `DataLoader`, callbacks (early stopping, checkpoints, CSV logs, hyper-parameter schedules), `History` |
+| **Evaluation** | accuracy, confusion matrix, precision/recall/F1, regression and multi-label metrics, calibration, trustworthiness curves |
+| **Interpretation** | rule extraction, clause activity/precision, closed-form global & local feature importance, per-example explanations |
+| **Visualisation** | memory plots, automata heat-maps, convolutional clause patches, confusion matrices, vote distributions |
+
+## Installation
+
+```bash
+pip install torch            # pick the CUDA/CPU build from pytorch.org
+pip install torchtsetlin     # + optional extras: [viz] [vision] [sklearn] [docs] [all]
+```
+
+From source: `pip install -e ".[dev]"`, then `pytest` and `mkdocs serve`.
+
+## How learning works (in one paragraph)
+
+Each clause is an AND of literals (`x_k` or `NOT x_k`); every (clause, literal) pair has a
+Tsetlin automaton whose integer state decides whether the literal is *included*. For a
+training example, clauses of the true class receive **Type I** feedback (memorise the
+example's True literals, forget the rest) and clauses of a random other class receive
+**Type II** feedback (add a False literal so the clause stops matching), each with a
+probability controlled by the vote margin `T`. `torchtsetlin` evaluates a mini-batch with one
+matrix product, counts the feedback events per (clause, literal) with another, and turns the
+counts into binomial state transitions — the whole update is a handful of tensor ops. See the
+[concept pages](https://vlbthambawita.github.io/torchtsetlin/concepts/tsetlin-machine/) for
+details and references.
+
+## Documentation
+
+* Getting started, concepts, guides, examples and the full API reference:
+  <https://vlbthambawita.github.io/torchtsetlin/> (or `mkdocs serve` locally).
+* Runnable scripts in [`examples/`](examples): Noisy XOR, MNIST (flat and convolutional),
+  tabular data with thermometer encoding, regression.
+
+## Citation
+
+If you use torchtsetlin in research, please cite the Tsetlin machine papers whose algorithms
+you rely on (see the documentation) and this package:
+
+```bibtex
+@software{torchtsetlin,
+  author = {Thambawita, Vajira},
+  title  = {torchtsetlin: GPU-enabled, PyTorch-native Tsetlin machines},
+  year   = {2026},
+  url    = {https://github.com/vlbthambawita/torchtsetlin}
+}
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

torchtsetlin-0.1.0/README.md

@@ -0,0 +1,100 @@
+# torchtsetlin
+
+**GPU-enabled, PyTorch-native Tsetlin machines** — models, data preparation, training,
+evaluation, interpretation and visualisation in one package.
+
+[![CI](https://github.com/vlbthambawita/torchtsetlin/actions/workflows/ci.yml/badge.svg)](https://github.com/vlbthambawita/torchtsetlin/actions)
+[![docs](https://img.shields.io/badge/docs-mkdocs--material-blue)](https://vlbthambawita.github.io/torchtsetlin/)
+[![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+A [Tsetlin machine](https://tsetlinmachine.org) learns propositional rules
+(`IF x0 AND NOT x1 THEN class 1`) with teams of learning automata instead of gradients.
+`torchtsetlin` implements the family as ordinary `torch.nn.Module`s: the automata live in
+tensors, so a model moves between CPU and GPU with `.to(device)`, is saved with
+`state_dict()`, and learns from mini-batches with a single `model.update(x, y)` call.
+
+```python
+import torchtsetlin as tt
+
+x_train, y_train = tt.data.make_noisy_xor(5000, noise=0.4)          # Boolean features, int labels
+x_test, y_test = tt.data.make_noisy_xor(2000, noise=0.0, seed=1)
+
+model = tt.TsetlinMachine(n_features=12, n_classes=2, n_clauses=20, T=15, s=3.9).to("cuda")
+
+# PyTorch-style loop: update() is the analogue of loss.backward(); optimizer.step()
+for epoch in range(50):
+    model.train()
+    for i in range(0, 5000, 10):
+        model.update(x_train[i:i+10].cuda(), y_train[i:i+10].cuda())
+    model.eval()
+    acc = (model(x_test.cuda()).argmax(1) == y_test.cuda()).float().mean()
+
+print(model.rules()[:2])   # ['IF x0 AND NOT x1 THEN 1', 'IF x1 AND NOT x0 THEN 1']
+```
+
+Or with the built-in trainer:
+
+```python
+trainer = tt.Trainer(model, batch_size=10, callbacks=[tt.EarlyStopping(patience=20)])
+trainer.fit((x_train, y_train), epochs=100, val_data=(x_test, y_test))
+trainer.evaluate((x_test, y_test))          # {'accuracy': 0.99}
+```
+
+## Features
+
+| | |
+|---|---|
+| **Models** | `TsetlinMachine` (multi-class, optional integer clause weights), `CoalescedTsetlinMachine` (shared clauses; multi-class or multi-label), `RegressionTsetlinMachine`, `ConvTsetlinMachine` / `Conv1dTsetlinMachine` and convolutional coalesced / regression variants |
+| **Learning** | vote margin `T`, specificity `s`, memory depth, boosted true-positive feedback, clause-size constraint, drop-clause / drop-literal, focused negative sampling, **batched** (GPU-friendly) or **exact sequential** feedback |
+| **Data** | thermometer, one-hot, bit-plane, adaptive-threshold, colour-thermometer and hypervector encoders; synthetic datasets; torchvision helpers |
+| **Training** | `Trainer` for tensors / `Dataset` / `DataLoader`, callbacks (early stopping, checkpoints, CSV logs, hyper-parameter schedules), `History` |
+| **Evaluation** | accuracy, confusion matrix, precision/recall/F1, regression and multi-label metrics, calibration, trustworthiness curves |
+| **Interpretation** | rule extraction, clause activity/precision, closed-form global & local feature importance, per-example explanations |
+| **Visualisation** | memory plots, automata heat-maps, convolutional clause patches, confusion matrices, vote distributions |
+
+## Installation
+
+```bash
+pip install torch            # pick the CUDA/CPU build from pytorch.org
+pip install torchtsetlin     # + optional extras: [viz] [vision] [sklearn] [docs] [all]
+```
+
+From source: `pip install -e ".[dev]"`, then `pytest` and `mkdocs serve`.
+
+## How learning works (in one paragraph)
+
+Each clause is an AND of literals (`x_k` or `NOT x_k`); every (clause, literal) pair has a
+Tsetlin automaton whose integer state decides whether the literal is *included*. For a
+training example, clauses of the true class receive **Type I** feedback (memorise the
+example's True literals, forget the rest) and clauses of a random other class receive
+**Type II** feedback (add a False literal so the clause stops matching), each with a
+probability controlled by the vote margin `T`. `torchtsetlin` evaluates a mini-batch with one
+matrix product, counts the feedback events per (clause, literal) with another, and turns the
+counts into binomial state transitions — the whole update is a handful of tensor ops. See the
+[concept pages](https://vlbthambawita.github.io/torchtsetlin/concepts/tsetlin-machine/) for
+details and references.
+
+## Documentation
+
+* Getting started, concepts, guides, examples and the full API reference:
+  <https://vlbthambawita.github.io/torchtsetlin/> (or `mkdocs serve` locally).
+* Runnable scripts in [`examples/`](examples): Noisy XOR, MNIST (flat and convolutional),
+  tabular data with thermometer encoding, regression.
+
+## Citation
+
+If you use torchtsetlin in research, please cite the Tsetlin machine papers whose algorithms
+you rely on (see the documentation) and this package:
+
+```bibtex
+@software{torchtsetlin,
+  author = {Thambawita, Vajira},
+  title  = {torchtsetlin: GPU-enabled, PyTorch-native Tsetlin machines},
+  year   = {2026},
+  url    = {https://github.com/vlbthambawita/torchtsetlin}
+}
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

torchtsetlin-0.1.0/pyproject.toml

@@ -0,0 +1,83 @@
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "torchtsetlin"
+version = "0.1.0"
+description = "GPU-enabled, PyTorch-native Tsetlin Machine framework: models, data preparation, training, evaluation, interpretation and visualization."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Vajira Thambawita", email = "vajira@simula.no" }]
+keywords = ["tsetlin machine", "pytorch", "interpretable machine learning", "logic-based learning", "gpu"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+  "torch>=2.0",
+  "numpy>=1.22",
+]
+
+[project.optional-dependencies]
+viz = ["matplotlib>=3.5"]
+vision = ["torchvision>=0.15"]
+sklearn = ["scikit-learn>=1.1"]
+docs = [
+  "mkdocs>=1.5",
+  "mkdocs-material>=9.4",
+  "mkdocstrings[python]>=0.24",
+  "mkdocs-autorefs>=0.5",
+]
+dev = [
+  "pytest>=7",
+  "pytest-timeout",
+  "matplotlib>=3.5",
+  "scikit-learn>=1.1",
+  "torchvision>=0.15",
+  "ruff",
+  "build",
+  "twine",
+]
+all = ["torchtsetlin[viz,vision,sklearn,docs,dev]"]
+
+[project.urls]
+Homepage = "https://github.com/vlbthambawita/torchtsetlin"
+Documentation = "https://vlbthambawita.github.io/torchtsetlin/"
+Repository = "https://github.com/vlbthambawita/torchtsetlin"
+Issues = "https://github.com/vlbthambawita/torchtsetlin/issues"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+torchtsetlin = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"
+timeout = 600
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W", "B", "UP"]
+# UP006/UP007/UP035/UP045: keep typing.Optional/List/... for Python 3.9 runtime compatibility.
+ignore = ["E501", "B028", "UP006", "UP007", "UP035", "UP045", "E731", "B905"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["torchtsetlin"]

torchtsetlin-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

torchtsetlin-0.1.0/src/torchtsetlin/__init__.py

@@ -0,0 +1,73 @@
+"""torchtsetlin — GPU-enabled, PyTorch-native Tsetlin machines.
+
+Quick start::
+
+    import torchtsetlin as tt
+
+    model = tt.TsetlinMachine(n_features=12, n_classes=2, n_clauses=20, T=15, s=3.9).to("cuda")
+    for x, y in loader:                 # Boolean features, integer labels
+        model.update(x.cuda(), y.cuda())  # learn (Type I / Type II feedback)
+    pred = model.predict(x_test.cuda())  # argmax of the vote sums
+"""
+
+from . import data, functional, interpret, metrics, viz
+from .models import (
+    CoalescedTsetlinMachine,
+    Conv1dTsetlinMachine,
+    ConvCoalescedTsetlinMachine,
+    ConvRegressionTsetlinMachine,
+    ConvTsetlinMachine,
+    RegressionTsetlinMachine,
+    TsetlinMachine,
+    TsetlinMachineBase,
+)
+from .train import (
+    Callback,
+    CSVLogger,
+    EarlyStopping,
+    History,
+    HyperparameterSchedule,
+    LambdaCallback,
+    ModelCheckpoint,
+    ProgressLogger,
+    StateSummaryLogger,
+    Trainer,
+    evaluate,
+    predict,
+)
+from .utils import seed_everything
+
+__version__ = "0.1.0"
+__all__ = [
+    "__version__",
+    # sub-packages
+    "data",
+    "functional",
+    "interpret",
+    "metrics",
+    "viz",
+    # models
+    "TsetlinMachineBase",
+    "TsetlinMachine",
+    "CoalescedTsetlinMachine",
+    "RegressionTsetlinMachine",
+    "ConvTsetlinMachine",
+    "ConvCoalescedTsetlinMachine",
+    "ConvRegressionTsetlinMachine",
+    "Conv1dTsetlinMachine",
+    # training
+    "Trainer",
+    "evaluate",
+    "predict",
+    "History",
+    "Callback",
+    "EarlyStopping",
+    "ModelCheckpoint",
+    "CSVLogger",
+    "LambdaCallback",
+    "HyperparameterSchedule",
+    "ProgressLogger",
+    "StateSummaryLogger",
+    # utils
+    "seed_everything",
+]