mar345_248x110
Edited on 07-Feb-2017

2. Program mar345




2.1 Basic Concepts

The program has to perform several tasks:

User input is done via the user interface using text fields, option menues and arrow buttons.

The mar345-detector is driven by an autonomous mini-computer which communicates with the host computer through an Ethernet interface. It features a real-time operating system which provides the well known IP services (ftp, telnet, ping, Unix sockets). It comes with a fixed IP-address of 192.0.2.1 for the mar345-detector and requires the network card of the host computer to be set to address 192.0.2.2. Program mar345 talks to the scanner using standard Unix sockets on ports 4441, 4442, 4443 and 4444. Please verify, that a computer can successfully "ping" to IP-address 192.0.2.1 (i.e. the mar345 detector), otherwise program mar345 cannot control the detector. When connecting the detector directly to the host computer, a "cross-over" network cable with RJ45-connectors is MANDATORY. When using standard network cables (i.e. with 1:1 wiring), a hub or network switch must be placed inbetween the computer and the detector.

Transformation and data display requires memory as well as CPU-time. Typically, the program mar345 keeps the equivalent of 2.5 images in memory. When using images with 3450*3450 pixels, this corresponds to 75 MB. A minimum of 128 MB is therefore recommended for a host computer driving the detector, but 256 MB are actually more appropriate.

Data collection should always have highest priority. However, there is little protection against abuse of the host computer's resources by other processes. In particular, memory consuming data processing jobs can cause drops in performance of the workstation to such a degree that nothing else will work. I/O-operations can be even more critical. This affects network I/O, in particular.

Note: it is not advisable to write data out to an NFS-mounted disk since any problem on the network will affect data collection .



2.2 Environment

The program relies on a couple of predefined environment variables. The environment should best be defined within the shell startup scripts, i.e. files $HOME/.cshrc (C-shell) or $HOME/.tcshrc (TC-shell) or $HOME/.bashrc (Bourne-shell) using the corresponding syntax. The mar345dtb software distribution guide gives more details about how the mar software is organized. The official mar345 software distributions assumes that the default user's shell is (t)csh. Please note, that Linux's and Mac's default shell are bash! The following environment variables need to be declared:

Table 1: Environment variables

Variable Default value Description
MARHOME $HOME Root directory for mar software distribution
MARTABLEDIR $MARHOME/tables Location of calibration and configuration files
MAR_SCANNER_NO 000 Three digits serial number for mar345 scanner
MARLOGDIR $MARHOME/log Location of all log-output files and of data input files.
The program mar345 expects to find subdirectories beam, log, lp, spy and sets.
Very important: this directory must have write permission for the mar345 user!
MARMANDIR or
MARDOCDIR or
MARHELPDIR
$MARHOME/man/ Location of this documentation files. This should be the parent tree with subdirectories 1, pdf, html, help and mar345.
MARSTATUSFILE $MARHOME/log/mar345.status Periodically written output file containing hardware status bits. See section Output for further details.
MARMESSAGEFILE $MARHOME/log/mar.message Periodically written output file containing software messages. See section Output for further details.

The choice on how to set the environment variables depends on local usage and personal preference. In particular, you will have to decide wether you want to install the software in a location with general read access and no write access. Thus, the software may be installed e.g. in /usr/local/mar with subdirectories tables, doc, man, bin and log. It is essential that the user has permission to write into $MARLOGDIR and the following directories thereof:



2.3 Command Line Options

mar345 can be invoked in a terminal window plainly by typing "mar345". The program however understands the command line options given in Table 2. Do not run the program in the background and do not use this terminal window for other purposes. The program will send important output to the standard output and you don't want to miss it, although almost all output can also be found in the log file.

At startup, the program will tell you something like:


mar345: Version 5.4 (May 30 2011) by marxperts ...
mar345: Connected to host '192.0.2.1' on port 4441 (COMM)
mar345: Connected to host '192.0.2.1' on port 4442 (STAT)
mar345: Connected to host '192.0.2.1' on port 4443 (DATA)
mar345: Connected to host '192.0.2.1' on port 4441

=======================================================================
            Program     :  mar345
            Version     :  5.4  (May 30 2011)
            Scanner no. :  027
            Scanner mode:  345 mm @ 0.15 mm
            Started on  :  Thu Dec 22 10:35:01 2011
            LOG  file is:  /home/cla/log/log/mar.log.88
            STAT file is:  /home/cla/log/lp/mar.lp.88
=======================================================================



The program will also tell you if it is able to talk to the detector. If environment variables are not set you will be notified.

At startup, the program writes information about connection success or failure into file $MARLOGDIR/mar.message. This message is read and displayed by program marstart which is called automatically by program mar345. If the program cannot connect to the detector, the program mar345 will be halted. Program marstart then offers a choice of either killing process mar345 or continuing with program mar345 without network connection.

Note that it takes approx. 1 minute after turning on the mar345-detector before program mar345 can talk to them, even if the ping service is available within a couple of seconds time.

After the initializations, the program presents essentially two windows: an image display area and the mar345 main window with status information and further input buttons.

Table 2: Command line options for mar345

Name Alternative Arguments Example Description
  -host <string>   -host 192.0.2.1 Host name to use for the mar345 detector.
-p --port <number> -p 4441 Socket port to use for the mar345 detector
 
-c -colors <number> -c 32 No. of colors to use for image display.
  --default <number> --def 2300 Default scan mode to use (one of 3450,3000,2400,2300,2000,1800,1600 or 1200).
-d -debug <number> -debug 16 Debugging flag (undocumented).
-h -help     Print usage summary
  -hw     Run program without connecting to the mar345 detector
-k -keep     Keep raw spiral images on output of transformed image
-m -more <number> -more 3 Explicite erbosity level
  -nofull     Use smaller image display size
  -noinit     Skip initialization (selftest) of detector
  -noxf     Do not transform raw spiral images to Cartesian coordinates
  -setd     Allow to redefine DISTANCE from GUI
-s --server <number> -s 8888 TCP/IP-server port to listen for commands to drive the program mar345.
-v -verbose     Increase printed output. No arguments.



2.4 User Interface

Main Window

The user interface features 2 major windows:



2.4.1 "Main" Window

The main window controls all detector and goniostat functions. If the first place it consists of two areas:


2.4.1.1 Menu Bar

The menu bar allows for opening additional windows. Most of them can be opened either by selecting the corresponding choice with the mouse button or by pressing the corresponding short-cut key. Some of the windows can also be opened by pressing the status buttons or control buttons (see below).

2.4.1.1.1 Windows Menu

The Window menu pops up if the "Windows" button in the menu bar is pressed or if "Alt+w" is pressed while the pointer is in the main window. Most of the choices in the menu will allow to navigate from page to page in order to access specific functions:

Table 3: The "File" menu

Menu Menu Choice Shortcut Description
Windows Menu Image F1 Pops up the image display window
Progress F3 Pops up the progress window
X-ray Setup F3 Pops up the X-ray Setup window
Shutter Timer F4 Pops up the Shutter Timer window
Log-file F5 Pops up the log file window
Hardware Status F6 Pops up the Hardware Status window
Error Window F7 Pops up the Error window
Move Distance F8 Pops up the Move Distance window
Move PHI F9 Pops up the Move PHI window
Reset Scanner Ctrl+r Sends a reboot instruction to the mar345 scanner.
Quit Ctrl+q Leave program mar345

2.4.1.1.2 Help Menu

The Help menu pops up if the "Help" button in the menu bar is pressed or if "Alt+h" is pressed while the pointer is in the main window.

Table 4: The "Help" menu

Menu Menu Choice Description
Help Menu Documentation (html) Calls the WWW-browser and loads file $MARMANDIR/mar345/index.html
Online help Pops up a window with the possibility to get some basic online as read from file $MARMANDIR/help/mar345.hlp.
About Shows current program version





2.4.1.2 Status

The status area provides information about the current detector activities at all times, i.e. current motor positions, the shutter state, X-ray intensity readings, etc. It features text fields and push buttons which will dynaically change. Most of the status buttons have double functionality: they display current status (e.g. motor positions) and they can be pushed to pop up additional windows:

Table 5: The "Status"-buttons

  Button Action when pressed Description
Status Buttons marxperts none Shows ending time during data collection
Mon 15:30 none Current computer time
Scanner is IDLE none Current dtb or detector action (progress bar)
Shutter CLOSED none Shows current state of experimental beam shutter.
Image Name none Displays current image name during data collection
Scanmode none Displays current scan mode of mar345-detector
Distance Pops up the "Move Distance"-window Displays current distance detector to crystal
Phi Pops up the "Move Phi"-window Displays current PHI position
Intensity none Displays current reading of selected ionization chamber
Free Disk Space none Displays remaining disk space in current data directory
Collect Replaces the buttons "Scan, Erase, Initialize, Open Shutter" with a choice of different data collection options (see below)  
Scan Pops up the "Scan"-window  
Erase Immediately starts to erase the imaging plate in the currently selected scanmode.  
Initialize Pops up the "Initialize"-window  
Open Shutter Opens (or closes the local X-ray beam shutter  

The data collection menu and the way to set up different types of data collections is described in the separate chapter "Collect".



2.4.2 Image

The "Image"-window can be accessed by selecting the corresponding choice in the "Windows"-menu or by pressing the "F1"-key while the pointer is in the main window. This window is the area where to visually inspect images. The separate chapter "Image" describes the functionality of this window.


2.4.3 Progress


Progress Window

The "Progress"-window can be accessed by selecting the corresponding choice in the "File"-menu or by pressing the "F2"-key while the pointer is in the main window.

Here, you see the most important parameters of ongoing or programmed data collection runs.

The data set that is currently active is marked in "mar" red and white fonts, the queued ones are shown with a lighter background. The ones that are already finished are drawn with a grey background. In this window you will also find the time the data collection needs to complete and the actual ending time.

Table 6a: The columns in the 'Params' section of "Progress"-window

Name Description
Set Data set as programmed in the "Change Parameters" window.
Status Either "Active", "Queued" or "Done"
Images No. of remaining images out of total no. of images in this set
Time Exposure time in seconds. When working in DOSE mode, the time will be only approximated.
Distance The distance detector-to-sample in mm.
Phi The Phi at start of the current image in deg.
Delta-Phi The no. of oscillations * Delta-Phi in deg.
Format & Scanmode The shown string is the actual image name extension and corresponds to the choices for "Format" and "Scanmode" in the "Change Parameters"-window.
To go Time in hrs to terminate this set.
Ending at Time when this data set completes.
Image Full path name of current image (or first image in set).
The buttons in the lower part of the window are mostly self-explanatory. Some of the buttons will be made insensitive during certain operations. For instance, during a readout of the detector, the "Abort NOW"-button is disabled.

Table 6b: The buttons in the "Progress"-window

Name Description
Abort NOW Immediately abort the exposure or any motor movement.
Stop after IMAGE Stop data collection of all data sets after finishing exposure and readout of current image.
Stop after SET Stop data collection of all queued data sets after finishing the current set.
Close Closes this window. Get this window back with the "F2"-key.


2.4.4 X-ray Setup


X-ray Setup Window

The "X-ray Setup"-window can be accessed by selecting the corresponding choice in the "Windows"-menu of the main window.

Here, you can provide some information that is going to end up in the headers of images created by the mar345-detector. This information is strictly optional and there are no programs that are systematically making use of it. It would be good practice, though, to fill in the fields. A general experience is, that when working with images later you will have trouble to find notes written in a logbook, but it is straightforward to just look into the image header (e.g. with program catmar).


2.4.5 Shutter Timer


Shutter Timer Window

The "Shutter Timer"-window can be accessed by selecting the corresponding choice in the "Windows"-menu or by pressing the "F4"-key while the pointer is in the main window, or by selecting the corresponding tab in the main window.

Here, you may manually open the experimental beam shutter of the dtb without having to setup an exposure. It should be noted that for normal users there is little need to do so. When opening the shutter, there will be a clock showing the time elapsed since opening the shutter. The shutter will automatically closed after the time given in the "Close in [sec]" text field has elapsed .


2.4.6 Log


Log Window

The "Log"-window can be accessed by selecting the corresponding choice in the "Windows"-menu or by pressing the "F5"-key while the pointer is in the main window, or by selecting the corresponding tab in the main window. All hardware errors and warning as well as some additional information may be written inside the text area of this window.

In case of hardware problems, first have a look inside this window to get some history of the problem.


2.4.7 Hardware Status


Hardware

The "Hardware"-window can be accessed by selecting the corresponding choice in the "Windows"-menu or by pressing the "F6"-key while the pointer is in the main window.

Here, you can look at certain hardware bits in detail. The information presented here reflects the contents of the status block that is periodically sent by the mar345-controller to the computer. The entries should be self-explanatory. Watch the bits as they change state during a scan...


2.4.8 Error window


Error

The "Error"-window can be accessed by selecting the corresponding choice in the "Windows"-menu or by pressing the "F7"-key while the pointer is in the main window.

Here is where you will find important error messages and warnings.


2.4.9 Move Distance


Move Distance Window

The "Move Distance"-window can be accessed by selecting the corresponding choice in the "Windows"-menu or by pressing the "F8"-key while the pointer is in the main window or by pressing any of the distance status button in the status area.

Within this window, you can move the motor for the detector distance translation in the standard mar goniostat. You may also redefine the currently know position of the motor but only if the program "mar345" has been started with the command line argument "-setd". This is a protection for not accidentally overwrite an well determined parameter. Please note, that the scanner controller always keeps the currently known values. Unless the detector is physically removed from the translation page, there should be no need to redefine this value. In case of doubt, it is suggested to "initialize" the distance translation stage with a premeasured value taken from the scanner configuration file.


2.4.10 Move Phi


Move Phi Window

The "Move Phi"-window can be accessed by selecting the corresponding choice in the "Windows"-menu or by pressing the "F9"-key while the pointer is in the main window or by pressing any of the PHI status button in the status area.

Within this window, you can move the motor for the PHI axis in the standard mar goniostat. You may also redefine the currently know position of the motor.


2.4.11 Initialize


Initialize

The "Initialize"-window can be accessed by selecting the corresponding button in the main window. Here, you initialize the motor for the distance translation stage of the standard mar goniostat (see also chapter "Move Distance"). You may initialize the motor either at the far end (away from the sample) or at the near end (close to the sample). It should be noted that it is definitely safer to initialize the motor at the far end of the translation stage in order to avoid collisions with the goniometer head and/or or cryo-head.

Also, when pushing the Initialize-button the program reloads the configuration file $MARTABLEDIR/config.$MAR_SCANNER_NO. If you want to do some changes to the configuration file and try the parameters on-the-fly, this is the way to do it. Please note, that parameters that affect the graphical layout of the program usually require a restart of the program. For details about the configuration file, see chapter Configuration File in section Input.


2.4.12 Scan


Scan Window

The "Scan"-window can be accessed by selecting the corresponding button in the "Status"-area of the main window. Here, you may select a directory, image name, image number and scanmode and choose an action. You may:


This feature is not used very often unless for very special experiments. This is why this window is accessible only via one button. For producing an output file, there is no choice of format. Images will always be produced in the mar345-format that is described elsewhere. The output file name follows the same rule as described in the chapter about data collection.

With keyword "USE REFERENCE" in the configuration file, an additional field for "Reference image" is available starting with version 6.6 of the program. Here, you can enter the full name of a reference image. Please refer to the chapter 4.2.1 Directory, Image Root and Reference Image for further details.