
SYMLIB (CCP4: Library)NAMEsymlib  Subroutine Library for handling symmetry operationsDESCRIPTIONThe library symlib contains subroutines used for handling symmetry operations and performing symmetry related tasks in CCP4 programs, although a number of routines unconnected with symmetry operations also appear here, presumably for historical reasons.The subroutines have been arranged as much as possible into groups by function. There are often several versions of subroutines apparently performing the same or very similar tasks, reflecting the policy of never removing an existing routine in order to maintain compatibility with programs written using older versions of the library. CONTENTS
1. DESCRIPTION OF THE SYMMETRY LIBRARYIn CCP4 the information relating together information such as spacegroup name, number and symmetry opertions are stored in a library file which is defined by the logical name $SYMOP. In the standard configuration of CCP4 this is the file symop.lib which normally resides in $CLIBD. symop.lib holds information for all the standard spacegroups in the International Tables, plus alternative settings for monoclinic and some nonstandard spacegroups (eg I_{2}, I_{21} ...); R_{3}, H_{3} and so on. Format of the symmetry library fileEach spacegroup has an entry consisting of a header line followed by a list of symmetry operators. The header line contains the following items: LSPGRP NLINS NLINP NAMSPG NAMPG CRYSTAL NAMSPG_CIF
The subroutine MSYMLB3 should be used to retrieve information from the symmetry library. Note that not all the data items are compulsory for MSYMLB3, although older versions of the routine (MSYMLB2, MSYMLB, MSYGET) still need them.
The symmetry operations in the spacegroup then follows the header line, with one operation per line in the format eg X,Y,Z or Y,XY,Z+1/3 etc For example: 1 1 1 P1 PG1 TRICLINIC 'P 1' X,Y,Z 2 2 2 P1 PG1bar TRICLINIC 'P 1' X,Y,Z X,Y,Z 3 2 2 P2 PG2 MONOCLINIC 'P 1 2 1' X,Y,Z X,Y,Z 4 2 2 P21 PG2 MONOCLINIC 'P 1 21 1' X,Y,Z X,Y+1/2,Z ... 57 8 8 Pbcm PGmmm ORTHORHOMBIC 'P 2/b 21/c 21/m' 'P b c m' X,Y,Z X,Y,1/2+Z X,1/2+Y,1/2Z X,1/2Y,Z X,Y,Z X,Y,1/2Z X,1/2Y,1/2+Z X,1/2+Y,Z ... The spacegroup numbers are unique, so alternative numbers are generated by adding 1000, 2000 etc to the original spacegroup number. 2. HOW SYMMETRY OPERATIONS ARE STORED AND APPLIEDStorage of symmetry operationsIn symop.lib the symmetry operations in each spacegroup are listed as strings, for example X,Y,Z or Y,XY,Z+1/3 etc. To be useful within a program these string representations have to be converted to some mathematical representation. Typically a symmetry operation RSym will consist of a rotation operation R and a translation operation T (basically a vector). These are applied to a vector x to obtain x':
It is convenient to represent the rotation by a 3*3 matrix: ( R11 R12 R13 ) [R] = ( R21 R22 R23 ) ( R31 R32 R33 )and the translation by a column vector with 3 elements: ( T1 ) [T] = ( T2 ) ( T3 ). CCP4 uses 4x4 arrays to store these symmetry operations as follows: RSym = ( R11 R12 R13 T1 ) ( R21 R22 R23 T2 ) ( R31 R32 R33 T3 ) ( 0 0 0 1 )or RSym = ( [R]  [T] ) ( 0 0 0  1 )Essentially this is a 4x4 matrix holding 3x3 transformation matrix in the "toplefthand corner", the 3element column (translation) vector in the "toprighthand corner", and then (0 0 0 1) in the bottom row. The subroutine MSYMLB3 will obtain the set of symmetry matrices in this representation for a given spacegroup, whilst SYMFR2 or SYMFR3 will obtain individual matrices from the string representation mentioned above. (SYMTR4 will perform the inverse operation, converting matrices to string representation.) Application of symmetry operations1. Real Space CoordinatesUsing the convention outlined above, postmultiplying the 4x4 matrix by a column vector as follows: RSym . [xf] [yf] [zf] [1 ]will apply both the symmetry and the translation operations to real space coordinates with a single matrix multiplication. The CCP4 MODLIB library provides matrixvector routines MATVEC4 and TRANSFRM which can be used to perform this operation. 2. Reciprocal SpaceThe inverse of realspace symmetry matrices are applied to reflection indices by premultiplying them by a row vector representing hkl,
Note that only the operations in the appropriate Laue group are applied to reflection indices, so there are no translational components (i.e. the vector part of the operation, [T], is zero). The subroutine INVSYM will invert a 4x4 matrix stored in this representation, for the purpose of applying symmetry operations to reflection indices. 3. Axis VectorsReal space axis vectors are transformed like reciprocal space vectors, i.e. while reciprocal space axis vectors are transformed like real space coordinates, i.e. (See also the REINDEX documentation.) 3. DESCRIPTION OF THE GROUPS OF SUBROUTINESThe subroutines have been broken down into groups according to function.Group 1: Subroutines for deriving and manipulating symmetry operationsThis group contains routines for obtaining the lists of symmetry operators from the library, and converting between the string (eg Y,X,Z etc) and matrix representations of symmetry operators.Group 1a: Deriving symmetry operator matrices
INVSYM will generate the inverse matrix of a real space symmetry operation, to be applied to reflection indices as described in section 2. Internal routines:
Group 1b: Deriving information from symmetry operators
Group 2: Subroutines for testing reflection dataa) Centric reflectionsNb: routines CENTRC and CENPHS both appear to be unused.Call CENTRIC once to set up the symmetry elements in common blocks shared with CENTR. This defines the set of centric reflections. Then for each reflection, a call to CENTR will return whether it is centric. b) Epsilon zones
HKLEQ  used in SCALA to test if two reflections have equal indices. Group 3: Subroutines for choosing asymmetric unitsRemember that the choice of asymmetric unit is NOT UNIQUE. These routines define the set of CCP4 asymmetric units. The limits for these definitions are given in section 3.a) Subroutines for choosing asymmetric units for reflection data
Internal routines:
b) Subroutines for choosing asymmetric units in real space consistent with FFT expectations; FFT grids etc.
Internal routines:Group 4: Subroutines for testing coordinate data
Neither of the routines XSPECIALS or KROT appear to be used in supported CCP4 programs. Group 5: Subroutines for permuting symmetry operatorsThree subroutines for permuting symmetry operations. They do not really belong here in symlib, but are widely used invisibly in FFT routines using symmetry operations to permute axes for easier fast fourier calculations.
Group 6: Subroutines for generating and accessing a hash tableA set of routines used in SCALA, POSTREF and REBATCH.
Group 7: Miscellaneous subroutines
This is how the routines are used in CAD. A call to SETRSL with the cell dimensions and angles sets up coefficients in RECPLT, which are then used by the function STHLSQ to calculate the quantity "(sin(theta)/lamba)**2" for any given set of h, k, l indices. From Bragg's Law, this quantity is equal to 1/(4*d**2), that is, onequarter of the resolution. Within CAD, multiplication by 4 yields the resolution 1/d**2.
4. SUBROUTINES IN SYMLIBThe following subroutines are available. They are arranged alphabetically.Subroutine ASUGET(IHKL,JHKL,ISYM)Get original indices of reflection from asymmetric unit, i.e. reverse operation of ASUPUT. Symmetry defined by call to ASUSET.On input:
Subroutine ASUPHP(JHKL,LSYM,ISIGN,PHASIN,PHSOUT)Generate phase of symmetry equivalent JHKL from that of IHKL.On input:
Subroutine ASUPUT(IHKL,JHKL,ISYM)Put reflection into asymmetric unit defined by call to ASUSETOn input:
Subroutine ASUSETSet up & store symmetry informtion for later use in ASUPUT or ASUGETOn input:
Subroutine CALC_ORIG_PS(NAMSPG_CIF,NSYM,RSYM,NORIG,ORIG,LPAXISX,LPAXISY,LPAXISZ)Creates a list of equivalent origins for the named spacegroup.ARGUMENTS
Taken from Alexei Vagin Integer Function CCP4_HASH_LOOKUP(NSER)The function CCP4_HASH_LOOKUP returns the value NFIND (which was input when setting up the function in the subroutine CCP4_HASH_SETUP) for the large range variable NSER. Uses hashing. (see comments for CCP4_HASH_SETUP for description of hashing method).Subroutine CCP4_HASH_SETUP(NSER,NFIND)This subroutine sets up a value for the function ccp4_hash_lookup.When ccp4_hash_lookup(nser) is later evaluated it will return nfind This function will allow the efficient retrieval of an identifier for a large range variable (such as a crystal number). The values of the function ccp4_hash_lookup(nser) are stored in the array it(2, kpri) where kpri is the prime number used to generate the function. The array 'it' lives in the common block which is shared by ccp4_hash_setup and the function ccp4_hash_lookup NOTES: A hash table is a way of storing information so that it easily be retrieved without the need for indexing or long searches. NSER is referred to as the "key", which is "hashed" (computer science speak for "messed up") by the hashing function (in this case MOD(NSER4,KPRI) + 1) to determine where the value pair will be stored. The function LOOKUP can then search on the same basis when supplied with the key, to retreive the pair in (at most) 3 calculations. Note that KPRI (the table size) MUST BE A PRIME in order for this method to work. Subroutine CCP4_HASH_ZEROIT()Initialises elements of array 'it' used in ccp4_hash_setup and ccp4_hash_lookup to zero.Subroutine CENTR(IH,IC)Input IH(3)  reflection indicesReturns IC Determine whether a reflection is centric (return IC=1) or not (IC=0). If none of the zone tests is satisfied, the reflection is noncentric. Logical Function CENTRC(KHKL,ICENT)Returns value as true if reflection khkl is centric, false otherwise. It is general for all point groups  but only for the unique set of indices which conforms to the criterion of maximising the value ofas produced by e.g. subroutine turnip in protin and ulysses. In this case the required tests are controlled by 7 flags in icent for
(the last is needed in pg312) Subroutine CENTRIC(NSM,RSMT,IPRINT)This is Randy Read's method of defining centric reflections. It uses NSM and the symmetry operators stored in RSMT(4,4,NSM)It decides how many centric zones there are, and flags them. set up tests for 0kl h0l hk0 hhl hkh hkk h,hl hkh hkk h 2h l 2h h l hkl Zones are encoded using an idea from a program by Bricogne. If h*zone(1) + k*zone(2) + l*zone(3) is equal to 0.0, that reflection is in that zone. All that is needed is the most general conditions  a reflection is either centric or not. Subroutine DETERM(det,a)Gets determinant of a matrix
Subroutine EPSLN(NSM,NSMP,RSMT,IPRINT)It works out the epsilon cards using NSM and the symmetry operators stored in RSMT(4,4,NSM).This is Randys program description: zones defined as for centric zones, but fourth number on each line is the multiplicity corresponding to this zone. last card should always be 0 0 0 n, where n is appropriate for the lattice (1 for primitive, 2 for face centred, etc.), so that general reflections get a value for epsilon. be very careful of the order of the zones. cards for reciprocal lattice rows should be given before those for planes, because the first test that is satisfied defines the zone. Subroutine EPSLON(IH,EPSI,ISYSAB)Input IH(3)  reflection indicesReturns EPSI ( epsilon zone) , and ISYSAB flag. Systematic absences flagged with ISYSAB = 1 Find the zone a reflection falls into, and return the appropriate value for the reflection multiplicity factor. Each reflection must have a zone. Logical Function FACTRZ(N)Returns true if N has all prime factors <= 19Subroutine FNDSMP(MINSMP, NMUL, SAMPLE, NSAMPL)Find suitable grid sample, approximately = SAMPLE/2 * maximum index, with required factor, and no prime factor > 19On entry:
Logical Function HKLEQ(IH,KH)Checks if indices are equal.Returns true if indices ih = kh Subroutine HKLRANGE(IHRNG0,IKRNG1,IKRNG0,IKRNG1,ILRNG0,ILRNG1)Return HKL ranges chosen in PGNLAUEArguments: (INTEGER) HRNG0,HRNG1,KRNG0,KRNG1,LRNG0,LRNG1 Integer Function INASU(IH, NLAUE)Arguments:
INASU = +1 if h k l chosen Subroutine INVSYM(S,ST)Inverts a 4*4 matrix. Used here to get inverse symmetry operation for generating equivalent h k l, i.e.
h'(j) =Sum(I=1,3)[ h(i)*St(I,J,NS)] Arguments:
Integer Function KROT(NS)Apply NS'th symmetry operation to JP to get LP, check if lies in asymmetric unit given by NAU.Returns KROT=0 correct operation, =1 if not. Subroutine MSYGET(IST,LSPGRP,NSYM,ROT)Get symmetry operations for spacegroup LSPGRP from library file on stream IST, logical name SYMOP.Arguments:
Subroutine MSYMLB(IST,LSPGRP,NAMSPG,NAMPG,NSYMP,NSYM,ROT)Get symmetry operations from library file on stream IST, logical name SYMOP. Space group defined by LSPGRP  spacegroup number or NAMSPG  spacegroup name.Arguments:
Subroutine MSYMLB2(IST,LSPGRP,NAMSPG_CIF,NAMPG,NSYMP,NSYM,ROT)Identical to MSYMLB, except that on output NAMSPG_CIF has correct CIF format, e.g. 'P 21 21 21'NAMSPG_CIF should be as in _symmetry.space_group_name_HM Subroutine MSYMLB3(IST,LSPGRP,NAMSPG_CIF,NAMSPG_CIFS,NAMPG,NSYMP,NSYM,RlSymmMatrx)Another version of MSYMLB, with the following changes:
LSPGRP NLINS and contain either NAMSPG or NAMSPG_CIF LSPGRP NLINS NLINP NAMSPG NAMPG CRYSTAL NAMSPG_CIF where:
On entry:
Returns:
Subroutine PATSGP(SPGNAM, PGNAME, PATNAM, LPATSG)Determine Patterson spacegroup from true spacegroupOn entry:
Subroutine PGDEFN(NAMPG,NSYMP,NSYM,RSYMT,LPRINT)Arguments:
This subroutine chooses the primitive set of symmetry operators. If necessary it reorders the symmetry operators to give the primitive ones first. This subroutine works out the point group name NAMPG. That is ; it checks rotation axes, etc etc and recognises these point groups. (It DOES NOT cope with mirror planes etc) Gronigen MDF stuff: It now sets up the common block MDFPAR for MDF file mods and fills in the symmetry info. See subroutine for details. Subroutine PGMDF(JLASS,JCENTR,JSCREW)Gronigen subroutine.
Use this subroutine to transfer information to and from MDFPAR. Subroutine PGNLAU(NAMPG,NLAUE,LAUNAM)Choose Laue group from PG name.On entry:
The number nlaue is the same as the one set in CAD for this purpose. Pointgroup Laue group Limits 3 pg1 1bar hkl:l>=0 hk0:h>=0 0k0:k>=0 1,2 pg1bar 4 pg2 (b) 2/m hkl:k>=0, l>=0 hk0:h>=0 3/b,4/b.... pgm pg2/m 5 pg2 (c) 2/m hkl:k>=0, l>=0 h0l:h>=0 1003,1004 6 pg222 mmm hkl:h>=0, k>=0, l>=0 16 ... pgmm2 pgmmm 7 pg4 4/m hkl:h>=0, l>=0 with k>=0 if h=0 and pg4bar pg4/m k>0 if h>0 8 pg422 4/mmm hkl:h>=0, k>=0, l>=0 89.. pg4mm pg4bar2m pg4barm2 pg4/mmm 9 pg3 3bar hkl:h>=0, k>0 00l:l>0 143.. pg3bar 10 pg312 3/m hkl:h>=0, k>=0 with k<=h for all l. pg32 pg3m pg3m1 pg3barm1 if k = 0 l>=0 Space group numbers : 149151153 157 159 162 163 11 pg321 3bar1m hkl:h>=0, k>=0 with k<=h for all l. pg31m pg3bar1m if h = k l>=0 Space group numbers : 150152154 12 pg6 6/m hkl:h>=0, k>=0, l>=0 with k>=0 if h=0 pg6bar 6/m and k> 0 if h>0 13 pg622 6/mmm hkl:h>=0, k>=0, l>=0 with h>=k 177.. pg6mm pg6barm2 pg6bar2m pg 6/mmm 14 pg23 m3 hkl:h>=0, k>=0, l>=0 with l>=h, k>=h pgm3bar 15 pg432 m3m hkl:h>=0, k>=0, l>=0 with k>=l pg4bar3m pgm3barm Subroutine PRMVCI(PERM,JV,N,N1)
C Permute C C DO 10 I = 1,3 C BV(I) = PERM(I,1)*JV(N,1) + PERM(I,2)*JV(N,2) + C + PERM(I,3)*JV(N,3) C 10 CONTINUE C C Copy back C C DO 20 I = 1,3 C JV(N,I) = NINT(BV(I)) C 20 CONTINUE Subroutine PRMVCR(PERM,AV,N,N1)
See PRMVCI  this routine is its real equivalent. Subroutine PRTRSM(PGNAME, NSYMP, RSYMIV)Print reciprocal space symmetry operationsThe realspace symmetry matrices are applied by premultiplying them by a row vector hkl, ie (h'k'l') = (hkl)R Subroutine PSTOPH (PSIX,PSIY,PSIZ,PHIX,PHIY,PHIZ,AVPHI)Convert PSIX,PSIY,PSIZ (= epsx,epsy,epsz) to PHIX,PHIY,PHIZ, using AVPHIAll angles in radians Subroutine ROTFIXPermutes inverse symmetry operationsMatrices passed in Common block ATSYM Subroutine SETGRD(NLAUE,SAMPLE,NXMIN,NYMIN,NZMIN,NX,NY,NZ)Set up a suitable sampling grid for FFTInput:
This is ALL the point groups. PG1 PG1bar PG2 PGm PG2/m PG222 PGmm2 PGmmm PG4 PG4bar PG4/m PG422 PG4mm PG4bar2m PG4/mmm PG3 PG3bar PG32 PG3m PG3barm PG6 PG6bar PG6/m PG622 PG6mm PG6bar2m PG6/mmm PG23 PGm/3bar PG432 PG4bar3m PGm3bar mWe use: PG1 PG1bar PG2 PG2/m PG222 PGmmm PG4 PG4/m PG422 PG4/mmm PG3 PG3bar PG32 PG3bar/m PG6 PG6/m PG622 PG6/mmm PG23 PGm/3bar PG432 PGm3barmFor grid restrictions we only need to know the laue number. Here is the table: 3 pg1 1bar hkl:l>=0 hk0:h>=0 0k0:k>=0 1,2 4 pg2 2/m hkl:k>=0, l>=0 hk0:h>=0 3/b,4/b.... 5 pg2(c) 2/m hkl:k>=0, l>=0 h0l:h>=0 1003,1004 6 pg222 mmm hkl:h>=0, k>=0, l>=0 16 ... 7 pg4 4/m hkl:h>=0, l>=0 with k>=0 if h=0 and 8 pg422 4/mmm hkl:h>=0, k>=0, l>=0 89.. 9 pg3 3bar hkl:h>=0, k>0 00l:l>0 143.. 10 pg312 3/m hkl:h>=0, k>=0 with k<=h for all l. if k = 0 l>=0 Space group numbers : 149151153 11 pg321 3/m hkl:h>=0, k>=0 with k<=h for all l. if h = k l>=0 Space group numbers : 150152154 12 pg6 6/m hkl:h>=0, k>=0, l>=0 with k=0 if h=0 13 pg622 6/mmm 14 pg23 m3 15 pg432 m3m Subroutine SETLIM(LSPGRP,XYZLIM)Set appropriate box (asymmetric unit) for spacegroup (true spacegroup rather than FFT spacegroup) LSPGRP. For cubic symmetry spacegroups, this will be more than one asymmetric unit.On entry:
Subroutine SETRSL(A,B,C,ALPHA,BETA,GAMMA)Routine to calculate coefficients for (sin(theta)/lambda)**2 from h,k,l for general axes.First calculates the components of input axes in an orthonormal basis, then calculate components of reciprocal axes in same basis. The input angles are in degrees. Real Function STHLSQ(IH,IK,IL)Calculate (sin(theta)/lambda)**2 from h,k,l. The coefficients are set by a previous call to SETRSL. Works for any kind of axes.Real Function STS3R4(IH,IK,IL)Calculate (sin(theta)/lambda)**2 from h,k,l. The coefficients are set by a call to SETRSL. Works for any kind of axes.Subroutine SYMFR2(ICOL,I1,NS,ROT)Read and interpret symmetry operationsSYMFR2 recognises the following types of input: real space symmetry operations, e.g. X+1/2,YX,Z reciprocal space operations, e.g. h,lh,k reciprocal axis vectors, e.g. a*+c*,c*,b* real space axis vectors, e.g. a,ca,b The subroutine returns the appropriate 4x4 transformation matrix for each operation. The calling program must interpret the resulting matrix(ces) correctly. On entry I1 is the first character of ICOL to look at (say after keyword 'SYMM') NS is the number of the first symmetry operation to be read, & returns with the number of the last one read. On exit, ROT(4,4,NS) contains the realspace symmetry matrices, in standard convention, i.e.
x'(I)=Sum(J=1,3)ROT(I,J,NS)*x(J) + ROT(I,4,NS) Input:
Subroutine SYMFR3(ICOL,I1,NS,ROT,EFLAG)Read and interpret symmetry operations.Arguments:
Subroutine SYMTRN(NSM,RSM)Symmetry translation from matrix back to charactersThis translates the symmetry matrices RSM(4,4,NSM) into INT TAB character strings It gives the real and reciprocal space operations. eg X,Y,Z H , K, L eg Y,XY, Z HK, H, L etcThat is more complicated than you might think!! Subroutine SYMTR3(NSM,RSM)Symmetry translation from matrix back to charactersThis translates the symmetry matrices RSM(4,4,NSM) into INT TAB character strings It gives the real and reciprocal space operations. eg X,Y,Z H , K, L eg Y,XY, Z HK, H, L etcThat is more complicated than you might think!! Arguments :
Subroutine SYMTR4(NSYM,RSM,SYMCHS)Symmetry translation from matrix back to charactersThis translates the symmetry matrices RSM(4,4,NSM) into INT TAB character strings It gives the real and reciprocal space operations. eg X,Y,Z H , K, L eg Y,XY, Z HK, H, L etcThat is more complicated than you might think!! Arguments :
Subroutine SYSAB(IN,ISYSAB)Input IN(3)  reflection indicesReturns ISYSAB flag. Systematic absences flagged with ISYSAB = 1 Only reflns with EPSI > 1 need be considered. Subroutine XSPECIALS(NSYM,RSYM,XF,YF,ZF,NSPEC)
5. DEFINITION OF THE CCP4 ASYMMETRIC UNITThere is no standard defined asymmetric unit so the definitions are arbitrary and may differ between differ packages. The subroutines in group 3.a are used to define the CCP4 asymmetric unit, and to determine whether a reflection falls within this definition.Below are the definitions of the reciprocal space and the real space asymmetric units under the CCP4 convention. a. Reciprocal Space Asymmetric Unit DefinitionsThe reciprocal space asymmetric unit is defined in the subroutine ASUSET from the Laue group using calls to the s/r's PGDEFN and PGNLAU. The limits of the CCP4 asymmetric unit are (from PGNLAU):
b. Real Space Asymmetric Unit DefinitionsThe subroutine SETLIM contains the definitions of the real space asymmetric unit. Note that not all of the spacegroups have a definition within SETLIM.
(*) The limits are in fractional coordinates, and the lower limits are always x=0, y=0, z=0. 