# Installation and Getting Started with VIPR CLI

> 📊 **Presentation:** For a visual overview, see the [VIPR CLI Introduction Presentation](docs-sphinx/docs/VIPR%20CLI%20introduction.pdf)

## Prerequisites

- **Python Version**: Python 3.10 or higher (minimum: Python 3.10)
- **Access**: Helmholtz Codebase GitLab account at https://codebase.helmholtz.cloud/vipr

---

## Step 1: Prepare Virtual Environment

### Find available Python installations

**Linux:**
```bash
# List system Python installations
ls /usr/bin/python*

# Check installed versions
python3 --version
python3.10 --version
python3.11 --version
```

**macOS:**
```bash
# Check versions
python3 --version

# List all Python installations in PATH
which -a python python3

# Check Framework installations
ls /Library/Frameworks/Python.framework/Versions/
```

### Create virtual environment with Python 3.10+

**Using python3 (if it's 3.10+):**
```bash
python3 -m venv myenv310
```

**Using specific version:**
```bash
# Linux
python3.10 -m venv myenv310

# macOS (Framework installation)
/Library/Frameworks/Python.framework/Versions/3.10/bin/python3 -m venv myenv310
```

### Activate the virtual environment

```bash
source myenv310/bin/activate
```

---

## Step 2: Authentication Setup (Optional)

You can install the public VIPR repositories from `codebase.helmholtz.cloud/vipr` without authentication. A Personal Access Token is only needed for private repositories such as `vipr-gid-plugin`.

**→ See [Authentication Setup Guide](docs-sphinx/docs/setup/authentication.md) for detailed instructions with screenshots.**

**Quick Summary:**
- Public repositories such as `vipr-core` and `vipr-reflectometry-plugin` do **not** require a token
- For private repositories, create a token at: [Personal Access Tokens](https://codebase.helmholtz.cloud/-/user_settings/personal_access_tokens)
- Required scope for private repo access: `read_repository`

---

## Step 3: Install VIPR Core

Install VIPR Core using pip from the GitLab repository:

```bash
pip install git+https://codebase.helmholtz.cloud/vipr/vipr-core.git
```

**Example:**

```bash
(myenv310) user@machine vipr-cli % pip install git+https://codebase.helmholtz.cloud/vipr/vipr-core.git
  Resolved https://codebase.helmholtz.cloud/vipr/vipr-core.git to commit 5f150cc07fb19060ebcfe8b79d61a2b844ae520d
  Installing build dependencies ... done
  Getting requirements to build wheel ... done
```

---

## Step 4: Install VIPR Reflectometry Plugin

```bash
pip install git+https://codebase.helmholtz.cloud/vipr/vipr-reflectometry-plugin.git
```

---

## Step 5: Perform Test Prediction

Run a test inference using an example configuration:

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

### Expected Output

The system will:
1. Load the Reflectometry plugin
2. Discover and register external plugins
3. Load the neural network model from HuggingFace (if not cached locally)
4. Process the example data
5. Generate predictions

![VIPR CLI Output](docs-sphinx/docs/images/vipr_cli_output.png)
*Example terminal output showing successful inference workflow*

### Workflow Steps

The inference workflow includes:

1. **Loading data** - Reads CSV/DAT/TXT reflectometry data
2. **Loading model** - Downloads model configuration and weights from HuggingFace (if needed)
3. **Normalizing data** - Applies data normalization
4. **Preprocessing data** - Interpolates spectra using Reflectorch
5. **Performing prediction** - Runs the neural network inference
6. **Postprocessing results** - Creates matplotlib visualizations of reflectivity curves and SLD profiles, exports data tables as CSV

### Model Information

**Example Model:** `b_mc_point_xray_conv_standard_L2_InputQ`
- **Parameters**: 5.02 M
- **Parameterization**: `standard_model` with 2 layers (8 predicted parameters)

**Parameter Ranges:**
- **Thicknesses**: [1.0, 500.0] nm
- **Roughnesses**: [0.0, 60.0] Å
- **SLDs**: [0.0, 50.0] × 10⁻⁶ Å⁻²

**Training Details:**
- Trained on curves discretized at exactly 128 uniform points
- Q range: q_min in [0.001, 0.03] Å⁻¹, q_max in [0.1, 0.4] Å⁻¹

### Results

Results are stored in the local storage directory (`storage/results/`) relative to your current working directory (PWD):
- Predicted reflectivity curves (CSV)
- Polished predictions (CSV)
- SLD profiles (CSV)
- Visualization plots (PNG)


**Example Result Directory Structure:**

```
storage/
└── reflectorch/
    └── results/
        └── 38ac6778-6e5c-4140-8db0-841ff245152b/
            ├── diagrams/
            │   ├── reflectivity_primary_Experimental.csv
            │   ├── reflectivity_primary_Polished.csv
            │   ├── reflectivity_primary_Predicted.csv
            │   ├── residuals_vs_q_Polished.csv
            │   ├── residuals_vs_q_Predicted.csv
            │   ├── sld_profile_Polished_SLD.csv
            │   └── sld_profile_Predicted_SLD.csv
            ├── images/
            │   └── reflectivity_matplotib.png
            └── tables/
                └── model_parameters.csv
```

---

## Troubleshooting

### Runtime plugin config not found

If you see:
```
VIPR: Runtime plugin config not found: /path/to/vipr-plugins.yaml
```

This is a warning and can be safely ignored for basic usage. The system will use default plugin configurations.

### Model downloads

After installing the required plugins, provision models explicitly:

```bash
vipr huggingface download
```

Subsequent runs will use the already downloaded files.

---

## Working Directory

⚠️ **Important:** VIPR uses relative paths for:
- **Data files** specified in configuration files
- **Result storage** (controlled by `VIPR_RESULTS_DIR` environment variable, defaults to `storage/results`)
- **Configuration file paths**

### Best Practices

**Option 1: Consistent Execution Directory (Recommended)**
```bash
# Always execute vipr commands from the same directory
cd vipr-framework/
vipr --config path/to/config.yaml inference run
vipr ui get-result --id <uuid>
```

**Option 2: Absolute Paths**
```bash
# Use absolute paths for all file references
export VIPR_RESULTS_DIR=/absolute/path/to/storage/results
vipr --config /absolute/path/to/config.yaml inference run
```

### Common Issues

**Problem:** `Exception: UI result <uuid> not found`

**Cause:** Executing vipr commands from different directories creates separate result storage locations.

**Example:**

```bash
# Inference runs from vipr-framework/ → stores in vipr-framework/storage/results/
cd vipr-framework/
vipr --config config.yaml inference run

# Result retrieval from vipr/ → looks in vipr/storage/results/
cd ..
vipr ui get-result --id <uuid>  # ❌ Not found!
```

**Solution:** Execute from the same directory or use absolute paths.

---

## Next Steps

- Explore other example configurations from the [Reflectometry plugin](https://codebase.helmholtz.cloud/vipr/vipr-reflectometry-plugin): `@vipr_reflectometry/reflectorch/examples/configs/`
- Prepare your own reflectometry data (CSV/DAT/TXT format) - see [Using Custom Configs](docs/installation/cli.md#test-with-custom-config) for details
- Customize prediction parameters using YAML configuration files - see [Configuration Guide](docs/plugins/built-in/inference.md#basic-configuration-structure)
- Check the web app documentation for interactive visualization options - see [Web App Setup Guide](VIPR_web_app.md)
