This computer is used to control beamline hardware, set up and align samples, and run scans. Navigate across screens using ctrl + alt + up/down arrow
Open terminal app by going to Applications and clicking on the terminal icon. Can open multiple tabs using File --> New Tab. Can right click on tabs to rename them as Phoebus, PyDM, Bluesky, etc.
Start nbs-gui
(Only for first-time setup) First, git pull the contents of livetable, nbs-bl, nbs-core, nbs-gui, and nbs-viewer located in /home/xf07id1/xraygui to ensure the most up-to-date versions are used. Then pip install --no-build-isolation -e all of these packages for first time setup. This can be done in the terminal or in the visual studio code. Then run nbs-viewer(this may no longer be necessary?).
Activate the appropriate environment if necessary (e.g., conda activate 2024-2.3-py311-tiled).
For first-time setup, run qsstart (queue server start) and leave this open. The following output is an example that indicates that QueueServer has fully started.
[I 2025-08-29 17:34:24,894 bluesky_queueserver.manager.manager] Starting ZMQ server at 'tcp://*:60615'
[I 2025-08-29 17:34:24,894 bluesky_queueserver.manager.manager] ZMQ control channels: encryption disabled
[I 2025-08-29 17:34:24,902 bluesky_queueserver.manager.manager] Starting RE Manager process
[I 2025-08-29 17:34:24,926 bluesky_queueserver.manager.manager] Loading the lists of allowed plans and devices ...
[I 2025-08-29 17:34:25,703 bluesky_queueserver.manager.manager] Starting ZeroMQ server ...
[I 2025-08-29 17:34:25,703 bluesky_queueserver.manager.manager] ZeroMQ server is waiting on tcp://*:60615
Open the GUI by running guistart. The GUI also can be opened by running nbs-gui --profile collection.
After the GUI opens, start queue server by going to the Queue Control tab, clicking Connect (this requires qsstart to be run already), and then clicking Open.
If any updates are made to the code, hit Close then Open in the Queue Server box on the GUI to update new code. To check that functions have updated, the IPython Kernel can be used to type the function name followed by ?? to check that updates are visible.
Open the live viewer by running viewerstart in a new tab.
Note that the GUI has some additional coding constraints than does running Bluesky in the terminal, so certain errors may appear while attempting to open the GUI even if Bluesky were to open with no errors.
Start phoebus
In the terminal app, run:
run-phoebus
The phoebus GUI should open. If it looks different, reloading one of the saved layouts should reset it.
Phoebus GUI
The currents archiver may need to be reloaded from /xf07id1/css-workspace-xf07id/CSS/RSoXS_Currents_archiver.plt.
Although mostly obsolete, the predecessor, CS-Studio can be opened by running run-css.
Start PyDM
Open a new tab in the terminal app (File --> New Tab).
Run:
conda activate pydm-local
"local" refers to the PyDM setup that is local to the environment in which it was created.
Open the GUI by running:
Before starting Bluesky, the beamline scientist should sync/pull the latest version of the beamline codebase onto the workstation used for beamline operation.
Open a new tab in the terminal app (File --> New Tab). Then run:
bsui
After Bluesky is loaded and is ready to accept a command, the beamline status will be printed out (the current metadata loaded up) and the command input line will appear green with the path to the current data folder. (add instructions for reverting to previous versions if there is trouble)
Input line for Bluesky
In case needed, can exit Bluesky by running:
exit
Restarting Bluesky may be needed for the following reasons:
Code was updated
Troubleshooting while running scans
There are instances when exiting a plan or bluesky at an unlucky time will change the behavior of the entire terminal, (text not being displayed when typing, or similar). In these cases, you must close the entire terminal (or tab) and create a new one.
Bluesky has has full control over beamline motors as well as data manipulation. Can also run a local version of Bluesky by instead running:
bsui_local
In this version, beamline hardware cannot be controlled, but the sample imager, as well as data and spreadsheets can be manipulated. This version is appropriate to run if the RSoXS station does not have scheduled beam time or control over the beam.
At any point, the current default Bluesky environment and python path can be checked in a terminal (outside Bluesky):
echo $BS_ENV
echo $BS_PYTHONPATH
If it is needed to run Bluesky using a different environment (e.g., a different version of Bluesky is needed) than what is set as the default, the environment path needs to be typed out explicitly for standard and local Bluesky as shown below. As of September 26, 2024, a newer version of Bluesky can be started by exiting the current Bluesky and then running the following. This became the default environment as of January 30, 2025.
It is possible to revert back to the default environment by running exit, then bsui. However, there may be a few errors (e.g., FileNotFoundError: [Errno 2] No such file or directory: '/home/xf07id1/.config/bluesky/md/oldversions%233'). These can be resolved by exiting Bluesky (exit), changing directory (cd) to the path shown in the error, viewing the files in this directory (ls), renaming files that are causing errors (mv [old_file_name] [new_file_name]), and then starting Bluesky (bsui). The following is an example. When switching environments, check the "Versions of DSSI software" output to ensure the version numbers change to those that are desired.
exit
cd /home/xf07id1/.config/bluesky/md
ls
mv oldversions#3 oldversions
mv versions#2 versions
bsui
Beamline staff or users can also login into terminal app
Open a new tab in the terminal app (File --> New Tab). Beamline staff can log in by running, for example:
su pketkar
Enter password and 2-factor authentication when prompted. This will change the appearance of the terminal according to the users NSLS-II home directory settings, and if beamline staff, will allow SSHing into IOCs etc. For reference, su means "switch user".
Add a user by running n2sn_add_user -l [username] USER or n2sn_add_user -n [life number] USER. Replace [username] and [life number] with the actual username or life number of the user. Ensure that the user has completed the necessary trainings.
Give access to Guacamole by running: n2sn_add_user -l [username] GUACCTRL. Alternatively, can grant user only view access by running: n2sn_add_user -l [username] GUACVIEW.
Remove a user by running: n2sn_remove_user -l [username] USER
Shutting down or restarting the computer (if needed)
Follow the instructions to mount solid samples onto the high throughput bar, solid samples into the TEM temperature control sample holder, and the liquid/gas holder. Throughout the whole pump-down process, ensure that the RSoXS main chamber pressure stays below 2e-7 Torr. If this pressure is exceeded at any point, close load lock gate valves, abort any venting processes, and pump down the load lock.
Test UHV compatibility in ex-situ chamber
This is a mandatory for liquid samples and strongly recommended for solid samples, especially if there are any doubts that off-gassing, leaks, etc. may occur. These samples can be pumped down in an ex-situ chamber to ensure they can reach necessary UHV pressures and that they remain intact during the pump-down process. Only samples that pass this test should be pumped down into a beamline load lock.
Liquid samples used in NIST's custom flow cell should be pumped down using the Hummingbird system.
Hummingbird system for testing UHV compatibility of liquid flow cell samples mounted onto NIST's custom TEM holder. The system uses a Pfeiffer Vacuum pump, and the settings can be viewed and edited using the buttons and screen on the top right-hand portion of the picture. The top left-hand portion is the chamber where the TEM holder can be loaded. In the picture, a rubber plug is loaded to seal the empty chamber.
Solid samples (or liquid samples mounted onto the high-throughput bar) can be sealed in a chamber that is connected to a HiCUBE system. A sample bar with mounted samples can be loaded into the chamber. Then, seal the chamber using a DN100CF (6") flange, G-600 copper gasket, and at least 8 nuts. Ensure that the gasket is aligned and flush with the flange grooves. Tighten the nuts using a star pattern to ensure there is even pressure on the gasket.
HiCUBE system for testing UHV compatibility of samples mounted onto high-throughput solid sample bar. The system uses a Pfeiffer Vacuum pump. Behind the pump, there is a venting valve that should be closed before switching on the pump. Samples can be loaded into the chamber removing the left-hand flange. There is a valve on the right-hand side of the chamber that can be opened or closed using a torque wrench to isolate the chamber from the pump.
First, test the empty chamber to ensure there are no leaks or contamination. The pump has a venting valve on the back side; ensure it is closed before switching on the pump. The chambers for samples mounted onto both the TEM holder and the high-throughput solid sample bar are pumped using a Pfeiffer vacuum pump, and the settings can be viewed and edited using the screen and buttons. If necessary, the right and left arrow keys can be pressed at the same time to edit a value and then pressed at the same time again to save the set value. Use the left and right arrow keys to navigate to "340: Pressure". In some cases, a few cycles of pumping may be necessary to remove all moisture present in the system. Do not proceed to testing samples unless the empty chamber can be pumped down successfully.
After the empty chamber has been pumped down successfully, load the samples and follow the same steps for pumping down. Use the table below to check that the chamber/samples can be pumped down to sufficient vacuums
Typical pressures (hPa) in ex-situ vacuum system
Pump spin speed
1200 Hz
1500 Hz
1 h
2 days
Hummingbird system,
empty with rubber stopper
1.2e-5
5.4e-6
Hummingbird system,
with TEM holder and liquid sample
1.4e-5
7.4e-6
4.6e-8
Hummingbird system,
with TEM holder and liquid sample,
maximum tolerable pressures
1.9e-5
8.6e-6
HiCube system,
pump + blanking flange
1e-5
6.3e-6
HiCube system,
pump + hose + blanking flange
3.4e-5
1.5e-5
HiCube system,
pump + hose + high-throughput solid sample bar (no samples) with copper tape + blanking flange
3.4e-5
2.2e-5
4.6e-7
Solid sample bar
Vent load lock
Ensure that sample manipulator is completely withdrawn into the load lock and that nothing impedes the gate valve.
In Bluesky enter y a 345. Alternatively, in PyDM, ensure that RSoXS Up Down (y motor) > 345. Also check visually that the y motor bellows is extended all the way upwards. This manipulator is most important to have out of the way so that nothing impedes the gate valve.Outboard side of RSoXS chamber. Red box: Y motor bellows.
In Bluesky enter th a 0. Alternatively, in PyDM (or nmode will always do this), ensure that RSoXS Rotation = 0. This helps ensure that in the future, the next bar is not loaded backwards by accident.
Isolate the necessary components of the chamber.
If downstream stations are not in operation, close photon shutter 10, the upstream endstation gate valve 27A, and the downstream gate valve 28.Purple boxes: Shutter and gate valves that should be closed to isolate RSoXS chamber. Green indicates open, and gray indicates closed. A shutter upstream of a gate valve must be closed before the gate valve can be closed such that the closed gate valve is not in the direct path of the X-ray beam.
Manually close the load lock gate valve, and check on the PyDM RSoXS Vacuum Monitor.Red box: solid sample load lock gate valve. Purple box: gate valve status. Gray means closed, and green means open.
Manually isolate the y motor bellows. This part can take a long time to pump down, so it is best to not break vacuum here where possible.Inboard side and downstream view of RSoXS chamber between SST1 and SST2 beamlines. Red box: valve to isolate y motor bellows.
Turn off the load lock ion gauge on the PyDM RSoXS Vacuum Monitor.Purple box: click this button to turn off ion gauge for solid samples load lock
Turn off the turbo pump by first hitting the "motor" button and then the "pump" button. Ensure that both that both buttons turn gray. The controller is located on the outboard side of the RSoXS chamber and is below the temperature controller and ion gauge controller of the liquid sample load lock.Solid sample load lock turbo pump controller. Red box: switch on/off motor. Orange box: switch on/off pump. Yellow box: motor speed.
Wait for the turbo pump speed to reduce by ~50%, which is below 500 Hz. This takes approximately 5 min.
Turn off the backing pump, which is on the inboard, SST2 side by holding the red button until the lights turn off. The light will then blink.Inboard side of SST2 and SST1 beamline, where backing pump for SST1 RSoXS solid sample load lock is located. Red box: press and hold the red and green buttons to turn off and on the backing pump, respectively.
On the turbo pump controller, start venting. Press the right arrow key twice, and hit the venting button.
Unscrew the load lock door so that it does not over pressurize.
Monitor the PyDM RSoXS Vacuum Monitor live plot as well as the RSoXS main chamber pressure to make sure it does not exceed its acceptable upper limit. If it does, turn off the venting, and begin the pump down procedure immediately.Purple box: live plot for pressure in the RSoXS main chamber and load lock
After the load lock pressure plateaus, open the load lock door when actively removing or loading a sample bar. Otherwise, it is good practice to leave the door closed to minimize dust and moisture getting into the load lock. Keep the seal of the door clean - if any dust or particle can be seen, clean the full seal with a Kimwipe and ethanol.
Often at this point, a sample bar from a prior beam time will be removed and a new bar will be loaded in soon. In this case, remember to remove any calibration samples from the old bar, exfoliate the HOPG (use tape to strip off a layer and ensure the new surface is smooth), mount calibration samples onto the new bar, (optionally) load the sample spreadsheet, image the new bar, load the new bar into the load lock, and start pump down.
Pump down load lock
If loading in a new sample bar, wear gloves while holding the bar. Face the front (flat side) of the bar upstream. Gently push the bar into the holder until it does not go up further, you will feel two catches as you put in the bar, be sure to push past the first and ensure the bar shoulders are close to flush with the receptacle. The bar can be tugged downward lightly to ensure that it is secure in the holder.
Close the load lock door and seal with the screw lock. Also, put the blackout cover back onto the load lock window, tighten it, and ensure no light can leak in.Outboard view of RSoXS chamber. Red box: blackout cover for solid sample load lock.
Turn off venting using the turbo motor controller.
Turn on the backing pump. Note, it will make a loud noise, and this is normal.
After the backing pump is quiet, and the pressure is in the 1e-1's, use the turbo motor controller to turn on the turbo pump. Hit the left arrow key twice to exit the venting menu. Then hit the "motor" button and then the "pump" button.Purple box: high pressure gauge for solid sample load lock that is used during the initial pump down of the load lock (when backing pump and turbo pump initially are turned on).
After the pressure reads LO<E-03, turn on the ion gauge, and then open the y motor bellows valve.
Monitor the ion gauge pressure. It may initially read an unrealistically low value on the order of 1e-11, but it should read a higher value after the gauge ignites, which can take longer and longer as the gauge ages, and at very low pressures. If the ion gauge does not read a realistic value after ~10 min, VERY CAREFULLY use a rubber wrench to lightly hit the ion gauge, which can assist it in igniting.Left image: outboard view of RSoXS chamber. Red box: ion gauge for solid sample load lock. Purple box: corresponding ion gauge readout.
Continue to monitor the pressure on the PyDM RSoXS Vacuum Monitor, and let the load lock pump down as long as possible (ideally overnight). The load lock manual gate valve can be opened when the pressure is below 5e-7 Torr, which is typically achieved in < 1 h.
The wait time while the load lock pumps down is a good time to pick spots from the sample bar image. If the RSoXS endstation has control, then this also can be a good time to run open beam scans and other calibration/setup procedures that do not require the sample bar. For example, the phoebus live plot can be checked to see that signal values are reasonable and that the diode signal increases appropriately after the chamber light is turned on. This is also a good time to turn on the detectors and let them cool down if they were switched off.
TEM sample holder
Beam time startup
Follow these instructions for instrument calibrations and optimizations when first getting beam.
If not done by now, have users run the sync-experiment command to authenticate into the correct proposal directory.
Obtain confirmation from other SST scientists, especially prior users, to ensure RSoXS can take control.
Go to the "SST Launch" tab on phoebus and choose "Endstation Selected: RSoXS".Choose "Endstation Selected: RSoXS" (green box) and ensure that there are no energy movements (orange box)
Go to the "PGM" tab on phoebus and check that the "Energy Move Status" shows ready (does not show "Moving") and that the "Energy Setpoint" values are not changing. Also, check that all "Individual Drives" are not disabled; if they are, go to the individual "Motor" tabs and click "Enable".Enable PGM motors if needed.
Ensure oxygen leak is turned on for M1, M2 (Mono:PGM), M3 (FS:7), and M4. DO NOT change to the RSoXS grating without ensuring the Oxygen is leaking. On phoebus, go to the "07ID M Vacuum" tab, and scroll to the right. The readouts for these mirrors should be above 1e-8 and appear orange/red to indicate that the pressures are higher than vacuum. These pressures also can be viewed in the pressure gauge racks downstream of the hutch.Beamline pressures in phoebus. Blue boxes: pressures indicate oxygen leak is running.It is especially important to check at the beginning of a cycle when the oxygen leak has been started recently, as the levels can be less stable. If the levels need to be adjusted, it is not required to wait for any equilibration period. The RSoXS grating can be used as soon as the pressures are adequate. The "07ID M Vacuum" tab can be found by going to the "SST Launch" main page and navigating to the "Vacuum" --> "M" menu. The readings are listed from downstream (left) to upstream (right). The green/red square next to the IP:1 readouts indicate whether the ion pump is on/off. The TCG (thermocouple gauge) is used for higher pressure readings. The CCG (cold cathode gauge, ion gauge) is used for very low pressure readings under typical ultrahigh vacuum operations. The IP:1 (indirect pressure reading) is based on the ion current reading in the ion pump and should be similar to the CCG reading.
Load the grating (PGM) which will be used for the measurements.
RE(grating_to_rsoxs())
On phoebus, PGM should show up as "RSoXS 250 l/mm" with CFF = 1.45 along with gold meshes as either Gold #1 or Gold#2. If it does not move for a long time, PGM motors may need to be enabled again in phoebus. Note, RE stands for "run engine". Any command containing RE will control a motor motion in the beamline and requires the full Bluesky (not Bluesky local) to be set up. Changing the grating in the middle of experiments is allowed, but we have noticed that energy does shift each time the gratings are shifted, so this is not suggested best practice.
Before setting a clear beam pathway to the RSoXS chamber, ensure that the components within the RSoXS chamber are withdrawn.
E.g., Detector cameras should be withdrawn, as direct beam on the camera can damage the sensor.
E.g., Samples should be out of the beam path, as unnecessary exposure can damage samples.
Open all upstream gate valves and shutters in the beamline other than the Fast Shutter. Verify in the RSoXS Vacuum Monitor - PyDM that there is a clear path from the source to the RSoXS chamber. If planning to use the downstream diagnostic module 7 (DM7) components (e.g., large area photodiode, fluorescence screen), also open PSH7.Purple box: The gate valves and shutters that need to be open (green) for the a clear beam pathway into the RSoXS chamber.
Calibrate mirror and grating position for maximum flux
Note the current EPU exit slit positions (on Phoebus) and mirror positions using the function below:
view_positions("MirrorConfiguration_RSoXS")
Set the EPU exit slit positions (on Phoebus) and mirror positions to those used for RSoXS. Run view_positions again to ensure the desired positions have been reached.
If loading any non-standard configuration, ensure that the Slit 1 horizontal aperture is sufficiently narrow.
Ensure that the beamstop moves into position (e.g., WAXS Beamstop ~71 mm in PyDM). For example, ampfault errors may need to be cleared before the configuration is properly loaded.
In Bluesky, set the energy to 270 eV, as this energy is commonly used for calibration, and expected flux values at this energy are better known and documented.
e 270
Check that there is flux on Izero mesh. Close the PSH10 shutter, and look at the RSoXS archiver live plot on phoebus. The Izero signal should go down and then up. If not, then beamline alignment is necessary. Prior set of alignment parameters can be referenced in the commissioning records.
Open the fast shutter and check that there is some flux on the beamstop diode. If not, the beamstop diode position needs to be adjusted. First, try using the motor to move the beamstop in and out while monitoring the phoebus live plot. Occasionally, the manual port aligner (three set of nuts on the beamstop assembly exterior) may need to be used to adjust other axes. Generally a quarter turn of one of the alignment nuts is more than enough.WAXS beamstop assembly. Use the port aligner nuts in the red boxes to move the beamstop from the bottom outboard to the upper inboard position in a rotational direction.To check if the photodiode is turned on and can sense photons, the chamber light can be turned on and off, and a large signal should be seen on the photodiode regardless of its position in the chamber. If this signal is not seen, the readout instrument can be restarted by running RE(setup_diode_i400()) in Bluesky.
If needed, optimize the flux. For quick adjustments, just adjust M3 pitch, but other mirror positions may need more in-depth alignment. Note any changes made.
Remember to close the fast shutter after the mirror and grating parameters are optimized.
assuming there is a sample named HOPG. If the sample has a different name, use that instead.
Rotate the sample to 20 degrees (RE(rotate_now(20))) to get the maximum signal, which will help get the best quality energy calibration. Ensure that the beam stays on the sample during rotation and that the signal is sufficiently high with low noise. This is important to obtain accurate energy calibration. If the signal is low-intensity and/or noisy, revisit beam alignment.
Set the Slit 1 vertical aperture to a small size (e.g., RE(bps.mv(slits1.vsize, 0.02))). This will increase energy resolution and make the calibration more precise.
For standard RSoXS measurements at the carbon edge, run:
The above command requires the RSoXS 250 l/mm nickel grating (for other gratings, CFFs will need to be picked accordingly). See the beamline calibration procedure for details of what this is doing. The beamline starts at some constant of fixed focus (CFF) value, and this number might need to be tweaked a bit using this calibration. The cs numbers are initial guesses for CFF. The calibration is run at 90° polarization (oriented vertically), as any sample rotation angle should work in this case. This nickel grating has groove depths that minimize higher order harmonics at the carbon edge. There is also another 250 l/mm grating made of gold that can be used if needed. The above calibrate_pgm_offsets command can be run with slightly different cs (possibly [1.35,1.37,1.385,1.4,1.425,1.45]). For energies ~1300 eV or higher, the 1200 l/mm gold grating can be used. The above calibrate_pgm_offsets command can be run with k=1200 and different cs (possibly [1.55,1.6,1.65,1.7,1.75,1.8]).
If the output graphs look like they are seeing the large HOPG peak at 291.65 eV clearly in all scans and the first local maximum is higher intensity than the second local maximum, accept the changes suggested. As an additional check after accepting the suggested changes, open the Fast Shutter, and jog the energy slightly below and then above 291.65 eV. The flux on the beamstop diode should peak at 291.65 eV. One more check is to run TEY NEXAFS scans on the HOPG sample. The peaks should appear sharp. Broad peaks indicate that energy resolution is poor.
If possible, the calibrate_pgm_offsets function should not be stopped prematurely, as it might cause the optics motors to slow down. However, if it is necessary to stop the function, the grating and mirror velocities should be reset (e.g., RE(bps.mv(grating.velocity, 0.1)) and RE(bps.mv(mirror2.velocity, 0.1))), and these optics angles should be moved at this velocity to ensure the proper velocity is set (e.g., RE(bps.mvr(grating, 0.1)) and RE(bps.mvr(mirror2, 0.1)), where mvr indicates a relative move). After making any additional necessary adjustments, calibrate_pgm_offsets can be run again.
Note/adjust slit positions
Note the current settings.
Slit, beamstop, etc. positions can be found in the Bluesky codebase (e.g., see WAXSNEXAFS). This is helpful in case it is necessary to reset to the current default positions at any point, and it can be useful to compare how slit positions change over time.
Note down the current flux. It is a good practice to keep a record of how the flux changes with respect to slit settings.
Ensure that all CCD cameras are retracted, and only the photodiode is in the beam path (e.g., the WAXSNEXAFS configuration). Move the sample bar out of the way (RE(load_samp("diode"))).
Set the energy to 270 eV (e 270), open the fast shutter, and note down the starting signal values on the photodiode and Au mesh. Close the fast shutter after this.
Beamstop_WAXS.read()
Izero_Mesh.read()
These signal values also can be viewed in the live plot in Phoebus.
Capture a single image using the current slit settings to gauge how much slit scattering appears on the camera.
Move to the SRM grating: RE(load_samp("srm_grating"))
Load the SAXS configuration: RE(load_configuration("SAXS"))
Capture a single image using a low beam energy (e.g., e 150) and a low exposure time (e.g., exp 0.01).
Inspect image in the Tiled browser or PyHyperScattering, jog position/ adjust exposure time if needed. Most importantly at this step - ensure the beamstop is adequately blocking the main beam at all times.
Load the WAXS configuration: RE(load_configuration("WAXS")), capture another single image, and adjust as needed until a good image is obtained.
Use NIST RSoXS Browser/ Nika in Igor to fit SDD
Update the bluesky metadata
RE.md['RSOXS_SAXS_SDD'] = 516
RE.md['RSOXS_WAXS_SDD'] = 39.19
The above only temporarily updates the SDD. The SDD and mask should be permanently updated in the Bluesky codebase.
Calibrate beam polarization angle
Calibrate sample positions
(All samples types) Create and load a spreadsheet that defines sample and acquisition parameters
(Out of date, talk with the beamline scientist) Enter sample parameters using the Sample Worksheet Guide. Remember to include reference samples such as HOPG, diode, etc.
(Out of date, talk with the beamline scientist) Enter the sample acquisition parameters using the Acquisition Worksheet Guide.
(Out of date, talk with the beamline scientist) Check for errors and scan time estimates in the spreadsheet using the Dry Run Package.
At the beginning of each cycle, update the cycle number in the Bluesky codebase rsoxs_scans package, where it is hard-coded. Also, run, e.g., RE.md[“cycle”] = “2024-2” in Bluesky.
Make a folder in the proposal directory to permanently store sample spreadsheets if there is not one already.
To make the directory, open a new tab on the terminal app on the RSoXS Control computer, and log in (e.g., su pketkar, etc.).
Navigate to the directory where spreadsheets are saved by running:
cd /nsls2/data/sst/proposals/2025-1/pass-316367
The cd command means change directory, and this example is for the 2025-1 cycle and for proposal number 316367. Change the cycle and proposal number accordingly.
Make a folder for spreadsheets by running:
mkdir spreadsheets
The mkdir command makes a new directory, and this example is for users from NIST.
Navigate into the directory (e.g., cd spreadsheets) and check that it has appropriate permissions by running ls -ld .. Do not run chmod 777 spreadsheets (which would give everyone, including users and beamline staff, permission to access, create, delete, and edit files in this directory).
Upload spreadsheet from a local computer to the folder in the proposal directory (e.g., using the Jupyterhub, SFPT, etc.).
Copy the spreadsheet from the proposal directory to the shared scratch space for use during beam time:
The above is an example file path and file name. It is recommended that all spreadsheets loaded into Bluesky have names that start with "in_" followed by the date these sheets are loaded (e.g., "2025-03-07") followed by a descriptive name.
(All sample types) authenticate into the correct proposal at the beamline
In the GUI, use the "New Proposal" button in the "User Metadata" section to enter BNL login credentials and proposal number. After submitting, the "User Metadata" section should update with the correct information. An additional check can be to run RE.md["proposal"] in the IPython Console and checking if the correct proposal information appears in the output.
Authenticating into a proposal using the GUI. Start by clicking on "New Proposal" (red box). Then enter BNL login credentials along with proposal number (green box), click submit, and close this pop-up window. The "User Metadata" section on the top middle-right should be updated with the new proposal information. Another way to check that the correct proposal is loaded is by running RE.md["proposal"] in the IPython Console (blue box) and checking that the correct proposal information shows up.
An alternative to using the GUI would be to open a terminal window and running the following command, sync-experiment -b SST1 -e rsoxs -p 318915, in which 318915 is an example proposal number. Then, a prompt for a username and password will appear. At the moment, a 2-factor authentication push notification is not sent, but this may change. The verbosity can be defined here if needed (e.g., sync-experiment -b SST1 -e rsoxs -p 316367 -v --verbose, sync-experiment -b SST1 -e rsoxs -p 316367 -v --no-verbose).
Solid samples
Image your samples on the imager microscope before loading into the load lock
Load the sample bar with the front facing up into the imager holder and switch on the microscope light. The front side of the bar is all flat on one plane. Ensure that the shoulders of the bar are fully against the holder. Be careful to not bend the bar while loading it.
The bar will slide along its long axis, and a telecentric image of the bar will be taken. After completion, the image is saved and a graphic should pop up. If the bar stops sliding before the image is saved, the imaging can be resumed by clicking the "Start" button on the "RSoXS screen 5" tab in phoebus.
Check if the image looks good and if the optical features on the samples are sufficiently visible to pick spots on the sample. If the image is too bright or dark, the microscope light power can be adjusted from the "RSoXS screen 5" tab in phoebus, and the image_bar command can be rerun. Placing a white piece of paper under the bar also can help obtain better images.
If samples are mounted on the back of the bar, reload the bar into the imager holder with the back side facing up, and rerun the image_bar command with front=False and a new file name (e.g., BarImage_Back).
After imaging is complete, remove the bar, and switch off the microscope lamp.
Locate samples from the image
If not already done, load a spreadsheet that has all samples listed. If this is a bar with some preloaded samples that already have positions calibrated, only list the new samples that require calibration.
Note there is no RE in this command - no motors will be moved, so the run engine is not needed.
The image will be loaded. Bluesky will show the current sample for which a spot needs to be picked. Right click on the image to pick the spot. Fiducial one is the hole at the top of the bar (with the skinny handle that you stuck into the holder), and fiducial 2 is the hole on the bottom of the bar. This step is so much easier if you list your samples going in order from the top to the bottom of the bar.
If a mistake is made, it is usually best to start over, although p will take you to the last sample - there will be two arrows.
If needed, repeat steps 2-4 for the back of the bar (front=False).
After all spots are picked from the image, save an updated spreadsheet:
It is good practice to save an image of the bar with the picked spots labelled. To do this, click the save icon on the loaded image, and save the image to the same directory that contains the spreadsheets and original bar image. Alternatively, the image also can be saved from Bluesky by running plt.savefig(filepath + filename).
Map sample positions to instrument reference frame using fiducials
This step is normally done at the start of the beam time when beam becomes available and before running energy calibrations.
f2 and f1 refer to the bottom and top fiducials, respectively. The numbers in the brackets are initial guesses for the X (inboard/outboard) positions for bar rotations of -90, 0, 90, and 180 degrees, which correspond to the left, front, right, and back of the bar, respectively. The numbers for y2 and y1 are the initial guesses for the vertical motor positions of the bottom and top fiducials, respectively. It is recommended to use initial guesses based on what worked for a particular bar previously (different bars have slightly different fiducial positions) rather than the generic RE(find_fiducials()) command. This protocol will produce 10 scans, which calibrate y2, x2 at each angle, y1, and then x1 at each angle. Each individual bar tends to have reproducible fiducial positions, but the positions can vary from bar to bar. It can be helpful to note down the fiducial positions to use as initial guesses in the future when reusing the same bar.
If all 10 scans show single peaks, enter y to accept; otherwise, enter n. In the latter case, rerun the find_fiducials command with adjusted initial guesses. To find good initial guesses, do the following:
Using PyDM, set RSoXS rotation to the desired angle (e.g., -90)
Turn on the fast shutter and chamber light using PyDM.Purple box: Fast Shutter for RSoXS chamber. The circle will light up green when the shutter is Open and gray when it is Closed.Yellow box: turns the chamber light on and off. In general, give ~30 seconds after turning off the chamber light to make sure no stray photons are sensed by the detector cameras.
Jog the X (RSoXS Inboard Outboard) and/or Y (RSoXS Up Down) motors, and watch the live plot in phoebus. The X and Y positions that give a maximum value for the beamstop signal should be entered into the find_fiducials command initial guesses.
Close the fast shutter and chamber light at this point
Rerun the find_fiducials command with adjusted initial guesses as needed until the fiducials are found properly.
If the find_fiducials command is not properly mapping the fiducial locations, the fiducial locations can be found completely manually, as described above. After these locations are noted, do the following steps.
Run the load_sheet command to pull up the spreadsheet saved after sample locations were picked from the image. The following steps will not work for a different spreadsheet where spots were not picked for the bar image or for a spreadsheet that already has fiducial positions mapped.
Run the correct_bar command. Enter parameters in the following order: [y2, x2 at -90°, x2 at 0°, x2 at 90°, x2 at 180°, y1, x1 at -90°, x1 at 0°, x1 at 90°, x1 at 180°]
After the fiducial positions are calibrated, the crosshairs for the optical chamber camera can be adjusted to ensure they are set to the correct positions, if desired.
Turn on the chamber light.
Load the front side of the top fiducial.
Adjust the vertical crosshair by running:
crosshair.x.set(50)
The number is arbitrary and can be adjusted until the crosshair lines up with the fiducial. Similarly, the horizontal crosshair can be adjusted by running crosshair.y.set(50). Note that after these adjustments, the crosshairs are only accurate for this rotation position of the bar. If the bar is rotated, only the vertical crosshair is accurate. However, it is helpful to have an accurate crosshair location for future troubleshooting.
Ensure that the sample positions have mapped out correctly.
Turn on the chamber optical light.
Load a sample, preferably one with a small area to ensure precision of mapping. The sample can be loaded either using the index number shown after running list_samples() (provides a list of sample names and acquisitions queued up for each sample) or using the sample name.
RE(load_samp(2))
RE(load_samp("SampleName"))
Check that after loading the first sample, the Bluesky command line shows the correct directory with the correct proposal number. This ensures that subsequent data are stored in this directory.
If needed, rotate the bar to 0°.
Check that the correct sample lines up with the crosshairs.
Note that after a sample is loaded, the Bluesky prompt should show the proposal directory path where data will be saved. Ensure that this contains the correct proposal number and cycle number.
If this bar contains older samples for which positions already were calibrated, this is the point where those older samples can be added to "Bar" tab of the newly saved spreadsheet. Ensure that the "location" and "bar_loc" columns are included for the older samples. Load the sheet with the combined sample list, run list_samples() to ensure all desired samples are displayed, and load one of the older samples using the load_samp command to ensure that the correct sample lines up with the crosshairs. If not, the bar may have been bent significantly in the process of adding new samples.
Make sure the fast shutter is closed and camera light is turned off at this point.
Pick optimal spot(s) on transmission samples using spiral scans
The sample spot located from the bar image may have appeared good optically, but may not be the optimal spot for transmission measurements. To find a more optimal spot (or multiple spots) for RSoXS measurements and to gauge sample uniformity, quick RSoXS exposures can be on multiple spots in a spiral pattern on the same sample. Typically, these are run at a single non-resonant energy (to minimize beam damage) and a single polarization (e.g., 0°).
Spiral Scan Pattern: Image showing the pattern of a 64-measurement spiral scan, with 0 being the center of the scan region.
This decreases the collection frequency of dark images, which otherwise are collected every time a change in the motor positions is detected. For spirals this eats a lot of time, and usually, this data is not used for rigorous analysis. However, if the intention is to use this data for rigorous analysis, skip this step. Note that anytime Bluesky is restarted, the default will be reset to waxs_normal_mode(), so waxs_spiral_mode() would need to be reactivated if continuing to run spiral scans.
Monitor the data as it is being collected using nbs-viewer or PyHyperScattering. Decide what spot(s) should be selected; it is strongly recommended to pick at least 3 spots per sample to ensure repeatability and homogeneity of the sample. For assistance in identifying what 'good' spots look like, see Guide to Picking Spiral Scans.
If a sufficient number of good spots have been identified for a sample before the full spiral scan is complete, the queue can be interrupted at any point. This can reduce the total time needed for spiral scans. Otherwise, let the scan/queue run to completion.
If more spiral scans are remaining, the queue can be resumed. The above step can be repeated as many times as needed until all spirals are completed.
After all spiral scans are completed and resolved, export the sample spreadsheet. Any sample for which multiple spots were selected will be saved as the original sample_id with an additional _1, _2, etc. at the end.
If later, it is desired to select different spot(s) than the ones selected while resolving spirals, this can be edited in the "location" column of the Bar tab in the exported spreadsheet.
After all spirals are completed and prior to running other types of scans, run the following to ensure dark images are collected at the appropriate frequency.
waxs_normal_mode()
Adjust inboard/outboard position for rotated grazing samples
The purpose of this process is to correct the axis of rotation such that the same spot on a sample is exposed by the beam after rotating from normal incidence to another angle.
The Bar tab of this spreadsheet should have the most up-to-date version of sample calibrations (e.g., fiducials mapping, spiral positions picked, rotation offsets).
This will generate a summary of the planned acquisitions with time estimates and steps planned out. It is very important to validate the output of this command. Take some time and read through the scans you will be running and be sure that they match your expectations - don't skip this step! Ensure that the time per scan and total time for the queue look reasonable.
Begin running scans
Run the run_acquisitions_queue command with dryrun=False.
Stop any active runs if needed
In nbs-gui, interrupt the RunEngine by hitting the Pause (or Pause Immediate in the dropdown) button in the Plan Control box. Do not hit ctrl + c, as it will close the GUI. However, if using the Linux terminal, interrupt the RunEngine by hitting ctrl + c in Bluesky once. If the scan does not pause in the next 30 seconds, run ctrl + c twice with the second immediately after the first. If the scan still does not pause, run ctrl + c ten times quickly. If the scan still does not pause, wait until it is completed. A more powerful stop is ctrl + \.
Run cleanup. If using the IPython kernel in nbs-gui or the standard Linux terminal, clean up the scan by running:
RE.abort()
If using the GUI queue, open the More dropdown menu in the Plan Control box and select Abort.
All spreadsheets exported from Bluesky will start with "out_" followed by a date and time stamp of when the sheet was exported. It is recommended to add a descriptive name.
Process Flowchart:
As of cycle 2023-1, the automated measurement loop involves iterating on your sample spreadsheet, picking up information both on the instrument side (updated positions, acquisition completion status), and between automated executions on personal/beamline Windows PCs (more acquisitions, re-ordering, other edits to samples). A flowchart is provided below.
Automated Run Queue Flowchart
Capture single image for solid or liquid samples in Bluesky
If loading a sample on the solid sample bar, run:
RE(load_samp("SampleName"))
If running a sample from the TEM load lock, skip this step.
Set the desired configuration, energy, polarization, and exposure time as needed.
RE(load_configuration("WAXS"))
pol 0
e 150
exp 0.01
Take a single image.
snapwaxs
Alternatively, the exposure time can be changed to e.g., 0.1 by running snapwaxs 0.1. Dark images are not necessarily connected for every single image, so to ensure a new dark image is taken, change the exposure time slightly.
Then delete the files from the spreadsheets_temporary folder. Use cp instead of mv so that permission inheritance will take place.
Hand over control if another station is running next
In Bluesky, run:
nmode
This command moves the slits, gold mesh, fast shutter, beamstops, cameras, and samples out of the way so that the path is clear for the beam to pass through the RSoXS chamber and into downstream stations. It also moves the PGM to the 1200 lines/mm grating, and going back to the RSoXS 250 lines/mm grating will require a new energy calibration for future RSoXS runs.
Check in PyDM that all motors actually are in the correct positions and that there are no errors. If there are any ampfault errors, fix those and rerun nmode until all motors are in the correct positions. Also ensure that the grating is moved to 1200 lines/mm and that the polarization is set to 0.Motor positions after nmode has run. Slit positions of -5 (BOT and IB) or 5 (TOP and OB) indicate they are out of the way.The constraints for RSoXS clear are:
Motor name
Constraint
XF:07ID2-ES1{FSh-Ax:1}Mtr.VAL
> 44
XF:07ID2-ES1{Scr-Ax:1}Mtr.VAL
> 120
XF:07ID2-ES1{Det-Ax:1}Mtr.VAL
< -90
XF:07ID2-ES1{Det-Ax:2}Mtr.VAL
< -90
XF:07ID2-ES1{BS-Ax:1}Mtr.VAL
< 20
XF:07ID2-ES1{BS-Ax:2}Mtr.VAL
< 20
XF:07ID2-ES1{Stg-Ax:Y}Mtr.VAL
> 100
XF:07ID2-ES1{Slt1-Ax:T}Mtr.VAL
> 4
XF:07ID2-ES1{Slt1-Ax:B}Mtr.VAL
< -4
XF:07ID2-ES1{Slt1-Ax:O}Mtr.VAL
> 4
XF:07ID2-ES1{Slt1-Ax:I}Mtr.VAL
< -4
XF:07ID2-ES1{Slt2-Ax:T}Mtr.VAL
> 4
XF:07ID2-ES1{Slt2-Ax:B}Mtr.VAL
< -4
XF:07ID2-ES1{Slt2-Ax:O}Mtr.VAL
> 4
XF:07ID2-ES1{Slt2-Ax:I}Mtr.VAL
< -4
XF:07ID2-ES1{Slt3-Ax:T}Mtr.VAL
> 4
XF:07ID2-ES1{Slt3-Ax:B}Mtr.VAL
< -4
XF:07ID2-ES1{Slt3-Ax:O}Mtr.VAL
> 4
XF:07ID2-ES1{Slt3-Ax:I}Mtr.VAL
< -4
Go to SST Launch tab in phoebus, click the "RSoXS Control" button, and check that "1" and "Clear" show up.Check that all RSoXS hardware is cleared out of the way of the beam path.
Go back to the SST Launch tab in phoebus and choose "Endstation Selected: none".Hand off control from RSoXS endstation.
Email lead beamline scientist (e.g., Cherno and Conan) and/or next set of users that RSoXS is clear, and that they take control on their station.
Move samples, detectors, and beamstops out of the way if RSoXS is running next
At this time, load lock can be vented, and a new bar can be pumped down.
Troubleshooting Recipes
Clearing ampfault errors
Go to DIODE-Local tab on phoebus.
Right click on the "Sel" button of the "MCS-8 MC:21 KSW (Top)" (or "MCS-8 MC:20 KSW (Mid)" or "MCS-8 MC:19 KSW (Bot)" ) motor and turn it "On".MCS-8 motors
Go to PyDM and click "Enable" on the ampfaulted motors.Enable motor
Go back to DIODE-Local on phoebus and turn off the motors that were turned on earlier.
Rerun Bluesky command. The command might need to be run twice before the motor actually moves to the desired position. If ampfaults appear again, this process may need to be repeated several times.
Restarting Bluesky
Some problems (such as darks not being taken) can be fixed by stopping any active scans and restarting Bluesky. From 2023-2 onward the bar will remain constant even after restarting Bluesky.
Restarting the diodes
If the diodes stop collecting data, it may be necessary to run the reset command:
RE(reset_diodes())
Look at the primary WAXS_Beamstop/ SAXS_Beamstop or on the CS Studio top left readout to see if this fixed it.
If that fails to fix it, you may need to manually power cycle both of them. (Contact the beamline scientist).
Restarting the camera server
The following are signs that the WAXS camera server has been disconnected:
No images have been captured in the last minute for an RSoXS scan. Also, scan is taking significantly longer than the predicted time.
On PyDM GUI, camera sensor temperature is significantly higher than -80 °C or at an unreasonable value like -300 °C.
Nothing is moving on the Bluesky terminal window.
Stop the scan. Note, the RE.stop() command may take 1+ hour to complete. However, the next steps can be done before this is completed.
Open a Google Chrome window, and go to xf07id-det2.nsls2.bnl.local. Log in using Username: admin, Password, greateyes. Click on "System" on the left-hand panel. Click "Start" on the Camera Server and any other "System Status" item that has a red light in front of it, and then click "Refresh"; this may need to be repeated several times until all lights show green.Greateyes system status
The following can be prepared in advance by the beamline scientist.
Note down the port number and name of the device (e.g. 6005, greateyesCCD2)
Connect to the device: manage-iocs attach greateyesCCD2. Alternatively, run: telnet localhost 6005.
Leave this terminal tab open for users to do the next steps. In case it is required to escape from here, type ctrl + ].
Navigate to the terminal window in which the camera is accessed.WAXS camera driverThen run:
[ctrl + x]
If this was done correctly, you should see the WAXS detector line in the pydm window on the first display flash grey, then purple and finally update with a correct temperature again, with temperature control “disabled”. Change it back to enabled (and set the target temperature back to -80 °C, if it has changed) as soon as you can, so the camera does not warm up too much.WAXS camera temperature control
Restart Bluesky, wait for the camera temperature to cool below -77 °C, and restart scans.
"Following error" indicates a motor moving is not translating to any physical hardware movement
It might indicate that a motor is broken or that a component has come loose.
Contact the controls room (631-344-2550) for the following issues:
EPU troubleshooting
The controls staff likely will try to reset the EPU as a first attempt to resolve the issue. After the reset and while the controls staff are still on the call, try a couple times to move to and away from the energies/polarizations that initially caused the error to check that the error is not produced again. If the error occurs again, the controls staff may attempt a power cycle or another deeper fix which may take some time. The staff will call back with an update or confirmation that the issue is fixed.
