Installation

g is pre-release and is not published on PyPI. Install it from a Git checkout and run it through the checkout's uv environment. This keeps g in a repository-local .venv/ and does not install packages into your system Python, Conda base environment, or other projects.

Use this page when you want to run your own GWAS. If you want to change the code, skip to Development Installation.

External Tools

Install or load these tools before syncing the Python environment:

just is not required to run g; it is a development task runner for this repository. Linux source builds use the cc compiler driver with Mold by default. Cargo uses up to 30 build jobs unless CARGO_BUILD_JOBS or --jobs overrides it. Run just doctor to verify that the installed compiler driver can invoke Mold.

Supported Platforms

Known unsupported distribution modes:

• PyPI package: not published.
• Conda package: not published.
• System Python or shared Conda base install: not recommended.

Verify The Install

After any install flow, verify the command surface from the same checkout and environment that will run the scan:

uv run g --help
uv run g regenie --help
uv run python -c "import g; print(g.__name__)"

CPU Install From Source

Clone the repository, let uv install the required Python version, and sync only runtime dependencies:

git clone https://github.com/kirilledition/g.git
cd g
uv python install 3.14
uv sync --python 3.14 --no-dev
uv run g --help
uv run g regenie --help

uv sync creates .venv/ inside the checkout and installs the local project there. Re-run uv sync --python 3.14 --no-dev after pulling a new commit.

Use --frozen when you want uv to enforce the checked-in lockfile without changing it:

uv sync --python 3.14 --no-dev --frozen

First checks after install:

uv run g --help
uv run g regenie --help

GPU Install From Source

First make sure the cluster node or workstation has a compatible NVIDIA driver. CUDA-enabled JAX is a base project dependency, so no separate GPU dependency group is required:

git clone https://github.com/kirilledition/g.git
cd g
uv python install 3.14
uv sync --python 3.14 --no-dev
uv run python -c "import jax; print(jax.devices())"

The base environment installs the CUDA-enabled JAX extra declared by this checkout. If JAX does not list the expected GPU, compare the installed extra with the current JAX installation matrix, then adjust the environment before measuring performance.

Select GPU execution in a config file:

[compute]
device = "gpu"

Use device = "cpu" for CPU execution. CPU mode is installed by the base runtime dependencies.

Run Your GWAS

g implements REGENIE Step 2 over BGEN input. It does not implement Step 1, so create the Step 1 prediction list with upstream regenie first and pass that file with --pred.

Minimal CPU shape:

uv run g regenie \
  --config cpu.toml \
  --qt \
  --bgen /path/to/genotypes.bgen \
  --sample /path/to/genotypes.sample \
  --phenoFile /path/to/phenotypes.tsv \
  --phenoCol phenotype_name \
  --covarFile /path/to/covariates.tsv \
  --covarCol age --covarCol sex \
  --pred /path/to/regenie_step1_pred.list \
  --out /path/to/output/g_regenie2

Here cpu.toml contains [compute] device = "cpu". Result output is always a chunked Parquet dataset. For a GPU run, use a config with [compute] device = "gpu" and submit it on a GPU node rather than a login node.

See Quickstart for quantitative and binary command examples, CLI for supported flags, Input Files for input contracts, and Output Files for artifact expectations.

Linux Cluster Without Root

On shared clusters, keep the checkout and caches in a user-writable filesystem such as $SCRATCH when available:

mkdir -p "${SCRATCH:-$HOME}/gwas-engine" "${SCRATCH:-$HOME}/.cache/uv"
export UV_CACHE_DIR="${SCRATCH:-$HOME}/.cache/uv"
export UV_LINK_MODE=copy

cd "${SCRATCH:-$HOME}/gwas-engine"
git clone https://github.com/kirilledition/g.git
cd g
uv python install 3.14
uv sync --python 3.14 --no-dev

If your site provides environment modules, load git, Rust/Cargo, and GPU-driver-compatible CUDA modules before running uv sync. If it does not, use the user-local installers linked in External Tools. Avoid sudo and avoid installing into a shared system Python.

Generic GPU SLURM job shape:

#!/usr/bin/env bash
#SBATCH --job-name=g-regenie2
#SBATCH --gres=gpu:1
#SBATCH --cpus-per-task=8
#SBATCH --mem=64G
#SBATCH --time=04:00:00

set -euo pipefail

cd /path/to/g
export UV_CACHE_DIR="${SCRATCH:-$HOME}/.cache/uv"
export UV_LINK_MODE=copy

uv run --no-sync g regenie \
  --config /path/to/gpu.toml \
  --qt \
  --bgen /path/to/genotypes.bgen \
  --sample /path/to/genotypes.sample \
  --phenoFile /path/to/phenotypes.tsv \
  --phenoCol phenotype_name \
  --pred /path/to/regenie_step1_pred.list \
  --out /path/to/output/g_regenie2

Adjust scheduler options for your cluster. Do not run GPU scans or large CPU scans on a login node.

Development Installation

Development workflows use just, development dependency groups, local checks, and sometimes the repository's SLURM wrappers. Start with the development documentation instead of the consumer flow:

• Development
• No-Nix Development
• Server Gauss SLURM

Common development setup:

just dev-bootstrap
just doctor
just check-local

GPU-capable development setup:

just dev-bootstrap-gpu
just doctor-jax

Documentation dependencies also belong to the development flow:

uv sync --group docs
just docs-build