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> 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 only)
Defaults:
MODE 2300 TIME 80 ROFF 0
MODE 2000 TIME 66 ROFF 0 ADC 10 AADD 0
BADD 0
MODE 1600 TIME 48 ROFF 0 ADC 10 AADD 0
BADD 0
MODE 1200 TIME 34 ROFF 0 ADC 10 AADD 0
BADD 0
MODE 3450 TIME 108 ROFF 0 ADC 10 AADD 0
BADD 0
MODE 3000 TIME 87 ROFF 0 ADC 10 AADD 0
BADD 0
MODE 2400 TIME 62 ROFF 0 ADC 10 AADD 0
BADD 0
MODE 1800 TIME 42 ROFF 0 ADC 10 AADD 0
BADD 0
PHI SPEED <speed> STEPS <steps_deg> 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. <def> is the default value to
be used.
Default: PHI SPEED 2000 STEPS 500 DEFAULT 0.0
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.
Default: OMEGA SPEED 2000 STEPS 500 MIN -90.0 MAX 90.00 DEFAULT 0.0
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
<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>
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 INCR STATS Z-AXIS SHELL WAVE ADC SPY HTML
SUMMARY QUEUE LASER
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). 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" 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) 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
The meanings are opposite to the USE flags given above.
Default: IGNORE OMEGA CHI THETA IMAGE SPIRAL SPK INCR STATS Z-AXIS SHELL
WAVE ADC LASER
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
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)
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)
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
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