Symmetry

Symmetry — Point symmetry handling

Functions

Types and Values

typedef SymOpList
typedef SymOpMask

Includes

#include "symmetry.h"

Description

Routines to handle point symmetry.

Functions

free_symoplist ()

void
free_symoplist (SymOpList *ops);

Frees a SymOpList and all associated resources.

Parameters

ops

A SymOpList to free

 

num_equivs ()

int
num_equivs (const SymOpList *ops,
            const SymOpMask *m);

Parameters

ops

A SymOpList

 

m

A SymOpMask, which has been shown to special_position()

 

Returns

the number of equivalent reflections for a general reflection in point group "ops", which were not flagged by your call to special_position().


get_pointgroup ()

SymOpList *
get_pointgroup (const char *sym);

This function parses sym and returns the corresponding SymOpList. In the string representation of the point group, use a preceding minus sign for any character which would have a "bar". Trigonal groups must be suffixed with either "_H" or "_R" for a hexagonal or rhombohedral lattice respectively.

Examples: -1 1 2/m 2 m mmm 222 mm2 4/m 4 -4 4/mmm 422 -42m -4m2 4mm 3_R -3_R 32_R 3m_R -3m_R 3_H -3_H 321_H 312_H 3m1_H 31m_H -3m1_H -31m_H 6/m 6 -6 6/mmm 622 -62m -6m2 6mm 23 m-3 432 -43m m-3m.

Parameters

sym

A string representation of a point group

 

parse_symmetry_operations ()

SymOpList *
parse_symmetry_operations (const char *s);

add_symop ()

void
add_symop (SymOpList *ops,
           IntegerMatrix *m);

Adds m to ops .

Parameters

ops

A SymOpList

 

m

An IntegerMatrix

 

get_equiv ()

void
get_equiv (const SymOpList *ops,
           const SymOpMask *m,
           int idx,
           signed int h,
           signed int k,
           signed int l,
           signed int *he,
           signed int *ke,
           signed int *le);

This function applies the idx -th symmetry operation from ops to the reflection h , k , l , and stores the result at he , ke and le .

Call this function multiple times with idx=0 .. num_equivs(ops, m) to get all of the equivalent reflections in turn.

If you don't mind that the same equivalent might appear twice, simply let m = NULL. Otherwise, call new_symopmask() and then special_position() to set up a SymOpMask appropriately.

Parameters

ops

A SymOpList

 

m

A SymOpMask, which has been shown to special_position()

 

idx

Index of the operation to use

 

h

index of reflection

 

k

index of reflection

 

l

index of reflection

 

he

location to store h index of equivalent reflection

 

ke

location to store k index of equivalent reflection

 

le

location to store l index of equivalent reflection

 

get_symop ()

IntegerMatrix *
get_symop (const SymOpList *ops,
           const SymOpMask *m,
           int idx);

This function returns a pointer to an integer matrix specifying a symmetry operation contained in the symmetry operator list, and identified by the specified index.

Parameters

ops

A SymOpList

 

m

A SymOpMask

 

idx

Index of the operation to get

 

special_position ()

void
special_position (const SymOpList *ops,
                  SymOpMask *m,
                  signed int h,
                  signed int k,
                  signed int l);

This function sets up m to contain information about which operations in ops map the reflection h , k , l onto itself.

Parameters

ops

A SymOpList, usually corresponding to a point group

 

m

A SymOpMask created with new_symopmask()

 

h

index of a reflection

 

k

index of a reflection

 

l

index of a reflection

 

get_asymm ()

void
get_asymm (const SymOpList *ops,
           signed int h,
           signed int k,
           signed int l,
           signed int *hp,
           signed int *kp,
           signed int *lp);

This function determines the asymmetric version of the reflection h , k , l in symmetry group ops , and puts the result in hp , kp , lp .

This is a relatively expensive operation because of its generality. Therefore, if you know you'll need to make repeated use of the asymmetric indices, consider creating a new RefList indexed according to the asymmetric indices themselves with asymmetric_indices(). If you do that, you'll still be able to get the original versions of the indices with get_symmetric_indices().

Parameters

ops

A SymOpList, usually corresponding to a point group

 

h

index of a reflection

 

k

index of a reflection

 

l

index of a reflection

 

hp

location for asymmetric index of reflection

 

kp

location for asymmetric index of reflection

 

lp

location for asymmetric index of reflection

 

get_ambiguities ()

SymOpList *
get_ambiguities (const SymOpList *source,
                 const SymOpList *target);

Calculates twinning laws. Returns a SymOpList containing the twinning operators, which are the symmetry operations which can be added to target to generate source . Only rotations are allowable - no mirrors nor inversions. To count the number of possibilities, use num_equivs() on the result.

The algorithm used is "Algorithm A" from Flack (1987), Acta Cryst A43 p564.

Parameters

source

The "source" symmetry, a SymOpList

 

target

The "target" symmetry, a SymOpList

 

Returns

A SymOpList containing the twinning operators, or NULL if the source symmetry cannot be generated from that target symmetry without using mirror or inversion operations.


is_subgroup ()

int
is_subgroup (const SymOpList *source,
             const SymOpList *target);

Parameters

source

A SymOpList

 

target

Another SymOpList, which might be a subgroup of source .

 

Returns

non-zero if every operation in target is also in source .


new_symopmask ()

SymOpMask *
new_symopmask (const SymOpList *list);

Parameters

list

A SymOpList

 

Returns

a new SymOpMask, which you can use when filtering out special reflections.


free_symopmask ()

void
free_symopmask (SymOpMask *m);

Frees a SymOpMask and all associated resources.

Parameters

m

A SymOpMask to free

 

describe_symmetry ()

void
describe_symmetry (const SymOpList *s);

Writes the name and a list of operations to stderr.

Parameters

s

A SymOpList

 

symmetry_name ()

const char *
symmetry_name (const SymOpList *ops);

Parameters

ops

A SymOpList

 

Returns

a text description of ops .


set_symmetry_name ()

void
set_symmetry_name (SymOpList *ops,
                   const char *name);

Sets the text description of ops to name . See symmetry_name(). name will be copied, so you can safely free it after calling this function, if that's otherwise appropriate.

Parameters

ops

A SymOpList

 

name

New name for the SymOpList

 

get_matrix_name ()

char *
get_matrix_name (const IntegerMatrix *m,
                 int row);

is_centrosymmetric ()

int
is_centrosymmetric (const SymOpList *s);

Parameters

s

A SymOpList

 

Returns

non-zero if s contains an inversion operation


is_centric ()

int
is_centric (signed int h,
            signed int k,
            signed int l,
            const SymOpList *ops);

A reflection is centric if it is related by symmetry to its Friedel partner.

Parameters

h

h index

 

k

k index

 

l

l index

 

ops

A SymOpList

 

Returns

true if h k l is centric in ops .

Types and Values

SymOpList

typedef struct _symoplist SymOpList;

The SymOpList is an opaque data structure containing a list of point symmetry operations. It could represent an point group or a list of indexing ambiguities (twin laws), or similar.


SymOpMask

typedef struct _symopmask SymOpMask;

The SymOpMask is an opaque data structure containing a list of flags associated with point symmetry operations in a specific SymOpList. It is used to filter the operations in the SymOpList to avoid duplicating equivalent reflections when the reflection is somehow special (e.g. 'hk0').