Usage of SPEC Macros

This is a short description on how to use SPEC macros provided by DECTRIS. With the permission from Oliver Bunk, Swiss Light Source, PSI, we hand out a set of macros, which allow to control a PILATUS detector. If you have any questions please direct them to support@dectris.com and do not contact Oliver Bunk. The macros can help to integrate the detector into a SPEC environment but require a deeper understanding of SPEC for adaption to your own infrastructure. Please make sure that you have a correct SPEC licence from certif.com.

The macros are combined in a zip file.

Standard spec_commands are written italic, PILATUS specific spec_commands  are bold.
 

A Short Introduction

In the beginning a few words to SPEC: It is a command line interface to control motors at beamline/motorized installation and to read back detector values. Its main purpouse is to move a motor and then count* for a certain time with several devices. Then the motor moves to the next position and the detectors count* again. This is repaeted as often the scan got told to do so. However, the DECTRIS Pilatus detectors do NOT give back values (2d data) to SPEC but write images. The provided SPEC macros allow, however, to use the Pilatus with SPEC saving images to a defined folder.

*...counting means for SPEC one value of some device (e.g. the electrons arriving on a diode)
 

Simple SPEC usage (for non SPEC users)

ct ... simple command (values are only logged in the log file, not in the data file)

The data file .s is standard of SPEC and often used by the user to find the data

There are also log files which are recorded, where "all" data which is also seen on the SPEC screen is written. The three are:

• .log the standard
• .elog is only the command line
• .tlog looks the same a .log, maybe a bit less info 

Usual SPEC commands like mv, mvr are working (for details see certif.com). TIP: Using umvr updates the position after a move.
 

Usual usage of SPEC

Example 1:

dscan ebtrx -1 1 10 0.5

dsacn... relative scan 

ebtrx ... motor name 

min val

max val

number of intervals 

time to record image/data/counting  without moving time

Example 2:

timescan ... with no arguments just records the data (interrupt with Ctrl-C)

loopscan 10 0.5 0.5   ... 10 repetition 0.5 s and wait in between 0.5 
 

Configurations of the Macros

As mentioned above, a profound knowledge of SPEC is needed to carefully adapt the macros to its own needs. However, for a fast way of getting them to work only a few modifications have to be done. First the files have to be copied to a location e.g. /usr/local/lib/spec.d/macros and then the site.mac file has to be extended with the content of the site.mac.example file. The order of the qdofile has to adapted with the current entries. It is possible that ordering has to be changed depending on the current installation. 

In the pilatusii.mac file the following adaption have to be made:

• In line 527 the parameter _pilatusServerAndPortName[0][] = "localhost:41234" has to be changed to the correct IP of the detector (instead of localhost).
• To name the detector as you wish you can change the _pilatus_name in line 2832. 
• If you plan to add more than one detector please add them accordingly below and also change the value _pilatus_max in line 309.
• The energy threshold/energy (please read the "Pilatus User Manual" why a threshold energy has to be set and what is the difference between X-ray energy and threshold energy) is by default set to 12.4 keV (X-ray energy) and calculates a threshold energy of 55% (resulting in a used threshold energy of 6.8 keV). The default threshold ratio (now at 55%) can be changed in line 1559. The default in energy comes from a value called "_mono_get_energy_kev" and returns the 12.4 keV if nothing is defined. See code between line 345 and 379 for more details. The threshold can be any time adjusted by the pilatus_threshold command. Please ignore the "partial" feature in the macros, it is outdated. 
   

WORKING with PILATUS and SPEC

If the adjustments above are done it should be possible to connect to the detector and start camserver. You should be able to connect to a detector by using pilatus_on 1 on in SPEC. Then the threshold has to be set according to the needs of the experiment (see the Pilatus User Manual for details). For any further help please use pilatus_help or where it points to. Every time you do a SPEC count, there will be a text message, image saved at this path, but you can use SPEC as usual.

• The files are stored according to the standard setup  (e.g. .../pilatus_1/S00000-00999/S00007/). This default is basically default directory / pilatus number / scan number / image files.
• All motor positions are in the spec dat file and can be correleated with the images over the scan number (the log file has even more information)
• The file name consist of user account _ number of detector _ scan number _ scan point number _ burst point number .cbf (exaple: e17153_1_00007_00005_00000.cbf
   

Special modes

In the "standard" SPEC mode, the provided macros make one image at a time with the requested exposure time. To be ale to use the full capabilities of the PILATUS detectors there are two functions available which allows fasts series of images. By using one of the following two commands it is possible to make fast series of images. One mode allows to make a single series of images (here called burst mode) and anther allows to make a burst at each point. The latter is basically a pre-configuration where at each "normal" scan or ct of SPEC not one image is recorded but N imges with the set exposre time. Use also the help command in SPEC without argument.
 

BURST scan

burst_scan 17 0.1 (means just recording a series of 17 images where each is 100ms long (readout time adjusted to 3ms, but can be changed. min readout time for PILATUS detectors is 2.3ms). No motor is moved at all.
 

BURST at each point

burst_at_each_point 10 (every time the motor stops in a spec scan you do 10 images in a series) can be very useful when you need (e.g.) more dynamical range

normal scan and at each point of ANY scan which is done
 

USE 2 detectors at the same time

Connect second Pilatus by 

pilatus_on 2

to check pilatus_show_all ... should show all 

set the desired threshold 

and work as usual, the data is stored in the pilatus_2 (and pilatus_1) folder