linse/sics
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
sics/scan.tex
koennecke 6eb387654e - Removed automatic loading of status file on startup 
- make soft motor values the default all over
- Introduced nxscript putSlab
- Fixed a bug in polldriv
2007-02-23 14:31:43 +00:00

693 lines
34 KiB
TeX
Raw Permalink Blame History

\subsection{Scan}
The first version of the scan command was implemented in Tcl. This prooved
to be inefficient. Therefore scan was reimplemented in C. Scanning
seems to be simple but is not because of the many special cases
involved:
\begin{itemize}
\item Scans must be interruptable and continuable
\item Data files need to be written in different formats
\item Different output has to be generated at various steps
\item In polarization measurements, several points with different
magnetic field orientations need to be measured at the same instrument
position.
\item Users might want to be specify complex scan paths or scan on
logarithmic axis.
\end{itemize}
I order to cope with all this, the scan module is modifiable in two
ways: For each step of the scanning process there is an overloadable
function in the scan data structure. The first way to modify scan
behavious thus is to write new functions in C and to assign them to
the scan module. In order to support scriptable scans another system
is in place: Stored in a string dictioanary there are the names of
SICS functions which will be called at each scan operation. The scan
functions then invoke the functions specified. In order for this to
work, the scan must be configured "newscan". These two schemes exits
because the scan module is in transition to a refactoring towards the
second scheme.
The principal setup thus is a central scan object which deals with
all the scan management: storing variables, positions, counting
results etc. and the configuration of the scan. This is augmented by
libraries of scan functions which get invoked at the various
steps. There is a standard scan library which is doumented here as well.
\subsubsection{Scan Variables}
Scan variables are held in this data structure:
\begin{flushleft} \small
\begin{minipage}{\linewidth} \label{scrap1}
$\langle$scanvar {\footnotesize ?}$\rangle\equiv$
\vspace{-1ex}
\begin{list}{}{} \item
\mbox{}\verb@@\\
\mbox{}\verb@ typedef struct {@\\
\mbox{}\verb@ char Name[132];@\\
\mbox{}\verb@ pIDrivable pInter;@\\
\mbox{}\verb@ pDummy pObject;@\\
\mbox{}\verb@ float fStart;@\\
\mbox{}\verb@ float fStep;@\\
\mbox{}\verb@ float *fData;@\\
\mbox{}\verb@ int dataList;@\\
\mbox{}\verb@ int logVar;@\\
\mbox{}\verb@ }VarEntry, *pVarEntry;@\\
\mbox{}\verb@@$\diamond$
\end{list}
\vspace{-1ex}
\footnotesize\addtolength{\baselineskip}{-1ex}
\begin{list}{}{\setlength{\itemsep}{-\parsep}\setlength{\itemindent}{-\leftmargin}}
\item Macro referenced in scrap ?.
\end{list}
\end{minipage}\\[4ex]
\end{flushleft}
The VarEntry structure holds the data for each single scan variable.
These are its name, its object data structures, the start and step
values for the scan and in dataList the positions actually reached
during the scan.
Scan variables have an interface:
\begin{flushleft} \small
\begin{minipage}{\linewidth} \label{scrap2}
$\langle$scanvarint {\footnotesize ?}$\rangle\equiv$
\vspace{-1ex}
\begin{list}{}{} \item
\mbox{}\verb@@\\
\mbox{}\verb@/**@\\
\mbox{}\verb@ * MakeScanVar creates a scan variable. All the necessary checks are @\\
\mbox{}\verb@ * performed@\\
\mbox{}\verb@ * @{\tt @}\verb@param pSics The interpreter in order to locate the variable.@\\
\mbox{}\verb@ * @{\tt @}\verb@param pCon A connection object for error reporting@\\
\mbox{}\verb@ * @{\tt @}\verb@param name The name of the variable to scan@\\
\mbox{}\verb@ * @{\tt @}\verb@param start The start position from which to scan@\\
\mbox{}\verb@ * @{\tt @}\verb@param step The step width with which to scan.@\\
\mbox{}\verb@ * @{\tt @}\verb@return A pointer to a new scan variable object on success, NULL@\\
\mbox{}\verb@ * else@\\
\mbox{}\verb@ */@\\
\mbox{}\verb@ pVarEntry MakeScanVar(SicsInterp *pSics, SConnection *pCon, char@\\
\mbox{}\verb@ *name, float start, float step);@\\
\mbox{}\verb@ /**@\\
\mbox{}\verb@ * make a variable which is logged during the scan but not driven.@\\
\mbox{}\verb@ * @{\tt @}\verb@param pSics The interpreter in order to locate the variable.@\\
\mbox{}\verb@ * @{\tt @}\verb@param pCon A connection object for error reporting@\\
\mbox{}\verb@ * @{\tt @}\verb@param name The name of the variable to log@\\
\mbox{}\verb@ */@\\
\mbox{}\verb@ pVarEntry MakeLogVar(SicsInterp *pSics, @\\
\mbox{}\verb@ SConnection *pCon, char *name);@\\
\mbox{}\verb@ /**@\\
\mbox{}\verb@ * InitScanVar clears the list of scan points@\\
\mbox{}\verb@ * @{\tt @}\verb@param pvar The scna variable to clear@\\
\mbox{}\verb@ */@\\
\mbox{}\verb@ void InitScanVar(pVarEntry pVar);@\\
\mbox{}\verb@ /**@\\
\mbox{}\verb@ * DeleteVarEntry deletes a scan variable.@\\
\mbox{}\verb@ * @{\tt @}\verb@param pData The scan variable entry to delete.@\\
\mbox{}\verb@ */@\\
\mbox{}\verb@ void DeleteVarEntry(void *pData);@\\
\mbox{}\verb@ /**@\\
\mbox{}\verb@ * ScanVarName returns the name of the scan variable@\\
\mbox{}\verb@ * @{\tt @}\verb@param pVar The scan variable to query.@\\
\mbox{}\verb@ * @{\tt @}\verb@return The name of the scan variable. Do not delete pointer.@\\
\mbox{}\verb@ */@\\
\mbox{}\verb@ char *ScanVarName(pVarEntry pVar);@\\
\mbox{}\verb@ /**@\\
\mbox{}\verb@ * ScanVarStart returns the start value for the scan @\\
\mbox{}\verb@ * @{\tt @}\verb@param pVar The scan variable to query.@\\
\mbox{}\verb@ * @{\tt @}\verb@return The start point for the scan.@\\
\mbox{}\verb@ */@\\
\mbox{}\verb@ float ScanVarStart(pVarEntry pVar);@\\
\mbox{}\verb@ /**@\\
\mbox{}\verb@ * ScanVarStep returns the start value for the scan @\\
\mbox{}\verb@ * @{\tt @}\verb@param pVar The scan variable to query.@\\
\mbox{}\verb@ * @{\tt @}\verb@return The step width for the scan.@\\
\mbox{}\verb@ */@\\
\mbox{}\verb@ float ScanVarStep(pVarEntry pVar);@\\
\mbox{}\verb@ /**@\\
\mbox{}\verb@ * StartScanVar starts the scan variable to drive to the next@\\
\mbox{}\verb@ * position.@\\
\mbox{}\verb@ * @{\tt @}\verb@param pVar The scan variable to start.@\\
\mbox{}\verb@ * @{\tt @}\verb@param pCon The connection to report errors to.@\\
\mbox{}\verb@ * @{\tt @}\verb@param i The position number to drive to@\\
\mbox{}\verb@ * @{\tt @}\verb@return 1 on success, 0 on failure@\\
\mbox{}\verb@ */@\\
\mbox{}\verb@ int StartScanVar(pVarEntry pVar, SConnection *pCon, int i);@\\
\mbox{}\verb@ /**@\\
\mbox{}\verb@ * AppendScanVar appends a position to the list of positions@\\
\mbox{}\verb@ * reached while scanning this variable.@\\
\mbox{}\verb@ * @{\tt @}\verb@param pVar The scan variable to append to.@\\
\mbox{}\verb@ * @{\tt @}\verb@param pos The position to append.@\\
\mbox{}\verb@ */@\\
\mbox{}\verb@ void AppendScanVar(pVarEntry pVar, float pos);@\\
\mbox{}\verb@ /**@\\
\mbox{}\verb@ * GetScanVarPos returns a position for an index.@\\
\mbox{}\verb@ * @{\tt @}\verb@param pVar The scan variable to append to.@\\
\mbox{}\verb@ * @{\tt @}\verb@param i The position number to retrieve@\\
\mbox{}\verb@ * @{\tt @}\verb@return The positiopn or -99999.99 for an error@\\
\mbox{}\verb@ */@\\
\mbox{}\verb@ float GetScanVarPos(pVarEntry pVar, int i);@\\
\mbox{}\verb@ /**@\\
\mbox{}\verb@ * CopyScanVar copies the scan positions to the array given.@\\
\mbox{}\verb@ * @{\tt @}\verb@param pVar The scan variable to copy from@\\
\mbox{}\verb@ * @{\tt @}\verb@param fData The array to copy to.@\\
\mbox{}\verb@ * @{\tt @}\verb@param np The number of slots in fData.@\\
\mbox{}\verb@ */@\\
\mbox{}\verb@ void CopyScanVar(pVarEntry pVar, float *fData, int np);@\\
\mbox{}\verb@ /**@\\
\mbox{}\verb@ * CheckScanVar checks if the scan variable can be driven through the@\\
\mbox{}\verb@ * whole range.@\\
\mbox{}\verb@ * @{\tt @}\verb@param pVar The scan variable to check@\\
\mbox{}\verb@ * @{\tt @}\verb@param pCon The connection object to which to report errors.@\\
\mbox{}\verb@ * @{\tt @}\verb@param np The number of points to check for.@\\
\mbox{}\verb@ * @{\tt @}\verb@return 0 on failuyre, 1 on success@\\
\mbox{}\verb@ */@\\
\mbox{}\verb@ int CheckScanVar(pVarEntry pVar, SConnection *pCon, int np);@\\
\mbox{}\verb@ /**@\\
\mbox{}\verb@ * queries if the variable is alogged variable or a drive one.@\\
\mbox{}\verb@ * @{\tt @}\verb@param pVar The variable to query.@\\
\mbox{}\verb@ * @{\tt @}\verb@return 1 if log var, 0 else@\\
\mbox{}\verb@ */@\\
\mbox{}\verb@ int isLogVar(pVarEntry pVar);@\\
\mbox{}\verb@@$\diamond$
\end{list}
\vspace{-1ex}
\footnotesize\addtolength{\baselineskip}{-1ex}
\begin{list}{}{\setlength{\itemsep}{-\parsep}\setlength{\itemindent}{-\leftmargin}}
\item Macro referenced in scrap ?.
\end{list}
\end{minipage}\\[4ex]
\end{flushleft}
\subsubsection{The Scan Object}
\begin{flushleft} \small
\begin{minipage}{\linewidth} \label{scrap3}
$\langle$scandata {\footnotesize ?}$\rangle\equiv$
\vspace{-1ex}
\begin{list}{}{} \item
\mbox{}\verb@@\\
\mbox{}\verb@/*--------------------------------------------------------------------------*/@\\
\mbox{}\verb@ typedef struct {@\\
\mbox{}\verb@ int i;@\\
\mbox{}\verb@ long lCount;@\\
\mbox{}\verb@ long Monitors[10];@\\
\mbox{}\verb@ float fTime;@\\
\mbox{}\verb@ } CountEntry, *pCountEntry;@\\
\mbox{}\verb@/*---------------------------------------------------------------------------*/ @\\
\mbox{}\verb@ typedef struct __ScanData {@\\
\mbox{}\verb@ pObjectDescriptor pDes;@\\
\mbox{}\verb@ pICallBack pCall;@\\
\mbox{}\verb@ pDynar pScanVar;@\\
\mbox{}\verb@ char objectName[132];@\\
\mbox{}\verb@ int iScanVar;@\\
\mbox{}\verb@ int iNP;@\\
\mbox{}\verb@ int iMode;@\\
\mbox{}\verb@ float fPreset;@\\
\mbox{}\verb@ char pFile[1024];@\\
\mbox{}\verb@ FILE *fd;@\\
\mbox{}\verb@ SicsInterp *pSics;@\\
\mbox{}\verb@ SConnection *pCon;@\\
\mbox{}\verb@ char pRecover[1024];@\\
\mbox{}\verb@ char pHeaderFile[1024];@\\
\mbox{}\verb@ int (*PrepareScan)(pScanData self);@\\
\mbox{}\verb@ int (*WriteHeader)(pScanData self);@\\
\mbox{}\verb@ int (*WriteScanPoints)@\\
\mbox{}\verb@ (pScanData self, @\\
\mbox{}\verb@ int iPoint);@\\
\mbox{}\verb@ int (*ScanDrive)(pScanData self, @\\
\mbox{}\verb@ int i);@\\
\mbox{}\verb@ int (*ScanCount)(pScanData self,@\\
\mbox{}\verb@ int i);@\\
\mbox{}\verb@ int (*CollectScanData)@\\
\mbox{}\verb@ (pScanData self,@\\
\mbox{}\verb@ int iP);@\\
\mbox{}\verb@ pStringDict scanFunctions;@\\
\mbox{}\verb@ long lPos;@\\
\mbox{}\verb@ void *pCounterData;@\\
\mbox{}\verb@ char pCounterName[512];@\\
\mbox{}\verb@ int iChannel;@\\
\mbox{}\verb@ pDynar pCounts;@\\
\mbox{}\verb@ int iCounts;@\\
\mbox{}\verb@ int iActive;@\\
\mbox{}\verb@ int iWindow;@\\
\mbox{}\verb@ char *pCommand;@\\
\mbox{}\verb@ void *pSpecial;@\\
\mbox{}\verb@ } ScanData;@\\
\mbox{}\verb@@$\diamond$
\end{list}
\vspace{-1ex}
\footnotesize\addtolength{\baselineskip}{-1ex}
\begin{list}{}{\setlength{\itemsep}{-\parsep}\setlength{\itemindent}{-\leftmargin}}
\item Macro referenced in scrap ?.
\end{list}
\end{minipage}\\[4ex]
\end{flushleft}
The CountEntry structure holds the entries for one counting
operations. These are the lCounts collected, up to 10 monitors and the
time needed for counting. This is the time read from the counter box.
The ScanData datastructure contains the following fields:
\begin{description}
\item[pDes] The standard SICS object descriptor.
\item[pCall] A pointer to the standard SICS callback interface. Scan support
the SCANPOINT message which will be executed after each
scan point.
\item[pScanVar, iScanVar] A dynamic array of VarEntry structures which
define the variables to drive in the scan. iScanVar is the total number of
scan variables. A scan might drive more then one motor or variable.
\item[iNP] is the number of scan points.
\item[iMode] is the counter mode to use.
\item[fPreset] is the preset value for the counter at each scan point. The
exponents set for the counter apply.
\item[pFile] is the name of the data file to write. This will be created
automatically from SICS variables at the start of a scan.
\item[fd] is the file descriptor for the open file when writing. fd will
be opened by WriteHeader and closed again after WriteScanPoints.
\item[pRecover] is the name of the recover file. After each scan point scan
writes some data to file which allows to restart an aborted scan.
\item[pHeaderFile] is the name of a template file which will be used for
generating the scan file header. Its format is simple: Everything except a
few keywords will be copied verbatim. The keywords will be replaced by their
apropriate values. Valid keywords are: !!DATE!! for the current date,
!!VAR(name)!! for the value of a simple Sics variable, !!DRIV(name)!! for a Sics scan
variable. The name of the variable is given in parenthesis.
!!VAR!! and !!DRIV!! can be distinguished easily: Try a run or
drive command on the variable in question. If it works and does not
complain, it is the second sort. The second sort are mostly motors or
collective variables such as lambda etc. Only one value of such a type per
line is permitted.
\item[pSics] a pointer to a SICS interpreter to use while running for
finding data.
\item[pCon] The connection object to use for error reporting during scan
execution.
\item[PrepareScan] checks limits of scan variables and memorizes
important scan information. Sometimes this is not wanted, that is why
it is parametrized here.
\item[WriteHeader] is a pointer to a function which writes the header part
of the scan file. Replace this function if another data format is needed.
\item[WriteScanPoints] is a pointer to a function which will be called after
each scan point to write the scan data to the data file. Replace this
function when another data format is needed.
\item[ScanDrive] is executed when the next point of a scan has to be reached.
i is the point of the scan.
\item[ScanCount] is executed when a scan point had been reached and a
counting operation has to be performed. i is the scan point where we are.
This function together with ScanDrive and the data writing functions allow for
customized scans.
\item[CollectScanData] reads all the scan data into the scan's data
structures after any scan point. Overload this if a different storage
scheme is required especiallay for polarising scans.
\item[scanFunctions] A string dictionary holding the names of the
configured functions for the various steps of the scan.
\item[posSoft] is a flag which is true if scan variable are stored with
soft position, i.e. with zeropoints applied.
\item[pCounterData] is a pointer to a counter structure. This defines the
counter to use and is initialized at creation of the scan data structure.
\item[pCountername] is the name of the counter used.
\item[iChannel] is the channel to use for counting. 0 is the main counter,
everything above one of the monitors.
\item[pCount, iCounts] is a dynamic array containing iCounts sets of
counting infomation. For each scan point this array holds the counts
measured. iCounts is also the current scan position.
\item[iWindow] the width of the window used for peak integration. See
integrate.w,c for more details.
\item[pCommand] It turned out that a way is needed to define user defined
speciality scans, especially for those magnetic polarized guys. The way
it is done is that scan has to be configured user. In this mode, ScanCount
will call a script which does everything necessary at the scan point,
including adding data to the data file. pCommand now holds the name of
the script to invoke.
\item[pSpecial] Usually NULL. A entry which allows customized scans to keep
some additional data in the scan data structure.
\end{description}
The functional interface to the scan module includes the following
functions:
\begin{flushleft} \small
\begin{minipage}{\linewidth} \label{scrap4}
$\langle$scaninter {\footnotesize ?}$\rangle\equiv$
\vspace{-1ex}
\begin{list}{}{} \item
\mbox{}\verb@@\\
\mbox{}\verb@/*------------------------- live & death ----------------------------------*/@\\
\mbox{}\verb@ pScanData CreateScanObject(char *pRecover, char *pHeader, @\\
\mbox{}\verb@ pCounter pCount, char *objName);@\\
\mbox{}\verb@ void DeleteScanObject(void *self);@\\
\mbox{}\verb@/*-------------------------------------------------------------------------*/@\\
\mbox{}\verb@ int AddScanVar(pScanData self, SicsInterp *pSics, SConnection *pCon, @\\
\mbox{}\verb@ char *name, float fStart, float fStep);@\\
\mbox{}\verb@ int ClearScanVar(pScanData self);@\\
\mbox{}\verb@ @\\
\mbox{}\verb@ int DoScan(pScanData self, int iNP, int iMode, float fPreset,@\\
\mbox{}\verb@ SicsInterp *pSics, SConnection *pCon);@\\
\mbox{}\verb@ int SilentScan(pScanData self, int iNP, int iMode, float fPreset,@\\
\mbox{}\verb@ SicsInterp *pSics, SConnection *pCon);@\\
\mbox{}\verb@ int RecoverScan(pScanData self, SicsInterp *pSics, SConnection *pCon);@\\
\mbox{}\verb@ @\\
\mbox{}\verb@ int GetScanCounts(pScanData self, long *lData, int iDataLen);@\\
\mbox{}\verb@ int GetScanVar(pScanData self, int iWhich, float *fData, int iDataLen);@\\
\mbox{}\verb@ int GetSoftScanVar(pScanData self, int iWhich, float *fData, int iDataLen);@\\
\mbox{}\verb@@\\
\mbox{}\verb@ int GetScanVarName(pScanData self, int iWhich, @\\
\mbox{}\verb@ char *pName, int iLength);@\\
\mbox{}\verb@ int GetScanVarStep(pScanData self, int iWhich, @\\
\mbox{}\verb@ float *fStep);@\\
\mbox{}\verb@ int GetScanMonitor(pScanData self, int iWhich, @\\
\mbox{}\verb@ long *lData, int iDataLen);@\\
\mbox{}\verb@ int GetScanNP(pScanData self);@\\
\mbox{}\verb@ float GetScanPreset(pScanData self);@\\
\mbox{}\verb@ @\\
\mbox{}\verb@ int ScanIntegrate(pScanData self, float *fSum, float *fVariance);@\\
\mbox{}\verb@ @\\
\mbox{}\verb@ int SimScan(pScanData self, float fPos, float FHWM, float fHeight);@\\
\mbox{}\verb@ /* @\\
\mbox{}\verb@ creates a simulated gaussian shaped peak with the parameters given.@\\
\mbox{}\verb@ */@\\
\mbox{}\verb@ int ResetScanFunctions(pScanData self);@\\
\mbox{}\verb@ /*@\\
\mbox{}\verb@ resets the configurable scan functions to their default values.@\\
\mbox{}\verb@ */@\\
\mbox{}\verb@ int NonCheckPrepare(pScanData self);@\\
\mbox{}\verb@ /*@\\
\mbox{}\verb@ a function for the PrepareScan field in the scan data structure@\\
\mbox{}\verb@ which does not check the boundaries of the scan as the default@\\
\mbox{}\verb@ PrepareScan does.@\\
\mbox{}\verb@ */@\\
\mbox{}\verb@ int AppendScanLine(pScanData self, char *line);@\\
\mbox{}\verb@ /*@\\
\mbox{}\verb@ AppendScanLine appends a line to the scan data file. When finished@\\
\mbox{}\verb@ it updates the position pointer in the file to point behind the@\\
\mbox{}\verb@ added line. @\\
\mbox{}\verb@ */@\\
\mbox{}\verb@ int StoreScanCounts(pScanData self, char *data);@\\
\mbox{}\verb@ /*@\\
\mbox{}\verb@ parses the numbers in data and stores them as the count and@\\
\mbox{}\verb@ monitor data for the current scan point.@\\
\mbox{}\verb@ */ @\\
\mbox{}\verb@/*------------------------ Interpreter Interface --------------------------*/@\\
\mbox{}\verb@ int ScanFactory(SConnection *pCon, SicsInterp *pSics, void *pData,@\\
\mbox{}\verb@ int argc, char *argv[]);@\\
\mbox{}\verb@@\\
\mbox{}\verb@ int ScanWrapper(SConnection *pCon, SicsInterp *pSics, void *pData,@\\
\mbox{}\verb@ int argc, char *argv[]);@\\
\mbox{}\verb@@\\
\mbox{}\verb@@$\diamond$
\end{list}
\vspace{-1ex}
\footnotesize\addtolength{\baselineskip}{-1ex}
\begin{list}{}{\setlength{\itemsep}{-\parsep}\setlength{\itemindent}{-\leftmargin}}
\item Macro referenced in scrap ?.
\end{list}
\end{minipage}\\[4ex]
\end{flushleft}
All functions take a pointer to a ScanData structure as their first
parameter. The functions:
\begin{description}
\item[CreateScanObject] creates a scan object. The parameters are the
path to a recovery file, the path to a template file for file
generation and a pointer to a counter object.
\item[DeleteScanObject] removes the ScanData structure from memory
properly.
\item[AddScanVar] adds a variable to be scanned. Parameters are the
name of the scan variable, the start and step values for the scan and
a connection object to which errors shall be printed.
\item[ClearScanVar] clears all scan variables.
\item[DoScan] performs the actual scan. Parameters are the number of
points, the counter mode and preset, the connection object for which
the scan is done and the SICS interpreter executing the scan command.
\item[SilentScan] does the same as DoScan but suppresses all output to
data files. This is good for internal scans as in the optimize or
mesure modules.
\item[RecoverScan] loads the data about an aborted scan from the
recovery file and continues to execute it. This most certainly will
not work with custom scans. But is known to work with SICS TOPSI like
standard scans.
\item[GetScanCounts] allows to retrieve the counts collected in the
scan. Max iDatLen entries will be copied into lData.
\item[GetScanVar] retrieves the scan positions for the scan variable
number i. Max iDatLen entries get copied into fData.
\item[GetSoftScanVar] retrieves the scan positions for the scan variable
number i. The soft positions are retrieved, not the hard position stored
during the scan.
\item[GetScanVarName] retrieves the name of scan variable i.
\item[GetScanVarStep] gets the step of the scan variable i.
\item[GetScanMonitor] allows to retrieve the monitor counts collected
in monitor i during the
scan. Max iDatLen entries will be copied into lData.
\item[GetScanNP] returns the number of points in the scan.
\item[GetScanPreset] returns the counter preset value for the scan.
\item[ScanIntegrate] integrates the peak after a scan. Returns the
summed counts and the variance. See the section on integrate for more
details.
\item[ResetScanFunctions] reinstalls the default functions for scan
processing into the ScanData structure.
\item[NonCheckPrepare] Before a scan is started, various data
structures in the scan object are initialized. Thereby the scan
boundaries are checked against the motor limits. For some scans this
is not feasible. This version omits this check and must be entered as
the PrepareScan function field in the scan data structure by code
using the scan module.
\item[AppendScanLine] appends a line to the scan file. This is useful
for user configured scans, for instance in polarisation mode.
\item[StoreScanCounts] parses the data given in data and stores the
numbers as count values as the count data for the current scan point.
Another feature for supporting user configurable scans.
\item[SimScan] creates a simulated gaussian peak with the given
parameters. Used for debugging several things.
\item[ScanFactory] is the SICS interpreter object creation function
for the scan object.
\item[ScanWrapper] is the SICS interpreter object function for
interacting with the scan module.
\end{description}
\subsubsection{The Standard Scan Library}
The following functions constitute the standard scan library. Please
note that the scan file data format is driven by a template. The
format of this template is documented in the SICS managers
documentation.
\begin{flushleft} \small
\begin{minipage}{\linewidth} \label{scrap5}
$\langle$stdscan {\footnotesize ?}$\rangle\equiv$
\vspace{-1ex}
\begin{list}{}{} \item
\mbox{}\verb@@\\
\mbox{}\verb@ /**@\\
\mbox{}\verb@ * make a filename according to SICS rules for this scan@\\
\mbox{}\verb@ */@\\
\mbox{}\verb@ char *ScanMakeFileName(SicsInterp *pSics, SConnection *pCon);@\\
\mbox{}\verb@ /*@\\
\mbox{}\verb@ * write the header bits from the template@\\
\mbox{}\verb@ */@\\
\mbox{}\verb@ void WriteTemplate(FILE *fd, FILE *temp, char *filename, pScanData pScan, @\\
\mbox{}\verb@ SConnection *pCon, SicsInterp *pSics);@\\
\mbox{}\verb@ /**@\\
\mbox{}\verb@ * write the header of the scan file@\\
\mbox{}\verb@ */@\\
\mbox{}\verb@ int WriteHeader(pScanData self);@\\
\mbox{}\verb@ /**@\\
\mbox{}\verb@ * WriteScanPoints is called for each point to write the scan data@\\
\mbox{}\verb@ * to screen and to file.@\\
\mbox{}\verb@ */ @\\
\mbox{}\verb@ int WriteScanPoints(pScanData self, int iPoint);@\\
\mbox{}\verb@ /**@\\
\mbox{}\verb@ * Called before the scan to prepare. The default implementation@\\
\mbox{}\verb@ * checks if all scan positions are available and configures the@\\
\mbox{}\verb@ * counter.@\\
\mbox{}\verb@ */@\\
\mbox{}\verb@ int PrepareScan(pScanData self);@\\
\mbox{}\verb@ /**@\\
\mbox{}\verb@ * allocate a new data file@\\
\mbox{}\verb@ */@\\
\mbox{}\verb@ int prepareDataFile(pScanData self);@\\
\mbox{}\verb@ /**@\\
\mbox{}\verb@ * second version of PrepareScan which does not check scan limits@\\
\mbox{}\verb@ */ @\\
\mbox{}\verb@ int NonCheckPrepare(pScanData self);@\\
\mbox{}\verb@ /**@\\
\mbox{}\verb@ * prepare for a scan without complaining...@\\
\mbox{}\verb@ */@\\
\mbox{}\verb@ int SilentPrepare(pScanData self);@\\
\mbox{}\verb@ /**@\\
\mbox{}\verb@ * ScanDrive handles driving to the scan point iPoint.@\\
\mbox{}\verb@ */ @\\
\mbox{}\verb@ int ScanDrive(pScanData self, int iPoint);@\\
\mbox{}\verb@ /**@\\
\mbox{}\verb@ * ScanFastDrive starts driving to the scan point iPoint, but@\\
\mbox{}\verb@ * does not wait. Use this for implementing slightly faster@\\
\mbox{}\verb@ * scans.@\\
\mbox{}\verb@ */ @\\
\mbox{}\verb@ int ScanFastDrive(pScanData self, int iPoint);@\\
\mbox{}\verb@ /**@\\
\mbox{}\verb@ * ScanCount is called at each scan step to do the counting.@\\
\mbox{}\verb@ */@\\
\mbox{}\verb@ int ScanCount(pScanData self, int iPoint);@\\
\mbox{}\verb@ /**@\\
\mbox{}\verb@ * CollectScanData stores the scans count results into @\\
\mbox{}\verb@ * the scan data structure and prints the information about the@\\
\mbox{}\verb@ * scan progress.@\\
\mbox{}\verb@ */@\\
\mbox{}\verb@ int CollectScanData(pScanData self, int iPoint);@\\
\mbox{}\verb@ int CollectScanDataJochen(pScanData self, int iPoint);@\\
\mbox{}\verb@ int CollectSilent(pScanData self, int iPoint);@\\
\mbox{}\verb@/*===================================================================*/@\\
\mbox{}\verb@ /**@\\
\mbox{}\verb@ * Script invocation for writing the scan header.@\\
\mbox{}\verb@ */@\\
\mbox{}\verb@ int ScriptWriteHeader(pScanData self); @\\
\mbox{}\verb@ /**@\\
\mbox{}\verb@ * Script writing each scan point@\\
\mbox{}\verb@ */@\\
\mbox{}\verb@ int ScriptWriteScanPoints(pScanData self, int iPoint);@\\
\mbox{}\verb@ /**@\\
\mbox{}\verb@ * Script preparation of the scan.@\\
\mbox{}\verb@ */@\\
\mbox{}\verb@ int ScriptPrepareScan(pScanData self);@\\
\mbox{}\verb@ /**@\\
\mbox{}\verb@ * Script driving to a scan point@\\
\mbox{}\verb@ */@\\
\mbox{}\verb@ int ScriptScanDrive(pScanData self, int iPoint); @\\
\mbox{}\verb@ /**@\\
\mbox{}\verb@ * Script counting a scan point@\\
\mbox{}\verb@ */@\\
\mbox{}\verb@ int ScriptScanCount(pScanData self, int iPoint); @\\
\mbox{}\verb@ /**@\\
\mbox{}\verb@ * Script collecting scan data for each scan point@\\
\mbox{}\verb@ */@\\
\mbox{}\verb@ int ScriptScanCollect(pScanData self, int iPoint); @\\
\mbox{}\verb@ /**@\\
\mbox{}\verb@ * ScriptScanFinish invokes a script after the scan has finished@\\
\mbox{}\verb@ */@\\
\mbox{}\verb@ int ScriptScanFinish(pScanData self); @\\
\mbox{}\verb@ /**@\\
\mbox{}\verb@ * ConfigureScript assigns the script invocation functions for@\\
\mbox{}\verb@ * scan@\\
\mbox{}\verb@ */@\\
\mbox{}\verb@ void ConfigureScript(pScanData self);@\\
\mbox{}\verb@/*=====================================================================*/@\\
\mbox{}\verb@ int StandardScanWrapper(SConnection *pCon, SicsInterp *pSics, void *pData,@\\
\mbox{}\verb@ int argc, char *argv[]);@\\
\mbox{}\verb@@$\diamond$
\end{list}
\vspace{-1ex}
\footnotesize\addtolength{\baselineskip}{-1ex}
\begin{list}{}{\setlength{\itemsep}{-\parsep}\setlength{\itemindent}{-\leftmargin}}
\item Macro referenced in scrap ?.
\end{list}
\end{minipage}\\[4ex]
\end{flushleft}
\begin{flushleft} \small
\begin{minipage}{\linewidth} \label{scrap6}
\verb@"scanvar.h"@ {\footnotesize ? }$\equiv$
\vspace{-1ex}
\begin{list}{}{} \item
\mbox{}\verb@@\\
\mbox{}\verb@/*-----------------------------------------------------------------------@\\
\mbox{}\verb@ Header file for the SICS ScanVariable. This is a support module for@\\
\mbox{}\verb@ the SICS scan system.@\\
\mbox{}\verb@@\\
\mbox{}\verb@ Evolved during refactoring scan in November 2004@\\
\mbox{}\verb@ @\\
\mbox{}\verb@ copyright: see file COPYRIGHT@\\
\mbox{}\verb@@\\
\mbox{}\verb@ Mark Koennecke, November 2004@\\
\mbox{}\verb@-------------------------------------------------------------------------*/@\\
\mbox{}\verb@#ifndef SICSSCANVAR@\\
\mbox{}\verb@#define SICSSCANVAR@\\
\mbox{}\verb@#include "sics.h"@\\
\mbox{}\verb@@$\langle$scanvar {\footnotesize ?}$\rangle$\verb@@\\
\mbox{}\verb@/*---------------------------------------------------------------------*/@\\
\mbox{}\verb@@$\langle$scanvarint {\footnotesize ?}$\rangle$\verb@@\\
\mbox{}\verb@#endif@\\
\mbox{}\verb@@$\diamond$
\end{list}
\vspace{-2ex}
\end{minipage}\\[4ex]
\end{flushleft}
\begin{flushleft} \small
\begin{minipage}{\linewidth} \label{scrap7}
\verb@"scan.h"@ {\footnotesize ? }$\equiv$
\vspace{-1ex}
\begin{list}{}{} \item
\mbox{}\verb@@\\
\mbox{}\verb@/*---------------------------------------------------------------------------@\\
\mbox{}\verb@ S C A N@\\
\mbox{}\verb@@\\
\mbox{}\verb@ Header file for the SICS scan object.@\\
\mbox{}\verb@@\\
\mbox{}\verb@ Mark Koennecke, October 1997@\\
\mbox{}\verb@@\\
\mbox{}\verb@ Extracted scan variable: Mark Koennecke, November 2004@\\
\mbox{}\verb@@\\
\mbox{}\verb@ copyright: see copyright.h@\\
\mbox{}\verb@-----------------------------------------------------------------------------*/@\\
\mbox{}\verb@#ifndef SICSSCAN1@\\
\mbox{}\verb@#define SICSSCAN1@\\
\mbox{}\verb@ typedef struct __ScanData *pScanData;@\\
\mbox{}\verb@/*--------------------------------------------------------------------------*/@\\
\mbox{}\verb@#include "counter.h"@\\
\mbox{}\verb@@$\langle$scaninter {\footnotesize ?}$\rangle$\verb@@\\
\mbox{}\verb@#endif@\\
\mbox{}\verb@@$\diamond$
\end{list}
\vspace{-2ex}
\end{minipage}\\[4ex]
\end{flushleft}
\begin{flushleft} \small
\begin{minipage}{\linewidth} \label{scrap8}
\verb@"scan.i"@ {\footnotesize ? }$\equiv$
\vspace{-1ex}
\begin{list}{}{} \item
\mbox{}\verb@@\\
\mbox{}\verb@/*--------------------------------------------------------------------------@\\
\mbox{}\verb@ Internal header file holding the definition of the scan objects data@\\
\mbox{}\verb@ structure.@\\
\mbox{}\verb@@\\
\mbox{}\verb@ Mark Koennecke, October 1997@\\
\mbox{}\verb@----------------------------------------------------------------------------*/@\\
\mbox{}\verb@#include "sdynar.h"@\\
\mbox{}\verb@#include "scanvar.h"@\\
\mbox{}\verb@#include "stringdict.h"@\\
\mbox{}\verb@@$\langle$scandata {\footnotesize ?}$\rangle$\verb@@\\
\mbox{}\verb@@\\
\mbox{}\verb@/*@\\
\mbox{}\verb@ internal helper functions for scan implementations@\\
\mbox{}\verb@*/@\\
\mbox{}\verb@@\\
\mbox{}\verb@/*@\\
\mbox{}\verb@ CollectCounterData collects all the data from the configured counter@\\
\mbox{}\verb@ ans stows it away@\\
\mbox{}\verb@*/@\\
\mbox{}\verb@CountEntry CollectCounterData(pScanData self);@\\
\mbox{}\verb@void InitCountEntry(pCountEntry pCount);@\\
\mbox{}\verb@@$\diamond$
\end{list}
\vspace{-2ex}
\end{minipage}\\[4ex]
\end{flushleft}
\begin{flushleft} \small
\begin{minipage}{\linewidth} \label{scrap9}
\verb@"stdscan.h"@ {\footnotesize ? }$\equiv$
\vspace{-1ex}
\begin{list}{}{} \item
\mbox{}\verb@@\\
\mbox{}\verb@/*--------------------------------------------------------------------------@\\
\mbox{}\verb@ S T A N D A R D S C A N@\\
\mbox{}\verb@ @\\
\mbox{}\verb@ This is a library of scan functions for the SICS standard scan. @\\
\mbox{}\verb@@\\
\mbox{}\verb@ copyright: see copyright.h@\\
\mbox{}\verb@@\\
\mbox{}\verb@ Extracted from scan.c: Mark Koennecke, November 2004 @\\
\mbox{}\verb@----------------------------------------------------------------------------*/@\\
\mbox{}\verb@#ifndef SICSSTDSCAN@\\
\mbox{}\verb@#define SICSSTDSCAN@\\
\mbox{}\verb@@$\langle$stdscan {\footnotesize ?}$\rangle$\verb@@\\
\mbox{}\verb@@\\
\mbox{}\verb@#endif@\\
\mbox{}\verb@@$\diamond$
\end{list}
\vspace{-2ex}
\end{minipage}\\[4ex]
\end{flushleft}
Reference in New Issue View Git Blame Copy Permalink