GWAS engine with GPU acceleration via JAX
g is a pre-release GWAS engine for BGEN-backed REGENIE Step 2 association
scans. It is a Rust host application with a Python/JAX numerical backend: Rust
owns the CLI, configuration, planning, input, scheduling, runtime, telemetry,
resume, and Parquet output, while JAX and optional CUDA kernels perform the
association mathematics. Python embedding is not a supported API.
g does not implement REGENIE Step 1. Use upstream regenie to produce Step 1
prediction lists, then use g for Step 2 scans.
| Area | Status |
|---|---|
| Commands | g regenie runs one Step 2 request; g batch runs complete TOML configurations sequentially in one process. |
Quantitative REGENIE Step 2 (--qt) |
Supported. |
Binary score-test Step 2 (--bt) |
Supported. |
Binary approximate Firth fallback (--bt --binary-fallback firth_approximate) |
Experimental; upstream golden parity is not complete. |
| REGENIE Step 1 | Not implemented |
| Genotype input | Layout 2 BGEN with uncompressed, zlib, or BGEN v1.3 Zstandard blocks; an Oxford .sample file is required. |
| Sample identity | Strict non-empty, unique (FID, IID) pairs across aligned inputs. |
| Multiple phenotypes | Supported; per-phenotype complete-case samples are the default, with a shared complete-case mode available. |
| Result output | One chunked Parquet dataset per phenotype, plus effective configuration, manifest, logs, and telemetry. |
| Resume | Strict manifest-validated resume from committed Parquet chunks. |
| Execution | CPU by default; JAX GPU execution and eligible automatic CUDA fast paths are supported. |
| Unsupported surface | BED/PGEN, sample and variant filters, categorical covariates, SPA, exact Firth, and time-to-event traits. |
Unsupported REGENIE options are rejected rather than silently ignored. See Compatibility for the exact current surface.
For All of Us, the experimental Verily Workbench workflow adds explicit cohort preparation, pinned input manifests and verified result bundles. Start with its synthetic smoke test; controlled-data compatibility and cohort-scale performance still require qualification inside your workspace.
g is installed from a Git checkout because it is not published on PyPI.
The primary supported path is Linux with Python 3.14, Rust 1.97.1, uv, a
C/C++ compiler, and Mold. GPU execution additionally requires a compatible
NVIDIA driver and node.
git clone https://github.com/kirilledition/g.git
cd g
uv python install 3.14
uv sync --python 3.14 --no-dev --frozen
uv run g --help
uv run g regenie --helpThe supported runtime is exactly jax==0.11.0 with jaxlib==0.11.0; GPU
installs use its CUDA 12 extra for the project's NVIDIA V100/R535 deployment.
For CPU and GPU prerequisites, cluster installs, and development setup, use
Installation.
uv run g regenie \
--qt \
--bgen /path/to/genotypes.bgen \
--sample /path/to/genotypes.sample \
--phenoFile /path/to/phenotypes.tsv \
--phenoCol phenotype_continuous \
--covarFile /path/to/covariates.tsv \
--covarCol age --covarCol sex \
--pred /path/to/regenie_step1_pred.list \
--out /path/to/output/g_regenie2The packaged configuration selects CPU execution by default. --out is a
prefix: this example creates /path/to/output/g_regenie2.g/, with a separate
run directory and parts/ Parquet dataset for each requested phenotype.
For quantitative, binary, approximate-Firth, multi-phenotype, GPU, and output examples, continue with Quickstart.
Use g batch to run compatible complete TOML configurations sequentially while
reusing one Python/JAX process:
uv run g batch \
--config chromosome_21.toml \
--config chromosome_22.tomlBatch mode validates shared process policy and output-root separation before starting work, executes configurations in argument order, and stops at the first failure. See CLI and Configuration for the complete contract.
A typical run creates:
<out>.g/
logs/
events.jsonl
trait_0001_<phenotype>.regenie2_linear.run/
effective_config.toml
run_manifest.json
parts/
part_000000000_000000007.parquet
Binary run directories use .regenie2_binary.run. Parquet parts/ is the
completed result dataset; there is no consolidation step. Resume is opt-in with
[output].resume = true and rejects changes to result-affecting inputs or
execution policy. See Output Files and
Resume and Manifest.
Start with the User Guide. Canonical
user-facing contracts live under documentation/public/:
| Need | Page |
|---|---|
| Orientation and installation | Getting Started, Installation |
| Commands and worked examples | Quickstart, CLI |
| Supported REGENIE surface | Compatibility |
| TOML settings and merge rules | Configuration |
| Input and output contracts | Input Files, Output Files |
| Statistical models and result interpretation | Algorithm |
| Restarting interrupted work | Resume and Manifest |
| GPU and cluster operation | GPU and Clusters |
| Tuning and diagnosis | Performance Guide, Troubleshooting |
Contributor guidance starts at Development:
- Architecture
- Configuration frontend
- Testing and parity
- Benchmarking
- Development tooling
- Justfile command reference
- Style guide
Internal scratchpad notes live under documentation/scratchpad/. They are not
part of the primary published navigation and may be stale.
Use just help to inspect project recipes. The standard development entry
points are:
just dev-bootstrap
just doctor
just check
just testBuild or serve the documentation with:
just docs-build
just docs-serveThe published documentation site is expected at:
https://kirilledition.github.io/g/
Generated from Git-tracked files under crates/ and src/ using cloc.
| Language | Files | Blank | Comment | Code |
|---|---|---|---|---|
| Rust | 192 | 3,133 | 1,218 | 33,442 |
| Python | 40 | 740 | 583 | 4,453 |
| C++ | 2 | 119 | 6 | 1,108 |
| Markdown | 13 | 141 | 0 | 585 |
| CUDA | 2 | 24 | 2 | 474 |
| TOML | 12 | 39 | 5 | 240 |
| C/C++ Header | 1 | 12 | 3 | 56 |
| Total | 262 | 4,208 | 1,817 | 40,358 |
cloc version: 2.10.