373 lines
16 KiB
HTML
373 lines
16 KiB
HTML
<HTML>
|
|
<HEAD>
|
|
<TITLE>The Internal Scan Command</TITLE>
|
|
</HEAD>
|
|
<BODY>
|
|
<H1>The Internal Scan Commands</H1>
|
|
<h2>Scan Concepts</h2>
|
|
<p>
|
|
Scans in SICS involve an internal scan module and a lot of scripts which
|
|
wrap the internal scan module into a syntax liked by the users.
|
|
</p>
|
|
<p>
|
|
The internal scan module 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:
|
|
<ul>
|
|
<li>A controller for the scan process.
|
|
<li>A container to store scanned variables and counts during the
|
|
process of a scan. This includes commands to store and retrieve such
|
|
values.
|
|
<li>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.
|
|
</ul>
|
|
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.
|
|
</p>
|
|
<p>
|
|
The standard scan command can be configured into SICS using the command:
|
|
<dl>
|
|
<DT>MakeScanCommand name countername headfile recoverfil
|
|
<DD>MakeScanCommand initialises the SICS internal scan command. It will be
|
|
accessible as name in the system. The next parameter is the name of a valid
|
|
counter object to use for counting. The next parameter is the full pathname of
|
|
a header description file. This file describes the contents of the header of
|
|
the data file. The format of this file is described below. The parameter
|
|
recoverfil is the full pathname of a file to store recover data. The internal
|
|
scan command writes the state of the scan to a file after each scan point.
|
|
This allows for restarting of aborted scans.
|
|
</dl>
|
|
</p>
|
|
<p>
|
|
The scan object (named here xxscan, but may have another name) understands
|
|
the following commands:
|
|
<DL>
|
|
<DT>xxscan clear
|
|
<DD>clears the list of scan variables. Must be called before each scan with
|
|
different parameters.
|
|
<DT>xxscan add name start step
|
|
<DD>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.
|
|
<dt>xxxscan log var
|
|
<dd>This command adds a variable to be logged during the scan. Can be slave
|
|
motors such as stt, om, chi, phi during four circle work. These variables
|
|
are not driven, just logged. var is the SICS variable to log. Only drivable
|
|
parameters may be logged in such a way.
|
|
<DT>xxscan run NP mode preset
|
|
<DD>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.
|
|
<dt>xxscan continue NP mode preset
|
|
<dd>Continues an interrupted scan. Used by the recovery feauture.
|
|
<DT>xxscan silent NP mode preset
|
|
<DD>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. The difference to run is, that
|
|
this scan does not produce an output file.
|
|
<DT>xxscan recover
|
|
<DD>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.
|
|
<DT>xxscan getfile
|
|
<DD>This command returns the name of the current data file.
|
|
<DT>xxscan setchannel n
|
|
<DD>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.
|
|
<DT>xxscan getcounts
|
|
<DD>Retrieves the counts collected during the scan.
|
|
<dt>xxscan getmonitor i
|
|
<dd>Prints the monitor values collected during the scan for the
|
|
monitor number i
|
|
<dt>xxscan gettime
|
|
<dd>Prints the counting times for the scan points in the current scan.
|
|
<dt>xxscan np
|
|
<dd>Prints the number of points in the current scan.
|
|
<DT>xxscan getvardata n
|
|
<DD>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.
|
|
<dt>xxscan noscanvar
|
|
<dd>Prints the number of scan variables
|
|
<dt>xxscan getvarpar i
|
|
<dd>Prints the name , start and step of the scan variable number i
|
|
<DT>xxscan interest
|
|
<DD>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.
|
|
<dt>xxscan uuinterest
|
|
<dd>As above but the array of counts is transferred in UU encoded
|
|
format.
|
|
<dt>xxscan dyninterest
|
|
<dd>As above but scan points are printed one by one as a list
|
|
containing: point number first_scan_var_pos counts.
|
|
<DT>xxscan uninterest
|
|
<DD> Uninterest switches automatic notification about scan progress off.
|
|
<DT>xxscan integrate
|
|
<DD> Calculates the integrated intensity of the peak and the variance of the
|
|
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.
|
|
<DT>xxscan window [newval]
|
|
<DD>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).
|
|
<DT>xxscan simscan pos FWHM height
|
|
<DD>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.
|
|
<DT>xxscan command tclcommand
|
|
<DD>Sets the tcl command procedure to invoke at each scan point. See below
|
|
for the description of user defined scans (Old Style).
|
|
Invoked without argument command
|
|
returns the name of the current command procedure.
|
|
<dt>xxscan configure mode
|
|
<dd>Configures the several possible scan modes for the scan
|
|
object. Currently there are two:
|
|
<ul>
|
|
<li><b>standard</b>, the default mode writing ASCII files.
|
|
<li><b>amor</b>, a special mode the reflectometer AMOR which writes
|
|
NeXus files.
|
|
<li><b>script</b> Scan functions are overriden by the user.
|
|
<li><b>soft</b> The scan stores and saves software zero point corrected
|
|
motor positions. The standard is to save the hardware positions as
|
|
read from the motor controller.
|
|
<li><b>user</b> configures the old style user overridable scans.
|
|
</ul>
|
|
<dt>xxscan storecounts counts time mon1 mon2 ...
|
|
<dD>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.
|
|
<dt>xxscan storecounter
|
|
<dd>Store the counts and monitors in the counter object configured for
|
|
the scan into the scan data structure. Increments the scan pointer by
|
|
one.
|
|
<dt>xxscan appendvarpos i pos
|
|
<dd>Append pos to the array of positions for scan variable i. To be
|
|
used from user defined scan functions.
|
|
<dt>xxscan callback scanstart | scanpoint | scanend
|
|
<dd>Triggers callbacks configured on the scan object. May be used by
|
|
user functions implementing own scan loops.
|
|
<dt>xxscan function list
|
|
<dd>Lists the available configurable function names. The calling style
|
|
of these functions is described in the next section about stdscan.
|
|
<dt>xxscan function functionname
|
|
<dd>Returns the currently configured function for functionname.
|
|
<dt>xxscan function functionname newfunctionname
|
|
<dd>Sets a new function to be called for the function functionname in
|
|
the scan.
|
|
</DL>
|
|
</P>
|
|
<h2>User Definable Scan Functions</h2>
|
|
<p>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:
|
|
<dl>
|
|
<dt>writeheader
|
|
<dd>Is supposed to write the header of the data file
|
|
<dt>prepare
|
|
<dd>Prepare does all the necessary operations necessary before a scan
|
|
starts.
|
|
<dt>drive
|
|
<dd>Is called to drive to the next scan point
|
|
<dt>count
|
|
<dd>Is called at each scan point to perform the counting operation
|
|
<dt>collect
|
|
<dd>Is called for each scan point. This function is supposed to store
|
|
the scan data into the scan data structure.
|
|
<dt>writepoint
|
|
<dd>Is called for each scan point and is meant to print information
|
|
about the scan point to the data ile and to the user.
|
|
<dt>finish
|
|
<dd>Is called after the scan finishes and may be used to dump a data file
|
|
or perform other clean up operations after a scan.
|
|
<dt>userdata
|
|
<dd>This is the name of a user defined object which may be used to
|
|
store user data for the scan.
|
|
</dl>
|
|
The exact invocations of the functions:
|
|
<ul>
|
|
<li>writeheader scanobjectname userobjectname
|
|
<li>prepare scanobjectname userobjectname
|
|
<li>drive scanobjectname userobjectname point
|
|
<li>count scanobjectname userobjectname point mode preset
|
|
<li>collect scanobjectname userobjectname point
|
|
<li>writepoint scanobjectname userobjectname point
|
|
<li>finish scanobjectname userobjname
|
|
</ul>
|
|
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.
|
|
</p>
|
|
<h2>User Defined Scans(Old Style)</h2>
|
|
<p>
|
|
This feauture allows to override only the counting operation during a scan.
|
|
This feauture is deprecated in favour of the user overridable scan functions
|
|
described above. As it is still used, however, here is the documentation
|
|
for reference.
|
|
</p>
|
|
<p>
|
|
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 allow for 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:
|
|
<ol>
|
|
<li>Write a suitable macro procedure for the actions required at each
|
|
scan point. The procedure signature looks like this:
|
|
<pre>
|
|
proc myScanPoint {point} {
|
|
}
|
|
</pre> 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:
|
|
<dl>
|
|
<dt>xxxscan line text
|
|
<dd>Appends all the text after line to the scan data file.
|
|
<dt>xxxscan storecounts c1 c2 c3 c4 ...
|
|
<dd>Stores the first number given as count data, all the others as
|
|
monitor values in the internal scan data structure.
|
|
</dl>
|
|
<li>Test the procedure.
|
|
<li>Switch the internal scan command command into user scan mode with
|
|
the command:
|
|
<b>xxxscan configure user</b>
|
|
<li>Assign your procedure to the internal scan command with the
|
|
command: <b>xxxscan command myScanPoint</b>
|
|
<li>Use normal scan commands for doing your scan.
|
|
<li>Switch the internal scan command into normal mode with the
|
|
command:
|
|
<B>xxxscan configure standard</b>.
|
|
</ol>
|
|
In all this replace xxxscan with the name of the internal scan
|
|
command.
|
|
</p>
|
|
<h2>The Scan Command Header Description File</h2>
|
|
<p>
|
|
As if all this configurability is not enough, there is another
|
|
level of configurability.
|
|
The SICS internal scan command allows to configure the contents of
|
|
the header of
|
|
the ASCII scan data file through a template header file. This is only
|
|
possible when the scan functions are left in their default configuration.
|
|
If scan functions are overloaded it is the users repsonsability to take
|
|
care of data file writing.
|
|
This section describes
|
|
the contents of the template file. This header description file
|
|
consists of normal
|
|
text mixed with a few special keywords. The normal test will be copied to
|
|
output verbatim. The keywords indicate that their place will be replaced by
|
|
values at run time. Currently only one keyword per line is supported.
|
|
Keywords recognized are:
|
|
<DL>
|
|
<DT>!!DATE!!
|
|
<DD>Will be replaced with the file creation date.
|
|
<DT>!!VAR(name)!!
|
|
<DD>Will be replaced with the value of the SICS variable name.
|
|
<DT>!!DRIV(name)!!
|
|
<DD>Will be replaced with the value drivable variable name. Drivable variables are
|
|
all motors and all variables which may be used in a drive or run command.
|
|
<DT>!!ZERO(name)!!
|
|
<DD>Will be replaced with the value of the softzero point for motor name.
|
|
<DT>!!FILE!!
|
|
<DD>Will be replaced by the creation name of the file.
|
|
</DL>
|
|
Please note that text behind such a keyword in the line will not be copied to
|
|
the output.
|
|
</p>
|
|
<h2>Differential Scans</h2>
|
|
<p>
|
|
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:
|
|
<pre>
|
|
MakeDiffScan
|
|
</pre> 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 involved in a coordinated movement operate at the same speed
|
|
without mechanical coupling. The
|
|
procedure to use diffscan is:
|
|
<ul>
|
|
<li>Configure a scan variable into a SICS scan object: xxscan add var
|
|
start step
|
|
<li>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.
|
|
</ul>
|
|
The diffscan object has two configurable parameters:
|
|
<dl>
|
|
<dt>monitor
|
|
<dd>The monitor number to normalize against. For maximum precision
|
|
this should be a monitor with a lot of intensity on it.
|
|
<dt>skip
|
|
<dd>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.
|
|
</dl>
|
|
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.
|
|
</p>
|
|
<p>
|
|
Diffscan is usally wrapped in a common script command:
|
|
<dl>
|
|
<dt>fastscan motor start stop speed
|
|
<dd>which does a fast scan for motor from start to stop. Before the scan
|
|
the motors speed is set to speed. The motor is set to its original speed
|
|
after termination of the scan.
|
|
</dl>
|
|
This script can be copied from one of the older instrument command files.
|
|
</p>
|
|
<h2>Peak Analysis</h2>
|
|
<p>
|
|
There are several other feautures which can be configured into SICS
|
|
which interact very closely with the scan module:
|
|
<dl>
|
|
<DT>MakePeakCenter scancommand
|
|
<DD>MakePeakCenter initialises the peak analysis commands peak and center. The
|
|
only parameter is the name of the internal scan command.
|
|
</dl>
|
|
</p>
|
|
<h2>Common Scan Scripts</h2>
|
|
<p>
|
|
There exists a library of script functions around the scan module which are
|
|
commonly used. They provide an object oriented wrapper around the internal
|
|
scan command and the <b>cscan</b> and <b>sscan</b> commands. These
|
|
commands can be made available by including the scancommand.tcl file into
|
|
the instruments configuration file.
|
|
</p>
|
|
</BODY>
|
|
</HTML>
|
|
|