Read Shak(6) CONTRIBUTED MODULES Read Shak(6) NAME read shak - AVS module for displaying crystallographic or molecular models. shak_to_geom - offline filter for conversion of SCHAKAL input files to geometry SUMMARY (read shak module) Name fast animate Type data Inputs none Outputs Geometry Chemistry Parameters _N_a_m_e _T_y_p_e Schakal File browser representation choice show cell boolean show labels boolean show title boolean atom radius real bond radius real SUMMARY (shak_to_geom filter) shak_to_geom [-in _s_c_h_a_k_a_l-_f_i_l_e ] [-out _g_e_o_m-_f_i_l_e ] [ -cell ] [ -labels ] [ -title ] [ -rep ballandstick | spacefill ] [ -bonds _b_o_n_d-_r_a_d_i_u_s ] DESCRIPTION The _r_e_a_d _s_h_a_k module and the _s_h_a_k__t_o__g_e_o_m filter are crys- tallography front-ends for AVS. Both read an input file containing a description of the atomic co-ordinates of the structure or molecule to be visualized and output AVS geometry representing a ball-and-stick or space-filling model of it. The _r_e_a_d _s_h_a_k module is suited to interactive viewing whereas the _s_h_a_k__t_o__g_e_o_m filter is useful for off- line creation of a sequence of ._g_e_o_m files for animation by _f_a_s_t__a_n_i_m_a_t_e(_6) . The input language is a substantial subset of the one used by SCHAKAL88, and most SCHAKAL input files should be directly readable by read_shak. There are sample data files to be read using this module on the International AVS Center's anonymous ftp site, in the sample data's read_shak subdirectory. PARAMETERS Schakal File Keith Refson Last change: 06/02/91 1 Read Shak(6) CONTRIBUTED MODULES Read Shak(6) The file containing SCHAKAL records to describe a molecule or crystal structure. The file browser assumes an extension of .shak and only displays files with this ending. Representation Choose either a "ball-and-stick" or a "space-filling" representation. Atoms are drawn with a size proportional to their Van der Waals radii (see atom radius ). In the case of the "space-filling" model, no bonds are drawn. Atom radius Atoms are drawn as spheres whose radius is the Van der Waals radius multiplied by this factor in the "space- filling" representation. The default is 0.75. In the "ball-and-stick" representation the radii are multiplied by an additional factor of 1/3. Bond radius Bonds are drawn as tubes with the specified radius in Angstroms (default 0.1). If the radius is zero, then lines are used instead. Show cell Draw the edges of the crystal unit cell (see ADD, DUPL below). Show labels Label each atom with the chemical symbol and identifier string given in its ATOM record. Show Title Display the title string given by the TITLE record. OUTPUTS Molecule (geometry) The geometric representation of the molecule or crystal structure as selected by the parameters (eg space- filling/ball-and-stick etc). Molecule (chemistry) The molecular description as an AVS Chemistry data type, suitable for connection to "Display Molecule" or other Chemistry modules. Keith Refson Last change: 06/02/91 2 Read Shak(6) CONTRIBUTED MODULES Read Shak(6) There are no formal charges associated with the atoms since the SCHAKAL file format makes no provision for this. SCHAKAL FILE FORMAT The format of SCHAKAL input files is quite simple: each line or record begins with a label which is followed by the appropriate data. For example 9 CELL 1 1 1 ATOM Si 0.0000000 0.000000 0.00 ATOM O1 0.0000000 0.000000 1.65 ATOM O2 0.0000000 1.555635 -0.55 SYMM -0.5*x - 0.86603*y, 0.86603*x - 0.5*y, z SYMM -0.5*x + 0.86603*y, -0.86603*x - 0.5*y, z END Words or items in each record must be separated by one or more spaces, unless the item is a punctuation or other sym- bol (one of "+*/=:;,'\"<>()[]!?@\^_`{}~"). Upper and lower case are equivalent, and label names may be abbreviated to two letters. Multiple records or commands may be put on the same line, separated by a semicolon, or the same label may be repeated with different arguments by placing successive argument lists following a full colon. For example SYMM -X, -Y, -Z ; symm 1 + X,1+Y,1-Z and SY -X, -Y, -Z : 1 + X , 1 + Y, 1 - Z are both equivalent to the two separate SYMM commands SYMM -X,-Y,-Z SYMM 1+X,1+Y,1-Z A minimal dataset should specify all the atomic species and co-ordinates using ATOM records and finish with an END record. The TITLE record adds a title string which may be optionally displayed. (See below for an explanation of the exact syntax and meaning of these records.) Atoms are represented as spheres whose colour, radius and bonding are determined by the chemical symbol type. The colour is selected from a standard table and the radius is some frac- tion (set by the _a_t_o_m _r_a_d_i_u_s parameter) of the Van der Waals radius of the atom. When the END record is encountered, bonds are added between all pairs of atoms whose separation is less than or only marginally more than the sum of their bonded radii. The transformation commands SYMM, DUPL, TRANS and BOX operate on atoms already entered with ATOM records. That is, only atoms declared _p_r_i_o_r _t_o the occurrence of the Keith Refson Last change: 06/02/91 3 9 Read Shak(6) CONTRIBUTED MODULES Read Shak(6) transformation command in the file are affected. SYMM and DUPL are used to generate new atoms by transformations specifying symmetry operations and the TRANS command transforms the co-ordinates of a set of atoms. The transformation is given in the notation used by the _I_n_t_e_r_n_a_- _t_i_o_n_a_l _T_a_b_l_e_s _f_o_r _X-_R_a_y _C_r_y_s_t_a_l_l_o_g_r_a_p_h_y. Finally the BOX command fills one and optionally generates more crystallo- graphic unit cells. The unit cell of a crystal structure should be specified with a CELL record. A line box joining the unit cell corners may be displayed using the parameter _s_h_o_w _c_e_l_l or the _c_e_l_l command line option of _s_h_a_k__t_o__g_e_o_m. The corners of a single unit cell are normally added on execution of the END record, after any symmetry transformations. However they may be added to the atom list earlier (they are stored as pseudo-atoms) with the ADD command. In that case they are acted on by any following transformation commands which may therefore be used to generate the edges of more than one unit cell. SCHAKAL COMMANDS TITLE _t_i_t_l_e The title given as the argument to the TITLE record may be displayed interactively in _r_e_a_d__s_h_a_k or by specifying the -title option to the _s_h_a_k__t_o__g_e_o_m filter. CELL [ _a ] [ _a _b _c ] [ _a _b _c _a_l _b_e _g_a ] The CELL record specifies the crystallographic unit cell. There are four variants depending on the number of param- eters: 0 The unit cell is cubic with side 1. May be used to allow cartesian co-ordinates for atom input. 1 The unit cell is cubic with side _a. 3 The unit cell is orthorhombic with sides _a, _b and _c. 6 The six parameters are the lengths and angles of a general unit cell. ATOM _C_s[_N][_A] _x _y _z The atom type specification _C_s[_N][_A] should be comprised of the one or two letter standard chemical symbol _C_s an optional integer atom number, _N _i_n _t_h_e _r_a_n_g_e _0-_9_9_9_9 _a_n_d optional single letter _A. The chemical symbol is used to determine the atom radius for bonding (the covalent or ionic radius) and for display (the Van der Waals radius) as well as the colour. If it is not recognised then a default "unknown atom" type is used. Keith Refson Last change: 06/02/91 4 Read Shak(6) CONTRIBUTED MODULES Read Shak(6) The co-ordinates _x, _y, _z should be given as fractional co-ordinates within the unit cell in the usual crystallo- graphic manner. Of course if the unit cell is cubic with side 1 (which is the default if no CELL record is present) the fractional and cartesian co-ordinates are identical. The SCHAKAL command ASSUM BLANKS and the associated vari- ant form of the ATOM record are also allowed for compati- bility with existing SCHAKAL datasets. In that case ATOM records should take the form ATOM CS N[A] _x _y _z so that the atom number (which must be given) is separate from the chemical symbol. ADD Add eight pseudo-atoms (named A1-A8) at the corners of the unit cell. This is done implicitly upon execution of the END record, but if the ADD command is followed by the symmetry commands SYMM, DUPL, TRANS or BOX they will operate on the unit cell corners as well as ordinary atoms. This allows extra unit cell corners to be gen- erated and displayed. SYMM _s_y_m_m-_o_p DUPL _s_y_m_m-_o_p These commands apply symmetry transformations to atom records and generate new atoms which are added to the atom list. The difference between them is that SYMM operates only on atoms which were explicitly specified with ATOM records whereas DUPL also operates on those generated by SYMM, BOX and previous DUPL commands. Both commands operate only on the immediately preceding set of atoms in the input file. "Immediately Preceding" means the last block of ATOM records, unbroken by a DUPL, SYMM, BOX or END n command. In other words, an ATOM record fol- lowing any of these begins a new set and subsequent sym- metry operation commands apply only to it and its succes- sors. The syntax of the symmetry operation _s_y_m_m-_o_p may be specified in one of two ways; either a) in the operator form used by the International Tables for X-Ray Crystallography. This is a set of three comma-separated linear expressions involving the X, Y and Z co-ordinates, _e._g. X+1, X+0.5*Y-1/2,X-Z The allowed operators are "+", "-", "*" and unary "-". Constants can be given either in decimal notation or expressed as fractions using "/" (This is not a gen- eral operator: it acts only between constants). or Keith Refson Last change: 06/02/91 5 Read Shak(6) CONTRIBUTED MODULES Read Shak(6) b) as the 12 elements of the translation vector _t and rotation matrix _r in the order _t_1 _r_1_1 _r_1_2 _r_1_3 _t_2 _r_2_1 _r_2_2 _r_2_3 _t_3 _r_3_1 _r_3_2 _r_3_3. If an atom is situated at a special position of the sym- metry operator no new atom is generated. However no check is made to test whether the new atom maps onto any other existing atom. TRANS _s_y_m_m-_o_p The TRANS command transforms co-ordinates of the immedi- ately preceding set of atoms, changing the existing values rather than generating new atoms. It operates on atoms generated by SYMM, DUPL and BOX commands as well as those given directly with ATOM records. The syntax of the symmetry operations is the same as used in SYMM and DUPL. BOX [ _s_1 ] [ _s_1 _s_2 _s_3 ] [ _s_1 _s_2 _s_3 _s_4 _s_5 _s_6 ] The BOX command repositions all atoms by unit cell vec- tors so as to lie within a single unit cell as specified by CELL. It then expands the system by adding periodic images of atoms to fill a larger cell, whose size is determined by the parameters _s_1-_s_6. With no parameters, BOX simply relocates atoms into one unit cell. With one or three parameters _s_n is the addi- tional fraction that the unit cell should be extended by, either uniformly or by x,y,z separately. That is, by 1+s in each direction. If all six parameters are given they specify the limits, _x_m_i_n, _x_m_a_x, _y_m_i_n, _y_m_a_x, _z_m_i_n, _z_m_a_x in fractional co-ordinates, of the new box to be filled. END [ _n ] The END record with no parameter delimits the end of the data in the file. If no ADD record has been encoun- tered, it is implicitly executed at this point. If an integer parameter is supplied then END _n delimits a single crystallographic data set. A new molecule or structure is assumed to follow, and these will be stored as separate geometry objects within AVS. EXAMPLE READ SHAK | RENDER GEOMETRY | DISPLAY PIXMAP RELATED MODULES pdb_to_geom(6), fast_animate(6) Keith Refson Last change: 06/02/91 6 Read Shak(6) CONTRIBUTED MODULES Read Shak(6) BUGS The SCHAKAL commands MOL, GRUP, LIST and PACK are not imple- mented. MOL, GRUP and LIST records are ignored if they are encountered. PACK reports an error. The use of ATOM A to draw extra cell edges is also not supported. These may be implemented in future versions, especially if someone else volunteers to do it. No check is made as to whether a symmetry operation dupli- cates an existing atom, other than if the atom itself is at a special position of the operator. The syntax of the symmetry operations allowed in SYMM, DUPL and TRANS commands differs slightly from that allowed by SCHAKAL. a) It allows slightly more general expressions. b) Adjacent operators ("separators") are not allowed. Anyone who used this "feature" when writing SCHAKAL files needs their head examined. SEE ALSO _S_C_H_A_K_A_L_8_8, _A _F_O_R_T_R_A_N _p_r_o_g_r_a_m _f_o_r _t_h_e _G_r_a_p_h_i_c _R_e_p_r_e_s_e_n_t_a_t_i_o_n _o_f _M_o_l_e_c_u_l_a_r _a_n_d _C_r_y_s_t_a_l_l_o_g_r_a_p_h_i_c _M_o_d_e_l_s. Egbert Keller, Kristallographisches Institut der Universitat, Helbstr. 25, D-7800 Freiburg, Germany. (egbert.keller@sun1.ruf.uni- freiburg.dbp.de) _I_n_t_e_r_n_a_t_i_o_n_a_l _T_a_b_l_e_s _f_o_r _X-_R_a_y _C_r_y_s_t_a_l_l_o_g_r_a_p_h_y International Union of Crystallography, Kynoch Press, Birmingham, UK (1967) Keith Refson Last change: 06/02/91 7