Skip to content

Features and instruction-set builds

The crate in Cargo.toml is the implementation. The C ABI, the thread pool, and the wide kernels are selected by Cargo features and by the CPU, not by a -C target-cpu flag.

Cargo features

Feature Default What it builds
capi yes The lc_* entry points in include/linkcell.h.
parallel yes The rayon pool, and on Linux and macOS the OpenMP k-nearest team in src/knn_region.c.
minimage-capi no Also exports minimage's C ABI (minimage_*) from this library.
tune no lc_tune_set and lc_tune_pairs for scripts/tune-pairs.py. The public header does not declare them. Requires capi.
timing no SimdTiming (mesh_ns, scan_ns, knn_ns).
scotch no Serial Scotch (SCOTCH_graphPart). The library is not vendored.
ptscotch no PT-Scotch (SCOTCH_dgraphPart). The library is not vendored. The caller initializes MPI.

default is capi and parallel. --no-default-features builds the Rust API on one thread and omits the C ABI. Add --features capi when that build still has to export lc_*.

minimage is a dependency with default-features = false. The default link of liblinkcell omits minimage_*. minimage-capi turns those symbols on for a caller that wants one archive. A static consumer that links minimage itself leaves the feature off, so the two archives do not define the same C symbols.

scotch compiles src/scotch_part.c and exports lc_scotch_part. ptscotch compiles src/ptscotch_part.c and exports lc_ptscotch_part. Without the feature, Method::Scotch and Method::PtScotch return ScotchDisabled.

The crate rust-version is 1.80. That is the oldest toolchain that builds the default features: the locked rayon 1.12 requires it. The Python module in python/Cargo.toml has rust-version 1.88. Its features are scotch (passes through to the crate), abi3 (CPython 3.12+ stable ABI), and abi3t (CPython 3.15+ free-threaded ABI).

Instruction-set builds

build.rs passes no -C target-cpu and no crate-wide target-feature. Each wide kernel carries its own target_feature and is called only after simd::select(). isa-allow.toml names the symbols allowed to contain those instructions. The release-library audit in CI checks the object code against that list.

select reads a test override on the calling thread, then LINKCELL_SIMD, then the widest path this CPU can run. The environment variable is read once and cached. Unknown names are ignored. A name the CPU cannot run selects scalar. Workers use that cached path. Accepted names are scalar, avx2, avx512, and neon. avx2fma is avx2, avx512f is avx512, and 0 is scalar.

AVX-512 is selected only when AVX-512F, AVX-512VL, POPCNT, and fused multiply-add (FMA) are all present. The build compiles those kernels only when rustc is 1.89 or newer (linkcell_avx512 in build.rs). On 1.80 through 1.88 the same source builds the scalar and AVX2 paths, and NEON on aarch64. A CPU with AVX-512F and without AVX-512VL uses AVX2. AVX2 is selected only when FMA is present, so Sandy Bridge stays on scalar. NEON is the aarch64 baseline. SVE intrinsics are nightly-only, so this crate ships the NEON kernel on aarch64 and no SVE kernel.

Stored distances are separate multiplies and adds, in the scalar order. FMA is a selection gate and, inside the pair tile, a screen. The value written for a kept lane is the direct sum of squares. The same input gives the same stored bits on every path and every thread count. simd_path returns scalar, avx2, avx512, or neon. The SIMD paths page is the dispatch explanation.

OpenMP team

With parallel, Linux and macOS compile src/knn_region.c. A failed probe is a build error on glibc Linux and on macOS. musl and any other target keep the rayon walk when that region does not build. macOS needs libomp. LIBOMP_PREFIX names a prefix that contains include/omp.h and lib/libomp.dylib, ahead of Homebrew.

An unmasked k-nearest query of at least 8192 points uses that team when the region was built. lc_set_threads(0) leaves the width unset. lc_set_threads(1) runs the search on the calling thread and starts no worker. OMP_STACKSIZE (or GOMP_STACKSIZE) sets the worker stack. A size below the floor, 64 KiB or PTHREAD_STACK_MIN when that is larger, is raised. OMP_THREAD_LIMIT caps the team. Under OMP_DYNAMIC the load average trims it. pin_knearest_to_least_loaded stays off until the caller sets it in code. The function ignores the environment.