linse/sics
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

PSI sics-cvs-psi-2006

Browse Source
This commit is contained in:
koennecke
2006-05-08 02:00:00 +00:00
committed by Douglas Clowes
parent ae77364de2
commit 6e926b813f
388 changed files with 445529 additions and 14109 deletions
Download Patch File Download Diff File Expand all files Collapse all files

276
doc/manager/iscan.htm
View File

@@ -3,31 +3,72 @@
<TITLE>The Internal Scan Command</TITLE>
</HEAD>
<BODY>
<H1>The Internal Scan Command</H1>
<P>
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 <a href=command.htm>MakeScanCommand
command</a> 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.
</P>
<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>xxscan clear
<DD>clears the list of scan variables. Must be called before each scan with
different parameters.
<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
@@ -40,27 +81,44 @@ 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 retuns the name of the current data file.
<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 counst collected during the scan.
<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 teh
<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,
@@ -77,20 +135,96 @@ 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. Invoked without argument command
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>Confugures the several possible scan modes for the scan
<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>
<h2>User Defined Scans</h2>
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
@@ -98,8 +232,8 @@ 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
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:
@@ -133,6 +267,106 @@ command:
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>