# Equivalence summary

Every comparison below is a byte compare of the outputs: every predicted value as raw doubles (or at 17
significant digits in printed output). "same" means byte-identical between the official LightGBM 4.7.0 wheel and
the TAKT library: the free package's library and the full version's library, both as delivered.

## Equivalence matrix (`tools/eqmatrix.py`): 4,497 prediction cases, 1,060,559,499 values

- **Models:** 23, trained on public data: LightGBM's own examples (regression, binary, 5-class multiclass and
  one-vs-all, lambdarank and rank_xendcg), scikit-learn's bundled sets (DART on breast cancer, random forest on
  digits, linear trees on diabetes), California housing (1,024 leaves; poisson, tweedie, gamma, huber, quantile,
  cross-entropy and cross-entropy-lambda objectives; 30% NaN with and without `use_missing`; 30% zeros with
  `zero_as_missing`), OpenML adult and credit-g (categorical) and kick (categorical- and missing-heavy).
- **Inputs:** each model's test split plus adversarial rows: NaN, ±inf, −0.0, subnormals, values at ±1e-35 and
  their float neighbours, values exactly on and next to every split threshold, out-of-range, negative and
  non-integer categories.
- **Input forms:** numpy float64 and float32 in C and Fortran order, CSR float64 and float32, CSC float64, pandas,
  pyarrow; the row-pointer C API (`LGBM_BoosterPredictForMats`) separately.
- **Prediction types:** normal, raw score, leaf index, SHAP contributions.
- **Iteration ranges:** all trees, the first k, a window [s, s+k).
- **Threads:** 1 and 4.
- **Also:** prediction early stopping; repeated calls in the pattern of permutation importance and partial
  dependence; models changed in memory between calls
  (`set_leaf_output`, `rollback_one_iter`, `update`, `refit`, `model_from_string`).

| Library | AMD Zen 3 (Ubuntu 24.04, glibc 2.39) | AMD Zen 4 (Debian 13, glibc 2.41) |
|---|---|---|
| full version | 4,497 cases same, 0 of 1,060,559,499 values differ | same, 0 differ |
| free package | same, 0 differ | same, 0 differ |
| free package, `TAKT_LGBM_CACHE_MB=0` | same, 0 differ | — |

## LightGBM's own test suites

- C++ test suite (LightGBM 4.7.0, `testlightgbm`): 34 of 34 pass with the unmodified source, the full version and
  the free package.
- Python test suite (`tests/python_package_test`): 1,689 passed, 19 skipped with the official wheel and with both
  TAKT wheels; the same 4 graphviz plotting tests fail with all three on a machine without the `dot` binary.

## Concurrency and long runs

- `tools/concurrency.py`: 5 shared boosters, 246 prediction tasks (the original data, permuted features,
  what-if scenarios, float32; normal, raw, leaf), 8–16 Python threads, shuffled order in every round, compared with
  the official wheel's sequential results; also with `TAKT_LGBM_CACHE_MB=16`. Full version and free package: 0
  mismatches.
- Soak runs with `TAKT_LGBM_VERIFY=1` (every accelerated call recomputed with LightGBM's original code and
  compared): a mix of analyses, batch prediction, iteration ranges, mutable boosters and new shapes on several
  threads. Full version: four runs, 10.5 hours in total on both machines, 2,427,751 calls, 0 differences. Free
  package: 30 minutes, 125,380 calls, 0 differences, 0 errors.

## ABI

The TAKT libraries export exactly the same 6,469 dynamic symbols as the official `lib_lightgbm.so`, need the same
shared libraries (libstdc++, libgomp, libm, libc and the others the official one needs) and no symbol versions
newer than the official one (glibc 2.27 at most). Built with the official compiler (gcc 12.2.1, gcc-toolset-12) in the manylinux_2_28 image with the official
build configuration.

## Note on bit-identity across systems

Some of LightGBM's outputs (probabilities, for example) pass through the system maths library, and numpy's own
results can depend on the CPU it dispatches to. The TAKT library reproduces the official library's output on the
same system; compare the two on the same machine.