The Internal Scan Commands

Scans are preformed from a variety of commands in SICS. All these commands are just Tcl--wrappers around an internal scan object implemented in C. This section describes this internal scan command and how it works. This internal scan command is installed into the SICS server via the MakeScanCommand command in the initialisation file. This command install the internal scan object under a user defined name. For the rest of this document it is assumed that this name is xxscan.

Scan Concepts

Scanning in SICS evolved a little over time. It turned out that scans are a demanding job for a programmer because of the plethora of special scans people wish to perform and the many data file formats which have to be supported. This requires a very high degree of configurability. Under several refactorings the internal scan command has grown to become:

A controller for the scan process.
A container to store scanned variables and counts during the process of a scan. This includes commands to store and retrieve such values.
A container for the configuration of the scan. A scan is configured by specifying functions to be called at the various steps during the scan. These are preconfigured to the standard scan functions. An API is provided to replace some or all of the scan functions by user defined ones.

The internal scan object is augmented by a library of standard scan functions. The transition to the new model is not yet clean in order not to break to much old code.

The scan object (named here xxscan, but may have another name) understands the following commands:

xxscan add name start step

This command adds the variable specified by the argument name to the list of variables scanned in the next scan. The arguments start and step define the starting point and the sptep width for the scan on this variable.

xxscan clear

clears the list of scan variables. Must be called before each scan with different parameters.

xxscan run NP mode preset

Executes a scan. The arguments are: NP the number of scan points, mode the counter mode to use (this can be either timer or monitor) and preset which is the preset value for the counter. Scan data is written to an output file.

xxscan continue NP mode preset

Continues an interrupted scan. Used by the recovery feauture.

xxscan silent NP mode preset

xxscan recover

Recovers an aborted scan. The scan object writes a file with all data necessary to continue the scan after each scan point. If for some reason a scan has been aborted due to user intervention or a system failure, this scheme allows to continue the scan when everything is alright again. This works only if the scan has been started with run, not with silent.

xxscan getfile

This command retuns the name of the current data file.

xxscan setchannel n

Sometimes it is required to scan not the counter but a monitor. This command sets the channel to collect data from. The argument n is an integer ID for the channel to use.

xxscan getcounts

Retrieves the counst collected during the scan.

xxscan getmonitor i

Prints the monitor values collected during the scan for the monitor number i

xxscan gettime

Prints the counting times for the scan points in the current scan.

xxscan np

Prints the number of points in the current scan.

xxscan getvardata n

This command retrieves the values of a scan variable during the scan (the x axis). The argument n is the ID of the scan variable to retrieve data for. ID is 0 for the first scan variable added, 1 for the second etc.

xxscan noscanvar

Prints the number of scan variables

xxscan getvarpar i

Prints the name , start and step of the scan variable number i

xxscan interest

A SICS client can be automatically notified about scan progress. This is switched on with this command. Three types of messages are sent: A string NewScan on start of the scan, a string ScanEnd after the scan has finished and a string scan.Counts = {109292 8377 ...} with the scan values after each finished scan point.

xxscan uuinterest

As above but the array of counts is transferred in UU encoded format.

xxscan dyninterest

As above but scan points are printed one by one as a list containing: point number first_scan_var_pos counts.

xxscan uninterest

Uninterest switches automatic notification about scan progress off.

xxscan integrate

Calculates the integrated intensity of the peak and the variance of teh intensity for the last scan. Returns either an error, when insufficient scan data is available or a pair of numbers. Peak integration is performed along the method described by Grant and Gabe in J. Appl. Cryst. (1978), 11, 114-120.

xxscan window [newval]

Peak Integration uses a window in order to determine if it is still in the peak or in background. This command allows to request the size of this window (without argument) or set it (with argument giving the new window size).

xxscan simscan pos FWHM height

This is a debugging command. It simulates scan data with a hundred points between an x axis ranging from 10 to 20. A gauss peak is produced from the arguments given: pos denotes the position of the peak maximum, FWHM is the full width at half maximum for the peak and height is its height.

xxscan command tclcommand

Sets the tcl command procedure to invoke at each scan point. See below for the description of user defined scans. Invoked without argument command returns the name of the current command procedure.

xxscan configure mode

Confugures the several possible scan modes for the scan object. Currently there are two:

standard, the default mode writing ASCII files.
amor, a special mode the reflectometer AMOR which writes NeXus files.

xxscan storecounts counts time mon1 mon2 ...

This stores an entry of count values into the scan data structure. To be used from user defined scan functions. The scan pointer is incremented by one.

xxscan storecounter

Store the counts and monitors in the counter object configured for the scan into the scan data structure. Increments the scan pointer by one.

xxscan appendvarpos i pos

Append pos to the array of positions for scan variable i. To be used from user defined scan functions.

xxscan callback scanstart | scanpoint | scanend

Triggers callbacks configured on the scan object. May be used by user functions implementing own scan loops.

xxscan function list

Lists the available configurable function names. The calling style of these functions is described in the next section about stdscan.

xxscan function functionname

Returns the currently configured function for functionname.

xxscan function functionname newfunctionname

Sets a new function to be called for the function functionname in the scan.

User Definable Scan Functions

The last commands in the last section allowed to overload the functions implementing various operations during the scan with user defined methods. This section is the reference for these functions. The following operations during a scan be configured:

writeheader: Is supposed to write the header of the data file
prepare: Prepare does all the necessary operations necessary before a scan starts.
drive: Is called to drive to the next scan point
count: Is called at each scan point to perform the counting operation
collect: Is called for each scan point. This function is supposed to store the scan data into the scan data structure.
writepoint: Is called for each scan point and is meant to print information about the scan point to the data file and to the user.
userdata: This is the name of a user defined object which may be used to store user data for the scan.

The exact invocations of the functions:

writeheader scanobjectname userobjectname
prepare scanobjectname userobjectname
drive scanobjectname userobjectname point
count scanobjectname userobjectname point
collect scanobjectname userobjectname point
writepoint scanobjectname userobjectname point

scanobjectname is the name of the scan object invoking the function. This can be used for querying the scan object. userobjectname is the name of a entity as specified as userdata in the configuration. point is the number of the current scan point.

User Defined Scans(Old Style)

In some cases users wish to control the scan more closely, i.e. do multiple counting operations at the same point etc. This is especially true when magnets are involved. In order to do this a facility has been provided which allows the user to specify a macro routine which is called at each point. This macro routine then performs all necessary operations and then is responsible for storing its data. In order to this commands have been defined which allow to append a line to the scan data file and to store measured data in the scan data structure. The last feature is necessary in order to make scan status displays and scan analysis, such as center detection, work. The following steps are required:

Write a suitable macro procedure for the actions required at each scan point. The procedure signature looks like this:
```
proc myScanPoint {point} {
}
```
And will be called with the number of the current scan point as a parameter. Besides all usual Tcl and SICS commands the following special commands may be used:

xxxscan line text
Appends all the text after line to the scan data file.
xxxscan storecounts c1 c2 c3 c4 ...
Stores the first number given as count data, all the others as monitor values in the internal scan data structure.
Test the procedure.
Switch the internal scan command command into user scan mode with the command: xxxscan configure user
Assign your procedure to the internal scan command with the command: xxxscan command myScanPoint
Use normal scan commands for doing your scan.
Switch the internal scan command into normal mode with the command: xxxscan configure standard.

In all this replace xxxscan with the name of the internal scan command.

Differential Scans

When aligning or when searching peaks a very fast scan is required. This is the differential scan. It starts a motor and collects counts while the motor is running. The counts collected are the monitor normalized difference to the previous reading. This functionality can be configured into SICS with the command:

MakeDiffScan

in the configuration file. An optional parameter defines another name then diffscan (the default) for this object. Differential scans can only be run against one motor as it cannot be guaranteed that motors in a coordinated movement operate at the same speed. The procedure to use diffscan is:

Configure a scan variable into a SICS scan object: xxscan add var start step
Run diffscan as: diffscan scanobjectname end_position_of_scan This runs the differential scan. Scanobjectname is the name of a SICS internal scan object. It will be used to store the results of the scan. While the scan is running some basic information is printed. The scan will range from the start given in the xxscan add command to the end position given in this call.

The diffscan object has two configurable parameters:

monitor: The monitor number to normalize against. For maximum precision this should be a monitor with a lot of intensity on it.
skip: The number of SICS main loop cycles to skip between readings. This can be used to control the amount of data generated during a differential scan. This may become a problem if there is fast hardware.

A word of warning: positions found in differential scans may not be totally correct. The differential scan might even miss peaks when the relationship between motor speed and sampling rate is bad.