VIPR Framework - CLI Reference¶

Complete command reference for the VIPR command-line interface.

Table of Contents¶

Command Overview
Inference Commands
Compare Commands
Registry Commands
Plugin Commands
Help Commands
Configuration
Common Workflows
Troubleshooting

Command Overview¶

vipr [OPTIONS] COMMAND [ARGS]

Global Options:

--config PATH - Path to configuration file (required for most commands)
--version - Show VIPR version
--help - Show help message

Inference Commands¶

Run Inference¶

Execute the full inference workflow with the specified configuration.

vipr --config <path-to-config> inference run

Examples:

# Using package notation
vipr --config @vipr_reflectometry/reflectorch/examples/configs/PTCDI-C3.yaml inference run

# Using relative path
vipr --config ./config.yaml inference run

# Using absolute path
vipr --config /path/to/config.yaml inference run

Example configs shipped in vipr-framework/examples/:

Fe_Pt_DN_Reflectorch.yaml - Iron/Platinum (spin-down) on Air/MgO
Fe_Pt_DN_Reflectorch_broad_bounds.yaml - Same sample with broader thickness bounds for the first layer
Fe_Pt_DN_NSF_model.yaml - Fe/Pt example using the NSF model setup
README.md - Overview of the shipped example workflows

If you are running from the vipr-framework repository root, you can use:

vipr --config ./examples/Fe_Pt_DN_Reflectorch.yaml inference run

Compare Commands¶

Compare existing stored results without rerunning inference.

Run Compare¶

vipr compare run --results <result-a> <result-b> [<result-c> ...]

Examples:

# Compare two stored results by full ID
vipr compare run --results 3a2d7b6e-... 51f9b3c1-...

# Compare using unambiguous short prefixes
vipr compare run --results 3a2d7b6e 51f9b3c1

# Use a YAML config
vipr --config ./examples/Fe_Pt_DN_compare.yaml compare run

# Set an explicit result ID for the generated compare result
vipr compare run --results RESULT_A RESULT_B --result-id my_compare_run

Compare example config shipped in vipr-framework/examples/:

Fe_Pt_DN_compare.yaml - Compare the stored results Fe_Pt_DN, Fe_Pt_DN_broad_bounds, and Fe_Pt_DN_NSF_model

CLI Options:

--results - Stored result IDs or unambiguous short UUID prefixes to compare
--result-id - Optional explicit result ID for the stored compare result

Config-based compare fields:

compare:
  results:
    - Fe_Pt_DN
    - Fe_Pt_DN_broad_bounds
    - Fe_Pt_DN_NSF_model
  result_id: Fe_Pt_DN_compare
  overlay:
    series_kinds:
      - polished
    include_experimental: true

Notes:

Compare requires at least two distinct stored results.
CLI values override compare.results and compare.result_id from YAML config.
The generated compare output is stored as a normal result with result_kind = compare.

Registry Commands¶

Query the component registry to discover available handlers, filters, and hooks.

List All Components¶

vipr discovery components

List Specific Component Types¶

# List available predictors
vipr discovery predictors

# List available data loaders
vipr discovery data-loaders

# List available model loaders
vipr discovery model-loaders

# List available hooks
vipr discovery hooks

# List available filters
vipr discovery filters

Filter by Plugin¶

# Show only components from specific plugin
vipr discovery predictors --plugin reflectometry

Show Plugin Summary¶

vipr discovery plugins

Plugin Commands¶

List Installed Plugins¶

vipr plugins list

Shows all plugins currently installed in your environment.

Help Commands¶

General Help¶

vipr --help

Command-Specific Help¶

# Inference help
vipr inference --help

# Registry help
vipr discovery --help

# Plugins help
vipr plugins --help

Configuration¶

Config Path Formats¶

VIPR supports three configuration path formats:

1. Package Notation¶

Access configs bundled with plugins using @package/path syntax:

vipr --config @vipr_reflectometry/reflectorch/examples/configs/PTCDI-C3.yaml inference run

2. Relative Path¶

Paths relative to your current working directory:

vipr --config ./my-configs/config.yaml inference run

3. Absolute Path¶

Full filesystem paths:

vipr --config /home/user/vipr/configs/config.yaml inference run

Inference Config Structure¶

Basic YAML structure for vipr --config ... inference run:

vipr:
  inference:
    # Data loading
    load_data:
      handler: csv_spectrareader
      parameters:
        data_path: './data.txt'
        column_mapping:
          q: 0
          I: 1
    
    # Model loading
    load_model:
      handler: reflectorch
      parameters:
        config_name: b_mc_point_xray_conv_standard_L2_InputQ
    
    # Preprocessing filters
    filters:
      INFERENCE_PREPROCESS_PRE_FILTER:
        - class: vipr_reflectometry.reflectorch.preprocess.interpolation_filter.InterpolationFilter
          method: preprocess_interpolate
          enabled: true
    
    # Prediction
    prediction:
      handler: reflectorch_predictor
      parameters:
        polish_prediction: true
        prior_bounds:
          roughnesses: [[0, 20], [0, 15], [0, 15]]
          slds: [[10, 13], [20, 21], [20, 21]]
          thicknesses: [[1, 400], [1, 10]]
          q_shift: [-0.002, 0.002]
          r_scale: [0.9, 1.1]

This example shows an inference configuration under vipr.inference. Compare-specific YAML uses the top-level compare: section shown in the Compare Commands section above.

Key Sections:

load_data: Specifies data source and format
load_model: Defines which ML model to use
filters: Custom preprocessing/postprocessing hooks
prediction: Inference execution parameters

Common Workflows¶

1. Test Installation¶

# Run example
vipr --config @vipr_reflectometry/reflectorch/examples/configs/PTCDI-C3.yaml inference run

# Check results
ls storage/results/

2. Run with Custom Data¶

# Create custom config (modify data_path)
cp example-config.yaml my-config.yaml

# Edit my-config.yaml to point to your data file

# Run inference
vipr --config ./my-config.yaml inference run

3. Explore Available Components¶

# See all available components
vipr discovery components

# Check specific component types
vipr discovery predictors
vipr discovery data-loaders

# Filter by plugin
vipr discovery predictors --plugin reflectometry

4. Compare Existing Results¶

# First generate inference results
vipr --config ./Fe_Pt_DN_Reflectorch.yaml inference run
vipr --config ./Fe_Pt_DN_Reflectorch_broad_bounds.yaml inference run
vipr --config ./Fe_Pt_DN_NSF_model.yaml inference run

# Then compare the stored outputs
vipr --config ./Fe_Pt_DN_compare.yaml compare run

5. Develop with Custom Plugin¶

# List current plugins
vipr plugins list

# Install your plugin
pip install -e /path/to/your/plugin