FMB User Guide & Reference

New User Overview

This page is designed as a first-stop reference page for new and returning users to FMB. This section walks through typical steps required at startup, with the goal of describing when the sections below will likely be of use. Because FMB supports a variety of different experimental modalities and special equipment, this sequence will not be complete for all setups.

Typical Start-up Sequence

1. Confer with beamline scientist regarding when the station will be ready.
2. (If necessary) Review hutch & control area layout, including:
   1. In-hutch layout:
      • Upstream components (ion chambers, slits, shutter, CRL, attenuator wheel)
      • Sample environment (sample stage, sample viewing camera(s))
      • Detector table (detectors, SAXS flightpath, beamstop diode -- typically within the SAXS flightpath)
   2. Station computer (SPEC window, hutch camera views, sample camera views, ImageJ, etc.)
   3. Ion chamber displays (red LED displays on control rack, on-screen display).
   4. Analysis computer: typically used for pyFAI (calibration), InstantPlot (viewing raw data), and NeXpy (viewing processed data).
3. Review scheme for mounting samples with beamline staff.
4. Review data-acquisition procedures (e.g. scan-types, special equipment).
5. Review most-used SPEC commands, e.g. for quering and moving motors, performing scans.
6. (For SAXS, WAXS, GISAXS, etc): Perform detector calibration
   1. Acquire powder patterns from AgBH (silver behenate) and/or LaB₆ powder patterns.
   2. Use pyFAI software to create mask (in .tif) and calibration files, known as "poni" files (for Point of Normal Incidence), for each scattering detector.
7. Set up "yaml" configuration files for automatic data processing -- consult beamline staff for assistance.
8. (If desired): Create a SPEC macro file for automating sequences of scans. Review save, load, verification of macro definitions in SPEC.
9. Align, obtain and evaluate data from first sample.
10. (If necessary) refine beam size, slit, and/or other configuration to optimize data.

Checking Beam Status

FMB beamline status page: http://new-status.chess.cornell.edu/id3b

CESR status page: https://cesrwww.lepp.cornell.edu/docs/statpanel/fullscore_auto.html

Useful SPEC commands

Moving motors and querying motor positions

For almost all motors: positions are in mm or deg.

wm motorname: show motor positions for given motor, e.g.: wm samx. NOTE both the User and Dial positions are shown. umv and ascan refer to the User positions.

we: returns motor positions for all configured motors.

umv motorname absolute_position: moves motor to absolute position, with updated motor position reported. SPEC prompt will be returned once the motion is complete. e.g.: umv samx 1.5 moves motor samx to position 1.5.

umvr motorname rel_position: move motor relative to current position, with updated motor position reported. SPEC prompt will be returned once the motion is complete. e.g.: umvr samx -1.25 moves motor samx by -1.25 from its current position.

twc motor1 step_size: interactively tweak motor1 by step_size using the left/right arrow keys.

twc motor1 step1_size motor2 step2_size: interactively tweak motor1 by step1_size using the left/right arrow keys, and motor2 by step2_size using the up/down arrow keys.

tw motorname step_size: interactively tweak motorname by step_size, permitting change of direction and increment size. Examples:

• tw samx 0.5 will tweak samx by 0.5 mm with each subsequent press of the return key.
• Type any non-numeric input to exit tweak.
• NOTE: we recommend specifying the step size as a positive value even if you want to tweak in the negative direction. (In that case, type '-' at the prompt prior to hitting return).
• Both the direction and size of increment can be changed by entering a (new) numeric value at the prompt.

Hutch / sample coordinate system definition

The hutch coordinate system, which is followed for most motorized directions is:

• +x direction: transverse to the beam, away from the hutch doors
• +y direction: propagation direction of the x-beam (right-to-left when facing the door from outside the hutch)
• +z direction: upward

For mapping applications, the sample stage often departs from this convention such that the motions correspond to the movement of the X-ray beam on the sample, as opposed to the motion of the sample in the beam. This choice results in more natural registry between data and a visual image of the sample. For instance, it is common to define positive z as a downward translation of the sample (the opposite of the hutch coordinate system), which corresponds to the X-ray beam moving up. For lateral motion: if the camera is placed behind the sample looking upstream, then the "+x" direction as defined by the hutch coordinate system moves the sample away from the door, corresponding (in the camera view) to a right-ward motion of the X-ray beam on the sample. Thus we would define positive samx to correspond to the "+x" hutch direction. If the camera is placed upstream of the sample looking downstream, then the "+x" direction of the sample is switched. That is, in that case "+x" in sample motion moves the sample towards the hutch door.

In summary, for mapping applications: +z direction corresponds to downard translation of the sample, and +x direction corresponds to transverse direciton away from the hutch doors (same as the hutch coordinate system). +y direction remains unchangted. For all other applications, follow the hutch coordinate system.

If unsure about the convention being used, consult with the staff scientist.

Shutter, attenuator, and slits

opens: open the in-hutch upstream shutter.

closes: close the in-hutch upstream shutter.

umv att 0: move attenuator completely out of the beam; att -1: fluorescent screen; att 12: significant attenuation

wg s1: print positions for upstream hutch slits. s1h and s1v correspond to horizontal and vertical openings in mm, respectively.

wg s2: print positions for downstream hutch slits (guard slits). s2h and s2v correspond to horizontal and vertical openings in mm, respectively.

• s1h, s1v, s2h, and s2v can be changed with umv commands; units are mm.

Organizing data (making folders, changing directories)

1. newdir dir_name make a new directory in the user's raw BTR directory, and makes it the working directory (i.e. newdir would make a folder called dir_name in the current user's BTR directory in DAQ and make it the working directory).
   • This replaces what used to be a multi-step process of navigating to the user's raw BTR diorectory, then running u mkdir dir_name, followed by cd dir_name.
   • Running newdir without any argument will prompt for the name of the directory you wish to create.
   • newdir can be run regardless of what the current working directory is. It will create the directory in the current user's BTR directory in DAQ and make it the working directory.
   • TIP: If you happen to restart spec (not a fresh start), running newdir and taking the default argument will ensure that you are back to the working directory you were at before the restart.
2. Update detector path to the current directory - need to run this every time directories are changed.
   1. For SAXS/WAXS, pil_setdir updates the Pilatus detector(s).
   2. For radiography/tomography, andor_setdir updates the Andor detector.
   3. For XRF, xps_setdir updates the xpress3 paths.
   4. For the Eiger, eig_setdir updates the detector paths.
3. newfile opens dialog to enter new filename and path for saving data, applied to next scan.

Data Acquisition / Scanning

All times are in seconds.

Time Scans

tseries: take a series of snapshots without any wait in-between.

• Usage: tseries number_of_snapshots exposure_time
• e.g. tseries 10 1 will take 10 snapshots with 1 second exposure per snapshot.

loopscan: take a series of snapshots with a wait in-between.

• Usage: loopscan number_of_snapshots exposure_time sleep_time
• e.g. loopscan 10 1 5 will take 10 snapshots with 1 second exposure per snapshot and wait 5 seconds between each exposure.

flyscan (motorless): a continuous series of snapshots with no overhead between points

• Usage: flyscan npts exposure_time
• Note that in this usage, "npts" is the real number of points in the scan. (not the number of intervals, as in dscan, flydcan, etc.)

Scanning One or More Motor

Step-wise scans

dscan: snapshots while moving a motor step-wise (not flyscanning)- relative positions

• Usage: dscan motorname relative_start relative_end intervals exposure_time
• Positions are relative to current position
• At the end of the scan, the motor will return to the position it was at when the scan command was executed.
• e.g. dscan bedx -10 10 20 1
  • Will scan the motor bedx from -10 to +10 mm relative to the current position, with 1 mm steps and 1 second exposure times
    • If the current position of motor bedx is 30, it will be scanned from 20 to 40. At the end of the scan, motor bedx will return to 30.

ascan: snapshots while moving a motor step-wise (not flyscanning)- absolute positions

• Usage: ascan motorname start end intervals exposure_time
• Positions are absolute, not relative to current position when the command is issued
• The motor does not return. It will remain at the final position (in this example, at 220) at the end of the scan.
• e.g. ascan bedx 200 220 20 1
  • Will scan bedx from motor positions 200 to 220, with 1 mm steps and 1 second exposure times, regardless of where motors are when the command is issued.

Flyscans

NOTE: flyscan and its variants can only be performed on a subset of motors and requires configuration. Consult a staff member prior to use.

flydscan: obtain data while continuously scanning a motor relative to the current position. Usage is identical to dscan.

• Usage: flydscan motorname relative_start relative_end intervals exposure_time
• At the end of the scan, the motor will return to its starting position prior to executing the scan.

flyscan: obtain data while continuously scanning a motor according to absolute positions. Usage is identical to ascan.

• Usage: flyscan motorname start end intervals exposure_time
• At the end of the scan, the motor will not return to its starting position.

flydmesh or flymesh: obtain data while tracing out a grid using two motors -- a "fast" (or flying) motor and a "slow" (non-flying) motor

• Usage for flydmesh: flydmesh fast_motorname relative_start relative_end intervals exposure_time slow_motorname relative_start relative_end intervals
• Usage for flymesh: flymesh fast_motorname start end intervals exposure_time slow_motorname start end intervals

Controlling which signal to plot

plotselect: choose what variable to show in the yellow SPEC plot.

Pilatus area detector macros

List of important commands

• pil_setup PILX #: sets up the detector with prefix (e.g. pil_setup PIL5 0).
  • Typical for simultaneous SAXS/WAXS: PIL5 = 0, PIL9 = 1, PIL11 = 2.
• pil_on|off: turns all configured detectors on|off.
  • pil_on # - turn on just one configured detector (e.g. pil_on 0 turns on the 0th configured detector).
• pil_von|voff: turns live view (video mode) on|off.
  • ImageJ plugin can only handle this for one detector at a time, so if you have multiples configured, make sure only one is on before running pil_von.
  • video mode must be off before starting captures or any scans.
• pil_setdir: sets all the pilatus paths to the current working directory.
• pil_settrig: choose trigger mode for configured detectors.
  • Use "Mult. Trigger" for external trigger (for flyscan, flymesh, tseries, ascan). This mode is almost always used.
    • Alternatively, pil_setex sets trigger mode as Mult. Trigger.
  • Use "Internal" for single snapshots (for tseries or dscans). This mode is not currently used.
    • Alternatively, pil_setint sets trigger mode as Internal.

Examples of usage with multiple detectors

See: PilatusExamples

Andor area detector macros

List of important commands

• andor_setup ANDOR#: sets up the detector with prefix.
  • Typical e.g. andor_setup ANDOR2.
• andor_on|off: turns andor detector capture on|off
• andor_von|voff: turns live view (video mode) on|off.
  • video mode must be off before starting captures or any scans
• andor_setdir: sets the andor save paths to the current working directory.
• andor_settrig: choose trigger mode.
  • use "Internal" for tseries, loopscans, etc.
  • use "External Start" for tomography movies with the air bearing rotation stage
• andor_setformat: save as .tiff or .hdf5
  • either: andor_setformat "TIFF1" or andor_setformat "HDF1".
  • saving to hdf5 is necessary for fast framing rates

Station computer links/procedures

Camera views

In-hutch microscope (Mako G-234C)

• To view images:
  • On a terminal window, run ImageJ to launch ImageJ.
  • From the toolbar: Plugins > EPICS_areaDetector > EPICS AD Viewer to open the EPICS_ADViewer_Plugin window
  • In the field labelled ‘PVPrefix’ enter the value ID3B_vis1:image1: (or ID3B_vis2:image1: if the second camera is used). Note the colon at the end.
  • Click on the Start button to open the image view window and start acquisition.
  • On a terminal window, run vis1_controls to or (vis2_controls if the second camera is used) to launch the MEDM cursor control screen.
• Launching IOC and more information (internal document -- staff access only)

In-hutch PTZ camera by hutch door/on south wall (original)

http://192.168.182.44 (requires login -- staff access only)

In-hutch PTZ camera (upstream wall)

http://192.168.182.81 (requires login -- staff access only)

3B 4-channel Video encoder

http://192.168.182.43 (requires login -- staff access only)

Cave cameras

from terminal, run vimba

Preamp gui

To restart preamp gui, from terminal, run show_amps.

Open counter/ion chamber viewer

From terminal, run conter_display.

Open beam position and station status viewers

• To start a viewer for beam positions, CESR correction, CESR and CHESS enables, beam current and time to next topoff: beam_positions
• To start a viewer for status lines stops and station stops: station_status

Defining macros

1. Edit the .mac file containing definitions for macros (e.g. my_macros.mac). This is saved in ~/Macros on the station computer. User-specific .mac files are often located in ~/Macros/User_Macros.
2. In SPEC, run udo my_macros.mac to read in your .mac file.
   • If your .mac file is in User_Macros, run udo User_Macros/my_macros.mac
3. Verify that your .mac file was read in successfully.
   • On SPEC, run prdef your_function_in_mac_file to see if the definition for that function displays correctly.

Data analysis- useful information

Group Permissions and Setting Your Default Group

When using shared directories or NoteBooks for data analysis, it is often convenient to permit group members to edit each others analysis files. This can be accomplished using two steps:

1. Setting the default permissions on files you create to "group writable" by issuing the command "umask 0002" or placing that command inside the file called ".bashrc" in your home directory.
2. Making sure all group members set your default group to the same group, e.g. "chess3buser" or your btr-specific group. This can be done using the group management utillity, found here.

File paths

Raw data: /nfs/chess/raw/current/id3b/YOUR-PROJECT-ID

Analysis area: /nfs/chess/aux/reduced_data/cycles/current/id3b/YOUR-PROJECT-ID

Note, instead of "current" you can also use the run cycle, e.g. "2020-3" (this is necessary for returning to data after a run is over)

Analysis area always stays accessible. Raw data is archived after two cycles. To request raw data be restored to disk, submit a service request: https://wiki.classe.cornell.edu/Computing/ServiceRequest

Remote access

Station computer (NoMachine) and lnx201

• CHESS Remote Access User Guide
• (Deprecated) Remote access with NoMachine

CLASSE IT documentation for NoMachine can be found here.

Transferring files

See SFTP / SCP file access or Globus. Globus is recommended for data transfer between CLASSE network and your own computer. Globus requires a one-time installation of Global Connect Personal. If this is not an option for you, please consult with the staff scientist for alternative methods.

Sample holder

For many ex situ measurements, it is convenient to mount multiple samples on a custom 3D-printed holder. Below are select examples.

• A sample holder with 15 mm round holes (PDF with dimension; STEP file)
• More to come...

While your holder design does not need to exactly replicate the example, please keep in mind the following key requirements:

1. Preserve the 'Keep Out Area'
   • This designated region must remain unchanged to ensure compatibility.
2. Maintain overall dimensions (with specific guidance)
   • Increasing the height of the holder is acceptable; however, doing so may reduce efficiency, as only one holder can be mounted at a time instead of two.
   • The width should be maintained wherever possible. This is important for proper stage travel and to prevent collisions during measurements.
3. Follow numbering and lettering conventions
   • It is strongly encouraged to use the same labeling system as shown in the example above. This will streamline data processing and facilitate efficient mapping.

Beamline software

• Getting started with remote computing for FMB, including JupyterHub setup.
• pyFAI calibration walk through for SAXS/WAXS
• InstantPlot documentation: SAXS/WAXS data viewing and interactive reduction
  • If you are a contributor to InstantPlot, please use GitLabs (private) for issue reporting.
• SAXSWAXS automation: Automated data processing
• SAXSWAXS workflow: command line tool for batch validation and processing to NeXus format
• GIWAXS automation
• HyperSpy visualization examples
• Praxes rough documentation
• (Obsolete / Used Prior to 2023): InstantPlot to NetCDF

Other useful links

Virtual tour

A 3D Virtual tour of the MSN-C user area, including inside FMB and SMB (screenshot shown above) is located here.

Rough flyscan time estimator

• Online estimation tool
• ScanTimeEstimator.xlsx

CHESS ion chamber flux calculator

• Flux calculator

X-ray attenuation calculators

• X-Ray attenuation length

Running Jupyter notebooks on the CLASSE cluster

• FMB-specific Guide: RemoteComputingFMB
• CLASSE-wide Guide: CLASSE JupyterHub
• (Obsolete) Accessing Jupyter prior to JupyterHub

CLASSE Git area

• CLASSE GitLab

X-CITE (Cyberinfrastructure Training and Education for Synchrotron X-Ray Science)

• X-CITE training materials

-- LouisaSmieska - 11 May 2022