cryosim/docs/calibration_tutorial.md

# CryoSim Calibration Tutorial

## Overview
This guide walks through calibrating CryoSim against test data from a real pump campaign.

## Step 1: Load Raw Data
```python
from cryosim.data.loader import load_test_data

df = load_test_data("path/to/test_campaign.csv", ft140_correction=11.4)
print(df.head())
print(f"Duration: {df.index[-1] - df.index[0]}")
```

## Step 2: Extract Fills
```python
from cryosim.data.loader import extract_fills

fills = extract_fills(df)
print(f"Found {len(fills)} fills")
for f in fills:
    print(f"  {f['start']} → {f['end']}: {f['P_start']:.0f} → {f['P_peak']:.0f} bar")
```

## Step 3: Convert to Calibration Format
```python
from cryosim.data.loader import fills_to_calibration_input

cal_fills = fills_to_calibration_input(fills, speed_scale=0.664)
```

## Step 4: Run Calibration
```python
import cryosim

result = cryosim.calibrate(hardware="old_icv", fills=cal_fills, maxiter=200)
print(result)
result.save_yaml("my_calibrated_config.yaml")
```

## Step 5: Validate
```python
for f in cal_fills:
    pred = cryosim.predict(hardware="my_calibrated_config.yaml", 
                           Pexit=f['Pexit_barg'], speed=f['speed_f'])
    error = abs(pred.mdot_kgpm - f['measured_mdot_kgpm']) / f['measured_mdot_kgpm'] * 100
    print(f"  P={f['Pexit_barg']:.0f}: predicted={pred.mdot_kgpm:.3f}, "
          f"measured={f['measured_mdot_kgpm']:.3f}, error={error:.1f}%")
```

## Notes
- FT140 readings are ~11.4x too high for LH2 (Coriolis meter density mismatch)
- Speed scale factor: LH2=0.664, LN2=5.0 (maps VFD% to model speed fraction)
- Example fills are in `cryosim/data_files/examples/example_fills.json`
- The flow cliff (~370-390 bar at 65% speed) is the most challenging region to calibrate