DESCRIPTION

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.

The scan arguments include the start and finish positions for each motor and the total time for the scan. The speed of each motor will be set to approximate that scan time. A final optional argument specifies a sleep interval between each counter reading.

While the motors are moved to the starting positions, the macros time how long it takes to read the counters and motors. These readings are simply to provide an estimate for how many points will be accumulated during the specified scan time.

At the beginning of the scan, the timer is set to count for the time contained in the global variable CSCAN_TIMER_PRESET, which should be longer than duration of the scan. The default value is 999 seconds (a value within the maximum count range of most of the timers spec supports).

At each scan point, a new reading is taken from all enabled counters. In the default case, the previous reading is subtracted to get the net counts during the scan interval. For counters that take instantaneous readings, for example, temperatures or photo diode currents, the optional counter_par() "cscan_instant" parameter can be created (see below) and given a nonzero value, in which case each reading will be used as is.

The position associated with each motor during a scan interval is the average of the most recent motor position reading and the previous motor position reading.

The count values associated with event-driven counters for spec server hardware and EPICS scalers and process variables are generally updated at a rate slower than the frequency with which the cscan macro can read the values via the get_counts call. That results in successive readings returning identical values. For these particular controller types (SPEC_SC, EPICS_SC and EPICS_PV), the cscan inner loop will get the counter_par() "timestamp" value associated with the current value and continue to read values until all the timestamps are updated. Checking the timestamps avoids reading identical values, but limits the rate at which cscan generates data by the frequency of the slowest scaler update time. The default timestamp checking for these controller types will be disabled if the optional counter_par() "cscan_poll" parameter exists and has a value of zero.

When timestamp checking is active, the rate at which points are collected will be slower. The number of points estimated at the start of the scan does not currently take that into account, so will overestimate the number.

The optional parameters "cscan_instant" and "cscan_poll" can be created on the optional scaler parameter screen in spec's hardware configuration editor. Type S to switch to the scaler screen and then p to create an optional parameter associated with a particular scaler. Or the parameters can be created during a spec session with the command along the lines of:

counter_par(mne, "cscan_instant", 1, "add")

That command creates the parameter with a value of 1. The value can be changed or read back the usual way. Note, though, parameters added during a session disappear on exit and on reconfig.

Only hardware controllers that allow reading counts or positions while counting or moving will work with these scans. The overhead time associated with reading particular controllers will vary greatly, and that will affect how many scans points are attainable. For controllers that respond very quickly, one should use a small sleeptime at each point to avoid having an excessive amount of data collected.

Use the disable macro to disable scalers that have significant overhead time when reading and are of no interest during the scan. See the disable help file for details.

If the motor controllers don't have the option of programming the step speed, the scans are still usable, but the scantime parameter will have no effect.

The macros will not set the motor to a speed faster than the steady-state parameter in spec's hardware config file. If the desired speed is less than the base-rate parameter, spec will set the base-rate to half the steady-state rate.

If the motors are already at the starting point of the scan when the macros are invoked, the readings done to estimate the overhead time will likely estimate too short an overhead, as for most motor controllers spec does not read the hardware if the motor is not active.

A cleanup macro is run at the end of the scan, if the scan is aborted or there is some other error. The cleanup macro restores motor speeds to what they were before the scan.

Note, pseudo motors that depend on real motors can't be effectively scanned, as the cscan macros only adjust the speed of the motors explicity specified in the scan arguments. Even if the macros attempted to calculate speeds for the associated real motors, the trajectory of the scanned motor may not be the true position at each point, as the relationship between the real motors and the pseudo motor may not be linear.

INTERNAL MACROS

The _cscan() macro function is called by the _cscan_prep and _cmesh_prep macros to perform the continuous scans. The following global symbols will have already been initialized by the calling macro:

_nm

number of motors to scan.

_m[]

contains motor numbers.

_s[]

contains starting position.

_f[]

contains final position.

_ctime

total count time for continuous scan.

_stime

optional sleep time between counter readings.

GLOBALS

_cscan_velocity_save[]

_cscan_base_rate_save[]

CSCAN_TIMER_PRESET

MACROS

cscan

c2scan

c3scan

c4scan

cdscan

cd2scan

cd3scan

cd4scan

cmesh

cdmesh

_cscan_prep

_cmesh_prep

_cscan(is_mesh, is_dscan)

cscan_cleanup(is_mesh, is_dscan)