CBASS - BNL's Beamline and Experiment Control System
To use the CBASS popup applet click here. A new window will open.
- Display Overview
- Menu Options
- Friedel Flip
- PXRR Database and Sweep Tool
- HTML Log
- Command Line
- Implementation Details
Figure 2.
CBASS Display Overview
The CBASS window has between one and six "pages" that can be selected by clicking on tabs named "Collect", "Setup", "Robot", "Pucks", "Canes" and "Beamline". Figure 2 shows the main window with the six page tabs. Not all tabs appear at each beamline, for example, the "Pucks" and "Robot" pages will be available only on beamlines that have BNL's robotic sample changer.
Group and project identifiers can be selected by pop-up selection boxes by pushing the appropriate buttons next to the command line. This information is used by PXDB. Counter readouts and monochromator wavelength are also displayed in this window pane. The white scrolled window displays output from the command server.
Collect Page
In about the middle of the Collect page on the left hand side, two sets of values are presented for the diffractometer angles (Omega, Kappa, Phi). The first set is the current position, in this case 20.0, 0.0, and 0.0. If you change any of these values, and then push the "Move" button, the axes will move to the new position. The second row of numbers is referred to as the "Relative Zero" or "Datum" position. This is the starting position for the data sweeps defined in the scrolled table at the top. If the "Collect Data" button was pushed in the screen shot above, three sweeps would be performed - one for each row in the data collection table. The first row would result in 10 images of oscillation width 1-degree being taken from Omega = 10 degrees to Omega = 20 degrees. These would be 5 second images resulting in data file names testdata_000.img through testdata_009.img. The following rows would result in similar collections except that the directories "dir1" and "dir2" would be created and the data would be placed there.
One can change the relative zero by changing the textfields and pushing the "Set Relative Zero" button, or you can set the relative zero to the current position by pushing the "Set Relative Zero to Current Position" button.
The "Detector" box at the right allows one to change the crystal-to-detector distance as well as the detector tilt (2-theta). To change one of these, edit the textfield, then push the appropriate button. If the exposure times are greater than one minute, one may need to select "Correct Zingers". For two-minute exposures with this option selected, the software would take two one-minute images and combine them while throwing away outliers caused by things like cosmic rays.
There are two ways to take images. Normal collection, which always forces proper dark image corrections, is started with the "Collect Data" button. Collection proceeds as was described for Figure 2.
Test shots, which take two-second darks in order to save time, can be collected by pushing "Test Shot/Fake Dark". These images are suitable for visual screening. Relative Zero is ignored, and the software will simply take a single image at the current position for the desired frame width and exposure time. If the "Width" field = 0, a "still" image will be taken.
Other buttons below the Diffractometer and Detector frames allow for diffractometer shutter control, homing the diffractometer in case of a power cycle of the instrument, pausing of the data collection, and aborting the data collection.
If the beamline is to be left unattended for a significant period of time, the user can activate the "Pause on Beam Dump" feature. With this enabled, the software will monitor the ring status as provided by the NSLS. When the software detects a beam dump, it will wait for the beam to come back, pause for a beamline-specific period of time, run a beamline-specific beam optimization routine, then resume data collection starting with a retaking of the image that was in progress when the beam dumped.
Automatic MAD
Figure 5. - Automatic MAD
MAD experiments can be programmed to run in an automatic fashion as seen in figure 5. There are four character codes that one can append to the wavelength value to cause the program to take action before taking the data sweep. In the top row of figure 5, ".979P" (P=Peak) will cause the software to scan the monochromator with a midpoint wavelength of .979 using the scanning parameters set in the Beamline page. When the scan is completed, an analysis will run and the monochromator will move to the peak of the scan, then the data sweep will proceed. In the second row, ".979R" (R=Rising edge) will cause it to scan and move to the rising edge before taking the data sweep. "I" for "inflection point" will work the same as "R".".96A" (A=Absolute) will move the wavelength to .96. Data collection will start without performing a monochromator scan.
Figure 3. - Beamline Page
Beamline Page
Basic beamline control, such as monochromator scans and frequently used beamline alignments, are controlled from the "Beamline" page (Figure 3).The intent of this page is to provide an interface to the beamline components and functions used during typical experiments. More complex beamline operations, such as mirror adjustments, which are normally performed by beamline staff are handled with BNL's GrEpx software, which provides full access to beamline motors.
Figure 4. - Table Tweak Box
Pushing the "Count" button will display the counter readings at the collimator, fluorescence detector, and an additional upstream counter. The diffractometer table can be adjusted with a "Tweak Box" (figure 4). Monochromator settings and scan parameters are controlled in the right hand side of the window. Buttons at the bottom of the page allow for beamline-specific realignments, shutter control, and monochromator scan analysis.
Figure 6. - Pucks Page
Pucks Page
The "Pucks" page (Figure 6) is designed to be used with the BNL sample mounting robot. The "Pin" buttons A1-D16 map to the robot dewar which contains four crystal pucks (A-D) that each contain 16 pins. Information describing the contents of each puck and the desired actions on each crystal are loaded into PxDB with a web-based interface (Figure 7). Pushing the "Load Puck Info" button will pop up a selection box that allows the operator to select pucks belonging to the current group. Selecting a puck will fill in the chosen puck position (A-D) with information and parameters found in PxDB. Pushing a pin button will load information into the "Collect" page table (figure 8). When collection is underway on items loaded in this fashion, the robot will mount samples from the appropriate puck/pin positions.
Figure 7 - Puck Description Web page
Figure 8 - Collect loaded from Pucks.
Directories of the form "./[PXID]/[XtalID]/sweep_number/ will be created automatically for the resulting data images to be collected. "Sweep number" is determined by querying PxDB for previous data sweeps performed on the XtalID with the current PXID. If the "Protocol" option menu is set to "Screen", then parameters will use defaults established at the beamline. These can be changed by pushing "Edit Default Screening Params..." (Figure 9).
Figure 9 - Default Screening Parameters
Canes Page
Figure 10. Canes Page
The "Canes" page loads cane information from PXDB in the same way that the "Pucks" screen is populated. Canes are numbered 1-6 starting at the bottom of the cane. Pushing the "Load" button for any sample will load the collect screen using the same file and directory creation protocol as the Pucks page.
Setup Page
Some experimenters liked the automatic directory creating protocol found in the Pucks and Canes pages and requested that a page be constructed where one could take advantage of those protocols to help organize their data that did not correspond to pucks or canes. When "Load" is pushed in the Setup page, it loads the collect page in the same fashion as the load buttons in the Pucks and Canes pages.
Figure 11 - Robot Page
Robot Page
As of this writing, the "Robot" page was set up for simple mounting and unmounting of individual samples. This page is normally used for testing by beamline staff only. The "Pucks" page provides everything necessary to drive the robot during data collection.
Tools Menu
A variety of features can be run from the "Tools" menu on the main menubar.
Project Management
Pushing "Project Management" in the tools menu pops up a web browser that points to BNL's PxDB login screen.
AutoAdxv
This executes ADSC's "ADXV" program with the "autoload" option. In this mode, ADXV will display images as they are collected.
AutoMax
The CBASS "automax" facility can be used to perform automatic beamline alignments during data collection. This tool prompts for the frequency in minutes for which the user would like optimizations to be run. When it is time for automax to perform an optimization, it pauses data collection, runs the beamline-specific realignment, then resumes collection
CrystalView
The "Crystal View" tool utilizes our Axis video server to display a live image of the crystal (Figure 12). On beamlines with the appropriate hardware, this can be used to center the crystal in response to the user clicking on the image.
Figure 12 - Crystal View
Friedel Flip
A Friedel Flip setup dialog provides a convenience for setting up Friedel Flip experiments. Figure 13 shows a request for 180 degrees of data. If one were to push "Setup Sweeps" with a wedge of 20 degrees, the collect screen would be populated as shown in figure 14.
Figure 13. Friedel Flip Setup
Figure 14. Friedel Flip experiment.
PXRR Database
Figure 1 - PXDB Main Menu
The PXDB database system has become an integral part of operations for the PXRR beamlines (X25, X29, X26C, X12B, X12C, X8C). CBASS will interface to this system for retrieving and organizing information concerning your experiment.
The PXDB "Sweeps Tool" (figure 15) is a very useful feature for summarizing beamline activity. It is also the entry point for accessing the HTML log generated by CBASS.
Figure 15 - PXDB Sweep Tool
HTML Log
CBASS generates an HTML log structured as follows: Off the directory from which CBASS is started, an html directory is generated with an "index.html" that is the root of the HTML log. It contains monochromater scan plots and analysis as well as parameters and links to the HTML logs of each sweep. (Figure 16). The data HTML logs (Figure 17) pointed to by the root HTML log contain JPEG images of each data image, periodic pictures of the crystal, and an i0 plot at the end of the run (if i0 is turned on, this is described later). Logging of jpegs for each image can be turned off with the command-line command "html_off".
Figure 16. HTML Log Root
Figure 17 - HTML Data Log
Command Line Commands:
There are a handful of useful commands that can be entered on the command-line of CBASS. Most of these are placed in the $CBASS_SITE_FILE by the beamline administrator to establish default behavior for the beamline:
bin_data - For collecting binned images
unbin_data - For collecting unbinned images
html_on, html_off - turns on and off the HTML logging of image jpegs
set_beamcenter <x coordinate> <y coordinate> - Sets the beamcenter that will be written in the image headers (using Denzo's convention).
i0_on, i0_off - Turns on/off i0 logging. This results in a count being performed for each image. A plot of the results is placed in the data html directory and log for each run (figure 18). A "master" i0 file is generated in the directory from which CBASS was started.
Figure 18 - i0 Plot
Implementation Details - This information is not needed for operation. It's presented here for those who might be interested.
Figure 19 - CBASS System Architecture
System Architecture and Configuration
The software is run under Linux at the NSLS. Since Python code is highly portable, it should be possible to run it under other operating systems as well.
CBASS is set up as a client/server system in which the GUI communicates with the CBASS control server over TCPIP sockets (Figure 19). Multiple clients can communicate with the server. This has been employed at NSLS beamline X25 where a Java applet running on a Windows-based laptop runs as a CBASS client to facilitate in-hutch goniometer control, while the main CBASS GUI runs at the user end-station.
The CBASS server is a multi-threaded program with individual threads responsible for processing commands from clients, sending status information to clients, reading the status of beamline motors that are under EPICS control, and listening for new client connections. One of the strengths of CBASS is that it is a relatively small and readable program consisting of roughly 7K lines of Python code. The server code is broken up in a modular fashion, with separate python modules written for diffractometer, detector, beamline, database, and robot control. This approach simplifies adapting CBASS to different hardware since only small individual modules would need to be coded.
BNL's lower level control is implemented with servers. This was done to isolate modules such as "goniometer_lib" and "detector_lib" from hardware differences. This was beneficial because our older Nonius CAD4 diffractometers and Brandeis detectors could only be controlled by SGI's, while we preferred to run our newer Compumotor-based diffractometers and ADSC detectors under linux. By writing servers with identical communication interfaces the upper level code doesn't have to change if we move or replace hardware. The beamline motors are served through the EPICS Channel Access server. Database access is accomplished by Python's interface to the Postgres database server. We control the sample mounting robot by communicating with a robot hardware server written at the ALS.
Beamline-specific routines, such as those used for automatic beam dump recovery and beam alignments, are found in the "cbass_macros.py" file in the CBASS configuration directory local to each beamline. Beamline staff, or even users depending on file-permissions, can add or modify routines and load them into the running system by typing "reload macros" in the CBASS command line.
The program can be tailored to different configurations through the editing of environment variables set in "cbass_env.txt" in the CBASS configuration directory. As previously mentioned, variables are set to indicate the use of the robot and project tracking database.
Most CBASS defaults can be set in the "cbass.site" file local to each beamline. This command file sets common flags and parameters, such as whether or not images should be binned or counter intensities should be monitored during data collection.