Symmetry

Symmetry — Point symmetry handling

Synopsis

#include "symmetry.h"


typedef             SymOpList;
typedef             SymOpMask;

void                free_symoplist                      (SymOpList *ops);
int                 num_equivs                          (const SymOpList *ops,
                                                         const SymOpMask *m);
SymOpList *         get_pointgroup                      (const char *sym);
SymOpList *         parse_symmetry_operations           (const char *s);
void                add_symop                           (SymOpList *ops,
                                                         IntegerMatrix *m);
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);
IntegerMatrix *     get_symop                           (const SymOpList *ops,
                                                         const SymOpMask *m,
                                                         int idx);
void                special_position                    (const SymOpList *ops,
                                                         SymOpMask *m,
                                                         signed int h,
                                                         signed int k,
                                                         signed int l);
void                get_asymm                           (const SymOpList *ops,
                                                         signed int h,
                                                         signed int k,
                                                         signed int l,
                                                         signed int *hp,
                                                         signed int *kp,
                                                         signed int *lp);
SymOpList *         get_ambiguities                     (const SymOpList *source,
                                                         const SymOpList *target);
int                 is_subgroup                         (const SymOpList *source,
                                                         const SymOpList *target);

SymOpMask *         new_symopmask                       (const SymOpList *list);
void                free_symopmask                      (SymOpMask *m);

void                describe_symmetry                   (const SymOpList *s);
const char *        symmetry_name                       (const SymOpList *ops);
void                set_symmetry_name                   (SymOpList *ops,
                                                         const char *name);
char *              get_matrix_name                     (const IntegerMatrix *m,
                                                         int row);
int                 is_centrosymmetric                  (const SymOpList *s);
int                 is_centric                          (signed int h,
                                                         signed int k,
                                                         signed int l,
                                                         const SymOpList *ops);

Description

Routines to handle point symmetry.

Details

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').


free_symoplist ()

void                free_symoplist                      (SymOpList *ops);

Frees a SymOpList and all associated resources.

ops :

A SymOpList to free

num_equivs ()

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

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.

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.

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.

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.

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.

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().

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.

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);

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);

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.

m :

A SymOpMask to free

describe_symmetry ()

void                describe_symmetry                   (const SymOpList *s);

Writes the name and a list of operations to stderr.

s :

A SymOpList

symmetry_name ()

const char *        symmetry_name                       (const SymOpList *ops);

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.

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);

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.

h :

h index

k :

k index

l :

l index

ops :

A SymOpList

Returns :

true if h k l is centric in ops.