Skip to content

Compute Kernels

Status Applies to Owner
Pre-release draft; development contract JAX association kernels and target bridge as of 2026-07-10 Compute maintainers

JAX kernels own statistical computation after native I/O has aligned samples and decoded genotype chunks. Public mathematical behavior is documented in Algorithm.

Source Map

Path Responsibility
src/g/compute/common/ Shared dtype, genotype, linear algebra, and p-value helpers.
src/g/compute/regenie2_linear/ Quantitative Step 2 state preparation and score/statistic kernels.
src/g/compute/regenie2_binary/ Binary null model, score test, candidate selection, correction, diagnostics, and Firth paths.
src/g/jax_backend.py Coarse group/chromosome/compute/materialize adapter called by Rust.
crates/engine/src/ Rust owner of aligned inputs, batching, scheduling, and host-result writing.
crates/compute-cuda/ Optional typed-XLA FFI CUDA reductions used by compatible GPU kernels.

Kernel Boundary

Kernels should receive:

  • aligned phenotype/covariate/prediction state;
  • variant-major genotype dosage chunks or packed GPU-compatible genotype data;
  • immutable numerical configuration;
  • typed device policy. Score/Firth widths and matmul precision are fixed kernel/runtime invariants.

Kernels should not:

  • read CLI/TOML/environment directly;
  • parse BGEN, phenotype, covariate, or prediction files;
  • write output files;
  • introduce hidden constants that affect public statistics or compiled shapes.

Quantitative Contract

Quantitative kernels implement REGENIE Step 2 linear association:

  • covariate projection/residualization;
  • LOCO-adjusted phenotype residuals;
  • additive allele-one dosage effect;
  • one-degree-of-freedom chi-squared statistic and LOG10P;
  • numerical masks for low residualized genotype variance.

Changing this path requires parity tests and public algorithm updates when statistics or accepted failure conditions change.

Binary Contract

Binary kernels implement:

  • chromosome-specific logistic null fitting with LOCO offset;
  • binary score statistic;
  • optional scalar approximate-Firth candidate selection and correction;
  • Firth and null-Firth solver diagnostics;
  • correction method and status labels for successful and failed rows.

Changing binary correction behavior requires tests for score-only, approximate Firth, diagnostics, failure-code mapping, and public documentation updates when user-visible statistics or tuning semantics change.

Numerical Configuration

Numerical thresholds and iteration policies are canonical TOML options and must be threaded from crates/interface/src/config.default.toml through the Rust RunPlan and typed JAX backend config into kernel config dataclasses.

Examples:

  • linear variance floors;
  • binary probability and variance floors;
  • null logistic nonconvergence policy;
  • Firth iteration, tolerance, and line-search limits.

Score arithmetic uses float32. Approximate-Firth outer components, reductions, solver state, convergence, likelihood, corrected statistics, and Newton fallback use float64; only the inner pseudo-logistic elementwise proposal uses float32 before widening its products for float64 reductions. JAX x64 is enabled, and JAX matmul precision is float32. These are fixed implementation policies, not configuration fields. Do not add module-level runtime constants for configurable numerical behavior or expose fixed width/runtime policy as configuration.

JAX Runtime

JAX runtime policy is configured before backend initialization. Code that imports JAX-heavy modules should stay behind explicit runtime boundaries when needed to preserve device/cache setup order.

The native typed-XLA handlers are compiled against the vendored headers from jaxlib==0.11.0. Production therefore supports exactly jax==0.11.0 and jaxlib==0.11.0. The project metadata pins JAX directly; JAX 0.11.0's own package metadata constrains jaxlib to that exact release. Backend construction checks both observed versions before any project-owned FFI target is registered, so a manually drifted --no-sync environment fails instead of crossing an unqualified native ABI boundary.

GPU approximate Firth uses a private CUDA component reduction when the Linux CUDA driver reports API 12.2 or newer and the selected device has compute capability 7.0 or newer. The checked-in compute-70 PTX is loaded lazily into the XLA execution context. It preserves the established float64 reductions, probability clipping, validity rules, and solver control flow; only component evaluation is fused. CPU runs and unsupported GPU environments retain the pure JAX implementation automatically. Failure after a successful capability proof, such as a driver rejecting the validated PTX during execution, is a runtime error rather than an in-flight solver switch; falling back after an executable starts would mix implementations.

Profile mode may intentionally synchronize device work for timing. Production progress logging must not add synchronization only for observability.

Testing

Relevant tests include:

  • tests/test_regenie2_linear.py;
  • tests/test_regenie2_binary.py;
  • tests/test_regenie2_binary_firth_null.py;
  • tests/test_regenie2_binary_scalar_firth.py;
  • tests/test_regenie2_parity.py;
  • tests/parity/.

Use Testing and Parity for validation tier selection.