DESCRIPTION

The vscan family of macros do variable step size scans over one or more motors, reciprocal space coordinates or monochromator energy, with points spaced closer together at a designated focus point.

Usage for the single motor version is:

vscan mot start focus end intervals time [minstep|0 [expon]]

The scan arguments include a start, focus and end position for each scanned motor or coordinate, with point spacing being closest together at the specified focus. The focus can be anywhere within the scan range, including the end points.

Optional arguments specify a minimum step size and an exponent used in calculating the step spacing.

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 reduce the density at the focus. Values greater than one concentrate the steps towards the specified focus.

If a global variable VSCAN_EXPON is set and is nonzero, it establishes the default exponent value for all the scans. If the exponent is unspecified on the scan line and VSCAN_EXPON is unset or zero, a default exponent of 1.2 is used. A macro argument will override VSCAN_EXPON.

If global variables VSCAN_MINSTEP, VHKLSCAN_MINSTEP or VESCAN_MINSTEP exist and have nonzero values, those values will be used as the default minimum step size for motor scans, HKL scans and energy scans, respectively. Macro arguments will override those values.

For motor scans, if the minimum step size is unspecified or set to zero, the minimum step size will be the motor resolution. The minimum step-size parameter can be set larger than the motor resolution to spread the points out around the focus. For multi-motor scans, if the minimum step size is specified, that value is used for all the motors. Otherwise, the minimum step size for each motor is its step resolution.

For reciprocal space scans, if unspecified and if VHKLSCAN_MINSTEP is zero or unset, the minimum step size will be 1e-5.

For energy scans the minimum step size defaults to 1 eV. The numerical value will be either 0.001 or 1, depending on whether the macros are configured to use KeV or eV energy units (set by the value of the E_mult global constant).

The step size at each position x is calculated as:

step = minstep + k * |x - focus|^expon

An iterative process is used to calculate the factor k given the minimum step size, scan range, focus and exponent. If there are too few steps over the range or for other unusual values, the process to determine k may fail, in which case a warning is printed. If the minimum step size is too big for the range and number of steps, the scan is aborted.

The vscan macros all use the new array scan engine.

Macros vscan through v4scan scan one to four motors. Macros dvscan through dv4scan are delta versions that return the scanned motors to their starting positions.

Reciprocal space version are vhscan, vkscan, vlscan and vhklscan.

As mentioned above, for multiple motor or multiple reciprocal-space coordinate scans, each scanned motor or coordinate requires a start, focus and end parameter.

The energy scan is vEscan. The vEscan arguments can include the word "fixQ" as an argument after the count time and before any optional minimum step size and exponent. As with the usual Escan, the "fixQ" option means to maintain the reciprocal space position for each energy value by moving the geometry-dependent motors as necessary.

INTERNAL MACROS

The _vscan_factor() macro function is used by _vari_angle_scan_prep, _vari_hkl_scan_prep and _vari_Escan_prep. The function iteratively calculates the sum of the steps in an inner loop and adjusts the k factor to minimize the difference (epsilon) between the sum of the steps and the requested range.

The iterations use a factor, k1, formed from the sum of a current value, k0, and an increment, delta. Initially, k0 is 0 and delta is 10.

The inner loop does a "break" if the accumulated range exceeds the specified range. When that happens the delta increment is halved and another iteration begins.

If the inner loop completes, then the accumulated range is less than the specified range. Epsilon is the difference. If epsilon is less than or equal to the previous minimum, the current factor k1 is assigned to k0. Otherwise the delta increment adjustment is halved.

When epsilon is less than half the minimum step size, the function returns the associated k factor. The function will also return after 40 iterations even if there is no convergence.

The _vscan_one_step() macro function calculates the step increment for the current position using the k factor along with the minimum step size and exponent.

ACKNOWLEDGMENTS

The vscan algorithm is based on the uascan macro from the APS USAXS beamline.

GLOBALS

VSCAN_MINSTEP

VHKLSCAN_MINSTEP

VESCAN_MINSTEP

VSCAN_EXPON

MACROS

vscan

v2scan

v3scan

v4scan

dvscan

dv2scan

dv3scan

dv4scan

vhscan

vkscan

vlscan

vhklscan

vEscan

_vscan_factor(start, focus, end, steps, exponent, minstep)

_vscan_one_step(x, k, focus, exponent, minstep)

_vari_angle_scan_prep

_vari_hkl_scan_prep

_vari_Escan_prep