libcrystfel  0.10.1
Typedefs | Functions
symmetry.h File Reference

Typedefs

typedef struct _symoplist SymOpList
 
typedef struct _symopmask SymOpMask
 

Functions

void free_symoplist (SymOpList *ops)
 
SymOpListget_pointgroup (const char *sym)
 
SymOpMasknew_symopmask (const SymOpList *list)
 
void free_symopmask (SymOpMask *m)
 
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)
 
int num_equivs (const SymOpList *ops, const SymOpMask *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)
 
IntegerMatrixget_symop (const SymOpList *ops, const SymOpMask *m, int idx)
 
SymOpListget_ambiguities (const SymOpList *source, const SymOpList *target)
 
int is_subgroup (const SymOpList *source, const SymOpList *target)
 
int is_centrosymmetric (const SymOpList *s)
 
const char * symmetry_name (const SymOpList *ops)
 
void set_symmetry_name (SymOpList *ops, const char *name)
 
void describe_symmetry (const SymOpList *s)
 
int is_centric (signed int h, signed int k, signed int l, const SymOpList *ops)
 
void pointgroup_warning (const char *sym)
 
void add_symop (SymOpList *ops, IntegerMatrix *m)
 
RationalMatrixparse_symmetry_operation (const char *s)
 
SymOpListparse_symmetry_operations (const char *s)
 
RationalMatrixparse_cell_transformation (const char *s)
 
char * get_matrix_name (const IntegerMatrix *m, int row)
 

Detailed Description

Point group symmetry

Typedef Documentation

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

Function Documentation

◆ add_symop()

void add_symop ( SymOpList ops,
IntegerMatrix m 
)
Parameters
opsA SymOpList
mAn IntegerMatrix

Adds m to ops.

◆ describe_symmetry()

void describe_symmetry ( const SymOpList s)
Parameters
sA SymOpList

Writes the name and a list of operations to stderr.

◆ free_symoplist()

void free_symoplist ( SymOpList ops)
Parameters
opsA SymOpList to free

Frees a SymOpList and all associated resources.

◆ free_symopmask()

void free_symopmask ( SymOpMask m)
Parameters
mA SymOpMask to free

Frees a SymOpMask and all associated resources.

◆ get_ambiguities()

SymOpList* get_ambiguities ( const SymOpList source,
const SymOpList target 
)
Parameters
sourceThe "source" symmetry, a SymOpList
targetThe "target" symmetry, a SymOpList

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.

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.

◆ 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 
)
Parameters
opsA SymOpList, usually corresponding to a point group
hindex of a reflection
kindex of a reflection
lindex of a reflection
hplocation for asymmetric index of reflection
kplocation for asymmetric index of reflection
lplocation for asymmetric index of reflection

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.

◆ 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 
)
Parameters
opsA SymOpList
mA SymOpMask, which has been shown to special_position
idxIndex of the operation to use
hindex of reflection
kindex of reflection
lindex of reflection
helocation to store h index of equivalent reflection
kelocation to store k index of equivalent reflection
lelocation to store l index of equivalent reflection

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.

◆ get_pointgroup()

SymOpList* get_pointgroup ( const char *  sym)
Parameters
symA string representation of a point group

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.

◆ get_symop()

IntegerMatrix* get_symop ( const SymOpList ops,
const SymOpMask m,
int  idx 
)
Parameters
opsA SymOpList
mA SymOpMask
idxIndex of the operation to get

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.

The returned IntegerMatrix is owned by the SymOpList and must not be freed separately. It is valid as long as 'ops' exists.

◆ is_centric()

int is_centric ( signed int  h,
signed int  k,
signed int  l,
const SymOpList ops 
)
Parameters
hh index
kk index
ll index
opsA SymOpList

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

Returns
True if h k l is centric in ops.

◆ is_centrosymmetric()

int is_centrosymmetric ( const SymOpList s)
Parameters
sA SymOpList
Returns
Non-zero if s contains an inversion operation

◆ is_subgroup()

int is_subgroup ( const SymOpList source,
const SymOpList target 
)
Parameters
sourceA SymOpList
targetAnother 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)

new_symopmask:

Parameters
listA SymOpList
Returns
A new SymOpMask, which you can use when filtering out special reflections.

◆ num_equivs()

int num_equivs ( const SymOpList ops,
const SymOpMask m 
)
Parameters
opsA SymOpList
mA 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.

◆ parse_cell_transformation()

RationalMatrix* parse_cell_transformation ( const char *  s)
Parameters
sTextual representation of cell transformation

Parses s, for example 'a,(b+a)/2,c', and returns the corresponding RationalMatrix.

Returns
a RationalMatrix describing the transformation, or NULL on error.

◆ parse_symmetry_operations()

SymOpList* parse_symmetry_operations ( const char *  s)
Parameters
sTextual representation of a list of symmetry operations

Parses s, for example 'h,k,l;k,h,-l', and returns the corresponding SymOpList

Returns
a SymOpList, or NULL on error.

◆ set_symmetry_name()

void set_symmetry_name ( SymOpList ops,
const char *  name 
)
Parameters
opsA SymOpList
nameNew name for the SymOpList

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.

◆ special_position()

void special_position ( const SymOpList ops,
SymOpMask m,
signed int  h,
signed int  k,
signed int  l 
)
Parameters
opsA SymOpList, usually corresponding to a point group
mA SymOpMask created with new_symopmask
hindex of a reflection
kindex of a reflection
lindex of a reflection

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

◆ symmetry_name()

const char* symmetry_name ( const SymOpList ops)
Parameters
opsA SymOpList
Returns
A text description of ops.