pylignum 0.2.0__tar.gz

pylignum-0.2.0/.gitignore

@@ -0,0 +1,136 @@
+.DS_Store
+.AppleDouble
+.LSOverride
+Icon
+._*
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk
+
+/build*/
+bin/
+obj/
+out/
+target/
+*.o
+*.obj
+*.so
+*.dylib
+*.dll
+*.a
+*.lib
+*.gch
+*.pch
+*.ilk
+*.suo
+*.pdb
+*.idb
+*.exp
+*.exe
+*.app
+*.i
+*.s
+*.bc
+
+CMakeCache.txt
+CMakeFiles/
+CMakeScripts/
+cmake_install.cmake
+install_manifest.txt
+compile_commands.json
+CTestTestfile.cmake
+_deps/
+*.cmake
+!.gitkeep
+
+.vs/
+*.vcxproj
+*.vcxproj.filters
+*.vcxproj.user
+*.sln
+*.sln.docstates
+*.opensdf
+*.sdf
+*.tlog
+
+.vscode/
+*.code-workspace
+.idea/
+*.swp
+*.swo
+*.swn
+*.njsproj
+
+*.pyc
+*.pyo
+*.pyd
+__pycache__/
+.pytest_cache/
+.tox/
+.coverage
+.coverage.*
+nosetests.xml
+coverage.xml
+*.egg-info/
+*.egg
+.eggs/
+dist/
+venv/
+env/
+.env/
+venv*/
+env*/
+
+compile_commands.json
+.cache/
+.clang-format
+.clangd
+
+*.json
+!model
+*.model
+*.xgb
+*.lgb
+*.txt
+*.csv
+*.tsv
+*.dat
+*.out
+*.log
+*.log.*
+*.pid
+*.bin
+
+test_lignum
+!CMakeLists.txt
+site/
+.venv/
+*.npy
+benchmarks/bench_model_*
+benchmarks/.cache/
+
+# Benchmark scripts write each run to benchmarks/results/; the reports worth keeping are moved into
+# its folders (one per machine and architecture), raw .md / .json / .txt included.
+/benchmarks/results/*
+!/benchmarks/results/*/
+!/benchmarks/results/README.md
+!/benchmarks/results/*/**/*.json
+!/benchmarks/results/*/**/*.txt
+
+# The docs site (Starlight) needs its npm and TypeScript files.
+!docs/package.json
+!docs/package-lock.json
+!docs/tsconfig.json
+
+# Local working notes (roadmap with measurements, session handoff); not part of the project.
+TASKS.md
+HANDOFF.md

pylignum-0.2.0/ARCHITECTURE.md

@@ -0,0 +1,170 @@
+# Architecture
+
+## Pipeline
+
+```
+model file ──parser──▶ TempBinNode forest (IR) ──Builder──▶ Model ──predict──▶ scores
+                       src/ir.hpp                 src/builder.cpp   src/model.cpp
+                                                      │
+                                        Model::save ──┼──▶ .bin ──mmap──▶ Model (zero-copy)
+                                                      │                   src/io.cpp
+                                     compile_forest ──┴──▶ C ──cc──▶ shared library (src/compiled.cpp)
+```
+
+- **Parsers** (`src/parsers/`) read LightGBM `model.txt` (`lightgbm_text.cpp`) and `dump_model()`
+  JSON, XGBoost JSON and UBJSON (`ubjson.cpp` rewrites it as JSON) into a library-neutral binary
+  tree. `src/load.cpp` recognises the format from the file's first bytes. All library-specific
+  semantics are resolved here (see "Split semantics").
+- **Builder** packs two tree levels into one 64-byte `KNode` and stores leaves in a separate array.
+- **Model** is a view: raw pointers to nodes/offsets/leaves plus a `shared_ptr<Data>` owning the
+  memory, which is either `VectorData` (built from a model file) or `MmapData` (binary file).
+
+## KNode
+
+```
+struct alignas(64) KNode {          // one cache line = two levels of a binary tree
+    double   thresholds[4];         // slot 0: root split, slot 1: left child, slot 2: right child, [3] unused
+    int32_t  children[4];           // four grandchildren; negative = leaf index (-k-1)
+    uint16_t features[4];
+    uint8_t  dirs[4];               // bit0: missing goes right, bit1: zero is missing (LightGBM)
+    uint8_t  kinds[4];              // slot_kind: Numeric, CatMask, CatRange, CatBitset
+};
+```
+
+If a child of the root is a leaf, both of its grandchild pointers reference that leaf and the slot's
+comparison is ignored.
+
+A categorical slot keeps its category set in the 64 bits of `thresholds[slot]`: a mask when every
+category is below 64, `[first, last - first]` when the set is contiguous, otherwise
+`[offset, words]` into `Model::cat_bitsets` (word 0 is always zero, so branch-free lookups of
+non-bitset slots read a valid address).
+
+## Kernel (src/model.cpp)
+
+- `Kernel<Acc, ZeroMissing>` predicts a block of rows: trees in tiles of `T_BLOCK` so a tile of
+  trees stays in cache while the block walks it. Strategies only decide how blocks are scheduled:
+  - `Serial`: blocks of `N_BLOCK` on the calling thread, no OpenMP region.
+  - `Rows`: OpenMP over blocks sized `n_samples / (2 * threads)`, rounded to 4, capped at `N_BLOCK`.
+  - `Auto`: `Serial` below 8 rows or with one thread, `Rows` otherwise (thresholds from
+    `benchmarks/batch_sweep.py`).
+- Four rows are interleaved to hide memory latency; leftover rows (fewer than four, e.g. a single
+  row) interleave four trees instead. Leaves are still added in tree order.
+- Per KNode the three comparisons are evaluated speculatively and the child is selected with
+  `children[(r << 1) | (r ? c : l)]`, which removes the dependency between the two levels.
+- Template parameters: accumulator type (`double` for LightGBM, `float` for XGBoost) and `Mixed`
+  (the model has trees that are not plain numeric). With `Mixed`, the traversal is specialised per
+  tree from `tree_kinds[]` (bits `ZeroMissing`, `Categorical`); otherwise there is no per-tree branch.
+- In categorical trees each slot branches on its kind (structural, predictable) and the categorical
+  test itself is branch-free (`cat_dir`), because NaN/range/category branches depend on the data.
+- Two step variants: branch-free (all three comparisons, default for numeric trees in 4-row walks) and
+  branchy (branch on the root comparison, evaluate only the taken child). Branchy is used for leftover
+  rows (fewer than four, e.g. one row) everywhere and for 4-row walks of categorical trees except on
+  Apple (`LIGNUM_BRANCHY_TAIL`, `LIGNUM_BRANCHY_CAT`); choices measured on x86-64, aarch64 and M4. The traversal (`step`, `walk4`, `walk1`) is force-inlined and works
+  on local copies of the model pointers; going through `Model&` members cost ~7-13%.
+- Leaves are added to a running sum loaded from `out_preds[i]`, in model order, so floating point
+  results are identical to the source library.
+- Multiclass (`Multi` template parameter): row i's K outputs live in `out[i*K .. i*K+K)`; each tree
+  adds its leaf to `out[i*K + tree_outputs[t]]`, still in model order. Softmax runs per row after the
+  last tile. XGBoost `multi:softmax` (argmax) is computed from raw margins in a temporary buffer,
+  because narrowing K columns to one in place would race between threads.
+
+## Binned kernel (src/binned.*, default)
+
+Built from the KNode form at load time (or mapped from the binary file):
+
+- Every used feature becomes a *dense feature* with a 16-bit code per row, computed once per row
+  block before the tree walk:
+  - numeric: `bin(x)` = number of the feature's split thresholds `t` with `t <= x` (branch-free
+    binary search over sorted unique thresholds), so `x >= t_k` ⇔ `bin(x) >= k + 1` exactly;
+  - categorical: the integer category under LightGBM or XGBoost rules; NaN and invalid values get
+    codes that are never in a set;
+  - NaN: `0xFFFF`.
+- `BNode` (64 bytes) holds **three** tree levels: 7 slots (16-bit threshold or decision-bit index,
+  16-bit dense feature) and 8 subtrees. The walk compares only along the path (3 dependent integer
+  comparisons per node); evaluating all 7 speculatively was 2x slower.
+- NaN without a branch: `0xFFFF` is above every threshold (goes right); slots whose NaN goes left
+  add 1 to the code, which wraps `0xFFFF` to 0.
+- Categorical splits are decided before the walk: per categorical feature a table maps each
+  category to the decision bits of all of that feature's slots in the model; each row copies one
+  table row per feature into its decision buffer, and a categorical slot reads one bit from L1.
+- LightGBM zero-as-missing: both edges of the zero band are added as cuts, so the band is one bin;
+  flagged slots override the comparison for that bin (branch-free).
+- Rows outside the 4-row groups (including a single row) walk four trees at once.
+- Results are identical to the KNode kernel, which remains for `load(..., binned=False)` and models
+  the binned form cannot represent; every Python test runs with both kernels
+  (`tests/python/conftest.py`).
+
+## Split semantics
+
+Every split is normalised to: **go right ⇔ `isnan(x) ? default_right : x >= threshold`**.
+
+| Library | Native rule | Translation in the parser |
+|---|---|---|
+| LightGBM | right iff `z(x) > t`, where dense input with `\|x\| ≤ 1e-35f` becomes 0 | `threshold = nextafter(t, +inf)`; for `t` in the zero band the threshold moves to the band edge |
+| LightGBM `missing_type=NaN` | NaN → `default_left` | direct |
+| LightGBM `missing_type=None` | NaN → 0.0, compared normally | `default_right = (0 >= threshold)` |
+| LightGBM `missing_type=Zero` | NaN → 0.0, and 0 is missing → `default_left` | direct; nodes where this differs from the natural direction of 0 get `ZeroIsMissing` |
+| XGBoost | left iff `float(x) < t` (t is float32), NaN → `default_left` | threshold = smallest double that rounds to ≥ `t` in float32 |
+| LightGBM categorical (`==`) | NaN → right; x ≤ -1 → right; else `int(x)` in set → left | categorical slot (see KNode) |
+| XGBoost categorical (`split_type` 1) | NaN → `default_left`; `c = int(float32(x))`; c < 0 or c ≥ 2^24 → left; c in `categories` → right | categorical slot with `dir_bits::XGBoostCategory` |
+
+XGBoost also accumulates and transforms in float32, and converts `base_score` to margin space with
+float32 `log`/logit (`binary:logitraw` uses `base_score` as is; multiclass models store a vector of
+per-class base scores already in margin space). XGBoost's softmax takes the max and `expf` in float,
+sums in double and divides by `float(sum)`; LightGBM's softmax is all double.
+
+Verified bit-exact by `tests/python/test_parity.py` on inputs with NaNs, zeros, values in the zero
+band and values placed exactly on every split threshold.
+
+## Binary format (version 0.6)
+
+64-byte header (`magic "LIGNUM"`, version, transform, flags {float32, special trees}, sigmoid,
+n_features, n_outputs, n_cat_words, section sizes), followed by 64-byte aligned sections: nodes, tree offsets,
+leaves, tree kinds, base scores, tree outputs (multiclass only), categorical bitsets and, when the
+`Binned` flag is set, a `BinnedFileHeader` followed by the binned kernel's sections (nodes, roots,
+tree kinds, dense features, cuts, zero bins, categorical decision tables).
+Loading validates the version and the file size, maps the file read-only and then checks every
+stored index (`src/validate.cpp`): children must point strictly forward (so a walk always ends),
+leaves, features, categorical bitsets and decision tables must be in range. This takes 0.15-0.64 ms
+for the benchmark models. `tests/cpp/test_fuzz.cpp` corrupts files at random and runs under
+ASan/UBSan in CI. Older versions are rejected; re-export from JSON.
+
+## Compiled mode (src/compiled.*)
+
+`compile_forest` generates C from the `BinnedForest`: `lignum_bin` (numeric binning specialised per
+feature: constant cut tables, unrolled binary search, linear count for <= 8 cuts) and one
+`lignum_block_<b>` per block of 16 trees. A block walks a chunk of rows (~2 MB of codes, decision bits
+and sums, `LIGNUM_COMPILED_CHUNK_KB`) before the next block runs, adding leaves (from a per-block
+table) in model order. The `LIGNUM_COMPILED_LOCALS` most used features of a block are read once per
+row into locals (int16 codes: NaN = -1, so the NaN-left comparison needs no wrap), kept in registers
+by an empty asm; leaf pairs become selects. Categorical decision bits, threads and transforms stay in
+the kernel (`BinnedKernel` receives the compiled forest; `Model::compiled_min_rows` sends small
+batches to the interpreter). Sources are compiled in parallel (gcc/clang, or one `cl /LD /MP`
+command), linked, cached by source hash and loaded with dlopen / LoadLibrary. The library exports
+`lignum_abi` and `lignum_fingerprint` (FNV-1a of trees, cuts, leaves, outputs, precision), checked by
+`load_compiled`.
+
+## Arrow input (src/arrow.cpp, src/columns.hpp)
+
+`predict_arrow` takes a record batch through the Arrow C Data Interface (`include/lignum/arrow.h`).
+With the binned kernel, an `ArrowColumns` `ColumnSource` lets `BinnedKernel` bin each feature column
+of a chunk straight from the buffers (typed conversion into a small contiguous buffer, then one
+binning loop); the direct kernel gets row-major blocks converted in L1-sized tiles. Values convert
+exactly like numpy's `astype(float64)`; nulls (column or batch) are NaN; dictionary columns give
+their indices.
+
+## APIs
+
+- C++: `include/lignum/lignum.hpp` (`lignum::load`, `predict_arrow`, `predict_arrow_stream`) and
+  `model.hpp` (`Model::predict`, `Strategy`).
+- C: `include/lignum/c_api.h`, built as the shared `liblignum` (`LIGNUM_BUILD_C_LIBRARY`, on by
+  default outside Python builds): loading, prediction (row-major and Arrow), compiled mode. Only
+  `Lignum*` symbols are exported; errors are reported through return codes and a thread-local
+  `LignumGetLastError()`.
+- Python: `python/bindings.cpp` (nanobind, abi3 for Python >= 3.12) + `python/lignum/__init__.py`,
+  published as `pylignum`.
+
+## Known limitations
+
+No multi-target / vector-leaf models, no LightGBM linear trees or random forests (rejected at load
+time).

pylignum-0.2.0/CLAUDE.md

@@ -0,0 +1,72 @@
+# Lignum — rules for working in this repo
+
+Lignum is a production inference engine for LightGBM/XGBoost models (C++20 core, Python bindings).
+Read [ARCHITECTURE.md](ARCHITECTURE.md) before touching the kernel or parsers. The roadmap with past measurements
+(`TASKS.md`) and the session handoff (`HANDOFF.md`) are local, untracked notes: read them when present.
+Published on PyPI as `pylignum`, imported as `lignum`.
+
+## Non-negotiable rules
+
+1. **Predictions are bit-identical to the source library.** Raw scores and transformed outputs must
+   equal `booster.predict(...)` exactly (`np.testing.assert_array_equal`, never `allclose`).
+   - Sum trees in model order, continuing from `out_preds[i]`; never pre-sum a block of trees.
+   - No `-ffast-math`, `-ffp-contract=fast`, `/fp:fast`.
+   - Library-specific semantics (thresholds, missing values, float32) are resolved in the parser,
+     not in the kernel. XGBoost uses float32 for comparisons, accumulation and transforms.
+2. **No performance regressions.** Any kernel change needs a before/after benchmark against the
+   previous commit (see "Benchmarking"). Put the numbers in the commit message.
+3. **No hand-written SIMD** unless a benchmark shows a clear win on both x86-64 and arm64.
+4. `KNode` is exactly 64 bytes (`static_assert`). Every union member must be naturally aligned per slot.
+5. The core is a library: no Kafka/network code, no dependencies beyond vendored simdjson and OpenMP.
+6. C++20. Code, comments, commit messages and repo docs in English.
+7. Every feature ships with tests: GoogleTest in `tests/cpp` for logic, pytest parity tests in
+   `tests/python` against real LightGBM/XGBoost models (include NaN, zeros, values exactly on thresholds).
+   Every Python test runs three times (`tests/python/conftest.py`): the binned kernel (default), the
+   KNode walk (`binned=False` / unsupported models) and compiled trees (`compile()`, blocks of 3 trees);
+   kernel and code-generator changes must keep all three exact. Parser changes also get fuzz tests
+   (`tests/cpp/test_fuzz.cpp`) and must reject corrupted files without crashing on Windows' 1 MB stack.
+8. Distributed builds never use `-march=native`/`-mcpu=native` (`LIGNUM_NATIVE` is for local benchmarks only).
+9. Kernel ideas are measured on x86-64 and aarch64 before they are kept: put compile flags in
+   `EXPERIMENT_CXX_FLAGS` of `.github/workflows/bench-lleaves.yml` and push; M4 alone has misled us
+   (categorical side table: faster on servers, slower on M4).
+10. Platforms: Linux, macOS and Windows (MSVC) for the core, the compiled mode and the wheels; CI
+    (`tests.yml`) tests all three. Don't add POSIX-only code without a Windows path.
+11. Releases: the version lives only in `python/lignum/__init__.py`. Wheels are built by
+    `.github/workflows/wheels.yml`; publishing is a manual run (`target=testpypi|pypi`, trusted
+    publishing, the `pypi` environment needs the owner's approval). A version can be uploaded once.
+    Pushes touching `src/`, `python/` or the build start a Wheels build: avoid pushing while a
+    publishing run is going.
+
+## Layout
+
+```
+include/lignum/   public API (lignum.hpp, model.hpp, c_api.h, arrow.h)
+src/              engine: parsers/ (LightGBM text/JSON, XGBoost JSON/UBJSON), ir.hpp, builder,
+                  model.cpp (kernels), binned.*, compiled.* (code generator), arrow.cpp, io.cpp (.bin)
+python/           nanobind bindings (bindings.cpp) + lignum package; python/README.md is the PyPI page
+tests/cpp         GoogleTest      tests/python   pytest parity tests (+ smoke.py for wheels)
+benchmarks/       bench.py, bench_arrow.py, cloud.sh (cloud server run); generated models/data gitignored
+docs/             Starlight (Astro) site; docs/scripts/api_reference.py writes the Python reference
+extern/simdjson   vendored (also used for exact number parsing in the text formats)
+```
+
+## Commands
+
+```bash
+make venv        # .venv with Python 3.12 via uv (lightgbm, xgboost, pytest, nanobind, ...)
+make py-build    # editable install of the package into .venv
+make test        # cpp-test + py-test
+make cpp-test    # cmake -DLIGNUM_BUILD_TESTS=ON, build, ctest
+cd docs && python scripts/api_reference.py && npm run build   # documentation site
+```
+
+macOS needs `brew install libomp`; CMake finds Homebrew's keg-only libomp automatically.
+
+## Benchmarking
+
+Compare against the previous state, not against memory:
+1. `git worktree add <scratch>/base <commit>` and install it into a separate venv.
+2. Run the same script on the same saved models and data with both venvs, at least twice.
+3. Report best and median for 1M rows and the median latency for 100 rows.
+4. For x86-64 / ARM numbers use `bench-lleaves.yml` (shared runners: compare engines within a job) or
+   `benchmarks/cloud.sh` on a dedicated cloud server.

pylignum-0.2.0/CMakeLists.txt

@@ -0,0 +1,165 @@
+cmake_minimum_required(VERSION 3.18...3.31)
+project(lignum LANGUAGES CXX)
+
+option(LIGNUM_BUILD_TESTS "Build the GoogleTest suite" OFF)
+option(LIGNUM_SANITIZE "Build with sanitizers (tests, not releases)" OFF)
+set(LIGNUM_SANITIZERS "address,undefined" CACHE STRING "Sanitizers for LIGNUM_SANITIZE (ASan hangs on some macOS versions: use undefined there)")
+option(LIGNUM_NATIVE "Tune for the build machine (-march/-mcpu=native). Never enable for distributed wheels." OFF)
+if(SKBUILD)
+    set(_lignum_c_default OFF)
+else()
+    set(_lignum_c_default ON)
+endif()
+option(LIGNUM_BUILD_C_LIBRARY "Build the shared library exposing the C API (include/lignum/c_api.h)" ${_lignum_c_default})
+
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_EXTENSIONS OFF)
+set(CMAKE_POSITION_INDEPENDENT_CODE ON)
+
+if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
+    set(CMAKE_BUILD_TYPE Release CACHE STRING "Build type" FORCE)
+endif()
+
+if(LIGNUM_SANITIZE AND NOT MSVC)
+    add_compile_options(-fsanitize=${LIGNUM_SANITIZERS} -fno-omit-frame-pointer -fno-sanitize-recover=all)
+    add_link_options(-fsanitize=${LIGNUM_SANITIZERS})
+endif()
+
+# ---------------------------------------------------------------------------
+# Core library
+# ---------------------------------------------------------------------------
+add_library(lignum STATIC
+    src/arrow.cpp
+    src/binned.cpp
+    src/builder.cpp
+    src/c_api.cpp
+    src/compiled.cpp
+    src/io.cpp
+    src/load.cpp
+    src/model.cpp
+    src/parsers/lightgbm.cpp
+    src/parsers/lightgbm_text.cpp
+    src/parsers/ubjson.cpp
+    src/parsers/xgboost.cpp
+    src/validate.cpp
+    extern/simdjson/simdjson.cpp
+)
+
+# Only the C API is exported from shared objects; C++ internals stay hidden. The static archive gets
+# its own file name: on Windows the shared library's import library is lignum.lib.
+set_target_properties(lignum PROPERTIES OUTPUT_NAME lignum_static CXX_VISIBILITY_PRESET hidden VISIBILITY_INLINES_HIDDEN ON)
+
+target_include_directories(lignum
+    PUBLIC  ${CMAKE_CURRENT_SOURCE_DIR}/include
+    PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src
+            ${CMAKE_CURRENT_SOURCE_DIR}/extern/simdjson
+)
+
+# Homebrew's libomp is keg-only, so AppleClang cannot find it without a hint.
+if(APPLE AND NOT OpenMP_ROOT AND NOT DEFINED ENV{OpenMP_ROOT})
+    foreach(prefix /opt/homebrew/opt/libomp /usr/local/opt/libomp)
+        if(EXISTS ${prefix}/include/omp.h)
+            set(OpenMP_ROOT ${prefix})
+            break()
+        endif()
+    endforeach()
+endif()
+
+target_link_libraries(lignum PRIVATE ${CMAKE_DL_LIBS})
+
+find_package(OpenMP)
+if(OpenMP_CXX_FOUND)
+    target_link_libraries(lignum PUBLIC OpenMP::OpenMP_CXX)
+else()
+    message(WARNING "OpenMP not found: lignum will predict single-threaded.")
+endif()
+
+# Results must match LightGBM/XGBoost bit for bit: no fast-math, no FMA contraction.
+if(MSVC)
+    target_compile_options(lignum PRIVATE /fp:precise)
+else()
+    target_compile_options(lignum PRIVATE -ffp-contract=off -fno-math-errno -funroll-loops)
+    if(LIGNUM_NATIVE)
+        if(APPLE AND CMAKE_SYSTEM_PROCESSOR MATCHES "arm64")
+            target_compile_options(lignum PRIVATE -mcpu=native)
+        else()
+            target_compile_options(lignum PRIVATE -march=native)
+        endif()
+    endif()
+endif()
+
+include(CheckIPOSupported)
+check_ipo_supported(RESULT LIGNUM_IPO_SUPPORTED OUTPUT _ipo_msg LANGUAGES CXX)
+if(LIGNUM_IPO_SUPPORTED)
+    set_property(TARGET lignum PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE)
+endif()
+
+# ---------------------------------------------------------------------------
+# Shared library with the C API
+# ---------------------------------------------------------------------------
+if(LIGNUM_BUILD_C_LIBRARY)
+    add_library(lignum_c SHARED src/c_api.cpp)
+    set_target_properties(lignum_c PROPERTIES OUTPUT_NAME lignum CXX_VISIBILITY_PRESET hidden VISIBILITY_INLINES_HIDDEN ON)
+    target_compile_definitions(lignum_c PRIVATE LIGNUM_EXPORTS PUBLIC LIGNUM_SHARED)
+    target_link_libraries(lignum_c PRIVATE lignum)
+    target_include_directories(lignum_c PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/include)
+
+    include(GNUInstallDirs)
+    install(TARGETS lignum_c LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR} ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
+            RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})
+    install(FILES include/lignum/c_api.h include/lignum/arrow.h DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/lignum)
+endif()
+
+# ---------------------------------------------------------------------------
+# Python extension (built by scikit-build-core)
+# ---------------------------------------------------------------------------
+if(SKBUILD)
+    # SKBUILD_SABI_COMPONENT is set when scikit-build-core builds an abi3 wheel (wheel.py-api).
+    find_package(Python 3.10 REQUIRED COMPONENTS Interpreter Development.Module ${SKBUILD_SABI_COMPONENT})
+    find_package(nanobind CONFIG REQUIRED)
+
+    # STABLE_ABI: one wheel for every Python >= 3.12 (ignored for older Pythons).
+    nanobind_add_module(_core STABLE_ABI python/bindings.cpp)
+    target_include_directories(_core PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src)
+    target_link_libraries(_core PRIVATE lignum)
+    install(TARGETS _core DESTINATION lignum)
+
+    # macOS wheels: LightGBM and XGBoost use Homebrew's libomp, and two copies of libomp in one
+    # process abort (OMP Error #15). So the extension looks for Homebrew's first and falls back to
+    # a copy shipped in the wheel (lignum/.dylibs), found through the same @rpath install name.
+    option(LIGNUM_BUNDLE_OPENMP "macOS: ship libomp in the wheel as a fallback for Homebrew's" OFF)
+    if(APPLE AND LIGNUM_BUNDLE_OPENMP AND OpenMP_CXX_FOUND)
+        set_target_properties(_core PROPERTIES
+            BUILD_WITH_INSTALL_RPATH ON
+            INSTALL_RPATH "/opt/homebrew/opt/libomp/lib;/usr/local/opt/libomp/lib;@loader_path/.dylibs")
+        find_library(LIGNUM_LIBOMP NAMES omp PATHS ${OpenMP_ROOT}/lib NO_DEFAULT_PATH REQUIRED)
+        get_filename_component(LIGNUM_LIBOMP_REAL ${LIGNUM_LIBOMP} REALPATH)
+        install(FILES ${LIGNUM_LIBOMP_REAL} DESTINATION lignum/.dylibs RENAME libomp.dylib)
+        # Reference libomp as @rpath/libomp.dylib (Homebrew's own install name is an absolute path).
+        add_custom_command(TARGET _core POST_BUILD
+            COMMAND install_name_tool -change ${LIGNUM_LIBOMP_REAL} @rpath/libomp.dylib $<TARGET_FILE:_core>
+            COMMAND install_name_tool -change ${LIGNUM_LIBOMP} @rpath/libomp.dylib $<TARGET_FILE:_core>
+            COMMAND install_name_tool -change /opt/homebrew/opt/libomp/lib/libomp.dylib @rpath/libomp.dylib $<TARGET_FILE:_core>
+            COMMAND install_name_tool -change /usr/local/opt/libomp/lib/libomp.dylib @rpath/libomp.dylib $<TARGET_FILE:_core>
+            VERBATIM)
+    endif()
+endif()
+
+# ---------------------------------------------------------------------------
+# Tests
+# ---------------------------------------------------------------------------
+if(LIGNUM_BUILD_TESTS)
+    include(FetchContent)
+    FetchContent_Declare(
+        googletest
+        URL https://github.com/google/googletest/archive/refs/tags/v1.17.0.tar.gz
+        DOWNLOAD_EXTRACT_TIMESTAMP TRUE
+    )
+    set(gtest_force_shared_crt ON CACHE BOOL "" FORCE)
+    set(INSTALL_GTEST OFF CACHE BOOL "" FORCE)
+    FetchContent_MakeAvailable(googletest)
+
+    enable_testing()
+    add_subdirectory(tests/cpp)
+endif()

pylignum-0.2.0/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2026 Kacper Piotrowski
+
+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.

pylignum-0.2.0/Makefile

@@ -0,0 +1,42 @@
+.PHONY: venv bench-deps py-build py-test cpp-build cpp-test test bench bench-quick docs clean
+
+PYTHON ?= .venv/bin/python
+CPP_BUILD_DIR ?= build/cpp
+
+venv:
+	uv venv --python 3.12 .venv
+	uv pip install --python $(PYTHON) numpy pandas scikit-learn lightgbm xgboost pytest nanobind scikit-build-core pyarrow ninja
+
+# Competitor engines for benchmarks/bench.py (lleaves 1.3 needs llvmlite < 0.45).
+bench-deps:
+	uv pip install --python $(PYTHON) treelite tl2cgen lleaves "llvmlite<0.45" onnxruntime onnxmltools onnxconverter-common
+
+py-build:
+	uv pip install --python $(PYTHON) --no-build-isolation -e .
+
+py-test: py-build
+	$(PYTHON) -m pytest tests/python -v --tb=short
+
+cpp-build:
+	cmake -S . -B $(CPP_BUILD_DIR) -DLIGNUM_BUILD_TESTS=ON
+	cmake --build $(CPP_BUILD_DIR) --parallel
+
+cpp-test: cpp-build
+	ctest --test-dir $(CPP_BUILD_DIR) --output-on-failure
+
+test: cpp-test py-test
+
+# Compares lignum with native LightGBM/XGBoost, TL2cgen, GTIL, lleaves and ONNX Runtime (see bench-deps).
+bench:
+	$(PYTHON) benchmarks/bench.py
+
+bench-quick:
+	$(PYTHON) benchmarks/bench.py --quick
+
+docs:
+	rm -rf site/
+	$(PYTHON) -m pip install mkdocs-material "mkdocstrings[python]"
+	$(PYTHON) -m mkdocs build
+
+clean:
+	rm -rf build/ .pytest_cache/ benchmarks/.cache site/