Environment:Interpretml Interpret Native Libebm Environment

Knowledge Sources	InterpretML Interpret build.sh _native.py
Domains	Infrastructure, Native_Compilation
Last Updated	2026-02-07 12:00 GMT

Overview

Cross-platform native C++ shared library (libebm) environment supporting Windows (.dll), Linux (.so), and macOS (.dylib) on x64 and ARM architectures.

Description

The libebm native library is the computational core of InterpretML. It implements the EBM boosting algorithm, feature discretization, interaction detection, score purification, and tensor manipulation in optimized C++. The library supports SIMD acceleration (AVX2, AVX-512) on x86_64 platforms and compiles for five platform targets: Linux x64, Linux ARM, Windows x64, macOS x64, and macOS ARM. The library is loaded at runtime via Python's `ctypes` module and communicates through a C-compatible bridge interface.

Usage

This environment is required for all EBM training and prediction operations. Any workflow that calls the native EBM library (boosting, bin construction, interaction detection, prediction) requires the appropriate platform-specific shared library to be available. The library is typically bundled with the pip/conda package, but must be compiled from source when installing via sdist or developing locally.

System Requirements

Category	Requirement	Notes
OS	Windows (x64), Linux (x64, ARM), macOS (x64, ARM)	Five platform targets supported
Architecture	64-bit required	32-bit not supported; checked via `struct.calcsize("P") * 8`
Compiler	C++17 compatible compiler	g++, clang++, or MSVC; build.sh handles detection
SIMD	AVX2 / AVX-512 (optional)	Auto-detected at runtime; falls back to scalar CPU

Dependencies

System Packages (Build from Source Only)

C/C++ compiler (g++ or clang++)
`apt-get` or `dnf` package manager (Linux)
CMake (implicit via build scripts)

Runtime

No runtime system dependencies beyond the shared library itself
Python `ctypes` module (standard library)

Credentials

No credentials are required.

Quick Install

# The native library is bundled with the pip package:
pip install interpret-core

# To build from source (development):
cd /path/to/interpret
./build.sh

# The built library will be in bld/lib/ as:
#   libebm.so (Linux), libebm.dll (Windows), libebm.dylib (macOS)

Code Evidence

Platform-specific library loading from `python/interpret-core/interpret/utils/_native.py:931-941`:

plat = platform.system()
if plat == "Windows":  # pragma: no cover
    extension = ".dll"
elif plat == "Linux":  # pragma: no cover
    extension = ".so"
elif plat == "Darwin":  # pragma: no cover
    extension = ".dylib"
else:
    msg = f"Unsupported platform {plat}"
    _log.error(msg)
    raise Exception(msg)

Architecture-specific binary selection from `python/interpret-core/interpret/utils/_native.py:970-979`:

if plat == "Linux" and machine == "x86_64" and is_64_bit:
    lib_file = "libebm_linux_x64"
elif plat == "Linux" and machine == "aarch64":
    lib_file = "libebm_linux_arm"
elif plat == "Windows" and machine == "AMD64" and is_64_bit:
    lib_file = "libebm_win_x64"
elif plat == "Darwin" and machine == "x86_64" and is_64_bit:
    lib_file = "libebm_mac_x64"
elif plat == "Darwin" and machine == "arm64":
    lib_file = "libebm_mac_arm"

SIMD acceleration flags from `python/interpret-core/interpret/utils/_native.py:66-73`:

AccelerationFlags_NONE = 0x00000000
AccelerationFlags_Nvidia = 0x00000001
AccelerationFlags_AVX2 = 0x00000002
AccelerationFlags_AVX512F = 0x00000004
AccelerationFlags_IntelSIMD = AccelerationFlags_AVX2 | AccelerationFlags_AVX512F
AccelerationFlags_SIMD = AccelerationFlags_IntelSIMD
AccelerationFlags_GPU = AccelerationFlags_Nvidia
AccelerationFlags_ALL = 0xFFFFFFFF

Common Errors

Error Message	Cause	Solution
`Unsupported platform {plat}`	Running on unsupported OS	Use Windows, Linux, or macOS
`Exception: Shared directory in symbolic not found`	Building from source without native code	Clone the full repository including `shared/libebm/`
`OSError: libebm.so: cannot open shared object file`	Native library not found at expected path	Reinstall via pip or build from source with `./build.sh`
`Out of memory in {native_function}`	Insufficient RAM for native operation	Reduce dataset size, max_bins, or outer_bags
`Thread start failed in {native_function}`	System thread limit reached	Reduce `n_jobs` parameter

Compatibility Notes

Windows: Only x64 (AMD64) 64-bit supported. 32-bit Windows is not supported.
Linux x64: Primary development platform. AVX2 and AVX-512 acceleration available.
Linux ARM (aarch64): Supported. No SIMD acceleration (scalar CPU fallback).
macOS x64: Supported via `.dylib`.
macOS ARM (Apple Silicon): Supported via `libebm_mac_arm.dylib`.
conda-forge: The `libebm` package is a separate conda-forge dependency. The pip build process does NOT compile the native library when building a bdist.
Debug builds: Append `_debug` to the library name (e.g., `libebm_debug.so`). Enabled by passing `is_debug=True` to `Native.get_native_singleton()`.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment