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.

Back to top

Typical start-up sequence

1. Confer with the beamline staff 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 the 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 with the 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.

Back to top

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

Back to top

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-ray beam (right-to-left when facing the door from outside the hutch)
• +z direction: upward

Back to top

Special note on mapping applications

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 vertical motion, it is common to define positive z as a downward translation of the sample, opposite to the hutch coordinate system. Under this convention, a positive z motion corresponds to the X-ray beam moving upward on the sample.

For lateral motion, the definition of positive x depends on the viewing geometry:

• If the camera is located downstream of the sample and looks upstream, positive x corresponds to the sample moving away from the hutch doors.
• If the camera is located upstream of the sample and looks downstream, positive x corresponds to the sample moving toward the hutch doors.

In both cases, positive x produces a rightward motion of the X-ray beam on the sample as viewed in the camera image.

The definition of the positive y direction remains the same as in the hutch coordinate system.

In summary, for mapping applications:

• Positive z (+z): corresponds to a downard translation of the sample.
• Positive (+x):
  • If the camera is downstream of the sample and views upstream: corresponds to a laterial translation of the sample away from the hutch doors (the same convention as the hutch coordinate system).
  • If the camera is located upstream of the sample and views downstream: corresponds to a lateral translation of the sample toward the hutch doors (the opposite of the hutch coordinate system).
• Positive y (+y): remains unchanged from the hutch coordinate system.

For all other applications, follow the hutch coordinate system.

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

Back to top

Useful SPEC commands

Querying motor positions and moving motors

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

• wm motor_name: displays the current position of the specified motor.

• we: displays the current position of all configured motors.

Note: wm and we display both the User and Dial positions. umv and scan commands refer to the User positions.

• umv motor_name absolute_position: moves the specified motor to the given absolute position while continuously reporting the motor position during the move. The SPEC prompt returns once the motion is complete.

• umvr motor_name rel_position: Moves the specified motor by the given relative distance from its current position while continuously reporting the motor position during the move. The SPEC prompt returns once the motion is complete.

• twc motor1 step_size: Interactively tweaks the specified motor in increments of step_size using the left and right arrow keys.

• twc motor1 step1_size motor2 step2_size: Interactively tweaks two motors simultaneously. Use the left and right arrow keys to move motor1 in increments of step1_size, and the up and down arrow keys to move motor2 in increments of step2_size.

• tw motorname step_size: Interactively tweaks the specified motor in increments of step_size. After each move, pressing Enter moves the motor by one increment. The direction and step size can be changed at any time during the tweak session.
  • Enter any non-numeric input to exit tweak.
  • NOTE: We recommend specifying a positive step size, even if you intend to move in the negative direction. To reverse the direction, enter - at the prompt before pressing Enter.
  • The direction and increment size can be changed at any time by entering a sign (+ or -) and/or new numeric value at the prompt.

Back to top

In-hutch shutter, attenuator, and slits

• opens: opens the in-hutch upstream shutter.
• closes: close the in-hutch upstream shutter.

Slits

• wg s1: print positions for upstream hutch slits (beam-defining slits). s1h and s1v correspond to horizontal and vertical openings in mm, respectively.
• wg s2|s3: print positions for downstream hutch slits (guard slits). s2h|s3h and s2v|s3h correspond to horizontal and vertical openings in mm, respectively.
• s1h, s1v, s2h|s3h, and s2v|s3v can be changed with umv commands

Attenuators

• umv att 0: moves the attenuator completely out of the beam.
• umv att 12: adds significant attenuation

Note: the position refers to the slot number on the attenuator wheel. The attenuator wheel is not used at all times. Consult with the beamline staff if you need to use the attenuator wheel. Consult with the beamline staff if you need to use the attenuator wheel.

Back to top

Organizing data (making folders, changing directories)

1. newdir dir_name creates a new directory called dir_name in the user's raw/DAQ BTR directory, and makes it the working directory.
   • 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.
   • You may run newdir to return to an existing 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, immediately after "newdir" and without any arguments..
   1. For Pilatus (typically SAXS/WAXS): pil_setdir
   2. For Eiger (typically GIWAXS or XRD): eig_setdir
   3. For radiography/tomography (Andor): andor_setdir
   4. For XRF (XSPRESS3): xps_setdir
3. newfile opens dialog to enter new filename and path for saving data, applied to next scan.
   • Within the same directory, you may reutrn to an exiting datafile with newfile
   • NOTE: Immediately after switching to a new working directory, you must provide a filename that differs from the filename used immediately before the directory change. Once a new filename has been specified, this restriction is lifted, and any valid filename, including the filename that was previously used in another directory may be used thereafter.

Back to top

Data acquisition / scanning

All times are in seconds.

Time scans

• tseries npts exposure_time: acquires the specified number of images using the given exposure time, with no delay between consecutive acquisitions.

• loopscan npts exposure_time sleep_time: acquires the specified number of images using the given exposure time, with a delay of sleep_time between consecutive acquisitions.

• flyscan npts exposure_time (motorless): acquires the specified number of images using the given exposure time, with no delay between consecutive acquisitions.

Note that npts is the real number of points in the scan. (not the number of intervals, as in dscan, flydcan, etc.)

Back to top

Scanning one or more motors

Step-wise scans

• dscan motor relative_start relative_end intervals exposure_time: scans motor from relative_start to relative_end relative to its current position. Data points or images are collected at evenly spaced positions, with an exposure time of exposure_time at each point. The step size is calculated as (relative_end - relative_start) / intervals. The total number of data points (or images) acquired is intervals + 1. At the completion of the scan, motor is returned to its original position.

• ascan motor start end intervals exposure_time: scans motor from start to end. start and end are absolute positions. Data points or images are collected at evenly spaced positions, with an exposure time of exposure_time at each point. The step size is calculated as (end - start) / intervals. The total number of data points (or images) acquired is intervals + 1. At the completion of the scan, motor is not returned to its original position.

Back to top

Flyscans

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

• flydscan motor relative_start relative_end intervals exposure_time: scans motor from relative_start to relative_end relative to its current position. At the completion of the scan, motor is returned to its original position.
  
  
• flyscan motor start end intervals exposure_time: scans motor from start to end. start and end are absolute positions. At the completion of the scan, motor is not returned to its original position.
  
  
• flydmesh fast_motor relative_start0 relative_end0 intervals0 exposure_time slow_motor relative_start1 relative_end1: scans fast_motor from relative_start0 to relative_end0 relative to its current position at each step of slow_motor. The step size of slow_motor is calculated as (relative_end1 - relative_start1) / intervals1. At the completion of the entire scan, fast_motor and slow_motor are returned to their respective original position.
  
  
• flymesh fast_motor start0 end0 intervals0 exposure_time slow_motor start1 end1: scans fast_motor from start0 to end0 at each step of slow_motor. The step size of slow_motor is calculated as (end1 - start1) / intervals1. At the completion of the entire scan, fast_motor and slow_motor are not returned to their respective original position.
  
  

For flyscan and its variants: Depnding on the motor being scanned (motor or fast_motor) and/or scan parameters, the macros may adjust intervals or intervals0, as well as the endpoint (relative_end, relative_end0, end, end0). Refer to the documentation on flyscan for more details.

Back to top

Controlling which signal to plot

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

Back to top

Detector macros

The following macros will function as intended only if the detector(s) have been properly configured in SPEC by the beamline staff.

Pilatus

The beamline is equipped with three Pilatus detectors. Relevant details for each detector are provided in the table below.

Name	Type	Pixel Array (Ver. × Hor.)	Pixel Size (µm)	Detector Index in SPEC
PIL5	Pilatus 300K	619 × 487	172	0
PIL9	Pilatus 200K	407 × 487	172	1
PIL11	Pilatus 200K	407 × 487	172	2

Image saving

To enable image saving with each scan:

• Run pil_on to enable image saving on all configured detectors (most commonly used).
• Run pil_on detector_index... to enable image saving on the specified detector(s), where each detector index is 0, 1 or 2.

To disable image saving with each scan:

• Run pil_off to disable image saving on all configured detectors (most commonly used).
• Run pil_off detector_index... to disable image saving on the specified detector(s), where each detector index is 0, 1 or 2.

Back to top

Streaming images

• Run pil_von to enable streaming mode of all configured Pilatus detectors, with a 1 second acquisition time.
• Run pil_von time to enable streaming mode of all configured Pilatus detectors, with the specified acquisition time in seconds.

• Run pil_von detector_index time to enable streaming mode of the detector with index number, where detector_index is 0, 1 or 2, with the specified acquisition time in seconds.

• Run pil_voff to disable streaming mode.

Note: Prior to enabling image saving with each scan, streaming mode must be disabled.

Back to top

Setting path to the current working directory

Run pil_setdir to set the path for all configured detectors to the current working directory.

Back to top

Displaying detector status

Run pil_show to display the status of all configured detectors.

Back to top

Eiger

Image saving

Run eig_on to enable image saving.

Run eig_off to disable image saving.

Back to top

Streaming images

Run eig_von to enable streaming mode, with a 1 second acquisition time.

Run eig_von time to enable enable streaming mode, with the specified acquisition time in seconds.

Run eig_voff to disable streaming mode.

• NOTE: Prior to enabling image saving with each scan, streaming mode must be disabled.

Back to top

Setting path to the current working directory

Run eig_setdir to set the path to the current working directory.

Back to top

Displaying detector status

Run eig_show to display the status of all configured detectors.

Back to top

Andor

Image saving

Run andor_on to enable image saving.

Run andor_off to disable image saving.

Back to top

Streaming images

Run andor_von to enable streaming mode, with a 1 second acquisition time.

Run andor_von time to enable enable streaming mode, with the specified acquisition time in seconds.

Run andor_voff to disable streaming mode.

• NOTE: Prior to enabling image saving with each scan, streaming mode must be disabled.

Back to top

Setting path to the current working directory

Run andor_setdir to set the path to the current working directory.

Back to top

Displaying detector status

Run andor_show to display the status of all configured detectors.

Back to top

Defining macros

Please consult with the beamline staff before defining and running your own macros!

1. Edit the .mac file containing your macro definitions (for example, my_macros.mac). Save your user-specific macro file in ~/Macros/User_Macros.
2. In SPEC, load the macro file by running udo User_Macros/my_macros.mac.
3. Verify that your .mac file was read in successfully by running prdef your_function_in_mac_file. If the macro has been loaded correctly, SPEC will display the definition of the specified function.

Back to top

Useful tools on the station computer

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)

Back to top

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)

Back to top

Preamp gui

From a terminal window, run show_amps.

Back to top

Counter/ion chamber viewer

From a terminal window, run counter_val.

Back to top

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.

Back to top

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, i.e. "YYYY-X" (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

Back to top

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 beamline staff for alternative methods.

Back to top

Remote access

• CHESS Remote Access Guide (CLASSE IT)
• NoMachine instructions (CLASSE IT)
• Getting started with remote computing for FMB, including JupyterHub setup.

Back to top

Beamline software and walkthrough/guides

• pyFAI calibration walkthrough for SAXS/WAXS detector calibration
• 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 to NeXus format
• SAXSWAXS workflow: command line tool for batch validation and processing to NeXus format
• GIWAXS automation
• NeXpy for viewing NeXus files
• HyperSpy visualization examples
• Praxes rough documentation
• (Obsolete / Used Prior to 2023): InstantPlot to NetCDF

Back to top

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. In addition, 3D‑printed sample holders with extended width may bend slightly at the end not bolted to the stage, making it difficult to maintain a constant sample‑to‑detector distance across the entire holder.
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.

Users are expected to arrive with their samples pre‑mounted on sample holders that conform to the design guidelines outlined above. Any questions or concerns regarding sample holder design or compatibility should be discussed with the beamline staff well in advance of the scheduled beam time.

XLEAP users: Please refer to XLEAP Sample Prep Guide for XRF-specific information.

Back to top

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

Back to top