Module models 

Registry of deep-learning QSM models and their downloadable ONNX weights.

Query the catalog with models::all_models / models::find_model. Native hosts fetch weights on use with the download feature; the onnx feature runs them via the pure-Rust tract engine from a byte buffer (native and WASM). Deep-learning model registry and weight management.

Several QSM stages have deep-learning implementations (BFRnet, QSMnet, xQSM, χ-sepnet, …). QSM-Core runs them via ONNX rather than bundling a Python/PyTorch/TensorFlow runtime. The trained weights are not vendored in this crate — they are fetched on first use and cached on disk.

This module is the single source of truth for which models exist and where/how to obtain their weights. It is split into three layers:

• Registry (always compiled). [ModelSpec] / [WeightFile] describe each model and its weight files (URL, SHA-256, size, license). [all_models] / [find_model] query the table. This layer has no heavy dependencies and is safe to expose through the WASM bindings so a JavaScript host (e.g. qsmbly) can discover download URLs and fetch weights itself.
• Download & cache (download feature). [download::ensure_model] fetches any missing weight files over HTTP, verifies their SHA-256, and stores them in a local cache. This is the path a native host (e.g. QSMxT) uses to “download on use”. WASM hosts skip this layer.
• Inference (onnx feature). Runs an ONNX graph with the pure-Rust tract engine. The entry points take the model as a byte buffer ([onnx::OnnxModel::load]) rather than a path, so the same inference code runs natively and in WASM. A native host feeds bytes from the download cache; a WASM host (e.g. qsmbly) fetches the weights in JavaScript and passes the bytes back into WASM to run.

The registry stays runtime-agnostic: tract is the default portable engine, but a host is free to read a model’s URLs from the registry and run it any other way.

Weight resolution order (native)

1. $QSM_MODEL_DIR/<file> — an explicit directory of local weight files (bring-your-own-weights; also how gated models like χ-sepnet are supplied).
2. The on-disk cache ([cache_dir]), if the file is present and its SHA-256 matches.
3. Download from [WeightFile::url] into the cache (download feature).

Modules

download

Native weight download and on-disk cache (download feature).

onnx

ONNX inference via the pure-Rust tract engine (onnx feature).

registry 🔒

The static table of known deep-learning QSM models.

Structs

ModelSpec

A deep-learning QSM model and everything needed to obtain and run it.

WeightFile

One weight file a model needs at inference time (an exported .onnx, plus any auxiliary file such as normalization statistics).

Enums

Framework

The framework the weights were originally trained in (before ONNX export).

ModelStage

The reconstruction stage a model implements.

WeightStatus

Whether a model’s weights are hosted and ready to run.

Functions

all_models

All models known to QSM-Core, in a stable order.

all_weight_bytes

Read every weight file of a model, in registry order, for native inference.

cache_dir

Root directory for cached weight files.

cache_path

The path a weight file would occupy in the cache (whether or not it exists).

find_model

Look up a model by its ModelSpec::id (case-sensitive), e.g. "qsmnet".

prefetch_with_progress

Pre-fetch (download + cache) all of a model’s weight files, reporting per-file progress via on_progress(file_name, downloaded_bytes, total_bytes).

primary_weight

Convenience: resolve a model by id and read its primary weight file. Combines find_model + primary_weight_bytes so callers (pipeline runners, external hosts) don’t repeat the lookup+fetch boilerplate. Errors if the id is unknown.

primary_weight_bytes

Read the bytes of a model’s primary (first) weight file for native inference.

resolve_local

Find an already-present copy of file without downloading, honoring the $QSM_MODEL_DIR override first, then the cache. Returns None if absent.

weight_file_bytes 🔒

Resolve one weight file to its bytes (local override / cache, then download).

weights

Convenience: resolve a model by id and read all its weight files, in registry order (for multi-file models like NeXtQSM). See all_weight_bytes.