Table of Contents
mar345_config_file - description of the scanner specific configuration file
for program mar345 (345 mm scanners)
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)
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
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
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
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
- 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
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
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
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
- 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
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
- <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>
name for internet browser to display html documentation. Introduced in version
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.
- 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: 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
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
- <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
Default: MONOCHROMATOR MIRRORS POLARIZATION 0.0
- GENERATOR <type> KV <kv> 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_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
- 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
Claudio Klein, marXperts GmbH, Norderstedt, Germany
© Copyright 2000-2017 marXperts GmbH, Norderstedt, Germany
|marXperts GmbH||Phone: +49 - (40) - 529 884-0|
|Werkstr. 3|| FAX: +49 - (40) - 529 884-20|
Norderstedt - GERMANY||info@marXperts.com|
Table of Contents