Table of Contents

mar345_config_file - description of the scanner specific configuration file for program mar345 (345 mm scanners)

Description

The scanner configuration file is a keyworded Ascii-file in free format. Lines starting with # or ! will be treated as comment lines. Currently the following keywords are implemented:

MODE <mode> TIME <time> ROFF <roff> ADC <adc> AADD <aadd> BADD <badd> PIXELSIZE <sz>
<mode> is the number of pixels in 1 dimension (1200, 1600, 2000, or 2300 at 0.15 mm pixelsize, and 1800, 2400, 3000 or 3450 at 0.10 mm pixelsize). <time> is the total scan time (and erase) in seconds. <roff> is the radial offset in pixels (version 0.x) or 2 micron units (version > 1.0 only) . <adc> is the target value for the A/D-converter (version > 1.0 only) <aadd> is the value to add to each spiral pixel in ADC-channel A (version > 1.0 only) <badd> is the value to add to each spiral pixel in ADC-channel A (version > 1.0 <sz> is the pixel size for this scan mode in mm only)
Defaults:
MODE 2300 TIME 80 ROFF 0 ADC 10 AADD 0 BADD 0 PIXELSIZE 0.15
MODE 2000 TIME 66 ROFF 0 ADC 10 AADD 0 BADD 0 PIXELSIZE 0.15
MODE 1600 TIME 48 ROFF 0 ADC 10 AADD 0 BADD 0 PIXELSIZE 0.15
MODE 1200 TIME 34 ROFF 0 ADC 10 AADD 0 BADD 0 PIXELSIZE 0.15
MODE 3450 TIME 108 ROFF 0 ADC 10 AADD 0 BADD 0 PIXELSIZE 0.10
MODE 3000 TIME 87 ROFF 0 ADC 10 AADD 0 BADD 0 PIXELSIZE 0.10
MODE 2400 TIME 62 ROFF 0 ADC 10 AADD 0 BADD 0 PIXELSIZE 0.10
MODE 1800 TIME 42 ROFF 0 ADC 10 AADD 0 BADD 0 PIXELSIZE 0.10

PHI SPEED <speed> STEPS <steps_deg> DEFAULT <def> USE|IGNORE FORWARD POSITIVE|NEGATIVE
<speed> gives the maximum motor speed in steps/sec. <steps_deg> is the gear ratio for translating steps into deg, e.g. STEPS 500 means: 500 steps = 1 deg. <def> is the default value to be used. USE or IGNORE turns PHI movements on or off. With keyword FORWARD, the PHI axis will move only in one direction, e.g. to go from 10 to 5 degrees, the PHI axis will move 355 degrees forward and not 5 degrees backward. With keyword NEGATIVE, the polarity of the motor can be changed, i.e. the current position and the target position of the axis will invert it’s sign.
Default: PHI SPEED 2000 STEPS 500 DEFAULT 0.0 POSITIVE

OMEG*a SPEED <speed> STEPS <steps_deg> MIN <min> MAX <max> DEFAULT <def>
<speed> gives the maximum motor speed in steps/sec. <steps_deg> is the gear ratio for translating steps into deg, e.g. STEPS 500 means: 500 steps = 1 deg. <min> is minimum sweep angle (in deg.) <max> is maximum sweep angle (in deg.) <def> is the default value to be used. USE or IGNORE turns OMEGA movements on or off. With keyword FORWARD, the OMEGA axis will move only in one direction, e.g. to go from 10 to 5 degrees, the OMEGA axis will move 355 degrees forward and not 5 degrees backward. With keyword NEGATIVE, the polarity of the motor can be changed, i.e. the current position and the target position of the axis will invert it’s sign.
Default: OMEGA SPEED 2000 STEPS 500 MIN -90.0 MAX 90.00 DEFAULT 0.0 POSITIVE

CHI SPEED <speed> STEPS <steps_deg> MIN <min> MAX <max> DEFAULT <def>
<speed> gives the maximum motor speed in steps/sec. <steps_deg> is the gear ratio for translating steps into deg, e.g. STEPS 500 means: 500 steps = 1 deg. <min> is minimum sweep angle (in deg.) <max> is maximum sweep angle (in deg.) <def> is the default value to be used.
Default: CHI SPEED 2000 STEPS 500 MIN -90.0 MAX 90.00 DEFAULT 0.0

THET*a SPEED <speed> STEPS <steps_deg> MIN <min> MAX <max> DEFAULT <def>
<speed> gives the maximum motor speed in steps/sec. <steps_deg> is the gear ratio for translating steps into deg, e.g. STEPS 500 means: 500 steps = 1 deg. <min> is minimum sweep angle (in deg.) <max> is maximum sweep angle (in deg.) <def> is the default value to be used.
Default: THETA SPEED 2000 STEPS 500 MIN -90.0 MAX 90.00 DEFAULT 0.0

DIST*ance SPEED <speed> STEPS <steps_mm> MIN <min_dist> MAX <max_dist> DEFAULT <def> USEMIN USEMAX USE|IGNORE POSITIVE|NEGATIVE
<speed> gives the maximum motor speed in steps/sec. <steps_mm> is the gear ratio for translating steps into mm, e.g. STEPS 100 means: 100 steps = 1mm. <min_dist> is the distance crystal-detector (in mm) at the near end of the translation stage. <max_dist> is the distance crystal-detector (in mm) at the far end of the translation stage. <def> is the default value to be used. USEMIN means: do not accept input of values smaller than <min_dist> USEMAX means: do not accept input of values larger than <max_dist> USE or IGNORE turns DISTANCE movements on or off. With keyword NEGATIVE, the polarity of the motor can be changed, i.e. the current position and the target position of the axis will invert it’s sign.
Default: DISTANCE SPEED 1000 STEPS 100 MIN 80.0 MAX 425.00 DEFAULT 100.0

POSITIVE

INITIALIZE MIN or MAX
The distance crystal-detector may be initialized at near end (MIN) or at the far end of the translation stage.
Default: INITIALIZE MAX

USE DISTANCE PHI OMEGA CHI THETA ERASE XRAY SOUND BASE DOSE IMAGE SPIRAL SPK RUN INDEX INCR STATS Z-AXIS SHELL WAVE ADC SPY HTML SUMMARY QUEUE LASER CENTER REFERENCE MAR345S
DISTANCE, PHI, OMEGA, CHI, THETA means: try to use the corresponding motors.
ERASE means: watch erase lamp status and stop data collection if erase lamps fail.
XRAY means: watch X-ray intensities as read by the ionization chambers and stop data collection if X-ray intensities drop significantly.
SOUND means: make noise when issuing warnings, errors, etc.
BASE means: use base control (i.e. motors, shutter).
CENTER means: apply file $MARTABLEDIR/center.### to images on output
DOSE means: do provide option for using DOSE mode.
IMAGE means: do provide option for old image output.
SPIRAL means: do provide option for spiral image output.
SPK means: do compress spiral images in spiral image output mode.
RUN means: append _RUNNUMBER (_1, _2, _3, _4) to image name roots in "Multiple Data Sets"
INDEX means: append string _INDEX to image name root in "Index"
INCR means: increment image number of consecutive images in "Index Data Sets" by 1. The default is to increment by a number depending on PHI position.
STATS means: some statistical values (average, sigma of total and of a box of 100x100 pixels in the 10:30 position of the detector are calculated and the results are logged into the separate output file ($MARLOGDIR/MAR345.x.LP).
Z-AXIS means: use a the OMEGA motor to drive a translation for the PHI axis.
SHELL means: provide 2 input fields in the "Change Parameters"-window to
submit shell commands, one to be executed before starting the data collection, the second to be executed before starting an exposure. No further program input is allowed during execution of the shell-command. The standard output of the shell will be displayed in the standard output window of mar345. Any shell-commands can be given. "mar345" expects files "$MARLOGDIR/mar345-com1.csh" and "$MARLOGDIR/mar345-com2.csh" to be present (see "man mar345" for an example).
WAVE means: provide a "Set"-button in the "Change Parameters"-window for changing the wavelength. The button is functional only if the shell-script "$MARLOGDIR/mar345-set.csh" is present (see "man mar345" for an example).
ADC means: use the ADC-offsets calculated by the electronics rather than those supplied by MODE <xxxx> AADD <aadd> BADD <badd> (version > 1.0 only).
SPY means: log internal information of the scanner into $MARLOGDIR/mar.spy (version > 1.0 only).
HTML means: create a summary file in HTML format for each collected dataset (version > 1.0 only).
SUMMARY means: create a summary file in ASCII format for each collected dataset (version > 1.0 only).
QUEUE means: put the next exposure command in the controller queue so the exposure starts immediately after the scan has finished. This normally happens sooner than if the scanner driving program on the host computer knows about the end of the scan and therefore saves some seconds of time depending on how busy the computer is. This may cause problems when using multiple oscillations so it is safer to use "IGNORE QUEUE". The default, however, is to use exposure queueing (version > 1.0 only).
LASER means: reports changes of laser status in log file and on the terminal screen. This is for testing lasers only (version > 2.2 only).
REFERENCE means: provide input fields for reference files in scan and collect menues. When reference files are given, they will be applied to images on output.
MAR345S means: the mar345 detector is equipped with a controller that allows for fast scan modes. This is mandatory for mar345s versions!
Default: USE DISTANCE PHI ERASE XRAY SOUND BASE DOSE RUN SPY HTML SUMMARY

QUEUE

IGNORE DISTANCE PHI OMEGA CHI THETA ERASE XRAY SOUND BASE DOSE IMAGE SPIRAL SPK RUN INCR STATS Z-AXIS SHELL WAVE ADC SPY HTML SUMMARY QUEUE LASER CENTER REFERENCE MAR345S
The meanings are opposite to the USE flags given above.
Default: IGNORE OMEGA CHI THETA IMAGE INDEX SPIRAL SPK INCR STATS Z-AXIS

SHELL WAVE ADC LASER CENTER REFERENCE MAR345S

IGNORE ERROR <n1> [<n2> [<n3>]] ...
Most hardware errors will make a data collection stop when encountered. Some hardware errors may, however, not be fatal, and it may be desirable to continue data collection, anyway. Also, some hardware errors may not be real. For instance, when the scanners reports that an erase lamp is off during erase, it is possible that only the light sensor is broken but the lamp itself works fine. In such cases, the error number as produced by the hardware can safely be ignored. The error numbers can be looked up in the mar.spy file. There, each message (error or not) has got a unique message number. Up to 20 hardware errors may be ignored but all must go in only one line. If there are multiple "IGNORE ERROR" lines, only the last one will be used.
Default: no errors ignored

INTENSITY MIN <intmin> WARNING <warn> DOSEMIN <dosemin>
<intmin> gives the minimum X-ray reading allowed during exposure. If reading is lower than this, data collection stops. To ignore this, option, set intensmin to -999 or alike. <warn> gives the allowed variation of X-ray intensity inbetween the start and the end of one exposure (in percent). If the variation is larger than <warn>, a warning message is issued and the data collection stops. This is to avoid unnecessary scans if the X-ray generator fails. To turn this option completely off, use IGNORE XRAY (see above) or give a very large value for <warn>. <dosemin> is the minimum intensity required to actually start an exposure when working in DOSE mode. If the intensity is less than <dosemin>, the exposure will not even be started but waits until the X-ray intensity as measured by the ionization chamber exceeds <dosemin>.
Default: INTENSITY MIN 2.0 WARNING 50.0 DOSEMIN 0.1

SPIRAL MAX <spmax> OFFSET <offset> SCALE <scale>
<spmax> is the maximum allowed value in a spiral pixel. The ADC makes use of thefull 16-bit range (65535), but linearity may slightly drop before reaching the saturation limit. <offset> gives the intensity offset to be added to the raw spiral data before transformation. <scale> applies a scale factor to the raw spiral data.
Default: SPIRAL MAX 65535 OFFSET 0 SCALE 1.0

BROWSER <internet_browser>
Program name for internet browser to display html documentation. Introduced in version 5.5.
Default: BROWSER firefox

COLORS <colors>
<colors> is the number of colors to be used for displaying data. The numbers are allocated in read/write mode and therefore, it is not possible to run many color intensive programs at one time on one screen. A good value for display of images is 32 colors. More colors will not visibly improve discrimination of signals. 16 colors is okay but will slightly decrease quality. 8 colors is the minimum.

COLORS 32

MEMORY 1 MB or 1000 kB or 1000000
The program mar345 reads a large calibration file during each scan. The files are 70 to 100 MB in size. To improve reading efficiency, data are read in in larger blocks. The default block size is 1 MB and probably doesn’t need to be modified. This feature is available from version 2.3 onwards.
Default: MEMORY 1 MB

NETWORK HOST <host> PORT <port>
Program mar345 tries to connect to host <host> through port <port> for communcating with the scanner. <host> should be an entry in file /etc/hosts named "192.0.2.1 mar345". Note that 192.0.2.1 is supposed to be out of the pool of unused IP-addresses.
Default: NETWORK HOST mar345 PORT 4123

PRIORITY <priority>
<priority> gives the desired "non-degrading" priority of the process. It is very important that mar345 has a higher priority than any other user process. Data collection should have precedence over all other applications. On SGI, use a value of 31 to 39. To be able to use this option, the super user has to edit /var/sysgen/mtune/disp and modify the "default" value of entry ndpri_hilim to 30. It may be necessary to run "autoconfig -f" and "reboot". On Linux, a special kernel is required. Use a value of -20 to -1.
Default: PRIORITY 31 (SGI) or PRIORITY -20 (Linux)

GAPS <345mm> <300mm> <240mm> <180mm> [TOLERANCE <N>]
The scanning head is mounted on a translation stage. During a scan the scanning head passes a couple of especially marked positions (gap) that serve as a reference for the correct scanning head positions. The positions are hardwired and scanner specific. For a scan at a certain diameter the positions should always stay the same. The positions are given in relative motor steps. The expected tolerance normally is +/- 5 steps. Larger variations of the found "gap" positions may indicate a problem with the scaning head spindle. The observed gaps will be written into image headers, so those values can be verified. If the "GAP" keyword is given and the observed gap for a scan at a certain diameter is not within the tolerance, an error message will be produced and data collection stops. Under normal conditions, the GAP keyword should be left out or the tolerance set to large values, e.g. 99999. This feature only is available from mar345 versions >= 2.0.
Default: GAPS 89600 78600 63900 49100 TOLERANCE 99999

WINDOW MAIN <x> <y> VIEW <x> <y> [<width> <height>]
This determines the geometry of the windows (mar345 Main and View window) at startup. Defaults should be okay, but depending on the settings for the window manager, you may want to change the x,y coordinates of the windows to give reasonable window locations. The size (width and height) of the main window is fixed, but for the "View"-window the size may be changed. Default size is: full screen.
Defaults: WINDOW MAIN 1115 38 VIEW 0 38 1095 954 (SGI)
Defaults: WINDOW MAIN 1110 0 VIEW 1 0 1095 954 (DEC Unix)
Defaults: WINDOW MAIN 1120 0 VIEW 1 0 1095 954 (Linux)

SCALE <s> or <filename>
Apply a scale factor <s> to all pixels in image on output or read scaling instructions from <filename>. By default, the program looks for existence of $MARTABLEDIR/scale.$MAR_SCANNER_NO. If the file does not exist and no keyword SCALE is given here, no scale factors will be applied.

STATUS <interval>
This option will write out the most relevant scanner status information into a file assigned by environment variable $MARSTATUSFILE. If this variable is not given, the filename will be $MARLOGDIR/mar345.status. <interval> is the frequency of update and must be given in milliseconds. A reasonable value is 2000. Values less than 250 milliseconds are reset to 250. If this keyword is missing or <interval> equals to 0, no status output will be generated (default).
Default: STATUS 0

COMMAND <interval>
This option will start a timer that looks for file $MARCOMMANDFILE which defaults to $MARLOGDIR/mar.com. MARCOMMANDFILE is a keyworded ASCII-file that may be used to feed-in commands from an external program. Simple commands (e.g. erase, open shutter, move phi, etc.) as well as entire data collections can be started this way. After evaluating MARCOMMANDFILE, the file is deleted. If a certain task or procedure is active, only commands ABORT or STOP will be accepted. All other commands will be executed after the current procedure has finished. <interval> is the frequency for looking for new MARCOMMANDFILEs and must be given in milliseconds. A reasonable value is 1000 to 2000. Values less than 250 milliseconds are reset to 250. If this keyword is missing or <interval> equals to 0, the timer will not will be started and MARCOMMANDFILE will be ignored. This is the default.
Default: COMMAND 0

SERVER PORT <port_number> WRITE <n> INTERVAL <interval>

Program mar345 (>= 5.5) and scan345 (>= 5.0) feature a TCP/IP-server that listens on for commands send via a TCP/IP-socket. The <port_number> specifies the port number to listen to. The value given in the configuration may be overridden by an optional command line argument (-s <port_number>). The option "WRITE n" is optional and is going to dump the information that would go into file mar.message (see above) as output on the TCP/IP-socket every "n" seconds. The default is n=0, i.e. no message output will be generated on the TCP/IP-socket. The <interval> on the optional INTERVAL keyword is equivalent to the keyword "COMMAND <interval>" (see above). I.e. when the programs run in TCP/IP-server-mode they will always also accept input via the ASCII-file set by MARCOMMANDFILE.
Default: SERVER PORT 0 (i.e. no TCP/IP-server port opened)

SETS <no. of programmable data sets>
This applies for "Multiple runs"-only. By default, 4 data collection runs can be programmed with independent parameters. An extended version allows for 8 programmable sets. Versions >= 2.0 allow for up to 64 sets.
Default: SETS 4

UNITS TIME <time_units> DOSE <dose_units>
<time_units> gives the number of milliseconds per time unit. <dose_units> gives the measured frequency per dose unit.
Default: UNITS TIME 1000 DOSE 1000

WAVELENGTH <lambda> or VARIABLE
<lambda> gives the used wavelength in Angstroem. When choosing VARIABLE, the interface provides a field for entering the wavelength that is currently in used. This value goes into image headers. Hence, it is strongly recommended to always supply the correct values!
Default WAVELENGTH 1.54178 (Cu-Kalpha)

COLLIMATOR WIDTH <width> HEIGHT <height>
<width> and <height> gives the aperture of the used collimator in mm. The values can be modified in the user interface (X-ray Setup). They only describe the experiment and will be written into image headers.
Default: COLLIMATOR WIDTH 0.3 HEIGHT 0.3

MONOCHROMATOR <type> POLARIZATION <polar>
<type> can be MIRRORS, SYNCHROTRON, GRAPHITE or alike. <polar> will give the polarization of the beam. The values can be modified in the user interface (X-ray Setup). They only describe the experiment and will be written into image headers.
Default: MONOCHROMATOR MIRRORS POLARIZATION 0.0

GENERATOR <type> KV <kv> MA <ma>
<type> can be SEALED TUBE, ROTATING ANODE, SYNCHTROTRON or alike. <kv> gives the kiloVolt setting, <ma> the milliAmpere setting. The values can be modified in the user interface (X-ray Setup). They only describe the experiment and will be written into image headers.
Default: GENERATOR ROTATING ANODE kV 50 MA 100

GAIN [150u] <gain_150u> [[100u] <gain_100u>]
<gain_150u> gives the ADC gain factor for scans in 150 micron mode, <gain_100u> gives the ADC gain factor for scans in 100 micron mode. Gain factors are calibrated with a flat X-ray field and should be close to 1.0 for <gain_100u> and 0.66 for <gain_150u>. If only one value is given on GAIN keyword, the same gain is used for both scan modes (which is not appropriate!). The values go into image headers but are useful only for data processing software like MOSFLM and DENZO. The full implementation of this feature has been done only in mar345 version >= 2.3.3
Default: GAIN 100u 1.000 150u 0.660

DATA_INTERVAL <t1> <t2> <t3>
These values are very ciritical program parameters concerning timing of data transfer across the network during scan. <t1> is the timeout in milliseconds to wait for new data to come in before looking again on the network socket after a block of data has been successfully transformed, <t2> is the time to wait in the case <t1> is a timeout after a block of data has been received and transformed before looking for more incoming data. <t2> is a timeout that occurs if a previous call with a timeout of <t1> has not been successful. <t3> is another timeout that happens only at the end of a scan if there are still some data missing. Most relevant is <t1>. However, these parameters are considered strictly internal and modification will have serious consequences on overall program preformance.
Default: DATA_INTERVAL 2 10 10

FLAG <value>
This keyword may be used for finding hardware problems during a scan. <value> is an integer value with the following hex codes:
0 -> normal scan
1 -> scan with laser turned OFF
2 -> scan with high voltage turned OFF
4 -> scan with erase lamps turned OFF
8 -> scan with rotation encoder index line turned ON
16 -> scan without data transfer
32 -> scan with ADC offset set to input values
64 -> scan with profile skipped
128 -> scan with debug protocol turned ON
256 -> scan with ADC adjustment turned off
The numbers can be combined, e.g. FLAG 3 would be a scan with high voltage and laser turned OFF.
These flags are only valid for mar345 versions >= 1.0. For version < 1.0, the only accepted flag is 1 to turn the rotation encoder index line ON (corresponding to FLAG 8 in the newer versions).
Default: FLAG 0

SHUTTER_DELAY <time>
This keyword is used by mar345 versions > 1.0 only. <time> is the time it takes (in milliseconds) to actually close the shutter once the controller has accpeted the command. The controller measures the time automatically (typically 10-20 msec) every time the shutter is closed. This delay adds to the actual exposure time introducing a small error. To compensate for this error, a shutter delay time entered here will cause the shutter to be closed by <time> milliseconds earlier. This procedure is not essential and may play a role only with very short exposure times (<5 sec or so).
Default: SHUTTER_DELAY 0

FURNACE UPDATE <sec> TIMEOUT <sec> STABILIZE <n> DEVICE <name>
This keyword works with a special compilation of mar345 version >= 2.5 only. It controls setting for operating a high temperature furnace controlled by an EUROTHERM temperature controller together with the mar345.
UPDATE gives the rate of temperature readings in seconds. This update rate is only used while the controller is NOT driving to a new target temperature. For this case, the update rates are increased automatically to 1 sec. Note, that there is a significant dead time of >= 1 sec. while the temperature enquiry is being done. That’s why the update rate should be set to relatively large values. Note also, that an UPDATE rate of 0 turns off completely usage and initialization of the temperature controller. This is useful when doing data collections without temperature control. Instead of modifying the keyword value for USAGE in the configuration file one may also provide the command line argument -furnace <sec>. The value on the command line overrides the entry in the configuration file!
TIMEOUT specifies the amount of seconds to elapse before a data collection gives up when it cannot reach the target temperature.
STABILIZE gives the required amount of consecutive temperature readings matching the condition: current temperature = target temperature +/- allowed deviation. I.e. the target temperature needs to be stable before it is accepted. Note that very small allowed deviations may cause the target temperature not be reached at all. The value range of <n> should be inbetween 1 and 10.
DEVICE specifies the name of the device to open. On Linux, this should be serial port /dev/ttyS0.
Default: FURNACE UPDATE 0 TIMEOUT 3600 STABILIZE 5 DEVICE /dev/ttyS0

See Also

mar345

Author

Claudio Klein, marXperts GmbH, Norderstedt, Germany

Copyright

© Copyright 2000-2017 marXperts GmbH, Norderstedt, Germany

Address

marXperts GmbHPhone: +49 - (40) - 529 884-0
Werkstr. 3 FAX: +49 - (40) - 529 884-20
D-22844 Norderstedt - GERMANYinfo@marXperts.com
www.marXperts.com


Table of Contents