Uppsala Software Factory

Uppsala Software Factory - DCUP Manual

1 DCUP - GENERAL INFORMATION

Program : DCUP
Version : 921217
Author : Gerard J. Kleywegt, Dept. of Cell and Molecular Biology, Uppsala University, Biomedical Centre, Box 590, SE-751 24 Uppsala, SWEDEN
E-mail : gerard@xray.bmc.uu.se
Purpose : data-collection utility program
Package : X-UTIL

2 REFERENCES

Reference(s) for this program:

* 1 * G.J. Kleywegt (1992-1999). Uppsala University, Uppsala, Sweden. Unpublished program.

* 2 * G.J. Kleywegt & T.A. Jones (1999 ?). Chapter 25.2.6. O and associated programs. Int. Tables for Crystallography, Volume F. To be published.

3 INTRODUCTION

This program was written mostly during one long night at the X31 beamline at EMBL/Hamburg while I was watching paint dry, err, my crystal being irradiated, for hours and hours. The idea came from the collection of ten-line Fortran programs at the EMBL/HH for calculating all sorts of handy things while you're setting up or doing data-collection.

DCUP knows of a number of relevant parameters and of some formulas to derive one parameter from a set of others. Parameters can be of four types: some you can only set, some you can only calculate, with some you can do both and with others you can't do either (doctors call these "constants"). In addition, a parameter may be integer or real.

4 STARTUP

Let's have a look at the output when you start the program (this example was run on an SGI, but typically you would run DCUP on a VAX, e.g. in Uppsala on R-AXIS or GRAPH).

All parameters get default values assigned to them and a number of calculable ones are actually calculated. DCUP then shows the default values of all parameters as well as a list of available commands. The capitalised letters are sufficiently unique and you don't have to type more. 

      
 ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE -----
< % 207 gerard rigel 18:41:43 progs/dcup> DCUP

   
 D-CUP - Data-Collection Utility Program - G.J. Kleywegt - V 0.4 @ 921217

   
 > VOLUME (R|B) = Unit cell volume (Angstrom**3)           =   1000000.00000
 > A*     (R|B) = Reciprocal A-axis (Angstrom**-1)         =         0.01000
 > B*     (R|B) = Reciprocal B-axis (Angstrom**-1)         =         0.01000
 > C*     (R|B) = Reciprocal C-axis (Angstrom**-1)         =         0.01000
 > VM     (R|B) = Reciprocal density (Angstrom**3/Dalton)  =        12.50000
 > DPHI   (R|B) = Oscillation angle (degrees)              =         1.43239
 > MISANG (R|B) = Misset angle for zone centre (degrees)   =        -5.71059

   
 D-CUP defaults :

   
 > RESOLN (R|B) = Resolution (Angstrom)                    =         2.50000
 > LAMBDA (R|S) = Wavelength (Angstrom)                    =         1.54180
 > XDDIST (R|B) = Crystal-to-detector distance (mm)        =       100.00000
 > AAXIS  (R|S) = A-axis of unit cell (Angstrom)           =       100.00000
 > BAXIS  (R|S) = B-axis of unit cell (Angstrom)           =       100.00000
 > CAXIS  (R|S) = C-axis of unit cell (Angstrom)           =       100.00000
 > ALPHA  (R|S) = Alpha angle of unit cell (degrees)       =        90.00000
 > BETA   (R|S) = Beta angle of unit cell (degrees)        =        90.00000
 > GAMMA  (R|S) = Gamma angle of unit cell (degrees)       =        90.00000
 > MW     (R|S) = Molecular weight (Dalton)                =     20000.00000
 > NMOL   (I|S) = Number of molecules per unit cell        =               4
 > SLEEP  (R|B) = Total data-collection time (minutes)     =       600.00000
 > FRTIME (R|B) = Collection time per frame (minutes)      =        10.00000
 > PHIRAN (R|B) = PHI range (degrees)                      =        90.00000
 > MISDIS (R|S) = Misset distance for zone centre (mm)     =       -10.00000
 > XYDIST (R|S) = Distance to detector centre (mm)         =        95.00000
 > VOLUME (R|C) = Unit cell volume (Angstrom**3)           =   1000000.00000
 > A*     (R|C) = Reciprocal A-axis (Angstrom**-1)         =         0.01000
 > B*     (R|C) = Reciprocal B-axis (Angstrom**-1)         =         0.01000
 > C*     (R|C) = Reciprocal C-axis (Angstrom**-1)         =         0.01000
 > VM     (R|C) = Reciprocal density (Angstrom**3/Dalton)  =        12.50000
 > DPHI   (R|B) = Oscillation angle (degrees)              =         1.43239
 > MISANG (R|B) = Misset angle for zone centre (degrees)   =        -5.71059
 > PI     (R|N) = Pi (radians/180 degrees)                 =         3.14159
 > RTODEG (R|N) = Radians to degrees (degree/radian)       =        57.29578
 > DEGTOR (R|N) = Degrees to radians (radian/degree)       =         0.01745

   
 D-CUP commands :
 SEt parameter value      Calculate parameter      SHow parameter
 List_parameters          SAve filename            Restore filename
 EValuate expression      ECho on_off              Affect on_off
 ?                        !                        Quit

   
 Command ?
 ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE -----

5 COMMANDS

5.1 SET


allows you to set the value (if permitted) of a parameter. You need only supply a unique part of the parameter name and its new value 

      
 ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE -----
 Command ? set aax 41.36
 > AAXIS  (R|S) = A-axis of unit cell (Angstrom)           =        41.36000
 Command ? set b 41.36

   
 ERROR - parameter name not unique

   
 Command ? set ba 41.36
 > BAXIS  (R|S) = B-axis of unit cell (Angstrom)           =        41.36000
 ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE -----

5.2 SHOW


lists the current value of one parameter 

      
 ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE -----
 Command ? sh bax
 > BAXIS  (R|S) = B-axis of unit cell (Angstrom)           =        41.36000
 ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE -----

5.3 CALCULATE


calculate the value of a parameter given the current values 

      
 ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE -----
 Command ? set cax 202.71
 > CAXIS  (R|S) = C-axis of unit cell (Angstrom)           =       202.71001
 Command ? cal vol
 > VOLUME (R|C) = Unit cell volume (Angstrom**3)           =    346765.81250
 ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE -----

5.4 EVALUATE


evaluate an expression which looks like: parval [operator parval] where "parval" is either the name of a parameter or a numeric value and "option" is one of +, -, * or /. All items must be separated by one or more spaces; an expression is evaluated from left to right and you may not use parentheses 

      
 ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE -----
 Command ? eval vol * pi * 2 / 360
  > RESULT =    6052.206
 Command ? eval 1 / aax * 3
  > RESULT =   7.2533846E-02
 ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE -----

5.5 LIST_PARAMETERS


list the current values of all parameters

5.6 ECHO


followed by either "on" or "off" toggles the formula echo; when on, DCUP will print the formulas it uses for calculating parameters 

      
 ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE -----
 Command ? echo on
 ECHO ON
 Command ? set mw 15000
 > MW     (R|S) = Molecular weight (Dalton)                =     15000.00000
 Command ? set nmol 8
 > NMOL   (I|S) = Number of molecules per unit cell        =               8
 Command ? cal vm

   
 VM     = VOLUME / (NMOL   * MW    )
 > VOLUME (R|C) = Unit cell volume (Angstrom**3)           =    346765.81250
 > NMOL   (I|S) = Number of molecules per unit cell        =               8
 > MW     (R|S) = Molecular weight (Dalton)                =     15000.00000
 > VM     (R|C) = Reciprocal density (Angstrom**3/Dalton)  =         2.88972
 ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE -----

5.7 AFFECT


followed by either "on" or "off" toggles the dependency echo; when on, DCUP will generate a list of all parameters which are influenced if you set or calculate a certain parameter, plus for each of them a similar list. Note that some parameters may "influence themselves" through successive application of different formulas 

      
 ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE -----
 Command ? affect on
 AFFECT ON
 Command ? set resol 2.3
 > RESOLN (R|B) = Resolution (Angstrom)                    =         2.30000
 ... changes will affect :
     DPHI
      ... which will affect :
          SLEEP
          FRTIME
          PHIRAN
     XDDIST
      ... which will affect :
          MISANG
          RESOLN
 Command ? cal vol

   
 VOLUME = a complicated function of the cell parameters
 > AAXIS  (R|S) = A-axis of unit cell (Angstrom)           =        41.36000
 > BAXIS  (R|S) = B-axis of unit cell (Angstrom)           =        41.36000
 > CAXIS  (R|S) = C-axis of unit cell (Angstrom)           =       202.71001
 > ALPHA  (R|S) = Alpha angle of unit cell (degrees)       =        90.00000
 > BETA   (R|S) = Beta angle of unit cell (degrees)        =        90.00000
 > GAMMA  (R|S) = Gamma angle of unit cell (degrees)       =        90.00000
 > VOLUME (R|C) = Unit cell volume (Angstrom**3)           =    346765.81250
 ... changes will affect :
     A*
     B*
     C*
     VM
 ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE -----

5.8 SAVE


save your current settings to a file for use in a later DCUP session 

      
 ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE -----
 Command ? save dcup.dat
 SAVE FILE WRITTEN
 ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE -----

5.9 RESTORE


read a DCUP macro (usually created with the SAVE command) 

      
 ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE -----
 Command ? res dcup.dat
 READING SAVE FILE
 Command ?  !
 Command ?  ! D-CUP SAVE FILE
 Command ?  !
 Command ?  > RESOLN (R|B) = Resolution (Angstrom)                    =         2.30000
 ... changes will affect :
     DPHI
      ... which will affect :
          SLEEP
          FRTIME
          PHIRAN
     XDDIST
      ... which will affect :
          MISANG
          RESOLN
 Command ?  > LAMBDA (R|S) = Wavelength (Angstrom)                    =         1.54180
 ... changes will affect :
     RESOLN
      ... which will affect :
          DPHI
          XDDIST
     XDDIST
      ... which will affect :
          MISANG
          RESOLN
 (...)
 > MISANG (R|B) = Misset angle for zone centre (degrees)   =        -5.71059
 > PI     (R|N) = Pi (radians/180 degrees)                 =         3.14159
 > RTODEG (R|N) = Radians to degrees (degree/radian)       =        57.29578
 > DEGTOR (R|N) = Degrees to radians (radian/degree)       =         0.01745
 Command ?
 END OF SAVE FILE
 ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE -----

5.10 QUIT


stop working with DCUP

5.11 ?


list available commands

5.12 !


ignore the rest of this line (can be used to make comments in a macro file)

6 FORMULAS


At present, the following formulas have been implemented: 

      
 ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE -----
 MISANG = ATAN (XDDIST / MISDIS) * (180.0/PI)
 DPHI   = (RESOLN / MAX (AAXIS ,BAXIS ,CAXIS )) * (180.0/PI)
 VM     = VOLUME / (NMOL   * MW    )
 C*     = AAXIS  * BAXIS  * SIN (GAMMA  * (180.0/PI)) / VOLUME
 B*     = AAXIS  * CAXIS  * SIN (BETA   * (180.0/PI)) / VOLUME
 A*     = BAXIS  * CAXIS  * SIN (ALPHA  * (180.0/PI)) / VOLUME
 VOLUME = a complicated function of the cell parameters
 PHIRAN = SLEEP  * DPHI   / FRTIME
 FRTIME = SLEEP  * DPHI   / PHIRAN
 SLEEP  = FRTIME * PHIRAN / DPHI
 XDDIST = XYDIST / TAN (2 * ASIN (0.5 * LAMBDA / RESOLN))
 RESOLN = 0.5 * LAMBDA / SIN (0.5 * ATAN (XYDIST / XDDIST))
 ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE -----

7 KNOWN BUGS

None, at present.

Uppsala Software Factory Created at Fri Dec 18 19:42:09 1998 by MAN2HTML version 971024/1.6