introduction

SPICE
Spectrometer Instrument Control Environment

Introduction Topics:

1. General introduction
2. Graphical user interface introduction
 3. Status display introduction


general introduction

INTRODUCTION

The introduction to SPICE is split into 3 sections:
1. General Information
2. Core Components
3. Triple-Axis Specific Features

GENERAL INFORMATION
The Spectrometer Instrument Control Environment (SPICE) is a LabVIEW based program written at ORNL for control of neutron scattering instruments. The core components of the program (outlined below) are written to be independent of the type of instrument allowing the software to be expanded to different instrument types. LabVIEW was chosen as the language for development for a number of reasons:

1. The most compeling reason to choose LabVIEW is the ease with which hardware can be interfaced. Almost all modern hardware comes shipped with LabVIEW drivers or (at least) drivers which are easily accessed from LabVIEW. This greatly simplifies the process of hardware integration in SPICE.

2. As LabVIEW's programming language, G, is a graphical programming language, a graphical user interface (GUI) is easily generated. The presence of a GUI greatly improves user friendliness.

3. LabVIEW supports a large number of communications protocols including TCP/IP, UDP, ActiveX and DataSockets (most of these protocols are used quite extensively in SPICE - for instance, the Status Display program is totally driven by LabVIEW DataSockets).

4. There are numerous mathematical functions and analysis tools incorporated directly into LabVIEW. This includes linear algebra, basic calculus (integration, differentiation, etc.), basic statistics, and curve fitting routines including Levenburg Marquardt algorithms.

5. Finally LabVIEW is largely platform independent allowing the code to be written and executed on several operating systems including Windows, Mac OS, and several Unix platforms.

CORE COMPONENTS

The core of SPICE consists of 2 components, a command line interpreter and a hardware interface layer. These 2 components are completely independent of the type of instrument being controlled.

1. Command Line Interpreter

The command line interpreter sequentially executes commands from a first-in-first-out (FIFO) stack. This command stack takes the form of a simple ascii file on the control computer which means that any process which is capable of writing to this ascii file is able to issue commands. Currently, commands can be issued through a provided command-line of the main program window or from the graphical user interface (see Information about the Graphical User Interface for more information).

The commands are all executed dynamically. This means that none of the commands are hard-wired into the program and commands can be added, removed, or modified without restarting the program. The available commands are specified in a top-level configuration file.

The command interpreter includes an integrated alias structure which is similar to the alias capabilities of UNIX. This allows users to rename commands or combine a frequently used command sequence into a single, simple command. There are 3 levels of alias definitions included in SPICE:
1. System - alias definitions specific to a specific class of instrument
2. Instrument - alias definitions specific to a specific instrument
3. User - alias definitions which which the user can specify

Another feature of the command line interpreter is a structure which allows access to any variable stored in LabVIEW global variable space from the command line. These variables are accessed using a syntax @(name) where name and its definition is stored in a variables configuration file. Detailed information about the use of this structure is given in the How to use command-line variables guide.

2. Hardware Interface Layer

The hardware interface layer consists of a series of classes and methods following the example of standard object-oriented programming languages. Any SPICE hardware driver must contain all the methods required for the specific class of hardware. For instance, to add a new motor controller and its included motor axes, 2 drivers are required, one for the controller class and one for the motor class (which will call the methods present on the controller driver). Provided that both drivers have the methods required for their respective classes, entries are added in the proper configuration files, the main program is re-initialized, and the new hardware is ready to be used. In this scheme, hardware can be added and removed dynamically without requiring a restart of the main program.

The currently implemented classes in SPICE are: controller, motor, counter (includes ratemeters), interfaces (gpib, rs232, etc.), and pseudomotors (not physical motors but quantities which can be derived from physical motors).

More detailed information about device drivers in SPICE can be found in the How to write a device driver guide.

TRIPLE-AXIS SPECIFIC FEATURES

The triple-axis implementation of SPICE contains several advanced features designed largely to expand flexibility. These include:

1. UB matrix: The conversion of angles to and from reciprocal space coordinates uses a UB matrix formalism. The UB matrix is typically used in a 4-circle diffractometer but has been modified in SPICE to work with the standard triple-axis geometry where one usually has 2 perpendicular arcs and a sample rotation axis to define the sample orientation. In addition, the formalism has been generalized to allow inelastic scans to be performed. The advantages of this formalism are:
(a) The arcs can now be used to make movements in reciprocal space
(b) Any crystal symmetry (including tricilinc) can be used within the program

2. Tabbed Graphical User Interface - see the Introduction to the GUI guide for more information.

3. Scanon - the scanon structure allows any combination of drives and counts to be converted into a properly formatted scan. For more information, see the How to create a custom scan guide.

4. Countfiles - Generally a scan consists of drives followed by counts to some specified preset (for instance, 30 seconds). The usual count in a scan can be replaced by a series of commands specified in a countfile. See the How to use a countfile for more information.

5. Status Display - A stand-alone program has been written to monitor the state of the triple-axis spectrometer. This program is written using LabVIEW DataSockets and, consequently, can be operated from any computer with a valid internet connection. More detailed information about the Status Display can be found in the Introduction to Status Display guide.

6. Drive, Scan, and Count - We have implemented a scheme where all changeable quantities (including physical motors, pseudomotors, sample enviroment quantities, flipper voltages, etc.) are all treated as motors. This means that the command to change the magnetic field strength is the same as the command to drive a physical motor which is the same as the command which changes the energy value. A consequence of this is that the majority of experiments can be performed with a knowledge of 3 basic commands: drive,scan, and count. This means that users only need to learn these 3 basic command to be able to perform many experiments and helps with user friendliness.


GUI introduction

GUI Introduction

The following tabs are available within the program: Click on the links below for more detailed information

Setup
Experiment
Nickel Calibration
Analyzer Calibration
User Defaults
Hardware
 Motors
Counters
Devices
Miscellaneous
Sample
Sample/Mode Information
UB Matrix
Angle Utilities

Drive/Scan/Count
Drive
Scan
Count Preset
Countfile
Spurion Check

Macro/Stack
 Edit Macro
View Command Stack

Notes

Data
Browse Data
Graph Data
Combine Data
Data Buffers
Analysis Log
Experiment Summary

Help
bine


Status Display introduction

Status Display

Description

A stand-alone program has been developed to display the status of the spectrometer. To accomplish this, all the information to display the status is published on a series of LabVIEW DataSockets. DataSockets are designed to remotely display controls and indicators from a LabVIEW program and utilize a publish and subscribe protocol similar to HTTP. As DataSockets can be accessed from any computer with an internet connection the Status Display program can be run remotely allowing users to monitor the status of the spectrometer as if they were sitting at the instrument.

Usage

The Status Display program developed for the triple-axis spectrometer is shown in the following image:
Status Display

The following information is included on the Status Display:

- Select Instrument - the instrument is chosen by a pull-down menu and the list of available instruments is specified in a configuration file.

- Expt # - the current experiment number

- Experiment title

- Detector Information - the detector information box shows the current values of all present channels as well as the current preset channel and value. NOTE that the Linear PSD and Are PSD tabs are included for future use and are currently empty.

- Ratemeters - the multi-colored dial represents the current counting rates. The avaliable ratemeters are selected by a pull-down menu (monitor in the above image). The number (x1 above) represents a multiplier and the current rate will be the number on the dial multiplied by the multiplier. The green light indicates that autoscaling is turned on - clicking on this light will turn off autoscaling and the multiplier can then be manually selected. Finally, the number above the ratemeter provides a digital display of the current rate.

- Motors - a list of all motors and the current position of these motors is shown on the right of the status display. All motors which are not hidden will be shown on the Status Display. To hide a specific motor, use the hide command or its GUI interface. There are 3 lights next to the motor position - the left-most light turns green when the motor is moving, the middle light turns blue when a lower limit is hit, and the right-most light turns red when an upper limit is hit.

- Plot - the current (or last run) scan is plotted in real time in the graph. The title for this plot shown the scan number, scan title, and the calculated values of the center of mass, full width at half maximum, and the sum of counts.

- Command bar - the bar at the bottom of the Status Display shows which command is currently executing.


HowTo Guides Top Level

How To Guides:

1. How to align a single crystal
2. How to write a macro
3. How to create a custom scan
4. How to use countfiles


HowTo align a triple-axis

How to align a triple-axis spectrometer:

This is a step-by-step guide to starting a new experiment and aligning the triple-axis spectrometer.

This guide is split up into 4 main sections:
1. Begin a new experiment
2. Align the monochromator
3. Use a powder standard to calibrate the energy and the sample scattering angle
4. Align the analyzer

1. Begin new experiment

Start a new experiment by typing begin from the command line (the begin command can also be launched from the GUI pull-down menus by selecting File - New - Experiment). This will launch a dialog window (see the figure below) with several fields which must be filled in before the new experiment can begin. The following elements must be supplied: experiment title, users, local contact, monochromator/analyzer selection, collimation, energy information (fixed Ei/Ef and the fixed energy value) and sample information (name, type, lattice constants, and alignment information (if applicable)). Use the tab key (or the mouse) to switch between fields in this dialog window.

begin new experiment

If a single crystal sample is selected, the user can choose how the initial orientation will be specified. The available choices are:

1. Specify a scattering plane - vectors which define the scattering plane and the lattice constants must be given with this option. NOTE: with this option, the 1st vector which defines the plane (h1,k1,l1) is assumed to be along the lower arc.
2. Start with no orientation specified - the lattice constants are specified with this option but no moves in Q-space will be allowed until a valid orientation has been specified. For information on how to define an orientation see How to align a single crystal.
3. Keep last used orientation - this option will retain the orientation last used in the program. This option is included primarily for cases where the same sample will be used in sebsequent experiments.

After the form is filled out, hit the Begin New Experiment button to initialize the new experiment.

2. Align the monochromator

The first step in aligning the spectrometer is the alignment of the monochromator crystal. NOTE: this should ONLY be performed under the supervision of the local contact. The monochromator alignment is accomplished through the following set of commands:
defcount monitor
preset time 2
scanrel m1 -1 1 .1
The above commands set the default counter to be the monitor, the preset to 2 seconds and performs a relative scan of motor m1 +/- 1 degree in steps of 0.1 degrees. If the resulting scan is symmetric, the m1 position can be driven to the center of mass by:
com m1
If the scan is not symmetric but the nominal peak position is given by the motor value PEAK, the m1 position can be driven to this value by:
drive m1 PEAK
The monochromator should now be aligned but the default counting channel should be set from the monitor back to the detector:
defcount detector

3. Calibration using powder standard

(a) The next steps involve running a standard sample to calibrate the energy of the incident beam (zero of motor m2) and the zero of sample scattering angle s2. First, drive the monochromator to the selected energy value (13.6 meV in this example), the analyzer scattering angle (s2) to the straight-through position, and the analyzer orientation angle (a1) to a transmission setting (Motors > Drive)

drive ei 13.6 a2 0 a1 90

This command can also be issued from the GUI by making the selections shown in the figure below and hitting the blue Drive button:

drive ei and a2 and a1

(b) Cursory check of the zero of s2. NOTE: This step may be skipped if the alignment is believed to be fairly accurate as it will only set a rough value for the s2 zero angle. It is suggested that an Al-B attenuator be used to prevent saturation of the detector. Scan s2 through the direct beam, from –1 to 1 in steps 0f 0.1 for a preset time of 1 second.

scan s2 –1.0 1.0 0.1 preset time 1

Set the s2 zero angle. If the direct beam is centred at 0.4, then type

zero s2 0.4

This can also be accomplished by using the setpos alias. Drive s2 to the center (0.4 in this example):

drive s2 0.4

and set the position to be 0:

setpos s2 0

This rough alignment is performed to ensure the ranges for the standard sample calibration are adequate. As mentioned above, if the alignment is believed to be fairly accurate, this step can be skipped.

(c) Nickel powder calibration of energy and zeroes.

Put the Ni powder can at the sample position and remove all PG filters (The filter removal is necessary as the calibration uses lambda/2 reflections).

The standard powder calibration is designed to be fully automated and should be run from the GUI. Details of the procedure are available in the help document for the calibrate command. The calibration is initiated from the GUI by selecting the Nickel Calibration tab from the Setup top-level tab. To begin a calibration, the user types in the energy at which the Ni calibration will be performed (13.5 meV in the example shown below), selects an appropriate count time (unless collimation is fairly tight, a count time of 1 second should be adequate), and clicks the blue Perform Calibration button. While the calculation is taking place, a green Calibration Running button is visible as shown in the image below.

calibration running

During the calibration, the user can examine the scans and the generated fit by selecting the Reflection pull-down menu. If any of the fits are not satisfactory, the Redo Fit button will bring up a popup box where initial guess parameters can be input. Following the completion of the calibration, the Calibration Running button will be replaced by the boxes shown below where the current and calculated zero angles for motors m2 and s2 are shown. The user can examine the output in the logfile or can click on the blue Print Results button to produce a hardcopy summarizing the fit information from the calibration. If the calibration seems satisfactory, the uses accepts the new zero angles by clicking on the blue Accept new zero angles button.

calibration finished

After accepting the new zero angles, the Accept new zero angles button will disappear and the current and calculated zero angles should now be identical as shown in the bottom image. This will complete the Ni powder calibration. A hardcopy of all the scans and the individual fits can be produced by hitting the blue HardCopy button.

calibration accepted

4. Analyzer alignment

A strong incoherent scatterer should be placed at the sample position. The typical options are to use the same Ni powder used above (being sure to be well away from any powder lines) OR use a vanadium sample. The analyzer is optimized by scanning some combination of a1, a2,ef ande. As most neutron scatterers seem to have their own favorite series of scans for completing this process (and because analyzer scans are not always symmetric) the alignment procedure for the analyzer has not been automated. Once a1 and a2 have been optimized (and they are positioned at that optimal position), the process of setting the zero angles has been automated and can be accessed from the GUI by selecting the Analyzer Calibration tab from the Setup top-level tab. The zero angles are set by hitting the blue Make current analyzer setting elastic button.
analyzer calibration

The spectrometer is now aligned and the next step in setting up an experiment involves aligning the sample.


HowTo align a single crystal

How to align a single crystal:

This guide is intended to describe the process of aligning a single crystal in SPICE. As the transformation from angles to reciprocal space is accomplished using a UB matrix formalism, this process is slightly different than that typically used on a triple-axis.

The simplest way to explain this process is with an example of a typical sample alignment. We will assume a single crystal of YBCO is mounted in the (h 0 l) scattering plane.

The approximate alignment of the sample can be specified when the begin command is issued to start a new experiment. An example for the case of YBCO in the (h 0 l) plane is shown in the figure below.

YBCO Begin New Experiment
The (h,k,l) indices of the 2 reflections which define the scattering plane vectors and the sample lattice constants must be given if the Specify Scattering Plane option if selected. It is important to note that in this case, the first vector given is assumed to be along the lower arc. For instance, if the sample was mounted such that the (0,0,l) direction was along the lower arc, the two reflections shown above should be swapped.

We will now make the assumption that the instrument has been aligned (see How to Align a triple-axis spectrometer). The following steps are needed to align the sample and input the alignement information into SPICE.

1. Ensure the monochromator and analyzer are in the elastic position:
drive e 0

2. Check the starting configuration of the UB Matrix. To do this, select the UB Matrix tab from the Sample top-level tab. If the begin box was filled in as shown above, the UB Matrix tab should have the mode set to Define scattering plane vectors and 1 reflection, the lattice constants and scattering plane vectors set as shown above and a single reflection set so that the first specified peak is along the lower arc.

initial ub matrix tab

3. Drive to a known reflection along the 1st specified direction (for instance drive to the (2,0,0) reflection for the case shown above):
drive h 2 k 0 l 0 e 0
the alias br will drive to a bragg position so the same command could be given as:
br 2 0 0

4. Close the beam shutter and mount the sample such that the first specified vector is along the bisecting lower arc. For the case shown above this corresponds to mounting the sample with the (1,0,0) direction along the lower arc.

5. Scan angles s1, s2, and sgl to optimize the intensity of a known reflection along the (1,0,0) direction - say the (2,0,0) peak in the example above. For the purposes of this example, we will assume the maximum was found at:
s2=-78.794
s1=-40.682
sgl=-2.5
 See the NOTE at the bottom of this guide regarding what happens if the specified direction is not sufficiently close to the lower arc.

6. We will now assume that the spectrometer is at the positions specified above. We will now enter the measured peak position in the UB Matrix tab - enter h=2, k=0, l=0 and press the green Add button. This should result in the following UB Matrix tab:
ub matrix 1 peak added
To calculate the UB matrix using the specified peak positions, click on the blue Calculate UB Matrix Update Orientation Information button. This will result in a popup box that contains information about the UB matrix calculation. Within this window you can see the peak information as it was given on the UB Matrix tab, the calculated angle position for the specified h,k,l (this is where a drive h k l will send the motors) and the calculated h,k,l from the motors as specified.
ub matrix calculation 1
We can see that the calculated h,k,l are not quite at (2,0,0) - this is because the a lattice constant given is not exactly consistent with the measured peak position. At this point you can either accept the orientation by clicking on the blue Accept Configuration button or cancel and tweak the orientation. In this example, we will choose the later and click the blue Cancel button.

There are a number of utilities present to do some simple angle calculations (and also the command-line calc command). One of these allows you to calculate the d-spacing from the measured s2 angle. This is shown in the following image:
d-spacing from 2-theta
from the above calculation, we can see that the measured d-spacing is 1.93216 which gives an a lattice constant of 2*1.93216=3.86432. We can put this value into the UB matrix tab for the a lattice constant and click on the blue Calculate UB Matrix Update Orientation Information button. This will now result in the following pop-up box:
ub matrix 2nd calculation
We can now see that the input lattice constant is more consistent with the measured s2 angle so we accept the orientation by clicking on the blue Accept Configuration button.

7. A valid orientation now exists but it only has information about the (h 0 0) direction. We need to check that the crystal is, in fact, in the (h 0 l) scattering plane as was originally input. To do this, we need to find another reflection in the scattering plane and re-calculate the UB matrix with the information from both reflections.

As the other direction which defines the scattering plane is the (0 0 l) direction, we will look for some peak along this direction (for the sake of this example, the (0 0 4) reflection will be assumed. As with the (2 0 0) case above, start by driving to the (0 0 4) position:

drive h 0 k 0 l 4 e 0

OR using the br alias

br 0 0 4

As the (0 0 4) direction should be (at least mostly) along the upper arc, we need to scan s2, s1, and sgu to properly align the (0 0 4) Bragg reflection. Let's assume that this reflection was optimized at:

s2=-49.43
s1=-116.0
sgu=3.5

We now need to input this information into the UB matrix. To do this, select the UB Matrix tab from the Sample top-level tab. The calculation mode now needs to be changed from Define scattering plane vectors and 1 reflection, to Define 2 non-colinear reflections. Assuming that the motors are now positioned at the optimal positions for the (0 0 4) Bragg reflection, we now add the reflection: first type in (0 0 4) for (h k l), then select Reflection 2 from the blue pull-down menu and finally add the reflection by hitting the green Add button. The UB Matrix tab should now look like the following:
UB matrix - 2 peaks example
We calculate the UB matrix, as before by clicking on the blue Calculate UB Matrix Update Orientation Information button. The resulting popup box should look like the following:
ub matrix popup - 2 peaks 1
From the above image, you can see that the calculated lposition for the (0 0 4) reflection is not exactly at (0 0 4) again indicating a problem with the lattice constant. As above, we can recalculate the c-axis lattice constant which indicates that it should change from 11.68 Angstroms to 11.732 Angstroms. Putting this new value in and re-calculating the UB matrix (the blue Calculate UB Matrix Update Orientation Information button) results in the following:
ub matrix popup - 2 peaks 2
We can see that both reflections are rather close to the correct values and the deviation in the (0 0 4) peaks stems from the fact that the 2 reflections are not precisely separated by 90 degrees.

The sample is now completely aligned in the (h 0 l) scattering plane.

NOTE Regarding Arcs

In the 2 peak configuration, the calculated positions for the arcs may not be the same as those input. The program calculates the set of arc values needed to put BOTH reflections in the scattering plane. This may correspond to a completely different set than those initially input. This is particularly true if the measured reflection is not very nearly along an arc. If that is the case, you may find that the calculated set of arc values will not be optimally aligned for either reflection. The only way to solve this problem is to optimize BOTH sgu and sglatBOTH reflections. If these values are now input into the UB Matrix calculation, a consistent and correct set of arc values should be calculated.


HowTo write a macro

How to write a macro:

A macro is essentially a series of commands which can be stored in a file. In this guide, we will describe the process of writing and executing macros.

Writing macros:

The simplest macros simply contain a list of commands, for example:

drive m2 40
count preset time 10 repeat 3
drive m2 60
count preset time 10 repeat 3

To save the macro to a file which can be executed from SPICE, the file should be saved in the User Macro directory the location of which can be found on the GUI by selecting the Default Directories tab from the Setup top-level tab. The User Macro directory location is stored on this tab in the Experiment Macro directory text box. In addition, the default extension for SPICE macros is .macro and the complete filename does not need to be specified when this extension is used. To make the process of writing macros simpler, we have included a graphical interface which can be accessed by selecting the Edit Macro tab from the Macro/Stack top-level tab. If the desired macro is typed into the top textbox on this tab, the green Write to file button will bring up a file dialog box which has the correct path and extension included.

runfile GUI interface

The example shown in the above macro shows a useful feature of the macro processing in SPICE - the ability to use loops. The loop syntax in macro is the following:

loop i=start,stop,step
.
.
.
endloop

if step is not included, a step size of 1 is assumed. In addition, the loop variable can be used in the commands contained in the loop by using the syntax %name. For example, in the image above, the first command in the loop is drive s2 50+%i where i is the loop variable. From the GUI, loops can be expanded by clicking of the yellow Expand button and the results are printed in the lower text box. The results of this expansion are shown in the above image and the various drives corresponding to different i values can be clearly seen. There are no limitations in this loop structure and embedded loops are also allowed.

Another feature which can be used in writing macros is the ability to pass on command line arguments. As an example of this, consider the following macro:

drive s2 40+%1
count preset time %3
drive s2 50+%2
count preset time %3

If this macro is then saved (let's assume the filename is testvariable.macro) then the command run testvariable 10 -5 100 will execute the following set of commands:

drive s2 40+10
count preset time 100
drive s2 50-5
count preset time100

This structure is useful when there is some set of commands which need to be repeated regularly but with slightly different parameters.
NOTE: there is no way of passing command line variables to a macro using the included graphical user interface. Therefor the run command will need to be used.

Executing Macros:

Macros can be executed using either the graphical user interface or the run command.

1. From the graphical user interface, as shown in the image above, the macro can be executed directly by hitting the blue Execute Macro button. As mentioned above, command line arguments cannot be passed to a macro using this method.

2. The second method of executing a macro is with the run command. Detailed information about this command can be found in the run help document.


HowTo create a custom scan

How to create a custom scan:

This guide is intended to describe the use of the scanon/scanoff structure in SPICE to produce a custom scan. The basic idea behind this structure is that it allows any combination of drives and counts (and other commands if required) to be converted into a custom scan. The best way to explain this structure is by first describing the commands which are present and then using an example.

Commands:

scanon: This command initiates the structure. It turns on a variable which prevents the normal output of commands, stores any errors that occur in subsequent commands, and records the returned values of any counts that occur.

stepend: This command signifies the end of a step in the scan. Any counts that have accumulated during the step are then output to the logfile and datafile and any errors that occured are printed in the logfile on a separate line (with the standard comment delimiter (#) in front of the messages.

stepbegin: This command is not required for operation of the scanon/scanoff structure but is included for flexibility. The execution of this command determines the point at which the motor positions will be stored for a step. For instance, if a drive to a specific h,k,l point occured in a step which was then followed by a drive of some motor, the user would probably want to record motor positions after the h,k,l drive and not after the subsequent motor drive. The use of the stepbegin command after the drive would allow the positions to be recorded at this point.

scanoff: This command ends the scan and turns off the scanon variable so that normal command execution is restored.

NOTE: if a scanon/scanoff generated scan is stopped before execution of the scanoff command, the program still believes that the scanon structure is activated and will NOT resume normal operation until a scanoff command is issured.

Examples:

The easiest way to understand the use of this structure is through a series of examples.

Example #1:

This example is not particularly useful but explains the basic funtionality of the structure.


HowTo use countfiles

How to use countfiles:

This guide is intended to describe using countfiles with the scan command.


HowTo write a device driver

How to write a device driver:

This guide is intended to describe device handling in SPICE and how to create new device drivers.


HowTo use command-line variables

How to use command-line variables:

A structure exists in SPICE where any quantity stored in global variable space can be used from the command line. The combination of this together with the ability to perform mathematical operations on the command line is very powerful and makes the command-line interface much more powerful.

Usage:

The use of these command line variables is best described with an example. An example of a command which extensively uses these command-line variables is the setpos alias. The definition of this alias is:

zero %1 @(%1.zero)+@(%1)-%2

To understand this definition lets consider a specific case. Let's assume the motor s2 isn't correctly zeroed. The user finds the correct zero to be at 1.5 degrees, moves to this position and then issues the following command:

setpos s2 0

If the currently stored zero angle for s2 is -0.5 degrees, the above setpos command will issue the following zero command:

zero s2 @(s2.zero)+@(s2)-0

Since @(s2) reads the current position for motor s2 (1.5 degrees) and @(s2.zero) will read the currently stored zero angle for motor s2 (-0.5 degrees), the parsing of the command-line variables translates the command to:

zero s2 -0.5+1.5-0

which the mathematical parser in the command-line then converts to:

zero s2 1.0

which is the correct zero angle which is needed to convert the current position (1.5 degrees) to the specified position (0 degrees). It should be fairly clear from the above example that the use of these command line variables takes a process which requires the user to know the current zero angle of a motor and the definition of how that zero angle should be properly applied and convert it to an alias which is very easy to use.

Definitions:

The definitions of command-line variables requires a knowledge of global variable names and the corresponding global variable files in LabVIEW and, therefore, should only be added or modified by someone with a fairly good understanding of the underlying code.

The command-line variables are defined in a configuration file. The location of that file is specified in the top-level configuration file (usually named configure.ini and located in the same location as the spice.exe executable - typcally c:\program files\spice). Under the [Paths] section, there is a Variables key which defines the name of the command-line variable configuration file. This file name will be relative to the System path, defined by the System key, which is relative to the top-level path, defined by the TopPath key. So, for example if the top-level configuration file looks like the following:

[Paths]
TopPath=C:\DataAcquisition
.
.
System=System
.
.
Variables=variables.txt

then the command-line variable definition file will be:

C:\DataAcquisition\System\variables.txt

The configuration file itself has a syntax which is best described through a series of examples.

Example 1:

[numdevices]
globalfile=instrument_globals.vi
globalname="Number of Devices"
globaltype=integer

This definition defines the number of devices reads the value from the Number of Devices integer control which is contained in the instrument_globals.vi global LabVIEW file. The name of the variable defines the name which can be accessed from the command line so access to this command would be @(numdevices). As an example, if there were 30 devices, the command:

comment "The number of devices for this spectrometer is @(numdevices)"

would generate the command

comment "The number of devices for this spectrometer is 30"

Example 2:

[alat]
globalfile=UBmat_globals.vi
globalname="Lattice Parameters"
globaltype=2dreal
rowindex=0
columnindex=0

This definition allows the a lattice constant to be used. This lattice constant is stored in a 2d real array in the UBmat_globals.vi file. This differs from example 1 in that the row index and column index of the 2d array must be specified to allow the variable to be extracted. For a 1d array, only the rowindex is needed. This command line argument is accessed by @(alat).

Example 3:

[zero]
prefix=motor
globalfile=MotorUserGlobals.vi
globalname="Motor Zeros"
globaltype=1dreal

The above definition allows the current stored zero angle for a motor to be used and is the variable employed in the example above. This differs from the previous 2 examples in that it includes the prefix= key. This allows an array to be indexed by a given name which in this case is the motor name. So Motor Zeros is a 1d real array stored in the MotorUserGlobals.vi file but the value returned from it depends on which motor name is given as the prefix. For instance, @(s1.zero) will return the zero angle for motor s1.

Existing Definitions:

The definition which currently exist in SPICE can be separated into 2 categories, those that require a prefix and those that do not:

No prefix required:

Variable Name | Usage | Description | Type
lastcommand | @(lastcommand) | The last as-typed command issued | string
defy | @(defy) | The default y variable | string
defx | @(defx) | The default x-variable | string
numdevices | @(numdevices) | The number of defined devices | integer
alat | @(alat) | The a lattice constant | real
blat | @(blat) | The b lattice constant | real
clat | @(clat) | The c lattice constant | real
alpha | @(alpha) | The alpha lattice constant | real
beta | @(beta) | The beta lattice constant | real
gamma | @(gamma) | The gamma lattice constant | real
energy | @(energy) | The stored energy value (meV) | real
methodreal0 | @(methodreal0) | The first real value returned from the method command | real
methodreal1 | @(methodreal1) | The second real value returned from the method command | real
methodreal2 | @(methodreal2) | The third real value returned from the method command | real
methodint0 | @(methodint0) | The first integer value returned from the method command | integer
methodint1 | @(methodint1) | The second integer value returned from the method command | integer
methodint2 | @(methodint2) | The third integer value returned from the method command | integer
methodstr0 | @(methodstr0) | The first string value returned from the method command | string
methodstr1 | @(methodstr1) | The second string value returned from the method command | string
methodstr2 | @(methodstr2) | The third string value returned from the method command | string
methodreturn | @(methodreturn) | The overall integer return code from the method command | integer

Prefix required:

Variable Name | Prefix | Usage | Description | Type
ulimit | motor | @(s1.ulimit) | The upper limit for the specified motor | real
zero | motor | @(s1.zero) | The zero angle for the specified motor | real
tolerance | motor | @(s1.tolerance) | The tolerance for the specified motor | real
speed | motor | @(s1.speed) | The speed of the specified motor | real
status | motor | @(s1.status) | The status of the specified motor | real
llimit | motor | @(s1.llimit) | The lower limit for the specified motor | real
motorunits | motor | @(s1.motorunits) | The units of measure for the specified motor | string
presetable | counter | @(detector.presetable) | Whether a counter if presetable or not | boolean
defpreset | counter | @(detector.defpreset) | The default preset value for the specified channel | real
countunits | counter | @(detector.countunits) | The units of counting for the specified channel | string
name | device | @(s2.name) | The name of the specified device | string
alias | device | @(s2.alias) | The alias of the specified device | string
type | device | @(s2.type) | The type of the specified device | string
desc | device | @(s2.desc) | The description of the specified device | string
vi | device | @(s2.vi) | The vi name for the specified device | string

NOTE: for prefix=device, the prefix can be any specified device (motors, counters, etc.) not only a motor (as used in the above example).


Commands Top level

Available Commands:

addpeak | help | scan
admin | hide | scanoff
alias | hold | scanon
analyzer | initialize | scansim
begin | lattice | scantitle
calc | logfileoutput | showdest
calibrate | lowerlimit | spv
collimation | method | stepbegin
comment | mode | stepend
contact | monochromator | title
count | password | tolerance
countheader | peak1 | ubcalc
defcount | peak2 | upperlimit
defxy | plusminus | users
drive | preset | wait
ef | run | zero
ei | sample |


addpeak

addpeak:

The addpeak command adds a reflection to the list which is used in refinement of the UB matrix.

The syntax for the addpeak command is:

addpeak h k l s2 s1 sgl sgu ei ef

OR

addpeak h k l

The first syntax specifies the motor positions explicitly while with the second syntax, the current motor positions are used.

The position and indices for the reflections to be used in refinement of the UB matrix can also be set from the GUI by selecting the UB Matrix tab from the Motors/Scanstop-level tab. Adding reflections for refinement is only available when the mode is set to Refine UB (3 non-coplanar reflections required) (shown in the image below). The peak can be added either using the current motor positions or by specifying the positions explicitly (as controlled by the blue pull-down menu). To refine both the lattice constants and the orientation using this list of reflections, hit the blue Calculate UB Matrix Update Orientation Information button. NOTE: as all 6 lattice constants are refined, 3 non-colinear reflections are required for this calculation to work.

NOTE: the orientation information is easier to modify from the GUI than from the command-line as it allows the user to preview the orientation information prior to accepting the changes. The addpeak command should only be executed from the command-line by experienced users as it could yield unexpected results. For detailed information about entering orientation information from the GUI see the How to align a single crystal guide.

ub matrix refinement


admin

admin:

The admin command enters/exits from the administrator mode.

The syntax for the admin command is:

admin

OR

admin quit

Typing admin with no arguments will prompt the user for the administrator password (as shown in the following image) provided the administrator mode is currently disabled.

admin password box

Typing admin quit (other valid replacements for quit are log, logoff, or exit) will exit from the administrator mode provided administrator privileges are currently enabled.


alias

alias:

The alias command will add a user defined alias.

The syntax for the alias command is:

alias name "def %1 %2*%3..." [minvars=n]

Where the alias definition must be in quotes and the optional minvars argument defines the minimum number of variables which must be specified when the alias is called from the command line.

Typing the alias command with no arguments will update all the stored alias definitions based on the entries in the alias configuration files and will give a list of all available alias definitions.

Alias definitions can also be added by manually adding an entry to the user alias configuration file. A typical entry has the following form:

[scanrel]
definition="scan %1 @(%1)+%2 @(%1)+%3 %4"
numbervars=4
minvars=4
help="Do a relative scan using the default preset. Eg. scanrel s1 -1 1 .1"

The above entry shows the alias definition for the scanrel alias. The alias name itself is the section name and the definition is defined using the definition key. Note that command-line arguments are specified using a %n syntax where the arguments included in the definition must be sequentially numbered. The numbervars key indicates the number of variables defined in the definition and the minvars indicates the minimum number of variables which must be given on the command line. This is included to allow alias definitions where some of the arguments are optional. The help key is used with the help command to provide additional information about a specific alias.


analyzer

analyzer:

The analyzer command sets the d-spacing of the analyzer based on definitions stored in the configuration file.

The syntax for the analyzer command is

analyzer name

where "name" must be defined with a corresponding d-spacing in the top-level configuration file.

The top-level configuration file is named configure.ini and is in the same location as the spice.exe executable (most likely c:\program files\spice). The analyzer entries in the configuration file have the following form:

[Analyzer]
PG002=3.355
PG004=1.6775
BE110=1.5
Si111=3.135
Ge111=3.267
none=0.0

where each entry represents an analyzer name and its corresponding d-spacing. To add a new entry, simply type in a new name and d-spacing. To make the program re-read the configuration file, type initialize software.

The analyzer command can also be accessed from the GUI by selecting the Experiment tab from the Setup top-level tab. To change the analyzer d-spacing, the green button at the bottom of the tab must be changed from "Monitoring ... Click to allow changes" to "Changing ... click to monitor". Select the analyzer name from the blue "Which Analyzer" pull-down menu and commit the changes by clicking on the blue "Update Parameters" button.

experiment setup


begin

begin:

The begin command begins a new experiment.

The syntax for the begin command is:

begin

This command will pop up the following dialog box which must be filled in before the new experiment will begin:
begin pop-up window
If a single crystal sample is selected, the user can choose how the initial orientation will be specified. The available choices are:

1. Specify a scattering plane - vectors which define the scattering plane and the lattice constants must be given with this option. NOTE: with this option, the 1st vector which defines the plane (h1,k1,l1) is assumed to be along the lower arc.
2. Start with no orientation specified - the lattice constants are specified with this option but no moves in Q-space will be allowed until a valid orientation has been specified. For information on how to define an orientation see How to align a single crystal.
3. Keep last used orientation - this option will retain the orientation last used in the program. This option is included primarily for cases where the same sample will be used in sebsequent experiments.

After the form is filled out, hit the Begin New Experiment button to initialize the new experiment.

This command can also be accessed from the GUI by choosing
File - New - Experiment from the pull-down menus as shown in the following image. 		GUI begin


calc

calc:

The calc command calculates motor positions for a given h,k,l,e,ei,ef (or vice-versa).

The syntax for the calc command is:

calc motor_1 value1 motor_2 value2 ...

where motor_n can be either a physical motor or a Q,E value. If Q,E values are given, the physical motor positions are calculated and if physical motors are given, the resulting Q-E positions (if any) are given.

The functionality of the calc command can be accessed through the GUI by selecting the Angle Utilities tab from the Sample top-level tab. NOTE that the buttons in the tab DO NOT issue calc command but rather operate directly. This is incorporated so that the user can perform calculations while other commands are running.

The available features on this tab are:
1. Calculate motor positions for above Q-E position: type in the h,k,l, and energy transfer and the resulting angles are given below the button.
2. Calculate Q of above motor positions: type in the positions of m2,a1,s2,s1,sgl.sgu and the resulting Q-E positions will be given in the top h,k,l,Energy indicators.
3. Drive to the above (h,k,l,E): this button will drive the motors to the h,k,l,Energy specified above.
4. Calculate -->: this button takes the observed sample scattering angle (s2) and calculates the resulting d-spacing and Q. This calculation uses the energy that is stored for both ei and ef. For instance, if you are working in fixed ef mode with a fixed ef value of 14.7 meV then this energy is used in the calculation.
5. Calculate angle between two (h,k,l) positions: this button take the (h,k,l) indices for 2 reflections and calculates the angle between these two positions. This (in conjunction with 6. below) is useful when 2 reflections have been measured but the indices are unknown.
6. Calculate angle between two Q's with above motor positions: this button take 2 sets of (s2,s1,sgl,sgu) motor positions and calculate the angle between them. This is useful (in conjunction with 5. above) when 2 reflections have been measured but the indices are unknown.

angle calculation utilities


calibrate

calibrate:

The "calibrate" command is used to perform a standard powder calibration.

The syntax for the "calibrate" command is :

calibrate begin [beg_opts]

is used to initialize the calibration. The options for calibrate begin (i.e. beg_opts) are any of:

1. file = filename (the name of the calibration file - a file name will be automatically generated if none is given)
2. standard = name (which must be included in the top-level configuration file)
3. energy = value (if no energy is specified, the current value of Ei is assumed).

OR

calibrate fit [fit_opts]

will fit either the LAST scan or a specified scan number using options specified in fit_opts. The avaliable options for calibrate fit are any of:

1. scan = n (will use the data in scan n - NOTE that the last scan will be used if no scan number is specified)
2. indices = h k l
3. npeaks = n (the number of Gaussians to fit to)
4. guess = back height1 fwhm1 pos1 height2 fwhm2 pos2 (where back=background, height1=the amplitude of peak 1, fwhm1=the full-width at half-maximum for peak 1, pos1=the position of peak 1, etc.)
5. peakstore = n (the peak position to store in the calibration file - this option is only needed if npeaks is greater than 1)

It is important to note that only one peak can be added at a time using the calibrate command so if multiple peaks are included in the scan which should both be added to the calibration file, the calibrate fit command must be issued multiple times (2 times for 2 peaks for example). In addition, note that a valid calibrate begin must be issued prior to any calibrate fit commands as the begin option generates and initializes the calibration file.

OR

calibrate finish [finish_opts]

will complete the calibration. The available option for calibrate finish is:

1. file=filename (if not given, the stored filename from the calibrate begin command is used)

An example of a macro which uses the calibrate command is shown below. Note this macro will do a complete Ni-powder calibration for energies between 5 and 20 meV.

calibrate begin standard ni energy %1
drive ei %1
preset time %2
drive s2 -2*57.3*asin((sqrt((81.8*3)/(%1*4)))/(7.048))
scantitle "Ni powder (0.5,0.5,0.5)"
scan s2 @(s2)+1.5 @(s2)-1.5 .1
calibrate fit indices 0.5 0.5 0.5
drive s2 -2*57.3*asin((sqrt((81.8)/(%1)))/(7.048))
scantitle "Ni powder (1,0,0)"
scan s2 @(s2)+1.5, @(s2)-1.5,.1
calibrate fit indices 1 0 0
drive s2 -2*57.3*asin((sqrt((81.8*2)/(%1)))/(7.048))
scantitle "Ni powder (1,1,0)"
scan s2 @(s2)+1.5, @(s2)-1.5,.1
calibrate fit indices 1 1 0
drive s2 -2*57.3*asin((sqrt((81.8*3)/(%1)))/(7.048))
scantitle "Ni powder (0.5,0.5,1.5) and (1,1,1)"
scan s2 @(s2)+5.5, @(s2)-2,.1
calibrate fit indices 0.5 0.5 1.5 npeaks 2 peakstore 1
calibrate fit indices 1 1 1 npeaks 2 peakstore 2
drive s2 -2*57.3*asin((sqrt((81.8*4)/(%1)))/(7.048))
scantitle "Ni powder (2,0,0)"
scan s2 @(s2)+2, @(s2)-2,.1
calibrate fit indices 2 0 0
calibrate finish

The above macro takes a single argument which is the energy in meV (%1 in the macro above). The drive commands use energy and the known d-spacing of Ni to drive to the calculated position for each of the Bragg reflections. The calibrate begin,calibrate fit, and calibrate finish commands perform the calibration.

The calibrate command cal also be accessed directly from the GUI by selecting the Nickel Calibration tab from the Setup top-level tab. To begin a calibration, the user types in the energy at which the Ni calibration will be performed, selects an appropriate count time, and clicks the blue Perform Calibration button. While the calculation is taking place, a green Calibration Running button is visible as shown in the image below.

calibration running

During the calibration, the user can examine the scans and the generated fit by selecting the Reflection pull-down menu. If any of the fits are not satisfactory, the Redo Fit button will bring up a popup box where initial guess parameters can be input. Following the completion of the calibration, the Calibration Running button will be replaced by the boxes shown below where the current and calculated zero angles for motors m2 and s2 are shown. The user can examine the output in the logfile from the calibrate finish command or can click on the blue Print Results button which will produce a hardcopy of the output from the calibrate finish command. If the calibration seems satisfactory, the uses accepts the new zero angles by clicking on the blue Accept new zero angles button.

calibration finished

After accepting the new zero angles, the Accept new zero angles button will disappear and the current and calculated zero angles should now be identical as shown in the bottom image. This will complete the Ni powder calibration.

calibration accepted


collimation

collimation:

The collimation command is used to set the instrumental collimation.

The syntax for the collimation command is:

collimation Source-Monochromator Monochromator-Sample Sample-Analyzer Analyzer-Detector

Example:

collimation 40 40 60 120

Where the collimation values are in minutes.

The collimation command can also be accessed from the GUI by selecting the Experiment tab from the Setup top-level tab. To change the collimation values, the green button at the bottom of the tab must be changed from "Monitoring ... Click to allow changes" to "Changing ... click to monitor". Type in the collimations in the collimation numerical controls (preMONO=source-monochromator; M-S=monochromator-sample; S-A=sample-analyzer; A-D=analyzer-detector) and commit the changes by clicking on the blue Update Parameters button.

collimation setup


comment

comment:

The comment command appends a text comment to the logfile.

The syntax for the comment command is:

comment "This is the comment" [title "This is the title"]

where the comment to be added and the optional title must be in quotes.

The comment command can also be accessed from the GUI by selecting the Notes top-level tab. The comment can be added to the logfile in 3 ways which are selected from the Method pull-down menu:

1. Insert into logfile *NOW* - this option doesn't issue the comment command but rather writes the comment text directly into the logfile.
2. Append to logfile following completion of current command - this option issues a comment command but places the command at the top of the command-stack so that it is the next command executed.
3. Append to logfile after completion of all input commands - this option issues a comment command at the end of the command stack to be executed following all other commands wating to be executed.

Once the appropriate method is chosen and the comment text written in the text box, the comment is added by clicking on the blue Insert Comment using method specified below button.

GUI interface to comment


contact

contact:

The contact command sets the local contact for the experiment to a specified value.

The syntax for the contact command is:

contact "local contact"

where the specified local contact must be in quotes.

The contact command can also be accessed from the GUI by selecting the User Defaults tab from the Setup top-level tab. To change the local contact for the current experiment, the green button at the bottom of the tab must be changed from "Monitoring ... Click to allow changes" to "Changing ... click to monitor". Type the new local contact name in the Local Contact box and click on the blue "Update Parameters" button.

user info


count

count:

The count command will count for a fixed preset.

The syntax for the count command is:

count [preset channel value] [repeat=n] [channel1 channel2 ...]

The preset can be in the form 'channel value' or 'countfile path' if the countfile option is used. The optional repeat=n argument will repeat the count n times. The optional [channel1 channel2 ...] will only display the results for the specified input channels. As an example, to count for 10000 monitor counts, the user would type:

count preset monitor 10000

and to repeat this count 10 times:

count preset monitor 10000 repeat 10

The count command can also be accessed from the GUI by selecting the Count Preset tab from the Drive/Scan/Count top-level tab. To count using a specified preset, the green button at the bottom of the tab must be changed from "Monitoring ... Click to allow changes" to "Changing ... click to monitor". Then click on the green button on the right corresponding to the channel which you would like to use as the preset channel, type in the appropriate preset value, put in a value for repeat (if needed), and click on the blue "Count using specified preset and repeat" button.
gui interface to count


countheader

countheader:

The countheader command is used to specify the headers for the data/logfiles. This is only effective in the countfile and scanon structures - the headers are ignored for normal scans. When envoked, each count in the data/logfile will have the specified name attached to the input channel name (i.e. detector_name1, etc.). The syntax for the countheader command is:

countheader header1 header2 ...

where header1, header2, ... are the headers for the data/logfile.

As an example, the command:

countheader count1 count2

will generate headers in the datafile (for a scan using either the countfile or scanon structure) of the form:

detector_count1 monitor_count1 time_count1 detector_count2 monitor_count2 time_count2

For more detailed information about countfiles, see the How to use countfiles guide and for further information about the scanon structure, see the How to create a custom scan guide.


defcount

defcount:

The defcount command sets the default counting channel. This will define which quantity is reported as the default y value in the logfile and datafile and will also determine which quantity will be plotted on the Status Display.

The syntax for the defcount command is:

defcount channel

where channel is a valid input channel. Typing the defcount command with no arguments will output the current default counting channel.


defxy

defxy:

The defxy command is used to specify the default x and y columns for a scan. This default value is what defines which columns are plotted on the Status Display plotting purposes. This is only effective in the scanon structure.

The syntax for the defxy command is:

defxy xvariable yvariable

As an example, the command:

defxy s2 detector

will set the default x-value to s2 and the default y-value to detector.

For more detailed information on the scanon/scanoff structure, see the How to create a custom scan guide


drive

drive:

The drive command will drive a series of motors (or pseudomotors including q,h,k,l,e,ei,ef) to the specified position.

The syntax for the drive command is

drive motor1 value1 motor2 value2 ...

Note: we have adopted a scheme where all movable quantities are considered to be either a motor or a pseudomotor. This includes physical motors, sample environment parameters (i.e. temperature, pressure, magnetic field, etc.), voltages (for flippers for instance) and reciprocal space and energy parameters. This means that the same drive command can be used to drive any of these values.

The drive command can also be accessed from the GUI. The Drive tab is found under the Motor/Scans top-level tab. The motors and pseudomotors are ogranized into categories for convenience. To add a motor to the list to be driven, simply select it from the appropriate list. To delete a motor, hit the relevant Delete button. Type in the destination for each of the included motors and hit the Drive button to initialize the drive. For the example shown in the photo below, motor s1 will be driven to 20 degrees, motor s2 to -45 degrees, and ei to 15 meV. For repeated short moves, a Jog+ and Jog- button will drive the relevant motor but the amount specified in JogStep.
gui interface to drive


ef

ef:

The ef command will put the instrument in a "Fixed final energy" configuration.

The syntax of the ef command is:

ef value

where value is the stored energy value. Note that this command does not drive the analyzer to this value of ef - to do so, type:

drive ef value

The ef command can also be accessed from the GUI by selecting the Experiment tab from the Setup top-level tab. To change to a fixed final energy configuration and/or the stored value of Ef, the green button at the bottom of the tab must be changed from "Monitoring ... Click to allow changes" to "Changing ... click to monitor". Select "Fixed Final Energy (meV)" from the pull-down menu, change the value for "Fixed Energy (meV)" and commit the changes by clicking on the blue "Update Parameters" button.

GUI interface to ef


ei

ei:

The ei command will put the instrument in a "Fixed incident energy" configuration.

The syntax of the ei command is:

ei value

where value is the stored energy value. Note that this command does not drive the monochromator to this value of ei - to do so, type:

drive ei value

The ei command can also be accessed from the GUI by selecting the Experiment tab from the Setup top-level tab. To change to a fixed incident energy configuration and/or the stored value of Ei, the green button at the bottom of the tab must be changed from "Monitoring ... Click to allow changes" to "Changing ... click to monitor". Select "Fixed Incident Energy (meV)" from the pull-down menu, change the value for "Fixed Energy (meV)" and commit the changes by clicking on the blue "Update Parameters" button.

GUI interface to ei command


help

help:

The help command displays help information for built-in commands and aliases.

The syntax for the help command is:

help command

where command must be either a built-in command or an alias. The text help for a built-in command is set in the top-level configuration file which is named configure.ini and is in the same location as the spice.exe executable (most likely c:\program files\spice). A typical help entry in this configuration file has the form:

[BuiltinHelp]
help="The help command displays help information for built-in commands and aliases.<CR_LF><CR_LF>The syntax for the help command is:<CR_LF><CR_LF> help command<CR_LF><CR_LF>where command must be either a built-in command or an alias."

The character combination <CR_LF> is used to distinguish a new line so that the help can be displayed in the logfile in multiple lines.

For an alias, the help is defined in the relevant alias file. An example of an alias with a defined help entry is shown below:

[driverel]
definition="drive %1 @(%1)+%2"
numbervars=2
minvars=2
help="Do a relative drive"


hide

hide:

The hide command can be used to show or hide the positions of a specific motor. This show/hide state defines which motor positions are printed in the logfile and which motor positions are displayed on the Status Display.

The syntax for the "hide" command is:

hide motor1 0/1 motor2 0/1 ...

where an argument of 1 hides the motor and 0 shows it. The hide command with no arguments will print out which motors are being held.

NOTE that all motor positions are recorded in the datafile (as opposed to the logfile) regardless of the show/hide state.

The hide command can also be accessed from the GUI by selecting the Show/Hide tab from the Setup - Hardware - Motors tabs. To hide (or show if already hidden) a given motor, the green button at the bottom of the tab must be changed from "Monitoring ... Click to allow changes" to "Changing ... click to monitor". Click on the Show button to show or hide a given motor (a green light means a motor is shown and a red light means the motor is hidden - in the image below, motors marc, mtrans, mfocus, and mcrystal are being hidden and all others are being shown). Once the show/hide state of the motors is acceptable, the hide command is issued by clicking on the blue Update Parameters button.

gui interface to hide/hold/zero


hold

hold:

The hold command holds a motor at its current position and prevents it from being driven.

The syntax for the "hold" command is:

hold motor1 0/1 motor2 0/1 ...

where an argument of 1 holds the motor and 0 removes the hold. The hold command with no arguments will print out which motors are being held.

The hold command can also be accessed from the GUI by selecting the Zeros and Holds tab from the Setup - Hardware - Motors tabs. To set a hold for a given motor, the green button at the bottom of the tab must be changed from "Monitoring ... Click to allow changes" to "Changing ... click to monitor". Click on the Hold button to set or remove a hold for a given motor (a green light means there is no hold and a red light means the motor is being held - in the image below, motors mtrans and mfocus are being held and all others are not). Once the hold state of the motors is acceptable, the hold command is issued by clicking on the blue Update Parameters button.

gui interface to hide/hold/zero


initialize

initialize:

The initialize command reads in the configuration files to initialize any changes.

The syntax for the initialize command is:

initialize [software]

If the optional software flag is given, the program will be re-initialized without restarting the hardware. Without the software flag, everything (including all hardware) will be re-initialized.


lattice

lattice:

The lattice command sets the lattice parameters.

The syntax for the lattice command is:

lattice a b c alpha beta gamma
(example: lattice 5 6 7 90 90 90)

OR

lattice [a=alat] [b=blat] [c=clat] [alpha=alphalat] [beta=betalat] [gamma=gammalat]
(example: lattice a=6 beta=89)

In the second syntax, any combination of individual lattice constants can be specified. This allows you to change one lattice constant without having to retype all 6 values.

The lattice command can also be accessed from the GUI by selecting the UB Matrix tab from the Sample top-level tab. Typing in the relevant lattice constants and pressing the blue Set Lattice Parameters button will issue the lattice command.

GUI interface to lattice


logfileoutput

logfileoutput:

The logfileoutput command controls suppression of command output to the logfile.

The syntax for the logfileoutput command is:

logfileoutput on/off

where on will enable output to the logfile and off will suppress the output.

This command is included to allow output from specific aliases look more satisfactory. For an example of an alias which utilizes the logfileoutput command, see the mcu alias.


lowerlimit

lowerlimit:

The lowerlimit command sets the lower limit for a motor.

The syntax for the "lowerlimit" command is:

lowerlimit motor1 value1 motor2 value2 ...

will set the lower limit for motor1 to value1, motor2 to value2, etc.

lowerlimit motor1 motor2 ...

will display the current lower limit for motor1, motor2, etc.

lowerlimit

when given with no arguments, the lowerlimit command will display the lower limits for all motors.

The lowerlimit command can also be accessed from the GUI by selecting the Limits tab from the Setup - Hardware - Motors tabs. To change the lower limit for a given motor, the green button at the bottom of the tab must be changed from "Monitoring ... Click to allow changes" to "Changing ... click to monitor". Type in the new lower limit(s) in the Low Limit numerical control and commit the changes by clicking on the blue Update Parameters button.

gui interface to limits and tolerance


method

method:

The method command executes a method from a device driver. This command is primarily used for debugging device drivers and should only be used by developers.

The syntax for the method command is:

method devicename methodname i int1 int2 ... d dbl1 dbl2 ... s str1 str2 ...

Where:
devicename is the name of the device
methodname is the name of the method to be executed
int1 int2 ... are the integer inputs for the method
dbl1 dbl2 ... are the double inputs for the method
str1 str2 ... are the string inputs for the method.

NOTE: improper use of this command could result in very unexpected behavior - it should only be used by developers.

For more information on device drivers see the How to write a device driver guide.


mode

mode:

The mode command defines the mode which will be used in angle calculations.

The syntax for the mode command is:

mode value [options]

Where value can be:

0 : single crystal - fix the angles in a specified scattering plane
1 : single crystal - allow movements out of the scattering plane and calculate angles to minimize deviation from a specified plane
2 : single crystal - allow movements out of the scattering plane and calculate angles so as to minimize the absolute deviation of the arcs (this is equivalent to mode 1 where the specified plane is defined by both arcs being at 0)
3 : power sample

options are only available for mode 0 or mode 1 and are used to specify the scattering plane. The optional arguments can be either of the form:

sgu value1 sgl value2 (the specified plane is defined by the arc angles sgu=value1 and sgl=value2)

OR

spv h1 k1 l1 h2 k2 l2 (the specified plane is defined by the set of arcs that are required to put the 2 specified vectors [(h1,k1,l1) and (h2,k2,l2)] in the scattering plane.

NOTES:

1. For mode 0 or 1 if options are not specified to define the scattering plane then the previously stored values will be used. However, the ubcalc command (or the GUI interface to ubcalc) will set the arcs automatically provided the ubmatrix is calculated using ubcalc mode 1 or 2. Therefore, in most cases, it is NOT NECESSARY to specify the optional arguments and they should onlybe used by advanced users.

2. The default mode will either be mode 0 or mode 3 (depending on whether a single crystal or powder sample is used) following the start of a new experiment and the user must explicitly select mode 1 or 2 if movements out of the scattering plane is required. This is done intentionally to prevent movements out of the scattering plane unless they are specifically requested.

The mode command can also be accessed from the GUI by selecting the Sample/Mode Information tab from the Sample top-level tab. To change the angle calculation mode, the green button at the bottom of the tab must be changed from "Monitoring ... Click to allow changes" to "Changing ... click to monitor". The required mode is selected with the blude Mode pull-down menu and the mode command is issued by clicking on the blue Update Parameters button. If mode 0 or 1 is selected, 2 numerical controls will be present where the values of Upper arc (sgu) and Lower arc (sgl) which specify the scattering plane can be input. See note 2 above about setting these values.
GUI interface to mode


monochromator

monochromator:

The monochromator command sets the d-spacing of the monochromator based on definitions stored in the configuration file.

The syntax for the monochromator command is

monochromator name

where "name" must be defined with a corresponding d-spacing in the top-level configuration file.

The top-level configuration file is named configure.ini and is in the same location as the spice.exe executable (most likely c:\program files\spice). The monochromator entries in the configuration file have the following form:

[Monochromator]
PG002=3.355
PG004=1.6775
BE110=1.5
Si111=3.135
Ge111=3.267

where each entry represents a monochromator name and its corresponding d-spacing. To add a new entry, simply type in a new name and d-spacing. To make the program re-read the configuration file, type initialize software.

The monochromator command can also be accessed from the GUI by selecting the Experiment tab from the Setup top-level tab. To change the monochromator d-spacing, the green button at the bottom of the tab must be changed from "Monitoring ... Click to allow changes" to "Changing ... click to monitor". Select the monochromator name from the blue "Which Monochromator" pull-down menu and commit the changes by clicking on the blue "Update Parameters" button.

GUI interface to monochromator


password

password:

The password command is used to set the administrator password.

The syntax for the admin command is:

password

To execute the password command, the user must be logged in as an administrator (see the admin command for more details). Assuming the administrator mode is enabled, typing password will first prompt for the current administrator password which must be correctly entered in the popup box shown below before the password can be changed.
enter current password
If the current password is entered, a popup box will appear (shown below) where the new password will be entered. This password must be identically typed twice before the password is accepted. To accept the new password, hit the blue OK button and to cancel the password command, hit the Cancel button.
enter new password


peak1

peak1:

The peak1 command sets the value for the 1st reflection to be used in the UB matrix calculation.

The syntax for the peak1 command is:

peak1 h k l s2 s1 sgl sgu ei ef

OR

peak1 h k l

The first syntax specifies the motor positions explicitly while with the second syntax, the current motor positions are used.

The position and indices for the first reflection can also be set from the GUI by selecting the UB Matrix tab from the Sample top-level tab. The first peak information is available when the mode is set to Define scattering plane vectors and 1 reflection (shown in the first image below) Define 2 non-colinear reflections (shown in the second image below). In both cases, the peak can be added either using the current motor positions or by specifying the positions explicitly (as controlled by the blue pull-down menu). In the second case (2 non-colinear reflections), to add the input information as the first reflection, the blue pull-down menu must be set to Reflection 1. There is also a green button at the bottom of the tab which allows you to swap the information for reflections 1 and 2. To calculate the UB matrix hit the blue Calculate UB Matrix Update Orientation Information button.

NOTE: the orientation information is easier to modify from the GUI than from the command-line as it allows the user to preview the orientation information prior to accepting the changes. The peak1 command should only be executed from the command-line by experienced users as it could yield unexpected results. For detailed information about entering orientation information from the GUI see the How to align a single crystal guide.

GUI interface to peak1 #1
ub matrix 2 peaks


peak2

peak2:

The peak2 command sets the value for the 1st reflection to be used in the UB matrix calculation.

The syntax for the peak2 command is:

peak2 h k l s2 s1 sgl sgu ei ef

OR

peak2 h k l

The first syntax specifies the motor positions explicitly while with the second syntax, the current motor positions are used.

The position and indices for the second reflection can also be set from the GUI by selecting the UB Matrix tab from the Sample top-level tab. The first peak information is only available when the mode is set to Define 2 non-colinear reflections (shown in the image below). The peak can be added either using the current motor positions or by specifying the positions explicitly (as controlled by the blue pull-down menu). To add the input information as the second reflection, the blue pull-down menu must be set to Reflection 2. There is also a green button at the bottom of the tab which allows you to swap the information for reflections 1 and 2. To calculate the UB matrix hit the blue Calculate UB Matrix Update Orientation Information button.

NOTE: the orientation information is easier to modify from the GUI than from the command-line as it allows the user to preview the orientation information prior to accepting the changes. The peak2 command should only be executed from the command-line by experienced users as it could yield unexpected results. For detailed information about entering orientation information from the GUI see the How to align a single crystal guide.

GUI interface to peak2 command


plusminus

plusminus:

The plusminus command is used to specify the direction of scattering for the monochromator, sample, and analyzer.

The syntax for the plusminus command is:

plusminus +/-1 +/-1 +/-1

OR

plusminus +/- +/- +/-

The monochromator scattering direction is fixed for a given instrument and cannot be changed using this command.

NOTE: All angles are positive in the trigonometric (i.e. counterclockwise) sense. The standard W configuration is either plusminus + - + OR plusminus - + - depending on the sign of the monochromator scattering direction.

The plusminus command can also be accessed from the GUI by selecting the Experiment tab from the Setup top-level tab. To change the scattering directions for the instrument, the green button at the bottom of the tab must be changed from "Monitoring ... Click to allow changes" to "Changing ... click to monitor". Select either Plus or Minus from the blue pull-down menus and commit the changes by clicking on the blue "Update Parameters" button. NOTE that the MONOCHROMATOR pull-down menu will not allow you to change the initial scattering direction as this is fixed by physical constraints on the instrument.

GUI interface to plusminus


preset

preset:

The preset command is used to set the default preset for counts and scans.

The syntax for the preset command is:

preset channel value

OR

preset countfile path

Where one can individually specify any of the arguments. For instance, "preset monitor" followed by "preset 234" is identical to "preset monitor 234". The same is true for countfile path - i.e. "preset countfile" followed by "preset path" is identical to "preset countfile path". For additional information about the use of countfiles, see the How to use countfiles guide.

The preset command can also be accessed from the GUI by selecting the Count Preset tab from the Drive/Scan/Count top-level tab. To set the default preset, the green button at the bottom of the tab must be changed from "Monitoring ... Click to allow changes" to "Changing ... click to monitor". Then highlight the green button on the right corresponding to the channel which you would like to set as the preset channel, type in the appropriate preset value, and click on the blue "Set Default Preset" button.
gui interface to preset


run

run:

The run command is used to execute a macro.

The syntax for the run command is:

run macroname var1 var2 ...

where macroname is the name of the macro and var1, var2, ... are variables to be passed to the macro. The macroname can be either a complete path, or the name of the macro file provided the macro is placed in one of the relevant macro directories. There are 3 levels of macros, system, instrument, and user and the run command will search for the macros in this order. The assumed filename extension in .macro and this extension is not required from the run command. For instance, typing "run example.macro" and "run example" will run the same macro provided the file is located in the system, instrument, or user macro directory.

For information and guidelines on writing macros, see the How to Write a Macro guideline.

Macros can also be edited and run from the GUI by selecting the Edit Macro tab from the Macro/Stack top-level tab. The macro is written in the top text box including loop structures as shown in the example below. To expand any loops, click on the yellow Expand button - the results will be printed in the lower text box. The macro can then be written to a file by clicking on the green Write to File button. This will automatically place the macro in the user macro directory and the default extension is .macro. The green Read from File button will repopulate the top text box with the contents of a previously written macro and the yellow Clear button will clear the text from the top text box. Once the macro has been is completed, the blue Execute Macro button will execute the commands in the macro.

GUI interface to run


sample

sample:

The sample command is used to set various properties of the sample.

The syntax for the sample command is:

sample type value name "sample name" mosaic value

Where the value of type can be either powder or crystal, the value of name must be included in quotes unless it is a single word, and the value of mosaic is the mosaic spread of the sample in minutes. Any combination of 1,2, or 3 arguments can be given in any order.

Examples:

sample type crystal
sample name "Test sample Number 2"
sample mosaic 45 type crystal

The sample command can also be accessed from the GUI by selecting the Sample/Mode Information tab from the Sample top-level tab. To set the sample information, the green button at the bottom of the tab must be changed from "Monitoring ... Click to allow changes" to "Changing ... click to monitor". The sample name is typed in the Sample Name text box, the Sample Type is selected with the blue pull-down menu, the Sample Mosaic is typed in the numerical control, and the sample command itself is issued by clicking on the blue Update Parameters button.
GUI interface to sample


scan

scan:

The scan command will perform a scan of any motor. As with the drive command, any movable quantity can be scanned - this includes physical motors, sample environment parameters (i.e. temperature, pressure, magnetic field, etc.), voltages (for flippers for instance) and reciprocal space and energy parameters (q,h,k,l,e,ei,ef).

The syntax for the scan command is

scan motor1 start stop step motor2 start stop step [n=npoints] [preset=channel,value] [file=path]

The step can be omitted if the n=npoints argument is specified and the n=npoints is not required provided each motor has a valid step.
If the preset option is omitted, the default will be used - the default preset is changed using the preset command. As with the preset command, the preset argument for scan can either be of the form 'channel value' or 'countfile path' if the countfile option is being used. The optional file=path argument of the scan command will bypass all given motor positions and read a list of positions from the file specified by path. Each line in this file should include motor names and there destinations (for instance, s1 10 s2 30 sgl 5).

Some examples of typical scan commands:

1. scan s2 20 40 2 s1 10 20 1 preset monitor 10000
(this is the most common form of the scan command)
2. scan s2 20 40 s1 10 20 n=10 preset monitor 10000
(this is an example which uses the n=npoints argument - note the result of this command is identical to example 1 above)
3. scan n=100 preset monitor 10000
(this will do 100 counts to a preset of 10000 monitor counts without moving any motors)

The scan command can also be accessed from the GUI. The Scan tab is found under the Drive/Scan/Count top-level tab. The motors and pseudomotors are ogranized into categories for convenience. To add a motor to the list to be scanned, simply select it from the appropriate list. To delete a motor, hit the relevant Delete button. Type in the Start, End, and Step for each of the included motors, type in a scantitle in the Scan Title text box, select an appropriate preset and hit the Start Scan button to start the scan. The number of steps cannot be changed directly but is included for convenience so that the user knows how many points will be generated by the scan command. The scan can also be simulated by clicking on the scansim button. For more information about simulating scans, see the scansim command.
gui interface to scan


scanoff

scanoff:

The scanoff command sets the scanon variable to false. This will end the scan started by the scanon command.

The syntax for the scanoff command is:

scanoff

The scanon structure is used to combine any set of drives and counts into a properly formatted scan (in both the datafiles and logfile).For more detailed information on the scanon/scanoff structure, see the How to create a custom scan guide


scanon

scanon:

The scanon command sets the scanon variable to true.

The syntax for the scanon command is:

scanon

The scanon structure is used to combine any set of drives and counts into a properly formatted scan (in both the datafiles and logfile). For more detailed information on the scanon/scanoff structure, see the How to create a custom scan guide


scansim

scansim:

The scansim command is used to simulate a scan.

The syntax for the scansim command is the same as for scan:

scansim motor1 start stop step motor2 start stop step [n=npoints] [preset=channel,value] [file=path]

For more information about the syntax for scansim, see the help document for the scan command.

The output of the scansim command will contain any errors that would occur during the scan. This includes checking for completion of the scattering triangle (in the case of a Q-E scan) and also checking that all destination motor positions are within allowed limits.

The scansim command can also be accessed from the GUI. The Scan tab is found under the Drive/Scan/Count top-level tab. The motors and pseudomotors are ogranized into categories for convenience. To add a motor to the list to be scanned, simply select it from the appropriate list. To delete a motor, hit the relevant Delete button. Type in the Start, End, and Step for each of the included motors, type in a scantitle in the Scan Title text box, select an appropriate preset and hit the Simulate Scan button at the bottom of the tab to initiate the simulation.

NOTE: unlike most GUI interfaces, the interface to scansim does not go through the command line. This is done intentionally so that the user does not need to wait until completion of the current command before he can see the results of the simulation.
GUI interface to scansim

The resulting popup window from simulating the scan generated from the scan GUI interface (shown above) is shown in the image below. Points 6,7,8 will generate an error because the destination for s2 is below the lower limit for motor s2 and points 9,10,11 generate errors because the scattering triangle cannot be completed. After the simulation popup box has been examined, hit the Cancel button to remove this popup box and continue normal operation of the program.
results of scansim


scantitle

scantitle:

The scantitle command sets the scan title to a specified value.

The syntax for the scantitle command is:

scantitle "This is the scan title"

where the specified title must be in quotes.

The scantitle can be set from the GUI when a scan is generated from the GUI. To do this, select the Scan tab under the Drive/Scan/Count top-level tab. When the contents of the scan are input (see the documentation for the scan command), the scan title is entered in the Scan Title text box. The blue Start Scan button will issue both the scantitle and the scan commands.

gui interface to scantitle


showdest

showdest:

The showdest command prints the destination for all specified motors in a scan command.

The syntax for the scandest command is:

showdest 0/1

where 1 will turn the option on and 0 will turn it off.

This command is useful for debugging (where one is concerned with the detination and physical motor positions being different) and also for commands where the final position and destination are intentially different (for instance, if a reciprocal space move is being issued with one or more motors being held).


spv

spv:

The spv command sets the scattering plane vectors.

The syntax for the spv command is:

spv h1 k1 l1 h2 k2 l2

where the scattering plane is defined by the peaks (h1,k1,l1) and (h2,k2,l2).

The parameters set from the spv command can also be set from the GUI by selecting the UB Matrix tab from the Sample top-level tab. The scattering plane vectors will only be available when the mode is set to Define scattering plane vectors and 1 reflection. The indices defining the scattering plane are typed in the control at the bottom of the tab. To calculate the UB matrix from this information hit the blue Calculate UB Matrix Update Orientation Information button.

NOTE: the orientation information is easier to modify from the GUI than from the command-line as it allows the user to preview the orientation information prior to accepting the changes. The spv command should only be executed from the command-line by experienced users as it could yield unexpected results. For detailed information about entering orientation information from the GUI see the How to align a single crystal guide.

GUI interface to spv


stepbegin

stepbegin:

The stepbegin command is used within the scanon structure to define where the motor positions are to be recorded for the current datapoint.
The stepbegin command is not required for the scanon structure but is included for flexibility.

The syntax for the stepbegin command is:

stepbegin

The scanon structure is used to combine any set of drives and counts into a properly formatted scan (in both the datafiles and logfile). For more detailed information on the scanon/scanoff structure, see the How to create a custom scan guide


stepend

stepend:

The stepend command is used within the scanon structure to indicate that we are moving to the next point in the custom scan. The syntax for the stepend command is:

stepend

The scanon structure is used to combine any set of drives and counts into a properly formatted scan (in both the datafiles and logfile). For more detailed information on the scanon/scanoff structure, see the How to create a custom scan guide


title

title:

The title command specifies the experiment title.

The syntax for the title command is:

title "experiment title"

where the experiment title must be in quotes.

The title command can also be accessed from the GUI by selecting the Experiment tab from the Setup top-level tab. To change the experiment title, the green button at the bottom of the tab must be changed from "Monitoring ... Click to allow changes" to "Changing ... click to monitor". Type the new experiment title in the appropriate box and click on the blue "Update Parameters" button.

GUI interface to title


tolerance

tolerance:

The tolerance command sets the tolerance for a motor.

The syntax for the "toleranace" command is:

tolerance motor1 value1 motor2 value2 ...

will set the tolerance for motor1 to value1, motor2 to value2, etc.

tolerance motor1 motor2 ...

will display the current tolerance for motor1, motor2, etc.

tolerance

when given with no arguments, the tolerance command will display the tolerance for all motors.

The tolerance command can also be accessed from the GUI by selecting the Tolerance tab from Setup - Hardware - Motors tabs.. To change the tolerance for a given motor, the green button at the bottom of the tab must be changed from "Monitoring ... Click to allow changes" to "Changing ... click to monitor". Type in the new tolerance in the Tolerance numerical control and commit the changes by clicking on the blue Update Parameters button.

gui interface to limits and tolerance


ubcalc

ubcalc:

The ubcalc command calculates the UB matrix.

The syntax for the ubcalc command is:

ubcalc mode

OR

ubcalc n1 n2 n3 n4 n5 n6 n7 n8 n9

OR

ubcalc file path

where mode is:
1. define scattering plane vectors, a single reflection, and the lattice constants.
2. define 2 non-colinear reflections are the lattice constants.
3. linear least-squares refinement of the orientation and lattice constants.

n1-n9 are read as the 9 elements of the 3x3 UB matrix array - this option should only be used by advanced users.
The file option reads from a UB matrix configuration file. This can be used to restore an old orientation and is used extensively in the GUI.

Calculation of the UB matrix can also be accomplished from the GUI by selecting the UB Matrix tab from the Sample top-level tab. The mode is selected from the blue pull-down menu. The options for the mode are:
1. Define scattering plane vector and 1 reflection
2. Define 2 non-colinear reflections
3. Refine UB (3 non-coplanar reflections required) (shown in the image below).
To recalculate the UB matrix using the selected mode, hit the blue Calculate UB Matrix Update Orientation Information button. This will result in a popup box where the results of the UB matrix calculation are presented (an example is shown in the lower image). The user can then choose to accept the calculation or CANCEL.

NOTE: the orientation information is easier to modify from the GUI than from the command-line as it allows the user to preview the orientation information prior to accepting the changes. The ubcalc command should only be executed from the command-line by experienced users as it could yield unexpected results. For detailed information about entering orientation information from the GUI see the How to align a single crystal guide.

GUI interface to ubcalc input

Output from ubcalc


upperlimit

upperlimit:

The upperlimit command sets the upper limit for a motor.

The syntax for the "upperlimit" command is:

upperlimit motor1 value1 motor2 value2 ...

will set the upper limit for motor1 to value1, motor2 to value2, etc.

upperlimit motor1 motor2 ...

will display the current upper limit for motor1, motor2, etc.

upperlimit

when given with no arguments, the upperlimit command will display the upperlimits for all motors.

The upperlimit command can also be accessed from the GUI by selecting the Limits tab from Setup - Hardware - Motors tabs.. To change the upper limit for a given motor, the green button at the bottom of the tab must be changed from "Monitoring ... Click to allow changes" to "Changing ... click to monitor". Type in the new upper limit(s) in the High Limit numerical control and commit the changes by clicking on the blue Update Parameters button.

GUI interface to upperlimit


users

users:

The users command sets the users of the experiment to a specified value.

The syntax for the users command is:

users "user1 user2 ..."

where the specified users must be included in quotes.

The users command can also be accessed from the GUI by selecting the User Defaults tab from the Setup top-level tab. To change the users for the current experiment, the green button at the bottom of the tab must be changed from "Monitoring ... Click to allow changes" to "Changing ... click to monitor". Type the user names in the User Name(s) box and click on the blue "Update Parameters" button.

GUI interface to users


wait

wait:

Wait for a specified period of time.

The syntax for the wait command is:

wait n

Where n is the number of seconds to wait for. OR

wait a:b:c

Where a:b:c is the specified time in hours:minutes:seconds. For instance, wait 1:10:5 will wait for 1 hour, 10 minutes, and 5 seconds.

Note that the time elapsed and remaining is continuously counted down on the Status Display while a wait command is executing.


zero

zero:

The zero command sets the zero angle for specified motor(s).

The syntax for the "zero" command is:

zero motor1 value1 motor2 value2 ...

where the zero angle for motor1 is value1, motor2 is value2, etc.

NOTE: the zero angle is defined in the following way:
Let HA be the hardware angle (the angle as contained in the motor controller), UA be the user angle (this is the 'real' angle which has an offset angle included - this is the angle that is reported from the program and on the Status Display), and ZERO be the zero angle. Then,

HA-zero=UA

Typing the zero command with no arguments will return the current zero angles for all defined motors.

To avoid having to remember the definition of the zero angle, an alias (setpos) has been written which will redefine the zero such that the current position of a motor will be some given value.

The zero angle can also be accessed from the GUI by selecting the Zeros and Holds tab from Setup - Hardware - Motors tabs.. To set the zero angle for a given motor, the green button at the bottom of the tab must be changed from "Monitoring ... Click to allow changes" to "Changing ... click to monitor". Type the new zero angle into the Zero numerical control (For instance, in the below image the zero angle for motor m1 is 0.011 degrees). Once the zero angles of the motors are acceptable, the zero command is issued by clicking on the blue Update Parameters button.

GUI interface to zero


Aliases Top level

Available System Alias Definition
setpos


br

br:

The br alias is used to drive to a specific Bragg peak.

The syntax for the br alias is:

br h k l

Where (h k l) are the indices of the Bragg reflection.

NOTE that the following information is not required to understand the usage of the command but is included for completeness:

The alias definition is:

drive h %1 k %2 l %3 e 0


com

com:

The com command will drive the specified motor to the center of mass of the last performed scan.

The syntax for the com alias is:

com motor

An important note about this command is that if you type the wrong motor in, the command will drive to the last stored center of mass even if the last scan didn't involve that motor. For instance, if the last scan was an alignment scan of motor s1 which produced a center of mass of 135 degrees and the user accidently types com s2 (instead of com s1), the drive command will try to drive motor s2 to 135 degrees.

NOTE that the following information is not required to understand the usage of the command but is included for completeness:

The alias definition is:

drive %1 @(com)

Where %1 is the specified motor name and @(com) will use the stored center of mass from the last performed command. For more information about the syntax of these @(...) variables, see the How to use and command-line variables guide.


driverel

driverel:

The driverel alias will move a motor by a specified amount relative to its current position.

The syntax for the driverel alias is:

driverel motor value

For example:
driverel s1 10 (this will drive motor s1 10 degrees past its current position)
driverel q -0.5 (this will drive psqeudomotor q 0.5 inverse angstrom below its current position)

NOTE that the following information is not required to understand the usage of the command but is included for completeness:

The alias definition is:

drive %1 @(%1)+%2

The syntax @(%1) will replace this string by the current position for motor %1. For more information about the syntax of these @(...) variables, see the How to use and command-line variables guide.


mcu

mcu:

The mcu alias will set the value for the multiplier for the monitor.

The syntax for the mcu alias is:

mcu value

This sets the monitor scaling factor to value. For instance, if one types mcu 10000 and then does a count preset mcu 10, the total preset will be 10*10000=100000 monitor counts.

NOTE that the following information is not required to understand the usage of the command but is included for completeness:

The alias definition is:

logfileoutput off; method mcu set_scale_factor d %1; logfileoutput on; comment "The monitor count unit was set to @(methodreal0)" title "Setting the monitor count unit

The logfileoutput off command is used to suppress the output from the method command which is not particularly readable to the average user and the logfileoutput on command is used so that the following comment is printed to the logfile. The @(methodreal0) represents the first returned real variable from the method command which will be the stored value of mcu. For more information about the syntax of these @(...) variables, see the How to use and command-line variables guide.


scanrel

scanrel:

The scanrel alias will perform a scan of the specified motor relative to its current position.

The syntax for the scanrel alias is:

scanrel motor start_rel stop_rel step

Note that no preset is specified in the above alias. This means that the preset used in this alias will always be the default. See the help document for the preset command to get more information about changing the default preset.

Example:
scanrel s1 -2 2 0.2

This command will perform a scan of motor s1 from 2 degrees below its current position to 2 degrees above its current position.

NOTE that the following information is not required to understand the usage of the command but is included for completeness:

The alias definition is:

scan %1 @(%1)+%2 @(%1)+%3 %3

The syntax @(%1) will replace this string by the current position for motor %1. For more information about the syntax of these @(...) variables, see the How to use and command-line variables guide.


set_temp

set_temp:

The set_temp alias will set the temperature setpoint.

The syntax for the set_temp alias is:

set_temp value

The temperature can be driven (in the same way as any motor) using the drive command (i.e. drive temp value). However, changing the temperature in this manner will not exit from the drive until the temperature gets within tolerance of the setpoint. If you wish to simply change the setpoint WITHOUT waiting until the temperature is within tolerance of the setpoint, use the set_temp alias.

NOTE that the following information is not required to understand the usage of the command but is included for completeness:

The alias definition is:

logfileoutput off; method temp set_setpoint d %1; method temp get_setpoint; logfileoutput on; comment "The temperature setpoint was set to @(methodreal0)" title "Setting the temperature setpoint"

This alias first turns off output to the logfile (logfileoutput off), calls the set_setpoint method on the temperature driver, calls the get_setpoint method on the temperature driver to read the setpoint from the controller, turns the output to the logfile back on (logfileoutput on), and finally issues a comment which reports this stored value.


setpos

setpos:

The setpos alias is used to redefine the current position to some specified value. It is an alias to the zero command which is designed to avoid the user having to remember the definition of the zero angle.

The syntax for the setpos alias is:

setpos motor value

This will redefine the zero angle of motor so that it is at position value. For example, the command setpos s1 100 will redefine the zero angle so that the current position now reads 100.

NOTE that the following information is not required to understand the usage of the command but is included for completeness:

The alias definition is:

zero %1 @(%1.zero)+@(%1)-%2

The argument @(%1.zero) will use the current zero angle for the motor specified by %1 and the @(%1) will use the current position for the motor specified by %1. For more information about the syntax of these @(...) variables, see the How to use and command-line variables guide.


SPICE_top

SPICE top page

Comments and/or questions regarding this help document should be sent to Mark Lumsden


analysis log tab

Analysis Log Tab:

The Analysis Log maintains a log of fits that have been performed. The data in this log gets emptied each time a New Plot is performed from the Graph Data tab so that the information contained within this log only involves data sets (or data buffers) currently displayed on the Graph Data plot. When a Hardcopy is generated from the Graph Data tab, the contents of the analysis log will be printed below the plot. This allows users to add comments to a plot by modifying the contents of the Analysis Log. The contents of the Analysis Log can be cleared by clicking on the Clear Analysis Log button at the bottom of this tab.
analysis log tab


browse data tab

Browse Data Tab:

The browse data tab is designed to allow quick browsing through the scans contained in the current experiment. To use this feature, simply type the scan number in the Run # box or use the up/down arrows (grey arrows next to the Run # label). Whenever the number changes, the scan is plotted and the ascii contents of the scan are displayed in the text box below the plot. If New Plot is selected, each plot will be plotted individually as shown in the image below.
browse data 1
To overplot several plots, select Overplot instead of New Plot and simply type in the scan numbers in the Run # box. As the number changes, each new scan number will be overplotted together with the pre-existing plots. An example of several Ni powder scans is shown in the image below.
browse data overplot

A hardcopy of the current plot can be obtained by clicking the Hardcopy button. The destination printer can be changed from the main program by selecting File - Page Setup from the pull-down menus as shown in the left panel image below. The page setup box will then appear (as shown in the right panel image below) and the printer can be changed by selecting the Printer setup ... button.
page setup popup
The standard printer selection box will then appear and the printer can be selected from the Name pull-down menu (see image below). Once the correct printer is selected the change will be applied by clicking on the OK button.
printer setup


combine data tab

Combine Data Tab:

The Combine Data tab is used to combine data sets. To combine several data sets, select the appropriate run numbers to be added in the +RunNums box, choose the appropriate +xColumn and +yColumn and the click on the Add to + list button. This will add this scan with the appropriate X and Y columns to the + Array. The same procedure can be followed in the "-" section to add scans to be subtracted. Once the appropriate scans are selected to be added and subtracted, a desciptor for the combined data set is typed into the Description box. The normalization for the combined data is specified by selecting the appropriate input channel from the pull down menu (showing Time in the image below) and the numerical normalization constant is typed in the box above this menu (showing 1 in the image below). NOTE that if the normalization constant is not reasonable (for instance if you counted to 1000000 monitor counts and use a monitor normalization of 1) the resulting numerical data may not appear correctly on the plot. The Bin Tolerance for the addition and subtraction can be changed and the top-most pull down menu can be used to select a buffer to use - select Next from the list to add the combined data as the next available buffer. Finally click on the Combine and Save to buffer button to complete the generation of the combined data set.
combine data

To plot a combined data set, go to the Graph Data tab and click on the top blue button to ensure that Graphing Data Buffers is selected (as opposed to Graphing Data Sets (any column) ). You can then select the data buffer to be plotted from the pull down menu (labelled Combined Ni powder data in the image below). The data can be plotted as a New Plot or overplot on top of existing plots by choosing either New Plot or Overplot from the pull down menu. Clicking on the Graph Data button will graph the combined data set. This data can be fit and hard copies can be generated as described in the Graph Data help document.

plot combined data


count/preset tab

Count/Preset Tab:

The Count/Preset tab provides a graphical user interface to the count and preset commands as well as the mcu alias. For more detailed information click on the command names below.

count : Perform a count to a specified preset.

preset : Define the default preset channel and/or value.

mcu : Set the monitor counting unit (scale factor).


data buffers tab

Data Buffers Tab:

The Data Buffers tab allows you to view data buffers (generated from the Combine Data tab) and save them to a user specified file. To examine a data buffer, select the relevant buffer using the blue pull down menu at the top of the page (labelled Combined Ni powder data in the image below). Below this menu there are 3 buttons which provide the Description of the data buffer together with its x-axis label and y-axis label. The data itself is displayed in an array containing the X,Y,Error, and Y(fitted) values (if no fit has been performed then the Y(fitted) value is empty). The data contained in this buffer can be saved to a file by clicking on the Save this buffer to file button. A file dialog box will then appear which allows the user to select the target filename.
Data Buffer screen shot


default directories tab

Default Directories Tab:

The Default Directories tab displays the path information relevant to the current experiment.

The following files/directories are listed on this page:

1. Experiment alias file - alias file containing user defined alias definitions
2. Experiment Macro directory - directory where the program will search for user defined macros.
3. Experiment Countfile directory - directory where the program will search for user defined countfiles.
4. Experiment Datafile directory - the directory where the datafiles will be stored
5. Experiment Logfile path - the file location of the logfile.
6. Experiment UB Matrix configuration directory - directory where UB matrix configuration files are stored.


experiment tab

Experiment Tab:

The following information can be set on the Experiment tab. For more detailed information click on the command names below.

ei : Set the instrument to a "Fixed incident energy" configuration.

ef : Set the instrument to a "Fixed final energy" configuration.

monochromator : choose the monochromator crystal

analyzer : choose the monochromator crystal

 collimation : choose the monochromator crystal

plusminus : choose the instrument scattering directions

title : set the experiment title


Experiment Summary tab

Experiment Summary Tab:

The Experiment Summary tab provides a summary of a specified range of scans within the current experiment. Changing the First Scan and Last Scan values will display a brief summary of the scan information in the Experiment Summary box. A hardcopy of this range of scans can be generated by clicking on the HardCopy button. If the pull down menu below the HardCopy button says Titles only then the information contained in the Experiment Summary box will be printed but if with graphs is selected (as in the image below) the hardcopy will contain graphs of the range of scans with a maximum of 6 scans displayed on a single page.
experiment summary screen shot


graph data tab

Graph Data Tab:

The graph data tab allows plotting and simple fitting of data in individual scans as well as combined data. To graph a single scan, the top-most blue button must say Graphing data sets (any column) (as opposed to Graphing Data Buffers - to change the selection simply click on the button). Type the appropriate scan number in the Run Number box. The default x and y values specified in the corresponding data file will then appear in the X_Data_Column and Y_Data_Column list boxes and the user can change these values to correspond to the desired x and y columns for the plot. If New Plot is selected, clicking on the Graph Data button will plot the scan with the specified x and y values.
To perform a fit to the data, enter the appropriate number of peaks in the Fit to N peaks box. The initial guesses can then be changed by clicking on the grey up/down arrows or by typing the numbers into the appropriate numerical boxes (when the guess values change, a solid curve corresponding to these initial guesses will be plotted). Any value can be held by clicking on the green light next to the relevant parameter. Once reasonable initial guesses are entered, the fit is performed by clicking on the Perform Fit button (the button will turn red and indicate Fitting while a fit is being performed). When the fit is completed, the fit coefficients and the chi-squared value will be displayed.
graph data single plot
To overplot several plots, select Overplot instead of New Plot, type the number in the Run Number box, select the appropriate x and y columns and click on the Graph Data button.. The data in each plotted scan can be fit by selecting the appropriate scan from the drop down menu next to the Perform Fit button (labelled Ni powder (1,0,0) in the image below). The same procedure as outlined above can be used to perform the fit.
graph multiple data sets

The data contained in data buffers can also be plotted in the Graph Data tab (for more information on generating and plotting data buffers, see the Combine Data help page).

A hardcopy of the current plot can be obtained by clicking the Hardcopy button. The destination printer can be changed from the main program by selecting File - Page Setup from the pull-down menus as shown in the left panel image below. The page setup box will then appear (as shown in the right panel image below) and the printer can be changed by selecting the Printer setup ... button.
page setup popup
The standard printer selection box will then appear and the printer can be selected from the Name pull-down menu (see image below). Once the correct printer is selected the change will be applied by clicking on the OK button.
printer setup


motors tab

Motors Tab:

The following information can be set on the Motors tabs. For more detailed information click on the command names below.

zero : Set the motor zero angles.

hold : Hold a specified motor at its current position.

hide : Show or hide a specified motor.

upperlimit : Set the motor upper software limit.

 lowerlimit : Set the motor lower software limit.

tolerance : Set the motor positioning tolerance.

setup :Reserved for future use.


sample mode tab

Sample/Mode Tab:

The following information can be set on the Sample/Mode tab. For more detailed information click on the command names below.

sample : The sample command allows you to set the sample name, type and mosaic spread.

mode : Set the angle calculating mode. If the mode is set to 0 or 1, a pair of numerical controls are present to set the reference arc values.


scan tab

Scan Tab:

The Scan tab contains a graphical interface to both the scan and scansim commands. For more detailed information on how to use the graphical user interfaces to these commands, click on the command names below:

scan : Scan motors or pseudomotors

scansim : Simulate a scan.


view command stack tab

View Command Stack Tab:

As described in the General Introduction, the processing of commands in SPICE occurs via a command line interpreter which sequentially executes commands from a first-in-first-out stack. The View Command Stack tab allows the user to see the commands remaining to be executed in the stack. An example is shown in the following image:
command stack
The uppermost text box shows the currently executing command and the lower box shows the list of commands to be executed. Note that the command at the top of this list will be the first executed. The command stack can be cleared by clicking on the blue Clear Command Stack button. The user will then be asked to confirm that they want to remove all commands from the stack. In addition, the STOP button will stop the currently running command and will also remove all commands from the stack.


user defaults tab

User Defaults Tab:

There are 2 sections of information on the User Defaults tab.

1. The user(s) names and the name of the local contact can be viewed/set. For more detailed information click on the command names below.

users: Set the users of the current experiment.

contact: Set the local contact of the current experiment.

2. The following files/directories are listed on this page:

1. Experiment alias file - alias file containing user defined alias definitions
2. Experiment Macro directory - directory where the program will search for user defined macros.
3. Experiment Countfile directory - directory where the program will search for user defined countfiles.
4. Experiment Datafile directory - the directory where the datafiles will be stored
5. Experiment Logfile path - the file location of the logfile.
6. Experiment UB Matrix configuration directory - directory where UB matrix configuration files are stored.

NOTE: the directories cannot be changed as they are set when the begin command is run.