# 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. ```bash 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: ```text 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 ```text my-package/ ├── manifest.yaml ├── configs/ │ └── NR-2layers-basic-v1.yaml └── saved_models/ └── model_NR-2layers-basic-v1.safetensors ``` ### 2. Compute SHA-256 checksums ```bash sha256sum configs/NR-2layers-basic-v1.yaml sha256sum saved_models/model_NR-2layers-basic-v1.safetensors ``` ### 3. Write manifest.yaml ```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 ```bash vipr registry bundle --manifest my-package/manifest.yaml --source-dir my-package/ ``` ## Inspect and promote (local backend) ```bash 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 ```bash export VIPR_HF_REPO=HW-SC/registry ``` ### 2. Prefetch registry packages (optional but recommended) ```bash vipr registry sync vipr registry sync --domain reflectometry --name fxc34ran ``` ### 3. Use HF URI in inference config ```yaml 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 `///...` - 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`: ```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 ```yaml 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 ```yaml 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 ```