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);
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);
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);
int                 is_centrosymmetric                  (const SymOpList *s);

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

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.

If you don't mind that the same equivalent might appear twice, simply call this function the number of times returned by num_ops(), using the actual point group. If repeating the same equivalent twice (for example, if the given reflection is a special high-symmetry one), call special_position() first to get a "specialised" SymOpList and use that instead.

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

special_position ()

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

This function determines which operations in ops map the reflection h, k, l onto itself, and uses m to flag the operations in ops which cause this.

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_ops() on the result.

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.

is_centrosymmetric ()

int                 is_centrosymmetric                  (const SymOpList *s);

s :

A SymOpList

Returns :

non-zero if s contains an inversion operation