diff --git a/Aramis-Intensity-Diagnostics/PBPS-calibration-guide.md b/Aramis-Intensity-Diagnostics/PBPS-calibration-guide.md index a0093cf..57508c4 100644 --- a/Aramis-Intensity-Diagnostics/PBPS-calibration-guide.md +++ b/Aramis-Intensity-Diagnostics/PBPS-calibration-guide.md @@ -1,27 +1,104 @@ -## Operating principle -Single shot diagnostic to measure relative pulse energy and beam position. Back-scattered X-rays from a thin target (typically 50 nm silicon nitride) are measured by four photodiodes positioned above, below, left and right of the X-ray beam. - -Position data maintains FEL pointing, while single-shot pulse energy measurements are used to normalise experiment data. There is one PBPS in the front-end and two further devices per end station. - -## How to use - -1. Open photon diagnostics [web app](https://sf-photodiag.psi.ch/app) -2. Under Position/calibration tabs,s elect device from drop down menu 1 -3. Select target from drop down menu 2 - default target is 50nm Si3N4 -4. Press calibrate - - -The calibration procedure normalizes the response of the 4 diodes, then scans the device horizontally and vertically over the FEL beam to calibrate the position response. - -Once completed (approx 1 minute) the plots are updated with the calibration response. Plotted on the x axis is the device motor position (horizontal - left plot and vertical - right plot) and on the y axis is plotted the normalized horizontal or vertical diode pair response. For a good setup the plot should be a straight line through the 3 data points. - -If you are happy with the calibration, press the "Push results/elog" button where the new calibration data is sent to the required data processing pipelines. After an automated restart (~30 seconds) both PV and BS position and intensity data will be calculated with the new calibration. An elog entry is made detailing the calibration data. - -## Error -**Soft limits** -Error message: `ERROR: Motor position outside soft limits` -Problem is a soft limit on either the device Motor X or Y is blocking the scan motion -1. Select all from drop down menu for motor X and motor Y of PBPS GUI (shown below) -2. Change motor soft limits to 1 and -1 for both motors -3. Retry calibration - \ No newline at end of file +## Operating Principle +The PBPS (Photon Beam Position Solid) is a **single-shot diagnostic** used to measure **relative pulse energy and beam position**. It functions by detecting **back-scattered X-rays** from a thin target, typically a **50 nm silicon nitride (Si3N4) film**. The scattered X-rays are captured by four **photodiodes** arranged around the beam: + +- **Top** (Up) +- **Bottom** (Down) +- **Left** +- **Right** + +These measurements are critical for: +- **FEL pointing stability** (by tracking beam position) +- **Experimental data normalization** (by measuring pulse energy) + +SwissFEL features **one PBPS in the front-end** and **two PBPS devices per end station**. + +--- + +## How to Use +### **1. Open the Photon Diagnostics Web App** +[Click here to open](https://sf-photodiag.psi.ch/app) + +### **2. Select the PBPS Device** +- Navigate to the **Position** or **Calibration** tab. +- In the **first dropdown menu**, select the PBPS device you want to calibrate. + +### **3. Choose the Target** +- In the **second dropdown menu**, select a target. +- **Default target:** **50nm Si3N4**. + +### **4. Start Calibration** +- Press the **Calibrate** button. +- The system will: + - Normalize the response of the **four photodiodes**. + - **Scan the PBPS device** horizontally and vertically across the FEL beam. + - **Update the plots** with the calibration response (takes ~1 minute). + +### **5. Analyze the Results** +- The updated plots show: + - **X-axis** → Device motor position (**Horizontal: left plot**, **Vertical: right plot**) + - **Y-axis** → Normalized **horizontal or vertical diode pair response** +- **A good calibration** results in a **straight line** passing through the three scan points. + +### **6. Push the Calibration Results** +- If the calibration looks good, press **"Push results/elog"**. +- This updates the data processing pipeline and generates an **elog entry**. +- After an **automated restart (~30s)**, the **PV and BS position & intensity data** will be updated with the new calibration. + + + +--- + + +The calibration procedure normalizes the response of the 4 diodes, then scans the device horizontally and vertically over the FEL beam to calibrate the position response. + +Once completed (approx 1 minute) the plots are updated with the calibration response. Plotted on the x axis is the device motor position (horizontal - left plot and vertical - right plot) and on the y axis is plotted the normalized horizontal or vertical diode pair response. For a good setup the plot should be a straight line through the 3 data points. + +If you are happy with the calibration, press the "Push results/elog" button where the new calibration data is sent to the required data processing pipelines. After an automated restart (~30 seconds) both PV and BS position and intensity data will be calculated with the new calibration. An elog entry is made detailing the calibration data. + + +## Troubleshooting +### **Soft Limits Error** +#### **Error Message:** +`ERROR: Motor position outside soft limits` + +#### **Cause:** +- The PBPS **Motor X or Y** has hit a **soft limit**, preventing the scan. + +#### **Solution:** +1. **Open the PBPS GUI** and locate the motor settings. +2. **Modify the soft limits**: + - Set **Motor X soft limits** to `-1` and `1` + - Set **Motor Y soft limits** to `-1` and `1` +3. **Retry Calibration**. + +### **Additional Debugging Tips** +- Ensure the **PBPS device is correctly selected**. +- Verify that the **target is installed properly**. +- Try manually moving the motor **in small steps** to check functionality. +- If the issue persists, check for **elog messages** indicating motor faults. + +--- + +## FAQ +**Q: How do I know if my calibration was successful?** +A: If the diode response fits a straight line and the y-axis range is a few percent, your calibration is good! + +**Q: What happens if I push bad calibration results?** +A: The **old calibration** will be overwritten, which may cause **incorrect beam position data**. Make sure to verify results before pushing. + +**Q: Why does calibration fail even after adjusting soft limits?** +A: The device may be in a fault state. Try **resetting the motor controller** or checking the motor motion is completing by checking the motor GUI. + +--- + +## 🎭 **Do Say / Don't Say** + +✅ **Do Say:** +- *"I just calibrated PBPS like a ninja!"* +- *"Let’s push these results to elog!"* + +❌ **Don't Say:** +- *"What’s a soft limit?"* +- *"Do I really need to calibrate this thing?"* + +---