Runtime controls

Kwker configures itself when it loads. It reads the CPU's features and cache sizes, picks the engine, and sets its thresholds from them. There is nothing to tune. This page covers the switches that exist anyway: for production fallbacks, debugging, resource limits and A/B timings. None of them changes a result; they only change speed and resource use.

What runs here

import kwker
caps = kwker.capabilities()
print(caps["isa"], caps["engines_usable"], caps["l2"], caps["cpus"])
r, report = kwker.observe(kwker.sorted, list(range(1000, 0, -1)))   # which engine stages ran
print(report["isa"], [s["name"] for s in report["stages"]][:3])

capabilities() returns the version, the engine in use, the engines built and usable, the CPU features, the cache sizes, the CPU count and the build. observe(fn, ...) runs one call with the engines' path report switched on. The report lists the stages that ran (with counts and cycles) and the scratch peak. Stage reports exist on the x86 engines; elsewhere traced is False.

From a shell, run python -m kwker doctor, or kwker-doctor (the C / C++ package's bin/). Add --json for scripts. To collect everything for a support request, run python -m kwker support-bundle. It writes a .tar.gz holding the doctor report, CPU details, package versions, the KWKER_* and threading environment variables, and a self-check on generated data. It holds none of your data.

Fallback switches

If you ever suspect Kwker in a production problem, KWKER_ISA=portable is the first check. It runs the scalar engine, which produces the same results. If the problem stays, the cause is not in an engine's SIMD code.

The same cap from Rust, C, C++ and Go, with a check that the results do not change:

use kwker::Isa;

fn main() {
    kwker::set_isa(Some(Isa::Portable));   // the scalar engine from now on
    println!("{:?}", kwker::isa());
    let mut a = [3, 1, 2];
    kwker::sort(&mut a);                     // the same result on every engine
    println!("{a:?}");
    kwker::set_isa(None);                    // back to the best engine
}

Portable
[1, 2, 3]

#include <stdio.h>
#include <kwker.h>

int main(void) {
    kwker_set_isa("portable");               /* the scalar engine from now on */
    printf("%s\n", kwker_isa());
    int32_t a[] = {3, 1, 2};
    kwker_i32_sort(a, 3);                    /* the same result on every engine */
    printf("%d %d %d\n", a[0], a[1], a[2]);
    kwker_set_isa(NULL);                     /* back to the best engine */
    return 0;
}

portable
1 2 3

#include <iostream>
#include <vector>
#include <kwker.hpp>

int main() {
    kwker::set_isa("portable");              // the scalar engine from now on
    std::cout << kwker::isa() << '\n';
    std::vector<int> a{3, 1, 2};
    kwker::sort(a);                          // the same result on every engine
    std::cout << a[0] << ' ' << a[1] << ' ' << a[2] << '\n';
    kwker::set_isa();                        // back to the best engine
}

portable
1 2 3

package main

import (
	"fmt"

	"kwker.io/go/kwker"
)

func main() {
	isa, _ := kwker.SetISA("portable") // the scalar engine from now on
	fmt.Println(isa)
	a := []int32{3, 1, 2}
	kwker.Sort(a) // the same result on every engine
	fmt.Println(a)
	kwker.SetISA("") // back to the best engine
}

portable
[1 2 3]

import io.kwker.Kwker;
import java.util.Arrays;

public class Example {
    public static void main(String[] args) {
        System.out.println(Kwker.setIsa("portable")); // the scalar engine from now on
        int[] a = {3, 1, 2};
        Kwker.sort(a); // the same result on every engine
        System.out.println(Arrays.toString(a));
        Kwker.setIsa(null); // back to the best engine
    }
}

portable
[1, 2, 3]

using Kwker;

Console.WriteLine(Sorter.SetIsa("portable")); // the scalar engine from now on
var a = new[] { 3, 1, 2 };
Sorter.Sort(a); // the same result on every engine
Console.WriteLine(string.Join(" ", a));
Sorter.SetIsa(null); // back to the best engine

portable
1 2 3

Algorithm classes

Besides the comparison core, which always runs, Kwker uses three optional classes of algorithm:

• adaptive: finishes early on inputs that are already sorted, reversed, all equal or nearly sorted, and sorts inputs made of runs of equal keys (timestamps, repeated readings) as one entry per run.
• counting: handles few distinct values, dominant or heavy values, and narrow key ranges.
• radix: radix and value-bucket passes for large inputs.

set_algorithms restricts them for the calling thread. A typical use is a latency-critical service that wants predictable timings on adversarial inputs, or isolating a slowdown. Results, including stable orders, are identical under every setting.

import numpy as np, kwker
prev = kwker.set_algorithms({"adaptive"})       # comparison core + presortedness checks only
a = np.random.default_rng(0).integers(0, 4, 100_000)
kwker.sort(a)                                    # same result, without the counting path
kwker.set_algorithms(prev)

Threads

Calls are single-threaded unless you pass threads=. Kwker never starts threads behind your back.

A parallel call made from inside another one's task runs on its caller's thread, so nesting never multiplies thread counts. Worker threads are kept between calls and exit after one second idle. Under PyTorch, Kwker uses PyTorch's own worker threads.

Memory

import numpy as np, kwker
kwker.set_scratch_limit(0)                       # allocation-free from here on (this thread)
a = np.random.default_rng(1).random(200_000); kwker.sort(a)
kwker.set_scratch_limit(None)
print(kwker.scratch_use())

In Rust, scratch_bound() returns the most scratch memory an operation can use.

Environment variables

python -m kwker doctor lists every KWKER_* variable that is set in the environment.

PyTorch switches

Environment variables that turn single PyTorch features off or change their limits:

Related

• Core concepts: engines, threads and memory explained.
• Large data: several cores and a memory limit for one call.
• Troubleshooting: what each doctor warning means.