KEYWORD SYMMETRY MODULE (KSM) ROUTINES

INTRODUCTION

The Keyword Kymmetry Module (KSM) routines are a set of routines to handle the interpretation and storage of symmetry data. The symmetry data are interpreted from data lines introduced by the 'SYMMETRY' keyword. They may be used in conjuction with one or more sets of Keyword Data Module (KDM) routines. A set of higher level routines is also available for to handle the reading and writing of such data. The code is closely based on that used in the CCP4 symmetry handling routines. However, in contrast to these, no messages are written by the routines themselves but all error conditions etc. are flagged for the calling program to report them in a manner it chooses.

The following sets of routines are available:

Set 'KSM' Symmetry Data
Get the Symmetry Data
List the Symmetry Data
Follow Symmetry Changes
Determining Systematic Absences
Conversion to Asymmetric Unit
Determination of Reflection Centricity
LIRL Convenience Routine

SET 'KSM' SYMMETRY DATA

Introduction

These routines handle the interpretation and storage of symmetry data.

The following routines are available:

Set symmetry - KSM_SET_SYMM
Reset default (undefined) symmetry - KSM_RESET

Set symmetry - KSM_SET_SYMM

The routine KSM_SET_SYMM is used to set symmetry data in the Keyword Symmetry Module.

 
Fortran call:
 
      SUBROUTINE KSM_SET_SYMM (VALSTR, IERR, ERRSTR)

 
Parameters:
 
 VALSTR    c  (R)   String. This may be one of the following:
                    CLEAR           Clears the current symmetry data
                    nspg            Space group code number
                    op1, op2, ...   Add the symmetry operations given
                                    to the current list of stored
                                    symmetry operators.
                    Note: The space group code and symmetry operation
                          definitions are those used in the CCP4 program
                          suite.
 IERR      i  (W)   Error flag =0 OK
                               =1 Invalid code or syntax error in string
 ERRSTR    c  (W)   Error description string if error found

Reset default (undefined) symmetry - KSM_RESET

This routine is used to resel the defaul (undefined) symmetry.

 
Fortran call:
 
      SUBROUTINE KSM_RESET

 
Parameters:
 
None

GET THE SYMMETRY DATA

Introduction

A special set of routines are required to retrieve symmetry information as the symmetry parameter data is more complex than for the other KSM parameters. Routines are also available to determine systematic absences, list symmetry operators and to set up the information to enable reflections to be assigned to a standard assymetric unit using CCP4 routines.

The following routines are available:

Get Full Symmetry Data - KSM_GET_SYMM
Get Basic Space Group Details - KSM_GET_SPGRP
Get Number of Symmetry Operators - KSM_GET_NSYM
Get the Crystal System and Lattice Type - KSM_GET_SYLAT

Get Full Symmetry Data - KSM_GET_SYMM

This routine is used to get the full symmetry detail including such items as the space group, point group and symmetry operator matrices.

 
Fortran call:
 
      SUBROUTINE KSM_GET_SYMM (NSPG, SPGNAME, PGNAME, NSYMMP, NSYMM,
     +                         RSM, RSMT, IFLAG)

 
Parameters:
 
 NSPG     i (W)   Space group number (will be 0 if symmetry operators 
                  were input explicitly.
 SPGNAME  c (W)   Space group name (will be blank if symmetry operators 
                  were input explicitly) (10 characters)
 PGNAME   c (W)   Point group name (10 characters)
 NSYMMP   i (W)   No. of primitive symmetry operators
 NSYMM    i (W)   Total number of symmetry operators (0 if symmetry not
                  defined)
 RSM()    r (W)   The NSYMM symmetry operators -  dimensioned (4,4,192)
 RSMT()   r (W)   The NSYMM inverted symmetry operators -dimensioned 
                  (4,4,192)
 IFLAG    i (W)   Flag = -1 undefined value
                       =  0 default value
                       =  1 value set explicitly
                       =  2 value set globally

Get Basic Space Group Details - KSM_GET_SPGRP

This routine renturns where possible the space group number and name and the number of primitive and total number of symmetry operators.

 
Fortran call:
 
      SUBROUTINE KSM_GET_SPGRP (NSPG, SPGNAME, NSYMMP, NSYMM)

 
Parameters:
 
 NSPG     i (W)   Space group number (will be 0 if symmetry operators were
                  input explicitly.
 SPGNAME  c  (W)  Space group name (will be blank if symmetry operators 
                  were input explicitly) (10 characters)
 NSYMMP   i (W)   No. of primitive symmetry operators
 NSYMM    i (W)   Total number of symmetry operators (0 if symmetry not
                  defined)

Get Number of Symmetry Operators - KSM_GET_NSYM

This routine returns the number of symmetry operators or 0 if no symmetry has been defined. This provides the simplest way of determining whether the symmetry has been defined.

 
Fortran call:
 
      SUBROUTINE KSM_GET_NSYM (NSYMM, IFLAG)

 
Parameters:
 
 NSYMM    i (W)   Total number of symmetry operators (0 if symmetry not
                  defined)
 IFLAG    i (W)   Flag =  0 default (undefined) value
                       =  1 value set explicitly

Get the Crystal System and Lattice Type - KSM_GET_SYLAT

This routine returns the crystal system type and lattice type if the symmetry has been defined via the space group number or name.

 
Fortran call:
 
      SUBROUTINE KSM_GET_SYLAT (SYST, LATT)

 
Parameters:
 
 SYST      c (W)  Crystal system (blank if symmetry not defined or 
                  defined using a set of operators and not via the 
                  space group number or name). Allow minimum of 12 
                  characters. Name wlll be returned in upper case. 
                  e.g. TRICLINIC, MONOCLINIC, ORTHORHOMBIC, 
                       TETRAGONAL, TRIGONAL, HEXAGONAL, CUBIC
 LATT      c (W)  Lattice type (blank if symmetry not defined or 
                  defined using a set of operators and not via the 
                  space group number or name). Allow minimum of 1 
                  characters. Name wlll be returned in upper case.
                  e.g. P, A, B, C, I, F, R

LIST THE SYMMETRY DATA

Introduction

Routines are available to give listings of the currently stored symmetry.

The following routines are available:

List Symmetry Data - KSM_SYMM_LIST
Write Symmetry Data Keyword Data - KSM_WRITESYMM

List Symmetry Data - KSM_SYMM_LIST

This routine lists the symmetry data including the space group number, name and point group (if known) and the symmetry operators to a file or a terminal.

 
Fortran call:
 
      SUBROUTINE KSM_SYMM_LIST (IUN, TERM)

 
Parameters:
 
 IUN   i (R)   Unit no. for listing o/p
 TERM  l (R)   .TRUE. o/p is to a terminal; .FALSE. o/p is to a file

Write Symmetry Data Keyword Data - KSM_WRITESYMM

This routine writes out the symmetry keyword data to a file or a terminal.

 
Fortran call:
 
      SUBROUTINE KSM_WRITESYMM (IUN, TERM)

 
Parameters:
 
 IUN   i (R)   Unit no. for listing o/p
 TERM  l (R)   .TRUE. o/p is to a terminal; .FALSE. o/p is to a file

FOLLOW SYMMETRY CHANGES

Introduction

In a similar manner to that used in the Keyword Data Module (KDM) and Laue Data Module (LDM) routines, facilities are available to track any changes made to the symmetry parameters during the operation of a program.

The following routines are available:

Reset symmetry changed flags - KSM_CH_RESET
Test symmetry changed flag - KSM_SYMM_CHANGED

Reset symmetry changed flags - KSM_CH_RESET

This routine is used to reset (cancel) the symmetry data changed flags for a requested channel or for all channels.

 
Fortran call:
 
      SUBROUTINE KSM_CH_RESET (ICHAN, IERR)

 
Parameters:
 
 ICHAN   i (R) Channel number for reset (1-16), 0 = all channels
 IERR    i (W) Invalid channel parameter

Test symmetry changed flag - KSM_SYMM_CHANGED

This routine is used to test the symmetry data changed flag set for a requested channel.

 
Fortran call:
 
      SUBROUTINE KSM_SYMM_CHANGED (ICHAN, IFLAG)

 
Parameters:
 
 ICHAN   i (R) Channel number for reset (1-16)
 IFLAG   i (W) Return flag =1  parameter value changed
                           =0  parameter value not changed
                           =-1 error in channel parameter

DETERMINING SYSTEMATIC ABSENCES

Introduction

Routines are available for determining whether or not a reflection is a systematic absence based on the currently stored symmetry data.

The following routines are available:

Check for Systematic Absence - KSM_SYSABS
Get Systematic Absence Based on H, K - KSM_SYSAHK

Check for Systematic Absence - KSM_SYSABS

This routine checks whether a given reflection is a systematic absence based on the symmetry information available. Its initial checks are based on the lattice type but it will then use the full symmetry information if this has been defined.

 
Fortran call:
 
        SUBROUTINE KSM_SYSABS (IH,IK,IL,ABSNT)

 
Parameters:
 
IH      i (R)     h index 
IK      i (R)     k index
IL      i (R)     l index
ABSNT   l (W)     returns =.TRUE. systematically absent, =.FALSE. not

Get Systematic Absence Based on H, K - KSM_SYSAHK

This is a variant on KSM_SYSABS and checks to see if a given 'h', 'k' reflection is absence regardless of 'l'. It only uses the lattice type and not the full symmetry.

 
Fortran call:
 
        SUBROUTINE KSM_SYSAHK (IH,IK,ABSNT)

 
Parameters:
 
IH       i (R)     h index 
IK       i (R)     k index
ABSNT    l (W)     returns =.TRUE. systematically absent, =.FALSE. not

CONVERSION TO ASYMMETRIC UNIT

Introduction

This routine prepares for the conversion of reflection indices to the asymmetric unit. It is equivalent to the CCP4 routine ASUSET but allows the internally stored symmetry to be accessed.

The following routines are available:

Prepare to Convert Indices to Assymetric Unit - KSM_AUSET

This routine calls the CCP4 routine ASUSET to prepare for converting indices to the asyymetric unit etc. using ASUPUT, ASUGET. The ASUSET routine is called via the KSM routine because it can access data stored internally within the Keyword Symmetry Module and avoid having to duplicate such data unnecessarily.

 
Fortran call:
 
      SUBROUTINE KSM_ASUSET (MLAUE)

 
Parameters:
 
MLAUE   i (W)   Returns the Laue group number

DETERMINATION OF REFLECTION CENTRICITY

Introduction

This routine prepares for the determination of the centricity of a reflection. It is equivalent to the CCP4 routine CENTRC but allows the internally stored symmetry to be accessed.

The following routines are available:

Prepare to Determine Centric Reflections - KSM_CENTRIC

This routine calls the CCP4 routine CENTRIC to prepare for determining whether a reflection is centric using the CENTR function. The CENTRIC routine is called via the KSM routine because it can access data stored internally within the Keyword Symmetry Module and avoid having to duplicate such data unnecessarily.

 
Fortran call:
 
      SUBROUTINE KSM_CENTRIC

 
Parameters:
 
None

LIRL CONVENIENCE ROUTINE

Introduction

A convenience routine is provided to pass the symmetry data from the KSM to a Laue Integrated Reflection List (LIRL)

The following routines are available:

Set Symmetry in LIRL - KSM_SYM_LIRL

This routine is a convenience routine is provided to pass the symmetry data from the KSM to a Laue Integrated Reflection List (LIRL). The routine LIRLF_SETSYM is called using the internally stored symmetry arrays.

 
Fortran call:
 
      SUBROUTINE KSM_SYM_LIRL (MINDX, IERR)

 
Parameters:
 
MINDX          i  (R)  Index as returned by LIRLF_INIT
IERR           i  (W)  Error return code =0  OK, =-1 Invalid index 
                       given or list not initialised

John W. Campbell
CCLRC Daresbury Laboratory
Last update 28 Jul 1997