Docs · Omnis platform

Platform, pipeline, and proof docs

Use this docs shell for CLI workflows, architecture, benchmark contracts, and public operating guidance across the Omnis platform.

CLIArchitectureBenchmarksDeployment

Viewing

OGX spec

Docs overview OGN CLI quickstart BioFlow API reference Benchmark pack

Need another page?

Search the docs

Jump to buyers, verification, demos, self-hosting, or adapters without opening the full docs tree first.

Key sections

Purpose Manifest (manifest.json) fields Chain params (chain_params.json)File layout Runtime override precedence OGX ingest semantics (for OGC and benchmarks)

Mobile navigation

Jump to section

Open

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)

JSONReference snippet

{
  "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

CodeReference snippet

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:

CodeReference snippet

[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