Configuration Reference

Configuration Reference

Scope. This page documents the feature/c config surface (mtpndd_pal_config_t / MTPNDDConfig.Builder). The feature/go .so accepts the same Java builder for ABI compatibility but interprets several fields differently or ignores them outright — see feature/go field mapping at the bottom of this page.

MTPNDD has three tiers of configuration:

1. Runtime — mtpndd_pal_config_t (C) / MTPNDDConfig.Builder (Java), passed to mtpndd_init / MTPNDDEngine.init
2. Compile-time defaults — #define MTPNDD_DEFAULT_* constants in mtpndd/mtpndd_common.h
3. CMake cache variables / options — controlled at configure time

Runtime — mtpndd_pal_config_t

Defined in mtpndd/mtpndd_common.h. Every field has a matching setter on MTPNDDConfig.Builder.

C field	Java setter	Type	Default	Meaning
n_workers	workers(int)	int32_t	0	Lace worker count. 0 = auto-detect (one per hardware thread)
lace_dqsize	laceDequeSize(long)	size_t	Lace's default	Per-worker Lace deque size
bdd_nodetable_size	bddNodeTableSize(long)	size_t	Sylvan default	Sylvan BDD node table capacity
mtpndd_nodetable_size	mtpnddNodeTableSize(long)	size_t	1 << 20	MTPNDD node table capacity
op_cache_size	operationCacheSize(long)	size_t	1 << 20	AND/OR/NOT operation cache entries
quick_growth_threshold	quickGrowthThreshold(double)	double	0.75	Load factor that triggers "quick grow" before GC. Set to -1 to disable quick grow and always GC first
edge_bucket_count	edgeBucketCount(long)	size_t	8	Hash buckets in each node's edge map. Must be a power of 2, ≤ 64
nodetable_bucket_count	nodetableBucketCount(long)	size_t	1024 (or 65537 with -DLARGE_NODETABLE)	Hash buckets in the canonical nodetable
node_slab_capacity	nodeSlabCapacity(long)	size_t	1024	Nodes per slab in the node memory pool
edge_entry_slab_capacity	edgeEntrySlabCapacity(long)	size_t	4096	Edge entries per slab
nodetable_entry_slab_capacity	nodetableEntrySlabCapacity(long)	size_t	2048	Nodetable entries per slab
edge_map_slab_capacity	edgeMapSlabCapacity(long)	size_t	2048	Edge maps per slab

Tuning notes

• n_workers — leave at 0 unless pinning for benchmarks. Scaling tapers above physical core count; hyperthreads help little on this workload.
• mtpndd_nodetable_size / op_cache_size — the defaults fit N-Queens up to N≈13. For larger problems bump both together; the op cache's hit rate dominates on dense AND chains.
• edge_bucket_count — default 8 is a good trade-off for sparse fanout. MTPNDD-heavy workloads with denser edge distributions may see small gains at 16 or 32. Must stay a power of 2 and ≤ 64 (collision tag is 6 bits).
• nodetable_bucket_count — controls average probe length. Defining LARGE_NODETABLE at compile time bumps the default from 1024 to 65537 for workloads that create many unique nodes.
• quick_growth_threshold — when nodetable load exceeds this, MTPNDD rehashes in place before triggering Sylvan GC. -1 disables and always runs GC first. Keeping it enabled is usually faster.
• Slab capacities — larger slabs reduce allocator pressure but increase steady-state RSS. Defaults are fine for single-node benchmarks.

Compile-Time Defaults (#define)

In mtpndd/mtpndd_common.h:

Macro	Default
MTPNDD_DEFAULT_NODETABLE_BUCKET_COUNT	1024 (65537 if LARGE_NODETABLE is defined)
MTPNDD_DEFAULT_EDGE_BUCKET_COUNT	8
MTPNDD_DEFAULT_NODE_SLAB_CAPACITY	1024
MTPNDD_DEFAULT_EDGE_ENTRY_SLAB_CAPACITY	4096
MTPNDD_DEFAULT_NODETABLE_ENTRY_SLAB_CAPACITY	2048
MTPNDD_DEFAULT_EDGE_MAP_SLAB_CAPACITY	2048

Override at configure time, e.g.:

cmake -B build -DCMAKE_C_FLAGS="-DLARGE_NODETABLE -DMTPNDD_DEFAULT_EDGE_BUCKET_COUNT=16"

CMake Variables

Variable	Type	Default	Notes
CMAKE_BUILD_TYPE	string	Release	Forced to Release if not set
MTPNDD_LOG_LEVEL	string (0/1/2)	1	0=QUIET, 1=INFO, 2=DEBUG. Statistics and per-op timing are only compiled in at 2
MTPNDD_BUILD_JNI	option	ON	Skip JNI shared library with OFF
MTPNDD_NQUEENS_ENABLE_DOT	option	ON	Dump DOT graphs from the nqueens test
SYLVAN_ENABLE_PIC	bool	ON (forced)	Required so JNI can link Sylvan into a shared lib

Runtime Knobs (Environment Variables)

Honored by the benchmarks:

• MTPNDD_BDD_SPAWN_CUTOFF=<n> — forwarded to Sylvan's sylvan_set_spawn_depth_cutoff (our fork's runtime knob). Limits the depth at which BDD ops still SPAWN new Lace tasks; setting a small cap can reduce scheduling overhead on deep formulas.

C API for Runtime Tuning

mtpndd/mtpndd_node.h exposes a two-phase AND threshold:

void mtpndd_set_two_phase_threshold(int value);
int  mtpndd_get_two_phase_threshold(void);

Controls the edge-count threshold above which mtpndd_and uses the filter-then-recurse path. Raise it to disable two-phase on small problems; lower it (including to 0) to always use two-phase. The default is tuned for the nqueens benchmark.

feature/go Field Mapping

The Go .so exposes the same MTPNDDConfig surface for ABI compatibility. Most fields map to the Go engine's equivalents; a few are Sylvan/Lace-specific and are ignored.

C / Java field	feature/go behavior
n_workers	Used only for the Go-native internal/work goroutine admission gate (GOMAXPROCS-sized semaphore). JNI callers additionally disable in-Go goroutine spawning entirely (the Java side is already parallel)
lace_dqsize	Ignored (no Lace)
bdd_nodetable_size	Maps to the pure-Go BDD unique-table initial capacity in internal/bdd/
mtpndd_nodetable_size	Maps to the Go NDD unique-table initial capacity
op_cache_size	Maps to both the NDD op cache and the BDD op cache initial slot counts
quick_growth_threshold	Ignored — Go tables auto-resize at a fixed 50 % load factor
edge_bucket_count	Ignored — Go nodes store edges in a stack-allocated array, not a hash map
nodetable_bucket_count	Ignored — Go's sharded open-addressing table sizes itself from mtpndd_nodetable_size
node_slab_capacity	Ignored — do not plumb this through. feature/go uses a fixed 256 K-node chunk size; forwarding the C value (2048) caused chunk-directory overflow on fattree12. This is an explicit feature/go invariant
edge_entry_slab_capacity	Ignored
nodetable_entry_slab_capacity	Ignored
edge_map_slab_capacity	Ignored

feature/go-specific knobs (not exposed via MTPNDDConfig; set internally by the JNI bridge at jni/main.go):

• cfg.SpawnPairThreshold = 1024 — disables in-Go goroutine spawning for JNI callers. Go-native callers (cmd/nqueens-bench) default to 4 and still parallelize intra-op.
• cfg.NDD.CacheClearInterval = cfg.BDD.CacheClearInterval = 1 << 62 — effectively disables periodic op-cache clears under JNI (the host process is long-lived; the clears would drop hit rate).
• Global SatCount memo — always on; the single biggest lever on fattree12 MF=3 (reduces SatCount from hundreds of seconds to ~10 s). Not tunable.