Registry Quickstart: Fe_Pt_DN Example

This guide shows how to register and load reflectometry models via the VIPR registry. It covers local package registration and HuggingFace-backed usage.

Option A — Domain convenience command

Use this when a domain-specific bundle command exists (Reflectorch, Flow, PANPE). It assembles the package directory and manifest.yaml automatically.

vipr reflectometry registry bundle-reflectorch \
  --config  /path/to/storage/reflectorch/configs/NR-2layers-basic-v1.yaml \
  --weights /path/to/storage/reflectorch/saved_models/model_NR-2layers-basic-v1.safetensors \
  --name    NR-2layers-basic \
  --version v1.0.0 \
  --description "Reflectorch baseline model for neutron reflectometry (NR, 2 layers)"

Output:

Model package registered: vipr://local/reflectometry/NR-2layers-basic@v1.0.0

Option B — Generic bundle with manifest.yaml

Use this when no domain-specific bundle command exists, or when you need full control over package layout.

1. Assemble the package directory

my-package/
├── manifest.yaml
├── configs/
│   └── NR-2layers-basic-v1.yaml
└── saved_models/
    └── model_NR-2layers-basic-v1.safetensors

2. Compute SHA-256 checksums

sha256sum configs/NR-2layers-basic-v1.yaml
sha256sum saved_models/model_NR-2layers-basic-v1.safetensors

3. Write manifest.yaml

format_version: 1
name: NR-2layers-basic
version: v1.0.0
domain: reflectometry
family: reflectorch
description: "Reflectorch baseline model for neutron reflectometry (NR, 2 layers)"

model_builder:
  handler: reflectorch_builder
  parameters:
    config_ref: configs/NR-2layers-basic-v1.yaml
    weights_ref: saved_models/model_NR-2layers-basic-v1.safetensors

default_predictor:
  handler: reflectorch_predictor
  parameters:
    calc_pred_curve: true
    polish_prediction: true

requires:
  preprocess_filters:
    - class: vipr_reflectometry.reflectorch.preprocess.interpolation_filter.InterpolationFilter
      method: preprocess_interpolate
      hook: INFERENCE_PREPROCESS_PRE_FILTER

artifacts:
  - role: config
    path: configs/NR-2layers-basic-v1.yaml
    sha256: 30560abf286990b789a9f136502c2314b3d6e68440feec442070459e67d63500
  - role: weights
    path: saved_models/model_NR-2layers-basic-v1.safetensors
    format: safetensors
    sha256: 27ec0e6d0d084e54106e38092a4028162aacb54802867e99bc387d8307a47743

metrics: {}
tags:
  source: bundle-command
  family: reflectorch

artifacts.path must be relative and must not escape the package directory (../ traversal is forbidden). SHA-256 checksums are verified before builder code runs. Bundle commands do not emit lineage by default. Use --include-lineage if you want absolute source paths in the manifest.

4. Register the package

vipr registry bundle --manifest my-package/manifest.yaml --source-dir my-package/

Inspect and promote (local backend)

vipr registry list
vipr registry show vipr://local/reflectometry/NR-2layers-basic@v1.0.0
vipr registry promote vipr://local/reflectometry/NR-2layers-basic@v1.0.0 production
vipr registry show vipr://local/reflectometry/NR-2layers-basic@production

Option C — Use HuggingFace-backed registry

1. Enable HF backend

export VIPR_HF_REPO=HW-SC/registry

3. Use HF URI in inference config

load_model:
  handler: registry_loader
  parameters:
    model_uri: vipr://hf/reflectometry/fxc34ran@v1.0.0

HF backend notes:

  • use pinned versions (@v1.0.0), not aliases

  • vipr registry promote is local-only

  • requested versions are validated against index.yaml before download

  • packages are fetched from the repository main revision via versioned path <domain>/<name>/<version>/...

  • if a requested version is missing from index.yaml, VIPR fails early with Version not found in index

Device and builder overrides in registry_loader

You can override model-builder parameters from inference YAML without editing manifest.yaml:

load_model:
  handler: registry_loader
  parameters:
    model_uri: vipr://hf/reflectometry/fxc34ran@v1.0.0
    device: cpu
    builder_parameters:
      some_extra: value

builder_parameters is merged into model_builder.parameters in memory only.

Full inference examples

A) Local registry

vipr:
  inference:
    filters:
      INFERENCE_PREPROCESS_PRE_FILTER:
        - enabled: true
          weight: -10
          class: vipr_reflectometry.reflectorch.preprocess.error_bar_filter.ErrorBarFilter
          method: preprocess_error_bar_filter
          parameters:
            filter_threshold: 0.3
            filter_remove_singles: true
            filter_remove_consecutives: true
            filter_consecutive: 3
            filter_q_start_trunc: 0.1
        - enabled: true
          weight: 0
          class: vipr_reflectometry.flow_models.preprocess.flow_preprocessor.FlowPreprocessor
          method: preprocess_flow
          parameters: {}
    load_data:
      handler: csv_spectrareader
      parameters:
        data_path: '@vipr_reflectometry/examples/data/Fe_Pt_DN.dat'
        column_mapping:
          q: 0
          I: 1
    load_model:
      handler: registry_loader
      parameters:
        model_uri: vipr://local/reflectometry/fxc34ran@v1.0.0
        device: cpu
    prediction:
      parameters:
        num_samples: 4000
        q_resolution: 0.1
        seed: 42
    preprocess:
      handler: ''
      parameters: {}
    postprocess:
      handler: ''
      parameters: {}
  result_id: Fe_Pt_DN_registry_local
  config_name: Fe_Pt_DN_registry_local

B) HuggingFace remote registry

vipr:
  inference:
    filters:
      INFERENCE_PREPROCESS_PRE_FILTER:
        - enabled: true
          weight: -10
          class: vipr_reflectometry.reflectorch.preprocess.error_bar_filter.ErrorBarFilter
          method: preprocess_error_bar_filter
          parameters:
            filter_threshold: 0.3
            filter_remove_singles: true
            filter_remove_consecutives: true
            filter_consecutive: 3
            filter_q_start_trunc: 0.1
        - enabled: true
          weight: 0
          class: vipr_reflectometry.flow_models.preprocess.flow_preprocessor.FlowPreprocessor
          method: preprocess_flow
          parameters: {}
    load_data:
      handler: csv_spectrareader
      parameters:
        data_path: '@vipr_reflectometry/examples/data/Fe_Pt_DN.dat'
        column_mapping:
          q: 0
          I: 1
    load_model:
      handler: registry_loader
      parameters:
        model_uri: vipr://hf/reflectometry/fxc34ran@v1.0.0
        device: cpu
    prediction:
      parameters:
        num_samples: 4000
        q_resolution: 0.1
        seed: 42
    preprocess:
      handler: ''
      parameters: {}
    postprocess:
      handler: ''
      parameters: {}
  result_id: Fe_Pt_DN_registry_hf
  config_name: Fe_Pt_DN_registry_hf