Native mining pruning controls

Native mining pruning controls reduce C++ HUIM search work during fit(). They are separate from the user-facing PatternEditor workflow, which edits an already fitted representation for governance review.

Pruning paths

Path

When active

Purpose

Controls

LIU

Compound-pattern mining, including the L=2 hot path. Bounded classifier mining uses exact candidate evidence before raising the utility floor.

Raises the utility threshold from locally strong candidate sequences so weaker branches can be skipped earlier.

Tune L, G, and topK. There is no separate public LIU switch.

LA

Generic utility-list child construction on the ordinary utility-ranked branch.

Stops constructing a child utility list once the remaining upper bound cannot pass the current retained-pattern utility floor.

Tune topK and G. Relaxed-root interaction branches bypass this utility-floor shortcut when needed.

EUCS

Eligible L > 1 native mining paths after the admitted item set is known. Small, dense, or very wide pair spaces are skipped automatically.

Builds a pair co-occurrence utility cache and skips pair intersections whose pair-level utility cannot enter the retained set.

Environment variables described below.

Native hot paths

The native dispatcher uses specialized miners for the most common bounded pattern depths before falling back to the generic bounded miner:

  • L=1 uses fused transaction preparation, singleton mining, top-K retention, and sparse training-matrix construction where the input layout is eligible.

  • L=2 uses a dedicated two-item miner with same-feature conflict checks and pruning before generic utility-list expansion is needed.

  • L=3 uses the 1.1.17 three-item hot path, including pair reuse, coverage de-duplication, same-feature conflict checks, gated EUCS pruning, and an optional pair-cache budget for sparse workloads.

  • Higher bounded values, and L=-1 unbounded mining, continue to use the generic native miner.

interaction_relaxed_mining=True now allows L=-1 or any integer L>=1. Dedicated relaxed paths are used where available, and higher bounded orders use the generic relaxed dispatcher.

Mining timeout and audit log

Use max_mining_seconds to set a wall-clock budget for the native mining stage. max_fit_seconds is still accepted as a backward-compatible alias, but new code should prefer max_mining_seconds because the budget applies to mining rather than the entire estimator fit() call.

When a budget is active, native miners check the deadline during search and return partial results where possible. The estimator records each mining attempt in mining_audit_log_ and exposes it as a DataFrame through get_mining_audit_log(). The log includes the requested K/L/G, timeout budget, elapsed time, status, relaxed-mining flag, and number of patterns returned.

EUCS parameters

EUCS is enabled by default for eligible L > 1 native mining paths, subject to workload gates that avoid building the cache when it is unlikely to pay off.

Variable

Default

Meaning

HUGIML_EUCS_ENABLE or HUGIML_EUCS_ENABLED

enabled

Set to 0, false, no, off, disable, or disabled to disable EUCS. Set to 1, true, yes, on, enable, or enabled to enable it. Invalid values keep the default.

HUGIML_EUCS_MIN_ITEMS

32

Skip EUCS when the admitted item universe is this size or smaller.

HUGIML_EUCS_MAX_CELLS

6000000

Maximum pair-cache cells allowed before EUCS is skipped.

HUGIML_EUCS_MAX_DENSITY

0.20

Maximum observed active-item density allowed before EUCS is skipped.

Practical guidance

Most users should leave these native controls at their defaults and tune the model-level parameters first:

  • L controls maximum pattern length.

  • G controls the information-gain gate.

  • topK controls the retained pattern budget.

EUCS environment controls are most useful for benchmarking, profiling, or workloads with unusually sparse or dense pair spaces.