OASYS tutorial files with simulation of ALS-U beamlines
Switch branches/tags
Nothing to show
Clone or download
Pull request Compare This branch is 15 commits ahead of lucarebuffi:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
ALS-U SXR Flagship beamline.ows
ALS-U TXR flagship beamline.ows
Looping and Scanning variable via Python scripts.ows
M3 Alignment sensitivity.ows
Shadow Source with SRW distributions.ows
Wavefront sensing.ows
[old]ALS_COSMIC-transition copy.ows



This repository contains a series of files that were used to demonstrate the capabilities of OASYS through scripting and widgets, and were used by Luca Rebuffi during a hands-on tutoral given at the ALS in March 2018 to provide real life examples on how these could be used to model ALS-U beamlines, the fourth generation synchrotron at Lawrence Berkeley National Lab.

Most of these capabilities have been ported to widgets, for easy reuse. These widgets can be found here, or via the Options>addons... menu in Oasys.

Questions relative to these scripts should be adressed to Antoine Wojdyla.

Please note that there are many other examples available here: https://github.com/oasys-kit/ShadowOui-Tutorial.


Mirror deformation under heatload

For DLSR and FEL, the first mirror (HHLO or HOMS) will experience a servere heatload, with the incident beam carrying up to 20kW. Even with very efficient cooling, the mirror will bulge and cause some wavefront error. We have studied these effects with FEM using ANSYS, and we provide a script that adequately loads the deformed mirror shape and allows to study the propagation.


A sample ANSYS deformation file is available here : 49_7.txt


We have written a script that allows to retrieve the wavefront after an element. For the script to work,


It seems that this element works well with toroidal mirrors, but at the moment compound focusing elements such as KB pairs seems to have some issues associated with the optical path. See "Hartmann sensor" below for a workaround

Wavefront analyzer

Decomposition of the wavefront on a Zernike basis. This requires poppy and might not work straight out of the box.


Tilt sensitivity analyzer

Since the misalignment of an optics can cause aberrations, it can be intersting to study the sensitivity to this misalignment. In this example, we show how in particular how astigmatism and coma change as a toroid is rotated along the tangential direction.

This is an example of use of poppy outside the OASYS environment, which can be useful if you couldn't make the previous example wrok (don't forget to install poppy by running pip install poppy in the terminal!)


Hartmann sensor

In order to get an unbiased estimate of the wavefront, it is possible to use the slope at a certain location in the beam to estimate the wavefront errors.

This is a workaround for the case where using the optical path length in the beam fails (e.g. many compounded optical elements or large source/incoherent illumination)

This is still under development: The reconstruction has numerical errors, and the units are not properly taken into account


Beamline energy resolution

We have written a script that allows to visualize various colors, to have a rough estimate of how the various wavelength blend during propagations and determine whether the resolution of the beamline will meet the specfications


Hettrick Underwood monochromator

The Hettrick Underwood monochromator is an example where the beam is focused before the monochromator (see MC Hettrick and JH Underwood "Stigmatic high throughput monochromator for soft x rays" (1986) for more information)

Notional ALS-U beamlines

Two of the notional beamline for the ALS-U project have been modeled using optical beamline simulations:

They bith aim at a 1:5000 energy resolution and a 5um beam at the exist slits, each operating in a different energy range (SXR: 250-1400eV; TXR:1-8keV)

Magic toroid configuration

Toroidal mirrors do exhibit severe aberrations, but there is a configuration in which the primary coma vanishes, leading to superior optical performances -- this is a first step towards the ideal diaboloid shape. For more information, see Appendix A in McDowell et al.(2004)

  • OASYS workspace: Magic_Toroid.ows

What we are working on

We are interested in a number of optical beamline simulations that could be helpful for the DLSR and FEL community:

  • determining the _actual volume of the phase space for an undulator (the σσ'> λ/4π approximation is only valid for gaussian sources; undulators seem to produce σσ'~λ/2π phase spaces in the blue region, and we would like to investigate this effect with the M^2 formalism
  • determining how the effective source position in an undulator varies with the wavelength under consideration (with SRW)
  • modeling of diaboloids, which are modified toroids that yield minimal aberrations (see McKinney et al. (2009))
  • we would like to see to what extent Forbes polynomials can be used to describe mirror shapes more accurately, possibly using QFit

Already integrated to OASYS

A few scripts we were working on have been integrated to the list of widgets in OASYS. Please refer to OASYS1-ALS-ShadowOui

Creating a source based on SRW calculation

Scanning a parameter for mirrors and gratings

How to make and use python scripts

Here is how to manipulate the beam in Oasys using python:

import Shadow

If you are going to modify the beam, make sure to duplicate the beams before you do so:

beam_hardcopy = in_object_1._beam.duplicate()

Ray attributes

Here's the Shadow Ray structure, so that you can access to specific properties within OASYS:

  1. position x in user units
  2. position y in user units
  3. position z in user units
  4. director cosine x (approx angle x' in rad)
  5. director cosine y
  6. director cosine z (approx angle z' in rad)
  7. electric field s-polarized Es_x
  8. electric field s-polarized Es_y
  9. electric field s-polarized Es_z
  10. flag: 1.0 the ray is good, <1 the ray is lost
  11. wavevector modulus: 2 pi / lambda
  12. ray index (starting from 1.0)
  13. optical path, in user units
  14. s-polarized phase Es_phi
  15. p-polarized phase Ep_phi
  16. electric field p-polarized Ep_x
  17. electric field p-polarized Ep_y
  18. electric field p-polarized Ep_z


Make sure you also explore these other tremendous resources: