scans
Scan Types
Introduction
The main use of spec is to perform scans to collect data. Usually, motors are scanned and counters are read. The standard spec macros include a variety of scans. The following sections summarize the types of scans available.
Scan arguments generally include the number of intervals and a count time. The number of points is one more than the number of intervals. For a scan from position 10 to 20, stepping by one unit at each point, there would be 10 intervals or 11 points. Positive count times are in seconds. Negative count times indicate counting to monitor counts (if there is a monitor counter available). The number of counts for the preset monitor counter is the absolute value of the argument.
Relative position (or delta) scans return motors to their original positions when the scan ends or if the scan is interrupted.
An interrupted scan can be restarted using the resume macro.
Typing a scan name with no arguments will display a usage summary (except for timescan which can be invoked with no arguments).
The macro mstartup provides a menu for setting a number of scan options along the following lines:
Scan Options:
Sleep (settle) time before each point (_sleep)? 0
Sleep (settle) time for each mesh scan row (_mesh_sleep)? 0
Show updated moving and counting during scans (_upd_flg)? NO
Save names and mnemonics with each scan (_sav_mne)? NO
Save motors in file at each point for HKL scans (_sav_geo_mot)? NO
Show motors on screen during HKL scans (_show_geo_mot)? YES
Geometry motors to show (_show_geo_list)? [tth] [th] chi phi
The value in parenthesis is the name of the global variable that stores the associated parameter. The _sleep parameter specifies a settle time to delay before each point in a scan. The _mesh_sleep parameter specifies a settle time for each new row of a mesh scan.
If _upd_flg is set, the screen display will show updated motor positions while moving to each scan point and updated counter readings while counting (if the associated hardware supports reading while active). The global variable UPDATE (also settable in mstartup) specifies the interval in seconds to sleep between screen updates.
Normally, all the motor and counter names and mnemonics are only written to the data file in the initial header or if the motor or counter configuration changes. If _sav_mne is set, those values are written in each scan header.
For reciprocal space scans, the default is to save HKL values but not diffractometer motor positions at each scan point, as motor positions can in practice be determined from HKL and the geometry parameters, also saved in the data file. If _sav_geo_mot is set, positions for all the geometry motors will be saved to the data file at each point, along with the HKL values.
Likewise, _show_geo_mot configures whether to display diffractometer motor positions at each scan point on the screen. The parameter _show_geo_list is an associative array indexed by motor number where a nonzero element value indicates that motor position should be displayed.
Scan descriptions are divided into the following types:
Simple Motor Scans
The most basic scans are simple motor scans that scan one or more motors with equal spacing between each scan point. The ascan macros are absolute position scans while dscan macros are relative position scans. Arguments consist of a motor mnemonic, starting position and ending position, repeated for each motor in the scan, followed by the number of intervals and the count time.
ascan and dscan can take an unlimited number of motors in the arguments (as of spec release 6.09.07). A number in the scan names means that is the number of motors expected in the arguments.
A special scan th2th is a d2scan of the motors tth (two theta) and th (theta), where the position arguments are the relative start and finish of the tth motor. The th motor will be set to one half the position of the tth motor, that is, th = tth/2 at each point of the scan.
Standard simple motors scans are:
ascan a2scan a3scan a4scan a5scan
dscan d2scan d3scan d4scan d5scan
th2th
Example usage:
ascan phi 10 20 10 1 d2scan tth -5 5 th -2.5 2.5 20 2 dscan tth -5 5 th -2.5 2.5 20 2 th2th -5 5 20 2
Note, the last three examples perform the same scan.
Simple Mesh Scans
Simple mesh scans involve two motors creating a grid of points. The mesh macro is an absolute position scan, while dmesh is a relative position scan. Both require arguments specifying motor mnemonic, starting position, ending position and intervals for each of the two motors, followed by the count time per point.
mesh dmesh
Example:
mesh chi 85 90 10 phi 100 120 10 10
The above scan will move phi to 100, scan chi from 85 to 90, step phi by two degrees, then scan chi again, repeating until the scan at phi = 120 is done.
Variable Step Size Scans
The vscan family of macros uses an algorithm to generate points of varying density -- sparse at the wings and dense at a specified point of interest or focus. Two parameters influence the algorithm. One is the minimum step size, which defaults to the motor resolution. The other parameter is an exponent that determines the density of points.
An exponent of zero results in evenly spaced points. An exponent of one gives logarithmic spacing between each end point and the focus. Values less than one spread the steps out more. Values greater than one concentrate the steps towards the specified focus.
The minimum step-size parameter can be set larger than the motor resolution to keep the point spacing from becoming too small. For the multiple-motor scans, if the minimum step size is specified, that value is used for all motors. Otherwise, the minimum step size for each motor is its step resolution.
Global variables VSCAN_EXPON and VSCAN_MINSTEP can be set to defaults for the exponent and minimum step size, although macro arguments will override those defaults.
The standard motor vscans are these:
vscan v2scan v3scan v4scan
dvscan dv2scan dv3scan dv4scan
Usage of vscan is:
vscan mot start focus end intervals time [minstep|0 [expon]]
Where start and end specify the range of the scan, focus is the position at or in between the endpoints where the greatest density of points will occur, intervals and time are as usual. The optional parameters minstep and expon are as explained above. To enter an exponent value without changing the minimum step size, enter a zero for minstep.
The scans are also available for reciprocal space coordinates. For these scans, the minimum step size is taken from the global variable VHKLSCAN_MINSTEP if set, otherwise it defaults to 0.00001 reciprocal space units. The scans are:
vhscan vkscan vlscan vhklscan
The first three keep the non-scanned reciprocal coordinate fixed. The last requires parameters for all three reciprocal space coordinates.
An energy vscan macro is available for energy scans:
vEscan
The global variable VESCAN_MINSTEP can be used to set the default minimum energy step size. The value should be in ev or Kev corresponding to how energy units have been configured (as reflected in the global variable E_mult).
See the vscan help file for complete details.
See the Expanded Region Scans below for an alternative method for varying the point density.
Region Scans
The region scan is a single motor scan that allows specification of consecutive regions containing different point densities. After the motor mnemonic, one specifies a start position, the end of the region and a number of intervals. One can then specify additional region end points and intervals in pairs. The last argument is the count time for all points.
rscan
For example:
rscan tth 10 20 100 30 50 40 20 1
would scan the tth motor with 100 intervals from 10 to 20 degrees, then 50 more intervals from 20 to 30 degrees, then 20 intervals from 30 to 40 degrees, counting for one second at each point.
Expanded Region Scans
Expanded scans add additional points outside the specified scan range using an expanded range. The expansion parameter determines the expansion factor, while the step_ratio parameter determines the spacing of the extra points. The purpose of the expanded scans is to collect an extended background at a lower density of points compared to the central feature of the scan.
The values for the expansion and step_ratio parameter are saved as global variables. If not specified explicitly in the scan command, the previous values will be used. Otherwise, the syntax of the expanded scans is the same as the standard ascan through a4scan and dscan through d4scan.
The range of the scan is expanded by the value of the expansion factor, which must be greater than one. If the range of the scan is form 10 to 20 (a range of 10) and the expansion factor is 2, the xascan will scan from 5 to 25 (a range of 20). The added points are applied in equal ranges and the beginning and the end of the scan.
The step_ratio parameter determines the step size in the expanded regions. For example, if the value is 2, each step in the expanded region will be twice as big as the steps in the specified scan interval.
Absolute and relative position scans are available for from 1 to 4 motors:
xascan xa2scan xa3scan xa4scan
xdscan xd2scan xd3scan xd4scan
Usage for xascan is:
xascan motor start finish intervals time [expansion] [step_ratio]
with the last two arguments optional.
See the Variable Step Size Scans above for an alternative method for varying the point density.
File Scans
File scans do motor scans based on motor positions and, optionally, count times from a file. The beginning of the file contains control lines starting with a # character. There must be a line starting with #M that contains a space-separated list of motor mnemonics. Following the control lines are lines that contain space-separated motor positions corresponding to the mnemonics. Each line of the file with such values corresponds to a point in the scan.
A control line starting with #L specifies the number of outer loops for a mesh scan. When present, the total number of points is divided into the specified number of loops, and a new plot is started for each such group.
The file can optionally have per-point count times as an additional value on each line. If count times are included, there needs to be one more column than the number of motors on each line. If fscan is invoked with a count time argument, the per-point count times will be ignored.
fdscan is a delta scan where the positions in the file are relative to the starting position of the scanned motors. At the end of the scan, or if the scan is aborted, motors are returned to their starting position.
fscan fdscan
Note, additional #X directives may be implemented in the future. To include comments, starting a line with # followed by a space character, then the comment.
Continuous Motor Scans
cscan, c2scan, c3scan and c4scan are on-the-fly scans. While the motors move from the start to end positions, the counters and motor positions are read continuously. Those on-the-fly readings are the values displayed, plotted and saved. There will surely be systematic errors in the values obtained this way, but one should be able to use these scans to get a quick sense of the data and locate the approximate positions of interesting features.
Similarly, cdscan through cd4scan perform continuous delta scans, where the position arguments are relative to the starting position of each motor. Unlike the non-delta continuous scan macros, the delta versions return the motors to the starting position.
The cmesh scan does a series of single motor on-the-fly scans while an additional motor is stepped through a specified range. The scan direction is reversed after each on-the-fly scan to minimize overhead time.
A cdmesh is a delta cmesh scan, where the motor positions are specified relative to the starting positions. In addition, the motors are returned to the starting positions at the end of the scan or if the scan is aborted.
Implemented scans are:
cscan c2scan c3scan c4scan
cdscan cd2scan cd3scan cd4scan
cmesh cdmesh
See the cscan help file for details.
Fly Scans
The fly-scan macros are similar to the cscan (continuous scan) macros in that counts are accumulated while a motor is in motion. With the continuous scans, the motor position is read on the fly, but is not strictly correlated with the counter reading. With the fly scans, counts are accumulated in an MCS (multi-channel scaler) device with the MCS channel advance controlled by pulses from the motor being swept. It is thus possible to associate the counts collected from each MCS channel with an accurate motor position.
There are macros for single-pass fly scans, mesh scans with one sweep motor and one motor that is stepped through a range, and 3D mesh scans where two motors are stepped through a mesh with the fly motor swept at each position:
flyscan flydscan
flymesh flydmesh flymesh3d flydmesh3d
See the flyscan help file for details.
Reciprocal Space Scans
The reciprocal space scans are available for instances of spec linked with a geometry module that includes diffractometer-dependent calculations to translate between motor positions and reciprocal space coordinates. Most geometry configurations have a three-dimensional reciprocal space with coordinates H, K and L. The two-circle geometry and a couple of surface geometries have a two-dimensional reciprocal space with coordinates H and K.
Linear scans in reciprocal space are available for each coordinate with hscan, kscan and lscan, or all coordinates can be scanned with hklscan. Circle and radial scans are also available that scan in a reciprocal space plane. The circle scans specify a reciprocal space radius and starting and ending angles. The radial scans specify an angle and starting and ending radii.
The hklscanarr macro takes an array of HKL positions and an optional count time as arguments. If the count time argument is missing, the last column of the array needs to contain the count time for each point. For 2D reciprocal space, only HK values are needed in the array.
hklscan hkscan hscan lscan kscan
hklscanarr
hklmesh hkmesh
hkcircle hlcircle klcircle
hkradial hlradial klradial
The circle and radial scans allow an optional trailing argument containing an expression to assign the unscanned coordinate. For example:
hkcircle 1 30 40 100 1 L=H/300
That would scan in the H-K plane from 30 to 40 degrees at a radius of 1, setting L to H/300 at each point. For proper parsing, either there can be no spaces in the expression or the expression needs to be in quotation marks.
Pseudo angles associated with geometries fourc, fivec, sixc, zaxis and psic can be scanned with the following:
aziscan azidscan (AZIMUTH in fourc, fivec, sixc and psic)
alphascan alphadscan (ALPHA in zaxis and psic)
betaascan betadscan (BETA in zaxis and psic)
nazscan nazdscan (NAZ in psic)
omscan omdscan thscan thdscan (OMEGA in psic)
psiscan psidscan (PSI in psic)
qazscan qazdscan (QAZ in psic)
The surface geometries include scans of the incident and reflected angles ALPHA and BETA:
abscan - scans ALPHA and BETA
abmesh - does an ALPHA scan for successive BETA values
rscan - scans both with ALPHA = BETA
r2scan - does a series of abscans where BETA has a fixed offset from ALPHA
(Note, the rscan definition in the surface geometry macros will override the standard region scan definition, described above.)
Usage is:
abscan alpha_start alpha_finish beta_start beta_finish intervals time abmesh alpha_start alpha_end alpha_intervals beta_offset_start beta_offset_end beta_intervals time rscan alpha_start alpha_finish intervals time r2scan alpha_start alpha_finish alpha_intervals beta_off_start beta_off_finish beta_intervals time
Energy Scans
The Escan energy-scan macro scans the motors associated with the monochromator that selects the photon energy incident on the sample. Units are eV or keV depending on the configuration of the E_mult parameter, set in the mstartup macro.
For geometries with reciprocal space calculations, an optional literal fixQ final argument means to keep HKL fixed at each point of the scan. Diffractometer motor positions will be recalculated for each energy value, and both diffractometer and monochromator motor positions will be adjusted for each point of the scan.
Escan
See also vEscan in the Variable Step Size Scans section above.
Non-Motor Scans
The timescan macro will count until halted, using the either the current default count time for each point, or an optional count time specified as the first argument. An additional optional argument can specify a sleep time between each count interval.
The loopscan macro is similar to timescan, but takes an initial argument that specifies the total number of points in the scan.
The tscan and dtscan macros are regular and delta temperature scans that call the settemp macro with the scanned temperature set point as argument.
All the above macros will read all active counters and perform whatever additional per scan point actions are included in the standard user hook macros, such as the measure1 measure2 and measure3 macros along with user_scan_loop.
timescan loopscan tscan dtscan
MCA Detector Arm Scans
The MCA detector arm scans are similar in effect to detector arm scans of a point detector, with scan points at the resolution of the MCA pixels. The detector arm is repositioned during the scan so that the entire configured range of angles is sampled. Currently, the macros are not installed by default, but are included in the file macros/mca_scans.mac in the spec distribution. Use mca_scan_setup to configure scans. Options include configuring the detector distance and width (in order to calculate the angle associated with each MCA pixel) and whether the MCA data should be overlapped, sorted and merged.
mca_ascan mca_dscan
See the macro source in macros/mca_scans.mac for more details.