Tutorial on Beamline Simulation - �Example Beamline in OASYS2.0 – BL18 HAXPES�

Thomas Rabedeau – SSRL

rabedeau@slac.stanford.edu

September 20, 2026

1

Oasys2/Shadow4 Concepts Explored

2

• SSRL BL18 HAXPES - Illustrate selected Oasys2/Shadow4 concepts using native capabilities without scripting (i.e., old school, manual ray tracing BL configurations)
• Concepts explored:
• Geometric undulator source approximation, save/load source rays
• Mirror set up
• Mirror shape error effect estimation using DABAM mirror data base
• Mirror shape error effect using mirror height error data (e.g., FEA, metrology,…)
• Beam coordinate system rotation (aka preserving what’s up)
• Four bounce dispersive mono system (two DCM in series)
• Native loop management for (single) variable scans – BDA size
• Native loop management with (multiple) attribute files – hKB2 shape error
• Full undulator source build
• Shadow Monte Carlo flux normalization using Spectra

​

BL18 Model - Oasys Widgets Employed

3

SSRL BL18 HAXPES – IVU w/ DCM and 2-Stage Focusing

4

SSRL BL18 HAXPES Optics Model

5

Idealized Geometric Source

6

Advantages

• simple source to initially debug model
• adequate for simple sources with on-axis viewing

Disadvantages

• does not faithfully represent source complexities especially off-axis wigglers or undulators (I would not use for flux calcs)

Where can I find SPEAR electron source characteristics?

• https://www-ssrl.slac.stanford.edu/ssrl/web/spear3#parameters--2/
• need to “dress” electron sigma and sigma’ (emission angles) with photon sigma_r and sigma_r’ (Elleaume formulation)
• sig_r = √(λ*2L) / 2π where L is ID length
• sig_r’ = √(λ/2L)
• sig_x_eff = √(sig_x^2 + sig_r^2)
• sig_x’_eff = √(sig_x’^2 + sig_r’^2)
• similar for sig_y_eff and sig_y’_eff
• for bends or wigglers include the radiation cone angle for photon energy of interest (see the CXRO orange book https://xdb.lbl.gov/Section2/Sec_2-1.html )

​

Shadow4 Geometric Source - “BL18 Undulator”

7

execute & write file

Shadow4 Geometric Source - “BL18 Undulator”

8

SSRL BL18 HAXPES Optics Model - Mirrors

9

Side Deflecting, Focusing Mirror - hKB

10

side deflecting

Focusing Mirror – DABAM Shape Error

11

Focusing Mirror – DABAM Shape Error

12

Focusing Mirror – Incorporating Height Error Data

13

mm units

Side Deflecting Optic Rotates Coordinate System

14

Often easier to keep track if you rotate the coordinate system back to the lab frame after a side deflecting optic. Use the empty element to do so.

SSRL BL18 HAXPES Optics Model - Monochromator

15

Double Crystal Mono (DCM)

16

For DCM2 dispersive to DCM1, add DCM2 1^st crystal with 0° rotation

wrt DCM1 2^nd crystal and

DCM2 2^nd crystal with 180°

rotation wrt DCM2 1^st crystal

DCM1 2^nd crystal orientation 180° with appropriately small source plane distance

DCM1 1^st crystal

Native Loop Single Variable Scan – DBA size

17

BL18 uses two-stage horizontal focusing where hKB focuses on a beam defining aperture (BDA) and hKB2 images the BDA to the sample position with 3:1 demagnification. This is a good opportunity to explore the effect of changing BDA size on the focus by scanning the BDA in a loop.

Native Loop Single Variable Scan – DBA size

18

linger mouse to display variable name

clear stored data before starting scan!!!

Native Loop Single Variable Scan – DBA size

19

Native Loop Scan with Attribute Files – hKB2 Shape Error

20

hKB2 images the BDA to the sample with 3:1 demagnification, but the image quality is impacted by hKB2 shape error. This is a good opportunity to explore the effect of changing hKB2 shape error in an attribute file scan loop.

Native Loop Scan with Attribute Files – hKB2 Shape Error

21

Native Loop Scan with Attribute Files – hKB2 Shape Error

22

Undulator Beam Structure

23

​

​

A real undulator beam has structure at harmonics of the fundamental photon energy. Flux curve below shows 7^th (left) and 8^th (right) harmonics.

emission not Gaussian

Undulator Beam Structure

24

A real undultor provides a more complex emission spectra that varies with undulator gap, slit acceptance, and mono photon energy

Undulator Beam Structure

25

A real undultor provides a more complex emission spectra that varies with undulator gap, slit acceptance, and mono photon energy

• need to match slit acceptance and DCM tune energy to undulator spectra
• eg., generous acceptance in the vertical will “red shift” the energy where flux through mono is maximized while conversely a narrow acceptance will “blue shift”

Undulator Source Build and Save for Repetitive Use

26

One of the compromises to converting Shadow to Python for maintenance simplification is it slowed down the execution especially, seemingly, the undulator simulation. A work around is to save the undulator rays to a named file for later read in.

https://journals.iucr.org/s/issues/2025/02/00/yn5118/index.html

Source – Undulator Monte Carlo Scaling to Photon Flux

27

1. Run the undulator Monte Carlo ray set through a slit.
2. Run Spectra (https://spectrax.org/spectra/) output through the same slit configuration and correct flux generated to desired bandwidth (e.g., 2eV) instead of the generic 0.1% BW.
3. Ratio Spectra flux thru the slit by Shadow MC rays thru the slit to get scaling relationship between MC rays and flux.

​

​

(the end)

28