Metadata-Version: 2.4
Name: idun
Version: 0.1.0
Summary: Tabular learners for the Apple silicon GPU (Metal): idun_gbm, idun_tabm and idun_realmlp, with CPU reference backends.
Keywords: gradient boosting,tabular,deep learning,TabM,RealMLP,Metal,Apple silicon,GPU
Author: Anton Shaniuk
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: <3.15,>=3.12
Requires-Dist: numpy<3,>=2.5
Requires-Dist: numba<0.69,>=0.68
Description-Content-Type: text/markdown

# idun

Tabular learning on the Apple silicon GPU. idun trains three learners on Metal, each with a CPU reference backend:

- **idun_gbm** (`idun.gbm`): histogram gradient boosting with LightGBM's model (depth-wise or leaf-wise trees,
  quantized gradients, categorical splits, seed bags). Its CPU and Metal backends build the same model, bit for bit.
- **idun_tabm** (`idun.tabm`): TabM (Gorishniy et al., ICLR 2025), a parameter-efficient ensemble of MLPs.
- **idun_realmlp** (`idun.realmlp`): RealMLP-TD (Holzmüller et al., NeurIPS 2024).

Every fit is deterministic: the same data, parameters and seed give the same bits, run after run (the networks on the
same GPU). The estimators follow scikit-learn's conventions without depending on it.

idun is in alpha (0.1): the interfaces may still change.

## Install

```bash
pip install idun            # Apple silicon with macOS 15 or later: the Metal wheel; elsewhere the CPU-only wheel
pip install idun-numerai    # the Numerai port
```

Python 3.12–3.14; the only dependencies are NumPy and numba. Metal needs an Apple silicon Mac (M1 or newer) with
macOS 15 or later. On Linux and Intel Macs the same package installs without the Metal library and runs the CPU
backends; asking for Metal there raises `idun.errors.BackendUnavailableError` rather than falling back.

## Quick start

```python
import idun
from idun.gbm import GBMRegressor
from idun.realmlp import RealMLPRegressor
from idun.tabm import TabMClassifier

gbm = GBMRegressor(num_trees=300, learning_rate=0.05).fit(X_train, y_train)
pred = gbm.predict(X_test)
cpu = GBMRegressor(num_trees=300, learning_rate=0.05, backend="cpu").fit(X_train, y_train)  # the same trees

clf = TabMClassifier(categorical=["sector"]).fit(X_train, labels)  # any labels, two classes or more
proba = clf.predict_proba(X_test)

mlp = RealMLPRegressor(n_seeds=4).fit(X_train, y_train)  # a bag of four seeds; predicts their mean

gbm.save("gbm.idun")
same = idun.load("gbm.idun")
```

`X` is a 2-D NumPy array, a pandas DataFrame or an Arrow table; missing values are allowed. The backend is `"metal"`
by default; pass `backend="cpu"` (idun_gbm) or `backend="reference"` (the networks' float64 reference) to run on the
CPU. Nothing switches backends behind your back.

Below the estimators: `idun.Dataset` bins a table once for reuse; the functional layer (`idun.gbm.train`,
`idun.tabm.train_tabm`, `idun.realmlp.train_realmlp`, seed bags through `train_seeds` and `predict_mean`) trains on
binned data or on `idun.data.PackedDataset`, a memory-mapped, date-sorted panel for data larger than memory, which
Metal reads without a copy. The docstrings document every public name.

## How it compares

On five OpenML tasks on an Apple M1 (8 GB): idun_gbm's RMSE is within 3 % of the median of LightGBM, XGBoost and
scikit-learn's HistGradientBoosting at the same nominal settings; idun_tabm and idun_realmlp are within 2 % of their
reference implementations (the `tabm` package and pytabkit on Torch's MPS device) on every task and better on most, and
idun_tabm fits in 0.45 of the reference's time.

## Licence

Apache-2.0. The NOTICE file lists the work idun builds on, including MLX's Steel GEMM (MIT), whose structure the
networks' GEMM kernel adapts.
