symmetry.h File Reference

Typedefs
typedef struct _symoplist	SymOpList
typedef struct _symopmask	SymOpMask

Functions
void	free_symoplist (SymOpList *ops)
SymOpList *	get_pointgroup (const char *sym)
SymOpMask *	new_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)
IntegerMatrix *	get_symop (const SymOpList *ops, const SymOpMask *m, int idx)
SymOpList *	get_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)
RationalMatrix *	parse_symmetry_operation (const char *s)
SymOpList *	parse_symmetry_operations (const char *s)
RationalMatrix *	parse_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

ops	A SymOpList
m	An IntegerMatrix

Adds m to ops.

describe_symmetry()

void describe_symmetry

(

const SymOpList *

s

)

Parameters

s	A SymOpList

Writes the name and a list of operations to stderr.

free_symoplist()

void free_symoplist

(

SymOpList *

ops

)

Parameters

ops	A SymOpList to free

Frees a SymOpList and all associated resources.

free_symopmask()

void free_symopmask

(

SymOpMask *

m

)

Parameters

m	A SymOpMask to free

Frees a SymOpMask and all associated resources.

get_ambiguities()

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

Parameters

source	The "source" symmetry, a SymOpList
target	The "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

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

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

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

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

sym	A 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

ops	A SymOpList
m	A SymOpMask
idx	Index 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

h	h index
k	k index
l	l index
ops	A 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

s	A SymOpList

Returns

Non-zero if s contains an inversion operation

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

)

new_symopmask:

Parameters

list	A 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

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.

parse_cell_transformation()

RationalMatrix* parse_cell_transformation

(

const char *

s

)

Parameters

s	Textual 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

s	Textual 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

ops	A SymOpList
name	New 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

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

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

ops	A SymOpList

Returns

A text description of ops.