mardtb 248x110
Edited on 19-May-2023

prev  up  down  next 

Input

1. Overview

Program mar345dtb/mardtb uses the following input files. Some of them are mandatory, others optional.

Table 1: mar345dtb input files.

File type File name Mandatory Description
Configuration $MARTABLEDIR/mar(345)dtb.cfg
or $MARTABLEDIR/config.### 		yes Configuration parameters for dtb and detector
Calibration $MARTABLEDIR/mar2300.###
$MARTABLEDIR/mar3450.### 		yes for mar345 detector Calibration files for mar345-detector
License $MARTABLEDIR/mardtb.license yes for DECTRIS detectors Encrypted license for mardtb with EIGER or PILATUS
Parameter $MARLOGDIR/mar(345)dtb.dat no Saved parameters from "Edit"
Shell script $MARLOGDIR/dtb.csh no Shell script template for executing external commands
Command $MARLOGDIR/dtb.com no Parameter file for triggering an action of the dtb or the scanner
Images ... no Image files in several formats
Carousel data $MARLOGDIR/csc/CSC.csv no Saved parameters from "CSC"
XDS data $MARLOGDIR/xps/XPS.dat no Saved parameters from "XPS"

### denotes a 3-digit serial number and usually is defined as $MAR_SCANNER_NO (or $MAR_DTB_NO if program mar345dtb is used without mar345 support). As of version 9, program mar345dtb tries to read file mar345dtb.cfg as configuration file, in the first place. To be compatible with older versions, if that file is not present, the program falls back to config.###.
The idea is to only use INCLUDE lines to file mar345dtb.cfg and thus separate parameters that are specific to the desktop beamline from those that are specific to the detector.

2. Configuration File

While all parameters used within program mar345dtb are set to reasonable defaults, there are quite a number of parameters that are specific for either a particular model of the desktop beamline or the mar345 image plate detector or the DECTRIS detectors. Therefore, the program must read in a configuration file for proper function. The configuration file is called config.$MAR_SCANNER_NO and resides in directory $MARTABLEDIR. If the configuration file doesn't exist, the program can't be started. The file is a keyworded ASCII-file which may be edited. Keep in mind that many of the parameters can be absolutely critical for hardware functions, so for editing you really have to know what you are doing!

Please note, that program mar345dtb is for support of the mar345 image plate detector, but for DECTRIS detectors the program is called mardtb and the corresponding configuration file is called mardtb.cfg.

prev  up  down  next 

2.1 Keywords

The configuration file is a keyworded ASCII-file in free format. Lines starting with # or ! are treated as comment lines. Almost all keywords and subkeywords can be truncated to 4 characters. A number of keywords are of general program use, other affect the dtb only and others the mar345-detector only:

2.1.1 General

The following keywords are of general importance to run the program:

prev  up  down  next 

2.1.2 Keywords for dtb

The following keywords affect the dtb only:

prev  up  down  next 

2.1.3 Keywords for mar345

The following keywords affect the mar345-detector only:

prev  up  down  next 

2.2 Example

The following file listing is a typical configuration file for a mar345-detector mounted on the dtb: 


! _____________________________________________________________________________
!
! Configuration file for mar345 S/N 184 and dtb S/N 010
! _____________________________________________________________________________
!
! =============================================================================
! =============================================================================
! ==                                                                         ==
! ==                    Keywords for general program usage                   ==
! ==                                                                         ==
! =============================================================================
! =============================================================================
!
USE       	DTB
USE             SCANNER
DTB       	PORT  4451   HOST 192.0.2.3 TIMEOUT 0
MAR345    	PORT  4441   HOST 192.0.2.1 TIMEOUT 0
MARMUX          PORT  502    HOST 192.0.2.100 INTERVAL 1000 IGNORE
!
INTENSITY	MIN 2000  WARN 20.0 DOSEMIN 2.0
!
USE  	  	SPY
USE	  	STATS
!
USE   		HTML
IGNORE		SUMMARY
IGNORE          SHELL
!
IGNORE          TTL
!
COLORS		64
SETS		30
!
BROWSER		firefox
EDITOR          kedit
MONTAGE		montagedtb.csh
SOUND		play
!
!
! Video params
! ============
!
! VIDEO         V4L2 or LIBXV or  EXTERNAL or IGNORE
!
VIDEO           V4L2 GREY DEVICE  /dev/video0
VIDEO           INPUT Composite1  NORM PAL IDLE 300
VIDEO     	BRIGHTNESS 60 CONTRAST 55 AVERAGE 5
VIDEO     	WIDTH 768  HEIGHT 576 SCALE 474 474 474
VIDEO     	ORIGIN 368  285
VIDEO           OVERLAY JPG 
!
THUMBNAIL	mar2thumb
LOOPFINDER	loopfind
!
! Sample changer params
! ====================
!
CSC             IGNORE
CSC             CAP CHECK BARCODELEN 10
CSC             MAXSHIFT 250 CORREL 0.7 NOSHIFT AUTO
CSC             ZMAX 2.0 XMAX 1.0 YMAX 1.0
!CSC            METHOD 1  CYCLES 1  PHOTOS  8  DPHI 45.0  START 0.0  TOLE 0.3
!CSC            METHOD 0  CYCLES 1  PHOTOS  4  DPHI 90.0  START 0.0  TOLE 0.3
CSC             METHOD 2  CYCLES 1  PHOTOS 12  DPHI 90.0  START 0.0  TOLE 0.3
!
!
! WINDOWS params for Linux:KDE (1280x1024 pixels)
! ===============================================
! WINDOWS         MAIN 1123  0 VIEW 45  0 1070 970
!
! WINDOWS params for Linux:GNOME (1280x1024 pixels)
! ================================================
! WINDOWS         MAIN 1122 22 VIEW 15 22 1095 942
!
! WINDOWS params for Linux:KDE (1680x1050)
! ========================================
! WINDOWS         MAIN 1525  0 VIEW 445  0 1070 1020
!
! WINDOWS params for Linux:KDE (1600x1200)
! ========================================
! WINDOWS         MAIN 1444 0 VIEW 45  0 1392 1174
!
! WINDOWS params for Linux:KDE (1920x1200)
! ========================================
! WINDOWS         MAIN 1765  0 VIEW 585  0 1170 1170
!
! WINDOWS params for Linux:KDE (1920x1080)
! ========================================
! WINDOWS         MAIN 1765  0 VIEW 585  0 1170 1050
!
MONOCHROMATOR	Mirrors
GENERATOR	Synchrotron
WAVE		DEFAULT 1.000 USE
!
! Log file versions to maintain:
!
VERSIONS        LOG 99  SPY 99 STATS 10 SCAN 99 TIME 99 PROFILE 99
!
! =============================================================================
! =============================================================================
! ==                                                                         ==
! ==                       Keywords affecting dtb only                       ==
! ==                                                                         ==
! =============================================================================
! =============================================================================
!
! ADC values to start with:
!
ADC  CHAMBER 1 OFFSET 1000  TOLERANCE 20 HIGH VARIANCE LOW 2 HIGH 20 EDIT
ADC  CHAMBER 2 OFFSET 1000  TOLERANCE 20 HIGH VARIANCE LOW 2 HIGH 20 EDIT
!
! Initialization commands
!
STARTUP  USE  TIME LOCK VERSION REMOTE
STARTUP  SKIP ADC SHUTTER HV CYCLE
!
! Shutter close delay in [millisec]
!
SHUTTER  25
!
! Find beam params
!
FIND CHAMBER 1  X 25  75  Y  25 75  %  SLIT 4.0 4.0
FIND CHAMBER 2  X 15  85  Y  15 85  %  SLIT 4.0 4.0
!
! Optimize beam params
!
OPTI CHAMBER 1  SPEED 10 100  SLIT 0.6 0.6                RANGE 2.0 2.0
OPTI CHAMBER 2  SPEED 20  30  SLIT 0.3 0.3 FIRST 0.3 0.3  RANGE 2.0 2.0
OPTI SHORT FWHM  SMOOTH 5
!
! Scaling factors for all motors:
!
UNITS     STEPS 1  SPEED 1  ACCEL 1 TIME 2.5
!
! Slits: Basecon-modul 1-4 (ID = 1-4)
! 1 mm  = 200 fsteps 		
! V 	= 100 fsteps/sec 
! A  	= 4000 fsteps/s*s
!
SLIT FIRST  VER STEPS 200 SPEED 100 ACC 4000 TIMEOUT 10 DEF 0.4 ID 1
SLIT FIRST  HOR STEPS 200 SPEED 100 ACC 4000 TIMEOUT 10 DEF 0.4 ID 2
SLIT SECOND VER STEPS 200 SPEED 100 ACC 4000 TIMEOUT 10 DEF 0.3 ID 3
SLIT SECOND HOR STEPS 200 SPEED 100 ACC 4000 TIMEOUT 10 DEF 0.3 ID 4
!
SLIT FIRST  VER MIN -0.03  MAX 4.0  SPEED 100 ACC 4000 BACK 0.2
SLIT FIRST  HOR MIN -0.04  MAX 4.0  SPEED 100 ACC 4000 BACK 0.2
SLIT SECOND VER MIN -0.04  MAX 4.0  SPEED 100 ACC 4000 BACK 0.2
SLIT SECOND HOR MIN -0.07  MAX 4.0  SPEED 100 ACC 4000 BACK 0.2
!
SLIT FIRST  HOR INITMIN NOINITMAX HASNOREF ABSOL HASMIN
SLIT FIRST  VER INITMIN NOINITMAX HASNOREF ABSOL HASMIN
SLIT SECOND HOR INITMIN NOINITMAX HASNOREF ABSOL HASMIN
SLIT SECOND VER INITMIN NOINITMAX HASNOREF ABSOL HASMIN
!
! Beamstop: Basecon-modul 5 (ID = 5)
! 0.15 mm  = 1 fsteps 	
! 1    mm = 6.666
! V 	= 2000 fsteps/sec
! A  	= 500 fsteps/s*s
!
BEAMSTOP  STEPS 6.6666666 SPEED 100 ACC 500 ID 5
BEAMSTOP  MINVAL 5.0  MAXVAL 45.0 DEFAULT 15.0
BEAMSTOP  REFERENCE 18.6 SPEED 50 SLOW 20 ACC 30000  TIMEOUT 20  METHOD 19
BEAMSTOP  HASNOMIN HASNOMAX  HASREF NOINITMIN NOINITMAX NEGATIVE NOINITAUTO
!
! Phi: Basecon-modul 6 (ID = 6)
! 1 deg = 800 fsteps 	
! V 	= 10000 fsteps/sec
! A  	= 20000 fsteps/s*s
!
PHI	STEPS 800 SPEED 10000 ACC 20000 BACKLASH -0.5  DEF 0.0 ID 6
PHI     REFERENCE -0.125 SPEED 4000 SLOW 200 ACC 20000 TIMEOUT 180 METHOD 20
PHI     HASNOMIN HASNOMAX HASREF NOINITMIN NOINITMAX NEGATIVE NOINITAUTO
!
! Theta: CAN-modul 1 (ID = 11)
! 1 mm  = 400 fsteps 	
! V 	= 2000 fsteps/sec
! A  	= 1000 fsteps/s*s
!
THETA	STEPS 400 SPEED 2000 ACC 1000 TIMEOUT 120 ID 11
THETA   MINVAL 0.0  MAXVAL 30.0 DEFAULT 0.0
THETA   REFERENCE MIN -0.115  MAX 30.0  SPEED 2000 ACC 20000 SLOW 500
THETA   HASMIN HASMAX INITMIN NOINITMAX NEGATIVE NOINITAUTO
!
! Distance: CAN-modul 2 (ID = 12)
! 1 mm  = 400 fsteps 	
! V 	= 4000 fsteps/sec
! A  	= 4000 fsteps/s*s
!
DISTANCE STEPS 400 SPEED 4000 ACC 4000 DEF 400.0 TIMEOUT 120 ID 12 
DISTANCE REFERENCE MIN 75.0  MAX 425.6  SPEED 2000 ACC 20000  SLOW 500
DISTANCE HASMIN HASMAX NOINITMIN INITMAX POSITIVE NOINITAUTO
!
! Vertical translation: CAN-modul 3 (ID = 13)
! 1 mm  = 20000 fsteps
! V     = 800  fsteps/sec
! A     = 2000 fsteps/s*s
!
TRANS VER  STEPS 20000 SPEED 800 ACC 2000 TIMEOUT 333 ID 13
TRANS VER  MINVAL -7.5  MAXVAL 7.5  DEFAULT 0.0
TRANS VER  REFERENCE MIN -7.80  MAX 7.80  SPEED 800 SLOW 500 ACC 2000
TRANS VER  HASMIN HASMAX INITMIN INITMAX POSITIVE NOINITAUTO
!
! Vertical rotation: CAN-modul 4 (ID = 14)
! 1 mm  = 2500 fsteps
! V     = 4000 fsteps/sec
! A     = 2000 fsteps/s*s
!
ROTAT VER  STEPS 2500 SPEED 3000 ACC 2000 DEF 0.0 TIMEOUT 444 ID 14
ROTAT VER  MINVAL -17.0  MAXVAL 35.0  DEFAULT 0.0
ROTAT VER  REFERENCE MIN -18.0  MAX 37.00 SPEED 3000 SLOW 500 ACC 10000
ROTAT VER  HASMIN HASMAX INITMIN INITMAX POSITIVE NOINITAUTO
!
! Horizontal translation: CAN-modul 5 (ID = 15)
! 1 mm  = 1600 fsteps
! V     = 4000 fsteps/sec
! A     = 10000 fsteps/s*s
!
TRANS HOR  STEPS 1600 SPEED 4000  ACC 10000 DEF 0.0 TIMEOUT 555   ID 15
TRANS HOR  MINVAL -9.8   MAXVAL 9.8  DEFAULT 0.0
TRANS HOR  REFERENCE MIN -10.00  MAX 10.00 SPEED 4000 SLOW 500 ACC 10000
TRANS HOR  HASMIN HASMAX INITMIN INITMAX POSITIVE NOINITAUTO
!
! Horizontal rotation: CAN-modul 6 (ID = 16)
! 1 mm  = 1600 fsteps
! V     = 4000 fsteps/sec
! A     = 10000 fsteps/s*s
!
ROTAT HOR  STEPS 1600 SPEED 4000 ACC 10000 DEF 0.0 TIMEOUT 666 ID 16
ROTAT HOR  MINVAL -33.0   MAXVAL 33.0  DEFAULT 0.0
ROTAT HOR  REFERENCE MIN -34.00  MAX 34.00 SPEED 4000 SLOW 500 ACC 10000
ROTAT HOR  HASMIN HASMAX INITMIN INITMAX NEGATIVE NOINITAUTO
!
! Crystal Z-translation: CAN-modul 7 (ID = 17)
! 1 mm  = 1600 fsteps
! V     = 4000 fsteps/sec
! A     = 10000 fsteps/s*s
!
CRYSTAL Z  STEPS 1600 SPEED 4000 ACC 10000 DEF 0.0 TIMEOUT 777 ID 17
CRYSTAL Z  REFERENCE MIN -20.00 MAX 20.00 SPEED 4000 SLOW 500 ACC 20000
CRYSTAL Z  HASMIN HASMAX NOINITMIN INITMAX NEGATIVE NOINITAUTO
!
! Chi: CAN-modul 8 (ID = 18)
! 1 deg = 437.5 fsteps
! V     = 2000 fsteps/sec
! A     = 10000 fsteps/s*s
!
CHI        USE
CHI        MAXVAL 90.0 DEFAULT 0.0  BACKLASH 0.5
CHI        STEPS 437.5 SPEED 2000 ACC 10000 TIMEOUT 888 ID 18
CHI        REFERENCE MIN -0.00   MAX 90.00 SPEED 1000 SLOW 100 ACC 20000
CHI        HASMIN HASMAX INITMIN NOINITMAX NEGATIVE NOINITAUTO
!
! ============================================================================
! Optional additional motors, e.g. for sample changer ... 
! ============================================================================
!
! Crystal x-translation: CAN-modul 9 (ID = 25)
! 1 deg = 20480/360 = 56.888 steps
! 1 mm  = R*sin(x) with R=3.0
! V     = 1000 fsteps/sec
! A     = 5000 fsteps/s*s
!
CRYSTAL X  USE
CRYSTAL X  STEPS 56.888 SPEED 800 ACC 5000 DEF 0.0 BACK 0.0 TIMEOUT 777 ID 26
CRYSTAL X  REFERENCE MIN -1.650  MAX 1.300  SPEED 500 SLOW 500 ACC 3000
CRYSTAL X  INITMIN INITMAX HASMIN HASMAX NEGATIVE NOINITAUTO
CRYSTAL X  OFFSET  0.0
!
! Crystal y-translation: CAN-modul 10 (ID = 26)
! 1 deg = 20480/360 = 56.888 steps
! 1 mm  = R*sin(x) with R=3.0
! V     = 1000 fsteps/sec
! A     = 5000 fsteps/s*s
!
CRYSTAL Y  USE
CRYSTAL Y  STEPS 56.888 SPEED 800 ACC 5000 DEF 0.0 BACK 0.0 TIMEOUT 777 ID 27
CRYSTAL Y  REFERENCE MIN -1.801  MAX 1.300  SPEED 500 SLOW 500 ACC 3000
CRYSTAL Y  INITMIN INITMAX HASMIN HASMAX POSITIVE NOINITAUTO
CRYSTAL Y  OFFSET  0.0
!
! Cryo actuator: CAN-modul 11 (ID = 24)
! 1 mm  = 1600 fsteps 
! V     = 4000 fsteps/sec
! A     = 10000 fsteps/s*s
!
ACTUATOR    USE
ACTUATOR    STEPS 1600 SPEED 3000 ACC 10000 DEF 0.0 TIMEOUT 888 ID 24
ACTUATOR    BACKLASH 0.0 MINVAL 0.0 MAXVAL 24.9
ACTUATOR    REFERENCE MIN 0.00  SPEED 3000 SLOW 1500 ACC 10000
ACTUATOR    HASMIN HASNOMAX INITMIN NOINITMAX HASNOREF POSITIVE NOINITAUTO
!
! ============================================================================
! Optional additional motors, e.g. for crystal plate scanner XPS
! ============================================================================
!
!
! Crystal plate scanner module 18 (ID = 28)
! 1 mm  = 1600 fsteps
! V     = 3000 fsteps/sec
! A     = 10000 fsteps/s*s

XPS_X       IGNORE
XPS_X       STEPS 1600 SPEED 3000 ACC 10000 DEF 0.0 TIMEOUT 888 ID 28
XPS_X       BACKLASH 0.0 MINVAL 1.0 MAXVAL 89.0
XPS_X       REFERENCE MIN 0.00  MAX 90.0 SPEED 3000 SLOW 1000 ACC 10000
XPS_X       HASMIN HASMAX INITMIN INITMAX HASNOREF POSITIVE ABSOL
!
! Crystal plate scanner module 19 (ID = 29)
! 1 mm  = 1600 fsteps
! V     = 2000 fsteps/sec
! A     = 10000 fsteps/s*s
!
XPS_Y       IGNORE
XPS_Y       STEPS 1600 SPEED 3000 ACC 10000 DEF 0.0 TIMEOUT 888 ID 29
XPS_Y       BACKLASH 0.0 MINVAL 1.0 MAXVAL 1390.0
XPS_Y       REFERENCE MIN 0.00  MAX 140.0 SPEED 3000 SLOW 1000 ACC 10000
XPS_Y       HASMIN HASMAX INITMIN INITMAX HASNOREF POSITIVE ABSOL

! ============================================================================
! Remote control settings
! ============================================================================
!
REMOTE     USE
REMOTE     MASK 16777215     ! for csc,  without actuator use: 16777214
REMOTE     ADC      ENABLE NOEDIT
REMOTE     THETA    POS1 0.0     POS2   5.0 ENABLE EDIT
REMOTE     DISTANCE POS1 DYNAMIC POS2 300.0 ENABLE EDIT
REMOTE     CHI      POS1 0.0     POS2  60.0 ENABLE EDIT
REMOTE     BEAMSTOP POS1 18.0    POS2  45.0 ENABLE EDIT
!
! To enable beamstop on button CRYO run the following commands first:
! dtbcmd 103,1,41,5
! dtbcmd 103,1,40,100
! dtbcmd 103,1,39,500
! dtbcmd 103,1,38,-300
! dtbcmd 103,1,37,-120
! These commands need to be given only once and the dtb needs to be rebooted
! afterwards.
!
! =============================================================================
! WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARN
! =============================================================================
!
! USE CRYO and USE AMPTEK protect the detector from 
! driving into collision. If these keywords are removed while
! the cryo-system INCLUDING cryo-mount (!!!) or AMPTEK are present
! considerable damage to both detector and dtb can be produced.
!
! When setting IGNORE CRYO it is ESSENTIAL to also remove
! the cryo-mount (by removing part of the cryo-stream exhaust).
!
! =============================================================================
!
USE       CRYO  
CRYOPARAM OXFORD
! CRYOPARAM XTREME
! CRYOPARAM DISTANCE 0 THETA 25
IGNORE    AMPTEK
!
! =============================================================================
! =============================================================================
! ==                                                                         ==
! ==                     Keywords affecting mar345 only                      ==
! ==                                                                         ==
! =============================================================================
! =============================================================================
!
GAIN            100U 1.00  150U 0.63
!
! Never ever change keywords from here on
!
MODE 2300       ROFF 120     ADC 50 AADD -42  BADD -42 PIXELSIZE 0.15
MODE 2000       ROFF 120     ADC 50 AADD -42  BADD -42 PIXELSIZE 0.15
MODE 1600       ROFF 120     ADC 50 AADD -42  BADD -42 PIXELSIZE 0.15
MODE 1200       ROFF 120     ADC 50 AADD -42  BADD -42 PIXELSIZE 0.15
!
MODE 3450       ROFF 120     ADC 50 AADD -42  BADD -42 PIXELSIZE 0.10
MODE 3000       ROFF 120     ADC 50 AADD -42  BADD -42 PIXELSIZE 0.10
MODE 2400       ROFF 120     ADC 50 AADD -42  BADD -42 PIXELSIZE 0.10
MODE 1800       ROFF 120     ADC 50 AADD -42  BADD -42 PIXELSIZE 0.10
!
FLAG		0
!
!IP-Diameter:   345mm    300mm    240mm    180mm    
!GAPS           89659    78656    63903    49146    (08:49 on 30-Oct-2000)
!

prev  up  down  next 

3. Calibration Files

If used with a mar345-detector, program mar345dtb requires calibration files. Those calibration files contain flood field correction factors as well as the geometrical information required to transform spiral coordinates into a Cartesian grid system. The file names are:

These files are very large in size (73 MB and 103 MB, respectively). Every time the scanner reads out the plate this file has to be processed. While most of the file contents are binary data, some part of the header is ASCII. Program catmar allows to look into the header.

4. Parameter File

Program mar345dtb continuously saves parameters whenever they change within the program. When starting the program, the saved parameters are read back so the user always finds the latest changes after quitting a mar345dtb session. The parameter file read at startup is called dtb.dat and resides in directory $MARLOGDIR. If the parameter file doesn't exist, program defaults will be used. The program, however, will always create a new parameter file dtb.dat. The parameter file is a keyworded ASCII-file which may be edited.

Parameter files can be created and loaded from within the program. This is useful when working on a project where you always apply the same set of parameters. The parameter files carry the extension ".set" and may be saved using the "Edit -> Save Parameters ..." menu option in the main window. The parameters can be read back by using the "Edit -> Load Parameters ..." menu option ( also see chapter 6.2 in section Edit).

4.1 Keywords

The keywords used in the parameter file dtb.dat are as follows:

Table 2: Keywords in dtb.dat

Keyword Arguments Example Description
SET N   USE|SKIP 10.   USE N is the data set number followed either by string USE or SKIP
DIRECTORY STR /data STR is a string with a path name
ROOT STR xtal STR is a string with image root name
SCANMODE N 0 N is one of 8 scanmodes, either 1200, 1600, 1800, 2000, 2300, 2400, 3000 or 3450
FORMAT mar|cbf mar Image output format: either "mar" or "cbf"
COLLECT TIME|DOSE TIME Exposure mode, either TIME or DOSE
BLOCKS N 1 N is the number of PHI-blocks
NFRM N 50 N is the number of images per block
FFRM N 1 N is the first image number
OSCI N 1 N is the number of oscillations
DPHI F 0.5 F is the Delta-PHI per image
IPHI F 0.0 F is the PHI-increment between images
DISTANCE F 220.0 F is the distance detector-to-sample
PHI F 45.0 F is the starting PHI angle
CHI F 0.0 F is the current CHI angle
THETA F 0.0 F is the current 2-theta angle
WAVE F 1.54178 F is the current wavelength
BEAMSTOP F 18.5 F is the current beamstop position
XTAL_Z F 0.0 F is the relative crystal translation
SLIT1 F   G 0.71   0.63 F and G are hor. and ver. slit apertures for chamber 1 slits
SLIT2 F   G 0.45   0.43 F and G are hor. and ver. slit apertures for chamber 2 slits
ERASE     Erase plate before starting data collection
PHOTO     Save crystal photo after each image
THUMBNAIL     Produce thumbnails from data images during data collection
SPIRAL     Also create raw spiral images during data collection
OPTIMIZE START     Optimize beam before starting data set
OPTIMIZE [-]N   IMAGE|HRS|MIN|LOSS 30 LOSS Optimize beam during data collection after given time or after N images or after N percent loss of X-ray intensity. A negative sign preceding N indicates this option to become deselected.
APPEND [SET] [VIAL] [BARCODE] SET BARCODE Append set and/or vial no. and/or barcode (+identifier) to file root on image creation
VIAL N 14 Carousel position to take sample from
CENT NONE|MANUAL|XYZ|AUTO [CONFIRM] [SHIFT] XYZ CONFIRM Crystal centering method, XYZ and AUTO may be followed by CONFIRM, XYZ may also be followd by SHIFT
COMOPT [1][+2][+3][+4][+5] 2+5 Selection of parameters to pass to shell script dtb.csh
COM1/2/3/4/5 STR sleep 1 Custom argument for shell script dtb.csh

Up to here, the keywords are valid for the "SET" number given on the top. With a new SET keyword, the following keywords will be valid for that new set, so a dtb.dat may contain data for all 30 possible sets and the corresponding entries will be used to update the "Edit"-page. A couple of keywords have to be given only once since they are not related to that page:

Keyword Type Value Description
SOURCE STR Rotating Anode STR is the id of the X-ray source as given in the "Header Info"-window
POWER F   G 50.0   100.0 F and G are kV and mA settings of X-ray source as given in the "Header Info"-window
FILTER STR Mirrors STR is the id of the monochromator as given in the "Header Info"-window
CENT F   G 0.0   0.0 Deviations of center coordinates as given in the "Header Info"-window
TRANSLATIONS F   G -2.048   -1.888 Refined beam positions of motors TRANS_HOR and TRANS_VER
ROTATIONS F   G -3.241   1.435 Refined beam positions of motors ROT_HOR and ROT_VER
ADVANCED|SIMPLE     Choice of advanced or standard layout for "Edit..."-window
CSC N1  N2  N3  N4  N5  N6
[NO]SHIFT   [NO]STORE 		3 2 5 4 4 18 Values to fill in into the "CSC operation"-fields on the "CSC"-page (Change sample, etc.).
MARMUX N or STR 1 or TTL Choice of "Close generator shutter after finishing data collection"

4.2 Example

The following example contains parameters for only 1 data set. 




#=====================================================
# Date: Mon Feb 18 19:03:08 2002
# Automatically saved by mar345dtb: DO NOT EDIT!!!
#=====================================================
# ----------------------------------
SET       1  USE
DIRECTORY /home/mar345/data/
ROOT      xtal
SCANMODE  1200
FORMAT    mar
COLLECT   DOSE
TIME      10
BLOCKS    1
NFRM      1
FFRM      2
OSCI      1
DPHI      1.000
IPHI      89.000
DISTANCE  350.000
PHI       45.000
CHI       -0.000
THETA     0.000
WAVE      1.541790
BEAMSTOP  10.050
XTAL_Z    0.000
SLIT1     0.710  0.630
SLIT2     0.400  0.400
OPTIMIZE  START
OPTIMIZE  -30 images
ERASE
PHOTO 
THUMBNAIL
# ----------------------------------
# --- Shell commands  ---
COMOPT    1+5
COM1
COM2
COM3
COM4
# --- Optional Header Info ---
SOURCE    Rotating Anode
POWER     50.00   100.00
FILTER    Mirrors
POLAR     0.000
CENT      0.0  0.0
REMARK    
# --- Refined X-ray beam positions ---
TRANSLATIONS     -2.048    -1.888
ROTATIONS        -3.261    -2.508
# --- Edit Data Collection in expert mode ---
ADVANCED DATA COLLECTION FEATURES
# --- Crystal translation disabled in Edit ---
XTAL_Z    DISABLED
# --- Sample Changer Settings: Change, Load, Unload, Give, Take, Pin ---
CSC       1 2 1 2 2 18 SHIFT NOSTORE
MARMUX    1

5. Command File

Program mar345dtb may be completely driven by external commands, i.e. all relevant settings and push-button actions can be bypassed. The command interface comes into variants:

This ASCII-file interface becomes active, if the configuration file has a positive argument on keyword COMMAND. A typical value would be "COMMAND 1000", i.e. the program would look all 1000 msec for existence of a file dtb.com. If it does exist, it is read and evaluated . If it does contain a command, the file will be deleted (!) and the command will be executed. While the given command is in progress, a new dtb.com may be created, but it will be evaluated only after the previous command has completed - except commands that contain a STOP or ABORT signal. External programs may monitor the progress of the activity either by evaluating the dtb.log, dtb.spy or dtb.status files, all residing in $MARLOGDIR.

The TCP/IP-interface becoms active, if the configuration file has a negative argument on keyword COMMAND. A typical value would be "COMMAND -8678", i.e. the program would listen on UNIX port 8678 for connections. The program allows for multiple connections on the same port. The syntax for commands to be accepted via the TCP/IP-port is identical to the dtb.com file, i.e. ASCII strings will be evaluated. In return, the TCP/IP-socket writes ASCII-strings back to the same socket containing status information. The syntax is the same as used in the dtb.status file. The frequency is approx. 1/sec.

Note, that the command interface can be used together with the GUI but bears a considerable risk of unwanted or unforeseen dtb or mar345 activity. It must be stated that usage of the command interface is beyond the responsibility of marxperts and all damage produced by running commands using that command interface are not within our liability!

As stated above, all the syntax of the parameter file is used to modify settings of the data collection parameters, i.e. all parameters belonging to a given "SET" will be used to override the corresponding parameters on the "Edit"-pages. The main difference is that the command file in addition to the (optional) keywords of the data collection parameters requires additional lines that actually provide a command to be executed. This line always starts with keyword COMMAND followed by the following arguments:

Table 3: Arguments for keywords COMMAND in dtb.com

Arguments Example Description
ERASE ERASE Erase the image plate
SCAN filename [scanmode] SCAN /data/lysozyme_001.mar1200 1200 The filename must follow the mar345dtb conventions. The scanmode and format will be taken from the image extension. If the scanmode is provided as additional argument, it will have precedence. When using the mar345s versions of the detector, it is mandatory to provide the scanmode to make a scan with a fast mode, since the image name extension for modes 1 and 5 in both cases is .mar2300. The scanmode is either a number from 1 to 8 or 2300, 2000, 1600, 1200, 1150, 1000, 800, 600 for mar345s detectors with a combination of normal (1-4) and fast (5-8) 150 micron scan modes. For a combination of 100 micron scan modes (1-4) and fast 150 micron scan modes (5-8), the scanmode parameter would be one of 3450, 3000, 2400, 1800, 1150, 1000, 800 or 600.
CHANGE <mode> CHANGE 1200 Change the scanmode. Scanmode can be 1 to 8 or one of the modes given in the configuration file, typically 1200, 1600, 2000, 2300, 1800, 2400, 3000 or 3450. For mar345s variants, the scanmode might be 1150, 1000, 800 or 600.
IPS n1,n2,... IPS 4,0 Native controller command for the mar345 image plate.
DTB n1,n2,... DTB 101,0 Native controller command for the dtb.
SHUTTER [OPEN|CLOSE] SHUTTER CLOSE Open or closes the shutter (or toggles current state).
MOVE <motor> <value> MOVE PHI 90.0 Drive <motor> to <value>. The motor must be a string as given in chapter Motors in section Introduction.
DEFINE <motor> <value> DEFINE DISTANCE 250.0 Define position of <motor> to be <value>. Beware: this command is VERY CRITICAL and should normally not be used.
INIT <motor> MIN|MAX|REF INIT THETA MIN Initialize <motor> motor at minimum (near end), maximum (far end) or reference.
OPTIMIZE [FIRST] [SECOND] OPTIMIZE Optimization beam in first and/or second chamber. Omitting FIRST and SECOND means using BOTH. COMMAND OPTIMIZE requires additional parameters to be provided on the OPTIMIZE keyword (see below).
FIND [FIRST] [SECOND] FIND SECOND Find the beam in first and/or second chamber. COMMAND FIND requires additional parameters to be provided on the FIND keyword (see below).
PROFILE [SLIT <h> <v>] [HOR <hor>] [VER <ver>] [PITCH <val>] PROFILE HOR 1.5 VER 1.5 SLIT 0.1 0.1 PITCH 0.05 Produce a beam profile covering <hor> mm in HORIZONTAL direction and <ver> mm in VERTICAL direction using slit apertures in chamber 1 of <h> and <v> mm, respectively. The advance per vertical movement will be <valr> mm. If some arguments are missing, the current settings of the GUI will be used.
SHAPE [CHAMBER] 1|2 [HOR|VER <val>] [TRUNCATE <t>] [SPEED <per>] SHAPE 1 HOR 0.9 TRUNCATE 15 SPEED 20 Produce a beam shape plot for chamber 1 or 2 for the HORIZONTAL or VERTICAL slit, using an aperture for the non-moving slit of <val> mm at a speed of <per> percent . If some arguments are missing, the current settings of the GUI will be used.
ADJUST [CHAMBER] 1|2 [WEAK|STRONG] [[OFFSET] <v>] [TOLERANCE <tr>] ADJUST CHAMBER 1 OFFSET 1000 TOL 10 CHAMBER 2 OFF 1000 TOL 20 Reset the ADC readings of chambers 1 or 2 to <v> units with a tolerance of <t> units. If some arguments are missing, the current settings of the GUI will be used.
COLLECT [<s1>] [<s2>] [<s3>] ... COLLECT 3 8 24 Collect data for sets <s1>, <s2>, etc. Please note, that unless the sets are being reprogrammed by the same command file (using the syntax of the dtb.dat file), the current values in the Edit-page of the GUI for the desired set are going to be used.
STOP [AFTER IMAGE|SET] [NOW] STOP AFTER SET Stop a data collection after finishing current IMAGE or current SET, or stop a motor movement NOW.
CONTINUE [AFTER] IMAGE|SET CONTINUE AFTER IMAGE Undoes the effect of STOP AFTER IMAGE or STOP AFTER SET.
ABORT ABORT Immediately stops current activity.
QUIT QUIT Makes program mar345dtb shutdown.
CSC {CHANGE <vial>} | {LOAD <vial>} | UNLOAD {GIVE <vial>} | {TAKE <vial>} | INIT | RESET | {MAGNET ON|OFF} | {SAVE <file>} | {READ <file>} | CSC LOAD 18 Sample changer operations as described in chapter CSC Operations in section CSC. The commands CSC SAVE and CSC READ will save or read sample status files, respectively.
CRYSTAL FIND |{CENTER [XY] [<x> <y> <z>]} CRYSTAL CENTER Triggers a crystal finding or centering procedure as described in chapter Crystal Centering in section Crystal. While FIND works without further options, CENTER may be followed by xyz-coordinates. If they are omitted, the automatic procedure will be tried.

6. Shell Script

Program mar345dtb allows to run external commands at certain times during data collection:

In all cases, the program relies on the existence of an executable shell script called dtb.csh which must reside in directory $MARLOGDIR. If that file doesn't exist, the program will continue immediately with the next step of data collection. Otherwise, the data collection will only continue if the commands in the shell script are finished. The shell script may be edited to add any desired command.

The following listing contains a very simple template for file dtb.csh. 




#!/bin/csh -f
set argc 	= $#argv 
set NUM 	= 2
set cmd		= $1
set LOG		= ( $MARLOGDIR/dtb.csh.log ) 
while ( $NUM <= $argc )
	set cmd = ( $cmd $argv[$NUM] )
	@ NUM++
end
#
echo "===============================================================" >> $LOG
echo "Time:    `date`" >> $LOG
echo "Command: $cmd"   >> $LOG
echo "===============================================================" >> $LOG
#
# Actual command
#
echo $cmd
sleep 2
#
exit

7. Images

mar(345)dtb autodetects image file formats. The program actually looks at contents of files rather than at file names only. mar(345)dtb accepts the following image formats:

Table 4: Image formats accepted by mar(345)dtb

Format Name suffix Description
mar345 .marXXXX Images produced by mar345 detector
cbf .cbfXXXX Images produced by mar software in CBF format
image .image Original format of 180mm/300mm scanners
pck .pck Images of 180mm/300mm scanners, "pck"-compressed.
marccd .mccd or .#### Images of marCCD detector
raw .raw Raw 32-bit data arrays without header
tiff .tif TIFF files with 32-bit data array for DECTRIS detectors

8. Carousel File

Program mar345dtb continuously saves carousel data whenever they change within the program. When starting the program, the saved parameters are read back so the user always finds the latest changes after quitting a mar345dtb session. The carousel file read at startup and updated during program execution is called $MARLOGDIR/csc/CSC.csv. The format is described in chapter Carousel File in section Output.

9. License File

Program mardtb needs a specific license file to operate together with DECTRIS detectors, either Pilatus3 or EIGER versions. This license file must be obtained from marXperts GmbH and requires program "mardtblicense" to be run on the target PC which is going to control the detector and mardtb goniostat. This license file is specific for a given installation and cannot be used for other setups. Please contact marXperts GmbH in case of doubt. When running program mardtblicense it is mandatory to run it on the host that connect to the mardtb hardware. Also, it is mandatory, that the mardtb is turned on at the time to run program mardtblicense and that the host is capable to connect to the mardtb hardware. In case of doubt, please check that you can login into the hardware with command "telnet 192.0.2.3". If this command does not succeed, the program mardtblicense will not be able to create the license information.

10. XPS Data and Definitions

When used with the crystal plate scanner, the program reads and stores data of a currently mounted crystallization plate from directory $MARLOGDIR/xps. In that directory XPS.dat stores current information of assigned drops that will be loaded automatically after reentering the software. File XPS.def however contains definitions for specific types of crystallization plates. This plain ASCII-file can be edited and new entries can be added to it. A crystallization plate definition section must contain the following entries:

Example:

NAME	Greiner CrystalQuick-X 2-Drops
ROWS	12	SEP 9.0
COLS	8	SEP 9.0
ORIGIN	12.43 9.79  TOP
DROPS	2 DX1 3.0 DY1 0.0
DIMENS	85.48 127.76

prev  up  next