Docs · OGN platform

GPU-native genomics operating system

From raw reads to GIAB-validated variant calls in a continuous GPU pipeline. This is the control surface for the engine: CLI, pipelines, benchmarks, and deployment runbooks.

CUDA 12+Hopper · AmpereGIAB-validated flowsSchemas stable

Viewing

OGX spec

Benchmark pack Example pipelines GitHub

OGX Bundle Specification (v1)

Purpose

OGX encapsulates the GPU-ready OmegaAlign index for a single contig/region. It is the contract between bundle builders and runtime mappers.

Manifest (manifest.json) fields

Field	Type	Req	Example	Notes
version	int	yes	1	Schema version
bundle_id	string	yes	chr20_10M	Human readable identifier
contig.name	string	yes	chr20	Single contig/region name
contig.length	int	yes	10000000	Bases in contig
files.graph	path	yes	graph/graph.ogx	GPU-ready graph
files.graph_sha256	path	yes	graph/graph.ogx.sha256	sha256sum sidecar
files.seeds	path	yes	seeds/shard_0000.ogx	Primary seed shard
files.seeds_sha256	path	yes	seeds/shard_0000.ogx.sha256	sha256sum sidecar
files.paths	path	yes	paths/paths.ogx	Path lookup table
files.paths_sha256	path	yes	paths/paths.ogx.sha256	sha256sum sidecar
files.ref_fasta	path	yes	ref.fasta	Reference sequence
files.ref_fai	path	yes	ref.fasta.fai	FASTA index
files.chain_params	path	yes	chain_params.json	Chain/WFA defaults
seeds_header.kind	string	yes	strobe	Seed generator kind
seeds_header.k/s/strobe_w/strobe_t	int	yes	25/15/80/3	Syncmer + randstrobe knobs
seeds_header.records	int	yes	123456	Seed record count
build.tool	string	yes	ogn_ogx_builder	Builder binary
build.tool_version	string	yes	0.3.0	Builder semver/sha
build.source_fasta	string	yes	chr20.fa	Provenance
build.source_gfa	string	yes	chr20.gfa	Provenance
build.timestamp_utc	string	yes	2025-11-18T04:05:06Z	ISO8601
metadata.notes	string	no	free text	Freeform annotations

Chain params (chain_params.json)

{
  "version": 1,
  "omega_chain": {
    "max_chain_gap": 5000,
    "max_dist": 2500,
    "max_chains": 32,
    "min_seed_score": 10,
    "max_seed_skip": 25,
    "diag_band": 1024
  },
  "scoring": {"match": 2, "mismatch": -4, "gap_open": -8, "gap_extend": -1}
}

Field	Type	Req	Overridable
version	int	yes	no
omega_chain.max_chain_gap	int	yes	yes
omega_chain.max_dist	int	yes	yes
omega_chain.max_chains	int	yes	yes
omega_chain.min_seed_score	int	yes	yes
omega_chain.max_seed_skip	int	yes	yes
omega_chain.diag_band	int	yes	yes
scoring.match	int	yes	yes
scoring.mismatch	int	yes	yes
scoring.gap_open	int	yes	yes
scoring.gap_extend	int	yes	yes

Non-overridable (“baked in”): seeds header, graph/seeds/paths checksums, bundle_id, contig name/length, and builder provenance. Override JSON that attempts to set unknown keys, mixes conflicting values (e.g., max_chain_gap at root vs omega_chain.max_chain_gap with different numbers), or contains no valid fields is rejected.

File layout

bundle_root/
  manifest.json
  chain_params.json
  ref.fasta
  ref.fasta.fai
  graph/graph.ogx(.sha256)
  seeds/shard_0000.ogx(.sha256)
  paths/paths.ogx(.sha256)

Runtime override precedence

Layer	Source	Notes
bundle	manifest + chain_params.json	always present
env	`OGN_OMEGA_CHAIN_OVERRIDES`	strict JSON; malformed ⇒ hard error
file	`OGN_OMEGA_CHAIN_OVERRIDES_FILE` or `--omega-chain-json`	file must exist and contain at least one valid field
cli	inline `OmegaChainOverrides` struct or `--omega-chain-json`	highest precedence

Later layers overwrite earlier ones; conflicts throw. ogn_ogx_load emits a single summary line such as:

[omega] omega.chain.source=bundle:env:file:cli fields=max_chains,max_dist hash=ab12...

Malformed JSON, empty objects, or conflicting keys abort the load, giving CI a hard failure mode for precedence violations.

OGX ingest semantics (for OGC and benchmarks)

ingest.bytes = sum of manifest.json, chain_params.json, graph, seeds, paths, ref_fasta, ref_fai, and associated sidecar .sha256 files.
ingest.read_bytes = optional additional bytes if a read source is streamed alongside the bundle (0 for pure bundle loads).
ingest.wall_ms = time from OGX load start until bundle is parsed and the Omega index is uploaded to device.
ingest.h2d_ms = host→device time for uploading the Omega index.
ingest.h2d_bytes = number of bytes copied to device for the OGX index (keys/offsets/counts/hits/contig tables).
ingest.h2d_gbps = h2d_bytes / h2d_ms, GB/s. These numbers are logged as ingest-summary source=ogx ... and flow into OGC manifests via the bench script.

Manifest contract (v1)

Required blocks: version, bundle_id, contig{name,length}, reference (id, build, coordinate_space), files (graph/seeds/paths/ref_fasta/ ref_fai/chain_params + sha256 sidecars), seeds_header, and build.
Optional: allowed_overrides enumerates which chain fields may be overridden at runtime. Unknown override keys are rejected by the schema.

Examples

Micro: tests/data/ogx/micro.ogx.json/manifest.json
Chr20: data/ogx/chr20_10M.ogx.json/manifest.json