Implementation:Interpretml Interpret TensorTotalsBuild

Knowledge Sources	Interpretml Interpret
Domains	Machine_Learning, EBM_Core
Last Updated	2026-02-07 12:00 GMT

Overview

TensorTotalsBuild is a C++ module that builds cumulative sum (prefix sum) totals across all dimensions of a multi-dimensional histogram tensor, enabling efficient sub-region queries during split finding.

Description

This module implements the TensorTotalsBuildInternal class which converts a raw histogram tensor (where each bin contains only its own counts/gradients/hessians) into a cumulative sum tensor where each bin contains the sum of all bins from the origin to that point. This prefix sum structure enables O(2^D) computation of any sub-region's statistics using inclusion-exclusion, rather than the naive O(N^D) summation.

The algorithm works dimension by dimension:

1. For each dimension, iterate over all "tubes" (1D slices along that dimension)
2. For each tube, accumulate the running sum by adding each bin's statistics to a running total stored in an auxiliary bin
3. The auxiliary bins track the partial sums for each dimension being processed

The module uses a FastTotalState struct to maintain iteration state per dimension, including current position, wrap-around point, and first position pointers. This allows efficient multi-dimensional traversal with proper carry propagation across dimensions.

The code includes extensive comments about future optimizations including:

• Building pair and triple-specific versions for better cache performance
• Building a second totals tensor from the opposite corner for faster split evaluation
• Sorting dimensions by length for better memory access patterns
• Combining totals building with split finding for better cache utilization

Usage

This module is called before split finding in both boosting and interaction detection. After histograms are computed for each bin, TensorTotalsBuild converts them to prefix sums so that TensorTotalsSum can efficiently compute the statistics for any sub-region.

Code Reference

Source Location

• Repository: Interpretml_Interpret
• File: shared/libebm/TensorTotalsBuild.cpp

Signature

template<bool bHessian, size_t cCompilerScores, size_t cCompilerDimensions>
class TensorTotalsBuildInternal final {
public:
    static void Func(
        const size_t cRuntimeScores,
        const size_t cRuntimeRealDimensions,
        const size_t* const acBins,
        BinBase* aAuxiliaryBinsBase,
        BinBase* const aBinsBase
#ifndef NDEBUG
        ,
        BinBase* const aDebugCopyBinsBase,
        const BinBase* const pBinsEndDebug
#endif
    );
};

I/O Contract

Inputs

Name	Type	Required	Description
cRuntimeScores	size_t	Yes	Number of score outputs
cRuntimeRealDimensions	size_t	Yes	Number of real dimensions (those with more than 1 bin)
acBins	const size_t*	Yes	Array of bin counts per dimension
aAuxiliaryBinsBase	BinBase*	Yes	Auxiliary bins used as temporary storage during prefix sum computation
aBinsBase	BinBase*	Yes	Input histogram bins (modified in-place to cumulative sums)

Outputs

Name	Type	Description
aBinsBase	BinBase* (in-place)	Bins converted from individual counts to cumulative prefix sums

Usage Examples

Pipeline Context

# This C++ module is called internally via the native bindings
# to build prefix sum totals before split finding
from interpret.glassbox import ExplainableBoostingClassifier
ebm = ExplainableBoostingClassifier(interactions=10)
ebm.fit(X, y)  # Internally calls TensorTotalsBuild before evaluating splits

Related Pages

• Environment:Interpretml_Interpret_Native_Libebm_Environment