ADX Options

Customization of ADX Data Collection

There are several ways of controlling the operation of the ADX data collection software:

Startup scripts

"start_ccd" scripts for ADX start up several programs on the data collection computer (which may be the station computer).

Always started:

  ccd_dc_api (main scheduler)
  ccd_status (maintains status file)
  adx_ccd_control (graphical interface)

Additional programs vary according to cases:

One Q4 detector, no MAD, use CompuMotor (some F1 users, F3):
  Note: use "start_ccdb" to start "B" CCD.

  ccd_bl_cm (communication with CompuMotor)
  ccd_xform (image correction)

Two Q4 detectors, no MAD, use CompuMotor (dual-CCD users):
  Note: script is called "start_ccdab".

  ccd_bl_cm (communication with CompuMotor)
  ccd_xform for CCD A (image correction)
  ccd_xform for CCD B (image correction)

One Q210 or Q270 detector, use CompuMotor (A1, F1, F2):

  ccd_bl_cm (communication with CompuMotor)
  det_api_workstation (send commands to PC in hutch)
  ccd_image_gather (receive image from PC in hutch)

One Q1 or Q4 detector, no MAD, do not use CompuMotor (G1):

  ccd_xform (image correction)

"start_rspec" scripts start up programs on the station computer.

Always started:

  rspec (communication between spec and other programs)
  quicktalk (runs in OpsTerm window, for user-spec I/O)
  spec, or oscam (hardware control)

Additional programs may be started:

Motor and shutter control use CompuMotor, no MAD, std crystallogr. (A1, F1, F3):

  CCDspec (GUI for table-alignment, etc)

Motor and shutter control use CompuMotor, MAD (F2):

  CCDspec (GUI for table-alignment, etc)
  ccd_bl_station (wavelength control)

Motor and shutter control use CompuMotor, reference-beam diffraction (F3):

  CCDspec (GUI for table-alignment, etc)
  ccd_bl_station (omega motor control)

Motor and shutter control use spec (G1):

  ccd_bl_station (motor and shutter control)

"start_ccd_plus" scripts consist of the "start_ccd" commands, followed by startup of rspec, followed by startup of the crystal-centering software.

The crystal-centering software consists of a server ("~specuser/CrystalCentering/center_server") running on the computer in the hutch, e.g. a1-vid, and a client ("~specuser/CrystalCentering/center_client") running on the computer whose name is given in CCD_CEHOSTNAME (can be the station computer or the data collection computer). Connection to ADX for motor control is made by the server. Both client and server display the video image and have active controls.

Command-line arguments

Command-line options for ADX programs include:

adx_ccd_control (graphical interface):

  -define_distance      Distance is not motorized, but may be defined (so as
                        to get into the header. This is always set at CHESS.

ccd_bl_cm (CompuMotor or other motor/shutter control communication):

  -uniblitz             Use Uniblitz shutter controller instead of CompuMotor.

ccd_bl_station (Communication to spec, via rspec):

  -s                    Shutter and spindle control are through spec instead
                        of CompuMotor. Implies that ccd_bl_station connects
                        with ccd_dc_api directly instead of with ccd_bl_cm.

ccd_xform (transformation of images, for Q1 or Q4):

  -td directory_name    Location of calibration files. Replaces directory given
                        by TABLES_HOME environment variable.
  -d A/B                Select A or B CCD of dual_CCD detector. Affects name
                        given to output file, inserting "A" or "B" after the
                        prefix.

adxv (display program):

  -autoload             Automatically load the image given by the name in the
                        current-image file, which is given by the environment
                        variable XFORMSTATUSFILE. When a new name is written
                        to the file, display a new image.
  -beam_center # #      Use the specified coordinates (in adxv mm.) for the 
                        direct beam position.
  -rotate #             Rotate the image display by the given angle, which must
                        be a multiple of 90. Used to display images from the
                        upside-down CCD in the dual-CCD detector.

  There are additional options; type "adxv -help" to get a list.

Configuration file

The ccd_config file, usually in ~/adsc, contains information about the configuration of the detector and data collection hardware. The meaning of entries that you may have to change is given here. Others are "boilerplate" and will not need modification (some are not even used). Lines beginning with # are comments and are ignored. Text following ! is explanatory and not found in the actual ccd_config file.

                   ! Information about the CCD detector
detector_sn #          ! Serial number
pixel_size #           ! Size of a pixel, in mm.
pixelsx #              ! Number of pixels in the X (horizontal) direction. For
                       ! Q4, this is the size of the whole image. For Q210, it
                       ! is the size of a single module.
pixelsy #              ! Number of pixels in the Y (vertical) direction
chip_size_x #          ! Number of pixels in the X direction on a single module
                       ! (not used for Q1 or Q4 detector)
chip_size_y #          ! Number of pixels in the Y direction on a single module
modular 0/1            ! 0 for Q1 or Q4, 1 for Q210
preferSWbin 0/1        ! default for binning, 0/1 for hardware/software binning

                   ! Default information about image transform process, most
                       ! may be changed through GUI.
darkinterval #         ! Interval between dark images, in seconds
dk_before_run 0/1      ! No/yes take new dark-current for each new run
repeat_dark 0/1        ! No/yes take a new dark-current every darkinterval secs
dezinger 0/1           ! No/yes dezinger images.
output_raws 0/1        ! No/yes save raw (uncorrected) images.
no_transform 0/1       ! Yes/no apply corrections, i.e. transform images
max_remark_chars #     ! Max characters allowed in the Comments fielda

                   ! Default camera information
wavelength #           ! Wavelength, in Angstroms
distmax #              ! Max. allowed distance, in units of 0.01 mm.
distmin #              ! Min. allowed distance, in units of 0.01 mm.
motor_type DC/stepper/NONE  
                       ! Type of motor running the phi rotation. If not using
                       ! CompuMotor for motor control, has no effect.

                   ! Delays to be sure events are properly sequenced
shutter_open_wait #    ! Time to wait for CCD to initialize before opening
                       ! shutter, in msecs
shutter_close_wait #   ! Time to wait for shutter to close before starting CCD
                       ! readout, in msecs

                   ! Control of which motors, etc. are to be active
usedistance 0/1        ! No/yes distance is motorized and can be controlled
usephi 0/1             ! No/yes phi (spindle) rotation is to be controlled
use2theta 0/1          ! No/yes 2-theta rotation (of the detector, usually)
                       ! is to be controlled
uselift 0/1            ! Same as use2theta
usekappa 0/1           ! No/yes kappa motor is to be controlled
useomega 0/1           ! No/yes omega motor is to be controlled. This is used
                       ! in reference beam diffraction experiments - see
                       ! ccd_auxfile information.
usegoniostat 0/1       ! No/yes goniostat has a HOME function, and can be set
                       ! to manual or computer-controlled mode
useautomount 0/1       ! No/yes automounter is to be controlled
automount_table #      ! Entries in automounter table, which will follow. Omit
                       ! if no automounter
-19200 -2100           ! Sample entries in automounter table. These tell the
-16450 -7850           ! software where the pins in each puck are located.
    .
    .
    .
usewavelength 0/1      ! No/yes wavelength can be controlled from GUI, via
                       ! ccd_bl_station, rspec, and spec
usethresh 0/1          ! No/yes shutter will be controlled through spec (as
                       ! opposed to CompuMotor or Uniblitz)

                   ! Options allowed for output image format
allowbinned 0/1        ! No/Yes allow 2x2 binning of output
allow32bit 0/1         ! No/Yes allow output as 4-byte integers rather than 
                       ! 2-byte unsigned integers

Examples of the "use" settings for different scenarios:

Data collection computer different from station computer, CompuMotor used,
no MAD, standard crystallography (A1, F1):

               Data collection computer         Station computer
usephi                  1                             N/A
usewavelength           0                             N/A
usethresh               0                             N/A
useomega                0                             N/A
motor_type              DC                            N/A

Data collection computer different from station computer, CompuMotor used,
MAD possible, standard crystallography (F2):

               Data collection computer         Station computer
usephi                  1                              0
usewavelength           1                              1
usethresh               0                              0
useomega                0                              0
motor_type              DC                           NONE

Data collection computer same as station computer, CompuMotor used, no MAD (F3):

                  Station computer
usephi                  1
usewavelength           0
usethresh               0
useomega              0 or 1, for standard or refernce beam crystallography
motor_type           DC or stepper, depending on motor in use

Data collection computer same as station computer, spec possibly used, no 
MAD (G1):

                  Station computer
usephi                0 or 1, depending on whether sample needs to rotate
usewavelength           0
usethresh             0 or 1, depending on whether spec "opens", "closes"
                              commands are available for shutter control and
                              pseudomotor "thresh" is defined (by spec)
useomega                0
motor_type             NONE

Auxiliary file for special cases

The "ccd_auxfile" file, located in ~/adsc, is used to specify options for non-standard data collection. A sample file looks like:

ccd_dc loop omega from -1.360 to -1.312 by 0.003
ccd_dc delay 60
ccd_dc after mymacro+1
ccd_bl_cm delay 10
ccd_bl_cm after mymacro+2
ccd_bl_cm count off
ccd_bl_cm CM_count off
ccd_dc monitor 93.20 95.75 0.05
end

The available options are:

ccd_dc loop omega from # to # by #: For each phi value, collect a set of images at different values of angle omega, which is controlled by spec (phi is controlled by Compumotor or spec). Omega values are incorporated in image file names. For reference-beam experiments.
ccd_dc delay #: Wait # seconds after each exposure before starting the next.
ccd_dc after macro: After each exposure, send the given macro to spec and wait for it to finish. + signs in macro are converted to spaces in string sent to spec.
ccd_bl_cm delay #: Wait # seconds after closing the shutter before reading out the detector.
ccd_dc after macro: After closing the shutter, but before reading out the detector, send the given macro to spec and wait for it to finish. If macro contains + signs, replace them with spaces.
ccd_bl_cm count off/on: Send spec command "ctfile #" before starting exposure, where # is the exposure time. When exposure finishes, record counts (written by spec to file "filect") in a file image_file.counts, where image_file.img is the image file being generated.
ccd_bl_cm CM_count off/on: After exposure, send "vme_counter name" to spec, where name is the name of the image file being generated. This will stop a counter started by Compumotor and write the counts to a file.
ccd_dc monitor # # #: After exposure, check sum of pixel values in a 3x3 square centered on the coordinates given by the first two numbers (in adxv mm.). If not the first image and sum has changed by more than the fraction given by the third number, halt collection with an error message.