From e62b303c7cdb32deecf94e29cf4a8369a9c805b7 Mon Sep 17 00:00:00 2001 From: Thomas White Date: Tue, 26 Jul 2011 18:02:27 +0200 Subject: Documentation and comments --- src/reflist-utils.c | 14 +++++++++++++- src/symmetry.c | 12 +++++++++++- 2 files changed, 24 insertions(+), 2 deletions(-) diff --git a/src/reflist-utils.c b/src/reflist-utils.c index 191c4bd9..a572faf7 100644 --- a/src/reflist-utils.c +++ b/src/reflist-utils.c @@ -263,7 +263,7 @@ void write_reflections_to_file(FILE *fh, RefList *list, UnitCell *cell) * The resulting list can be read back with read_reflections_from_file() or * read_reflections(). * - * This is a convenience function which simply opens @file and then calls + * This is a convenience function which simply opens @filename and then calls * write_reflections_to_file. * * Returns: zero on success, non-zero on failure. @@ -375,6 +375,18 @@ RefList *read_reflections(const char *filename) } +/** + * asymmetric_indices: + * @in: A %RefList + * @sym: A %SymOpList + * + * This function creates a newly allocated copy of @in, but indexed using the + * asymmetric indices according to @sym instead of the original indices. The + * original indices are stored and can be retrieved using + * get_symmetric_indices() if required. + * + * Returns: the new %RefList, or NULL on failure. + **/ RefList *asymmetric_indices(RefList *in, const SymOpList *sym) { Reflection *refl; diff --git a/src/symmetry.c b/src/symmetry.c index a978eff1..70820db2 100644 --- a/src/symmetry.c +++ b/src/symmetry.c @@ -1012,6 +1012,13 @@ void special_position(const SymOpList *ops, SymOpMask *m, * 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(). + * **/ void get_asymm(const SymOpList *ops, signed int h, signed int k, signed int l, @@ -1189,7 +1196,9 @@ int is_subgroup(const SymOpList *source, const SymOpList *target) * inversions. * To count the number of possibilities, use num_ops() on the result. * - * Returns: A %SymOpList containing the twinning operators + * 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. */ SymOpList *get_ambiguities(const SymOpList *source, const SymOpList *target) { @@ -1293,6 +1302,7 @@ SymOpList *get_ambiguities(const SymOpList *source, const SymOpList *target) free_symopmask(used); used = new_symopmask(src_reordered); + /* This is the first method from Flack (1987) */ for ( i=0; i