4.4.2 - Space Group Symmetry - JdlSymmetry

John W. Campbell

4.4.2.1 Introduction

This class provides an object to store and process space group symmetry. Where required, it can access the sets of symmetry operators encapsulated within the JdlSymops object; the code for this is automatically generated from a CCP4 symops.lib file using the MakeJdlSymops program. As well as setting/storing the symmetry data, the class has methods to determine systematic absences, reflection centricity and to put reflections into the asymmetric unit for the Laue group or retrieve measured indices. There are also static methods to determine whether a reflection lies in an asymmetric unit and to decode/encode symmetry operators.

Class, constructors and methods:

Class Details
Accessible Fields
Constructors
Setting the Symmetry Data
Get Space Group Identifier
Symmetry changed
Get Basic Symmetry
Absent and Centric Reflections
Reflections in Asymmetric Unit
Encode/Decode Symmetry Operator
List Symmetry Data

4.4.2.2 Class Details

Package:: Jdl.JdlPX;
Class name:: JdlSymmetry
Class definition:: public class JdlSymmetry
Extends:: Object
Implements:: none
Actions:: none

4.4.2.3 Accessible Fields

The following accessible fields have been defined:

int klass
int icentr
int[] iscrew
int hrng0
int krng0
int lrng0
int hrng1
int krng1
int lrng1

4.4.2.4 Constructors

4.4.2.4.1 Introduction

Constructors are available to construct an empty JdlSymmetry object or ones derived from a space group number or name.

Constructors:

Default Constructor
Construct from Space Group Number
Construct from Space Group Name

4.4.2.4.2 Default Constructor

Constructs an empty JdlSymmetry object.

Constructor Definition:: public JdlSymmetry()
Parameters List:: none

4.4.2.4.3 Construct from Space Group Number

Constructs a JdlSymmetry object for a given space group number.

Constructor Definition:

public JdlSymmetry(int nspgrp)

Parameters List:

nspgrp: The space group number (as specified in the symmetry operators file).

4.4.2.4.4 Construct from Space Group Name

Constructs a JdlSymmetry object for a given space group name.

Constructor Definition:

public JdlSymmetry(String spgnam)

Parameters List:

spgnam: The space group name (as specified in the symmetry operators file).

4.4.2.5 Setting the Symmetry Data

4.4.2.5.1 Introduction

This section has methods for parsing lines of symmetry data and setting or resetting the symmetry.

Methods:

Parse KDM symmetry line - parseSymmetryLine
Set or add symmetry - setSymmetry
Reset symmetry - resetSymmetry
Symmetry completed - isCompleted

4.4.2.5.2 Parse KDM symmetry line - parseSymmetryLine

This method is used to parse a symmetry data (starting with the SYMMETRY keyword) line from a keyworded data set based on the JdlKeywordDataModule object class e.g the Diffraction Data Module file based on the class and defined in the JdlRotationDataModule class. If the line contains symmetry data, then that data will be parsed and, if valid, stored in the JdlSymmetry object.

Method Definition:

public int parseSymmetryLine (String line, JdlError err)

Parameters List:

line: The line string from the input file being parsed.
err: Error return object. If an error was found 'err.err' will be returned as true, error messages will be set in 'err.msg1' (and 'err.msg2') and the flag 'err.flag' will be set as follows:
= 0, OK
= 1, Not a symmetry line
= 2, No non-blank tokens on line
= -1, Set was specified
= -2, Subset was specified
= -4, Invalid symmetry specification

Method Return:

Flag:
= 0, Symmetry OK
= 1, Not a symmetry line
= 2, No non-blank tokens on line
= -1, Set was specified

= -2, Subset was specified

= -4, Invalid symmetry specification
= -4 Invalid symmetry specification

4.4.2.5.3 Set or add symmetry - setSymmetry

This method sets the symmetry for a given space group number or name or adds the specified symmetry operator.

Method Definition:

public boolean setSymmetry (String valstr, JdlError err)

Parameters List:

valstr: The value string. This may be:
(a) a space-group number (single token on line)
(b) a space-group name, ie a string beginning P,I,R,F,A,B or C (single token on line)
(c) a symmetry operation (anything else)
err: Error return object. If an error was found 'err.err' will be returned as true, error messages will be set in 'err.msg1' (and 'err.msg2') and the flag 'err.flag' will be set as follows:
= 0, OK
= 1, Specified space group not found or data incomplete in stored symmetry data (JdlSymops)
= 2, Error in symmetry operator
= -1, No symmetry data given

Method Return:

true if OK, false if error

4.4.2.5.4 Reset symmetry - resetSymmetry

Resets the symmetry to 'undefined'.

Method Definition:: public void resetSymmetry()
Parameters List:: none

4.4.2.5.5 Symmetry completed - isCompleted

This methods returns a flag indicating whether or not the symmetry input was completed.

Method Definition:: public boolean isCompleted()
Parameters List:: none
Method Return:: True if the symmetry input was completed, otherwise false.

4.4.2.6 Get Space Group Identifier

4.4.2.6.1 Introduction

This section has methods to return how the space group was input and the space group number and name if available.

Methods:

Get input type - getInputType
Get space group number - getSpaceGroupNumber
Get space group name - getSpaceGroupName
No. of symmetry operators - numberOfSymmetryOperators
Get symmetry operator - getSymmetryOperator

4.4.2.6.2 Get input type - getInputType

This method returns a flag indicating how the symmetry was input.

Method Definition:: public int getInputType()
Parameters List:: none
Method Return:: The flag:
= 0, not input
= 1, input as space group number
= 2, input as space group name
= 3, input as operators

4.4.2.6.3 Get space group number - getSpaceGroupNumber

Returns the space group number if set.

Method Definition:: public int getSpaceGroupNumber()
Parameters List:: none
Method Return:: The space group number, 0 if not set.

4.4.2.6.4 Get space group name - getSpaceGroupName

Returns the space group name if set.

Method Definition:: public String getSpaceGroupName()
Parameters List:: none
Method Return:: The space group name, null if not set.

4.4.2.6.5 No. of symmetry operators - numberOfSymmetryOperators

This method returns the number of symmetry operators currently defined.

Method Definition:: public int numberOfSymmetryOperators()
Parameters List:: none
Method Return:: The number of suymmetry operators.

4.4.2.6.6 Get symmetry operator - getSymmetryOperator

This method returns a symmetry operator as a 4x4 matrix.

Method Definition:

public Jdl4x4 getSymmetryOperator(int isym)

Parameters List:

isym: The position of the symmetry operator in the list of operators from 1 to numberOfSymmetryOperators().

Method Return:

The symmetry matrix (null if isym out of range.

4.4.2.7 Symmetry changed

4.4.2.7.1 Introduction

The JdlSymmetry object enables changes of the symmetry to be tracked noting changes by setting flags (on up to 16 channels) when the symmetry is changed. This enables programs to check whether a calculation based on the symmetry to check whether a re-calculation is required.

Methods:

Reset changed flags - changedSymmetryReset
Test changed flags - symmetryChanged

4.4.2.7.2 Reset changed flags - changedSymmetryReset

Reset (cancel) the symmetry data changed flags for a requested channel or for all channels.

Method Definition:

public void changedSymmetryReset(int ichan)

Parameters List:

ichan: Channel number for reset (1-16), 0 = all channels.

4.4.2.7.3 Test changed flags - symmetryChanged

Tests a symmetry changed flag to see if the symmetry data has been changed since the flag was last reset (cleared). A change in any of the channels may also be tested in a single call to the method.

Method Definition:

public boolean symmetryChanged(int ichan)

Parameters List:

ichan: Channel number for test (1-16), 0 = all channels.

Method Return:

True if changed, false if not.

4.4.2.8 Get Basic Symmetry

4.4.2.8.1 Introduction

This set of methods return the crystal system, lattice type and Laue group number and name.

Methods:

Get system number - getSystem
Get lattice type - getLattice
Get Laue group name - getLaueName
Get Laue group number - getLaue

4.4.2.8.2 Get system number - getSystem

Get the crystal system number (1-7) Triclinic, Monoclinic, Orthorhombic, Tetragonal, Hexagonal, Rhombohedral, Cubic.

Method Definition:: public int getSystem()
Parameters List:: none
Method Return:: Returns the system number (1-7) Tri, Mon, Ort, Tet, Hex, Rho, Cub. Returns 0 if the symmetry was not set or completed.

4.4.2.8.3 Get lattice type - getLattice

This method returns the lattice type (1-7) for P, A, B, C, I, F, R lattices respecively.

Method Definition:: public int getLattice()
Parameters List:: none
Method Return:: Returns the lattice type number (1-7) P, A, B, C, I, F, R. Returns 0 if the symmetry was not set or completed.

4.4.2.8.4 Get Laue group name - getLaueName

This method returns the Laue group name as a String.

Method Definition:: public String getLaueName()
Parameters List:: none
Method Return:: Returns the Laue group name (blank if the symmetry was not set or completed).

4.4.2.8.5 Get Laue group number - getLaue

This method returns the Laue group as a number.

Method Definition:: public int getLaue()
Parameters List:: none
Method Return:: Returns the Laue group number (0 if symmetry not set or completed)

4.4.2.9 Absent and Centric Reflections

4.4.2.9.1 Introduction

This section has methods to check whether or not a given reflection is a systematic absence an whether it is a centric reflection.

Methods:

Systematic absence - systematicAbsence
Lattice systematic absence - systematicAbsHK
Centric reflection - isCentric
Centric reflection - isCentric
Centric reflection - isCentric
Reset harmonic details - resetHarmonicDetails

4.4.2.9.2 Systematic absence - systematicAbsence

Check for a systematic absence using the full symmetry.

Method Definition:

public boolean systematicAbsence(int ih, int ik, int il)

Parameters List:

ih: The 'h' index
ik: The 'k' index
il: The 'l' index

Method Return:

True if a systematic absence, false if not (or if the symmetry was not defined).

4.4.2.9.3 Lattice systematic absence - systematicAbsHK

This method checks for a systematic absence h, k whatever the l value using only lattice type.

Method Definition:

public boolean systematicAbsHK(int ih, int ik, int il)

Parameters List:

ih: The 'h' index
ik: The 'k' index
il: The 'l' index

Method Return:

True if a systematic absence, false if not.

4.4.2.9.4 Centric reflection - isCentric

This method tests to see if a reflection is centric based on the stored symmetry which must have been defined. Only use this version of the method if the symmetry data have already been verified.

Method Definition:

public boolean isCentric (int[] hkl)

Parameters List:

hkl: Array containing the reflection indices.

Method Return:

True if centric, otherwise false.

4.4.2.9.5 Centric reflection - isCentric

This method tests to see if a reflection is centric based on the stored symmetry which must have been defined. Only use this version of the method if the symmetry data have already been verified.

Method Definition:

public boolean isCentric (int h, int k, int l)

Parameters List:

h: 'h' index.
k: 'k' index.
l: 'l' index.

Method Return:

True if centric, otherwise false.

4.4.2.9.6 Centric reflection - isCentric

This method tests to see if a reflection is centric based on the stored symmetry which must have been defined.

Method Definition:

public boolean isCentric (int[] hkl, JdlError err)

Parameters List:

hkl: Array containing the reflection indices.
err: Error return object. If an error weas detected 'err.err' will be returned as true, a message will be returned in 'err.msg1' and 'err.flag' will be set as follows:
= 0, OK
= 1, Symmetry not properly set
= 2, Symmetry not defined

Method Return:

True if centric, otherwise false.

4.4.2.9.7 Reset harmonic details - resetHarmonicDetails

This method resets the harmonic increment and may reset the minimum and maximum harmonics for a Laue spot to be consistent with the systematic absences.

Method Definition:

public int resetHarmonicDetails(int nh, int nk, int nl, int[] harm)

Parameters List:

nh: The nodal 'h' index for the spot.
nk: The nodal 'k' index for the spot.
nl: The nodal 'l' index for the spot.
harm: A three element array with the harmonic data which are to be updated by the method. On returning from the method these array elements are updated as needed. The elements are the minimum harmonic, the maximum harmonic and the harmonic increment.

Method Return:

Returns the multiplicity; note that this could perhaps indicate that the spot is no longer a multiple (multiplicity = 1) or even that all the reflections in the range are absent (multiplicity = 0).

4.4.2.10 Reflections in Asymmetric Unit

4.4.2.10.1 Introduction

This section has methods to put a reflection into the appropriate asymmetric unit for the Laue group, to test if a reflection is in an asymmetric unit or to regenerate the original indices.

Methods:

Reflection into asymmetric unit - putIntoAsymmetricUnit
Is reflection in asymmetric unit - inAsymmetricUnit
Get measured indices - getOriginalIndices

4.4.2.10.2 Reflection into asymmetric unit - putIntoAsymmetricUnit

Puts a reflection into the asymmetric unit for the Laue group derived from the stored symmetry which must have been defined.

Method Definition:

public int putIntoAsymmetricUnit(int[] hkl_inp, int[] hkl_out, JdlError err)

Parameters List:

hkl_inp: input array containing h, k, l (measured).
hkl_out: output array containing h, k, l (in asymmetric unit).
err: Error return object. If an error weas detected 'err.err' will be returned as true, a message will be returned in 'err.msg1' and 'err.flag' will be set as follows:
= 0, OK
= 1, Cannot put reflection into asymmetric unit
= 2, Symmetry not defined

Method Return:

The number of the symmetry operation used, odd for I+, even for I- (the indices are returned inhkl_out).

4.4.2.10.3 Is reflection in asymmetric unit - inAsymmetricUnit

This is a static (class) method which may be used to determine if a reflection is within the asymmetric unit given the Laue group number.

Method Definition:

public static int inAsymmetricUnit (int[] ihkl, int nlaue)

Parameters List:

ihkl: Array containing h, k, l.
nlaue: The Laue group number.

Method Return:

Flag:
+1, if h k l chosen
-1, if -h-k-l chosen
0, if reflection is out-of-bounds

4.4.2.10.4 Get measured indices - getOriginalIndices

this method gets the original (measured) indices. This uses the internally stored and symmetry data to restore the original indices of a reflection from the unique indices and the symmetry number as determined from the putIntoAsymmetricUnit(..) method.

Method Definition:

public boolean getOriginalIndices(int[] hkl_inp, int isym, int[] hkl_out, JdlError err)

Parameters List:

hkl_inp: input array containing h, k, l (in asymmetric unit).
isym: The number of the symmetry operator used to put the reflection into the asymmetric unit (see putIntoAsymmetricUnit(..) method).
hkl_out: output array containing h, k, l (measured).
err: Error return object. If an error weas detected 'err.err' will be returned as true, a message will be returned in 'err.msg1' and 'err.flag' will be set as follows:
= 0, OK
= 1, Out of range symmetry number
= 2, Symmetry not defined

Method Return:

true if OK, false if not.

4.4.2.11 Encode/Decode Symmetry Operator

4.4.2.11.1 Introduction

This section has methods to decode or encode a symmetry operator from and to a String respectively.

Methods:

Decode operator - decodeSymmetryOperator
Encode operator - symmetryString
- symm_str

4.4.2.11.2 Decode operator - decodeSymmetryOperator

This static (class) method decodes a symmetry operator (real or reciprocal space) from its specification in character form (CCP4). e.g. X,1/2+Y,Z. The symmetry operator is returned in a 4x4 matrix.

Method Definition:

public static Jdl4x4 decodeSymmetryOperator (String symstr, JdlError err, JdlBoolean realsp)

Parameters List:

symstr: The string containing the symmetry operator.
err: Error return object. If an error weas detected 'err.err' will be returned as true, a message will be returned in 'err.msg1' and 'err.flag' will be set as follows:
= 0, OK
= 1, Error found - see error message ror details
realsp: This object is used to return a flag indicating whether the operator is for real space (true) or reciprocal space (false).

Method Return:

The symmetry operator in a 4x4 matrix.

4.4.2.11.3 Encode operator - symmetryString

This static (class) method encodes a symmetry operator string from a symmetry matrix into a string format (CCP4).

Method Definition:

public static String symmetryString(float[][] rm)

Parameters List:

rm: The 4x4 symmetry matrix in array form.

Method Return:

The string e.g. X,1/2+Y,Z.

4.4.2.11.4 - symm_str

Method Definition:: String symm_str(int isym)
Parameters List:: none

4.4.2.12 List Symmetry Data

4.4.2.12.1 Introduction

This section has a single method to list the contents of the object primarily for diagnostic purposes.

Method:

List contents - listContents

4.4.2.12.2 List contents - listContents

This method lists the contents of the object. The user has the option to choose whether or not the symmetry operators are to be listed in addition to the other symmetry details.

Method Definition:

public void listContents(boolean listops)

Parameters List:

listops: Set to true if the individual symmetry operators are to be listed, otherwise false.

⇑ Up 2 ⇑ Up 1 ⇑ Top of this