Crate hyalite 

hyalite — exact, SIMD-accelerated pairwise/database sequence alignment in pure Rust.

A reimplementation and improvement of Opal (Rognes-style inter-sequence SIMD Smith-Waterman). hyalite is a Rust reimplementation of Opal and is not affiliated with or endorsed by the Opal authors.

Determinism contract

This is the crate’s primary guarantee, not an implementation detail:

For identical inputs, every backend returns bit-identical results: the same score, the same database index, the same query end position, and the same target end position. The selected backend affects performance only, never results.

Holding this is why scores use a single, once-defined signed-integer arithmetic model with a documented saturation boundary (see ScoreWidth), and why tie-breaks are resolved by a scalar argmax over database index rather than a lane-order-dependent horizontal max.

The full specification every backend must implement against — the arithmetic model, the score-width proof’s coverage of intermediate cells, the tie-break rules, and what is and is not promised — lives in DETERMINISM.md at the repository root.

Status

Under construction (milestone M0): scalar backend, all four alignment Modes, Score and ScoreEnd search types. SIMD backends, traceback, and the striped align_pair path land in later milestones — see handover.md.

Structs

BestHit

The best-scoring alignment found, carrying exactly the four fields the determinism contract pins: score, database index, query end position, and target end position.

Database

An immutable, thread-safe set of target sequences plus the resolved scoring, mode, search type, and score width to scan a query against. Build one with Database::builder.

DatabaseBuilder

A builder for Database. Required: sequences, scoring, mode, max_query_len. search_type defaults to SearchType::Score.

Scoring

A validated substitution-matrix-plus-affine-gap scoring scheme.

Scratch

Per-thread mutable working memory for Database::scan. Create one per worker thread and reuse it across scans; it holds no reference to the database, so it can outlive individual scan calls but should match the database it was sized for.

Enums

Backend

The alignment backend actually used, or one that could be requested.

BackendChoice

How a Database should pick its backend: detect automatically, or force a specific one (for the CI matrix and benchmarking).

Error

A construction-time error. These arise only while building a scoring scheme or database — never in the alignment hot path, which is infallible by design.

Layout

The kernel data layout for the substitution scores, reported by Database::layout. Like the backend and score width, the layout is a performance choice only — it never changes results (see DETERMINISM.md).

LayoutChoice

How a Database chooses its kernel Layout: automatically from the database size, or forced (for benchmarking or pinning behaviour).

Mode

The alignment mode: which sequence ends are free (unpenalised) and whether the score is clamped to be non-negative (local).

ScoreWidth

The signed integer width a kernel runs in. The most-negative value is reserved as a saturation sentinel and is not a usable score.

SearchType

What the search computes and returns.

Constants

BACKEND_ENV_VAR

The environment variable that overrides backend selection at build.

Functions

align_pair

Align a single query against a single target and return the best-scoring BestHit.

Type Aliases

Result

Result alias for fallible hyalite construction paths.