RefList

RefList — The fast reflection list

Synopsis

#include "reflist.h"


typedef             RefList;
typedef             Reflection;
typedef             RefListIterator;

RefList *           reflist_new                         (void);
void                reflist_free                        (RefList *list);
Reflection *        reflection_new                      (signed int h,
                                                         signed int k,
                                                         signed int l);
void                reflection_free                     (Reflection *refl);

Reflection *        add_refl                            (RefList *list,
                                                         signed int h,
                                                         signed int k,
                                                         signed int l);
void                add_refl_to_list                    (Reflection *refl,
                                                         RefList *list);

Reflection *        first_refl                          (RefList *list,
                                                         RefListIterator **piter);
Reflection *        next_refl                           (Reflection *refl,
                                                         RefListIterator *iter);

Reflection *        find_refl                           (const RefList *list,
                                                         signed int h,
                                                         signed int k,
                                                         signed int l);
Reflection *        next_found_refl                     (Reflection *refl);

double              get_excitation_error                (const Reflection *refl);
void                get_detector_pos                    (const Reflection *refl,
                                                         double *fs,
                                                         double *ss);
double              get_partiality                      (const Reflection *refl);
double              get_lorentz                         (const Reflection *refl);
void                get_partial                         (const Reflection *refl,
                                                         double *r1,
                                                         double *r2,
                                                         double *p,
                                                         int *clamp_low,
                                                         int *clamp_high);
void                get_indices                         (const Reflection *refl,
                                                         signed int *h,
                                                         signed int *k,
                                                         signed int *l);
void                get_symmetric_indices               (const Reflection *refl,
                                                         signed int *hs,
                                                         signed int *ks,
                                                         signed int *ls);
double              get_intensity                       (const Reflection *refl);
int                 get_redundancy                      (const Reflection *refl);
double              get_esd_intensity                   (const Reflection *refl);
double              get_phase                           (const Reflection *refl,
                                                         int *have_phase);
double              get_mean_bg                         (const Reflection *refl);
double              get_peak                            (const Reflection *refl);
double              get_temp1                           (const Reflection *refl);
double              get_temp2                           (const Reflection *refl);

void                set_detector_pos                    (Reflection *refl,
                                                         double exerr,
                                                         double fs,
                                                         double ss);
void                set_partiality                      (Reflection *refl,
                                                         double p);
void                set_lorentz                         (Reflection *refl,
                                                         double L);
void                set_partial                         (Reflection *refl,
                                                         double r1,
                                                         double r2,
                                                         double p,
                                                         double clamp_low,
                                                         double clamp_high);
void                set_intensity                       (Reflection *refl,
                                                         double intensity);
void                set_redundancy                      (Reflection *refl,
                                                         int red);
void                set_esd_intensity                   (Reflection *refl,
                                                         double esd);
void                set_phase                           (Reflection *refl,
                                                         double phase);
void                set_mean_bg                         (Reflection *refl,
                                                         double mean_bg);
void                set_peak                            (Reflection *refl,
                                                         double peak);
void                set_symmetric_indices               (Reflection *refl,
                                                         signed int hs,
                                                         signed int ks,
                                                         signed int ls);
void                set_temp1                           (Reflection *refl,
                                                         double temp);
void                set_temp2                           (Reflection *refl,
                                                         double temp);

void                copy_data                           (Reflection *to,
                                                         const Reflection *from);
int                 num_reflections                     (RefList *list);
int                 tree_depth                          (RefList *list);
void                lock_reflection                     (Reflection *refl);
void                unlock_reflection                   (Reflection *refl);
#define             GET_H                               (serial)
#define             GET_K                               (serial)
#define             GET_L                               (serial)
#define             SERIAL                              (h,
                                                         k,
                                                         l)

Description

The fast reflection list stores reflections in an RB-tree indexed by the Miller indices h, k and l. Any reflection can be found in a length of time which scales logarithmically with the number of reflections in the list.

A RefList can contain any number of reflections, and can store more than one reflection with a given set of indices, for example when two distinct reflections are to be stored according to their asymmetric indices.

There are getters and setters which can be used to get and set values for an individual reflection. The reflection list does not calculate any values, only stores what it was given earlier. As such, you will need to carefully examine which fields your prior processing steps have filled in.

Details

RefList

typedef struct _reflist RefList;

A RefList represents a list of Bragg reflections.

This data structure is opaque. You must use the available accessor functions to read and write its contents.


Reflection

typedef struct _reflection Reflection;

A Reflection represents a single Bragg reflection.

This data structure is opaque. You must use the available accessor functions to read and write its contents.


RefListIterator

typedef struct _reflistiterator RefListIterator;

A RefListIterator is an opaque data type used when iterating over a RefList.


reflist_new ()

RefList *           reflist_new                         (void);

Creates a new reflection list.

Returns :

the new reflection list, or NULL on error.

reflist_free ()

void                reflist_free                        (RefList *list);

Destroys a reflection list.

list :

The reflection list to free.

reflection_new ()

Reflection *        reflection_new                      (signed int h,
                                                         signed int k,
                                                         signed int l);

Creates a new individual reflection. You'll probably want to use add_refl_to_list() at some later point.

h :

The h index of the new reflection

k :

The k index of the new reflection

l :

The l index of the new reflection

reflection_free ()

void                reflection_free                     (Reflection *refl);

Destroys an individual reflection.

refl :

The reflection to free.

add_refl ()

Reflection *        add_refl                            (RefList *list,
                                                         signed int h,
                                                         signed int k,
                                                         signed int l);

Adds a new reflection to list. Note that the implementation allows there to be multiple reflections with the same indices in the list, so this function should succeed even if the given indices already feature in the list.

list :

A RefList

h :

The 'h' index of the reflection

k :

The 'k' index of the reflection

l :

The 'l' index of the reflection

Returns :

The newly created reflection, or NULL on failure.

add_refl_to_list ()

void                add_refl_to_list                    (Reflection *refl,
                                                         RefList *list);

Adds a refl to list.

refl :

A Reflection

list :

A RefList

first_refl ()

Reflection *        first_refl                          (RefList *list,
                                                         RefListIterator **piter);

This function sets up the state required for iteration over the entire list, and then returns the first reflection in the list. An iterator object will be created and its address stored at the location given in piter.

list :

A RefList to iterate over

piter :

Address at which to store a RefListIterator

Returns :

the first reflection in the list.

next_refl ()

Reflection *        next_refl                           (Reflection *refl,
                                                         RefListIterator *iter);

This function looks up the next reflection in the list that was given earlier to first_refl().

refl :

A reflection

iter :

A RefListIterator

Returns :

the next reflection in the list, or NULL if no more.

find_refl ()

Reflection *        find_refl                           (const RefList *list,
                                                         signed int h,
                                                         signed int k,
                                                         signed int l);

This function finds the first reflection in 'list' with the given indices.

Since a RefList can contain multiple reflections with the same indices, you may need to use next_found_refl() to get the other reflections.

list :

The reflection list to search in

h :

The 'h' index to search for

k :

The 'k' index to search for

l :

The 'l' index to search for

Returns :

The found reflection, or NULL if no reflection with the given indices could be found.

next_found_refl ()

Reflection *        next_found_refl                     (Reflection *refl);

This function returns the next reflection in refl's list with the same indices.

refl :

A reflection returned by find_refl() or next_found_refl()

Returns :

The found reflection, or NULL if there are no more reflections with the same indices.

get_excitation_error ()

double              get_excitation_error                (const Reflection *refl);

refl :

A Reflection

Returns :

The excitation error for the reflection.

get_detector_pos ()

void                get_detector_pos                    (const Reflection *refl,
                                                         double *fs,
                                                         double *ss);

refl :

A Reflection

fs :

Location at which to store the fast scan offset of the reflection

ss :

Location at which to store the slow scan offset of the reflection

get_partiality ()

double              get_partiality                      (const Reflection *refl);

refl :

A Reflection

Returns :

The partiality of the reflection. See get_lorentz().

get_lorentz ()

double              get_lorentz                         (const Reflection *refl);

refl :

A Reflection

Returns :

The Lorentz factor for the reflection. To "scale up" a partial reflection, divide by this multiplied by the partiality.

get_partial ()

void                get_partial                         (const Reflection *refl,
                                                         double *r1,
                                                         double *r2,
                                                         double *p,
                                                         int *clamp_low,
                                                         int *clamp_high);

This function is used during post refinement (in conjunction with set_partial()) to get access to the details of the partiality calculation.

refl :

A Reflection

r1 :

Location at which to store the first excitation error

r2 :

Location at which to store the second excitation error

p :

Location at which to store the partiality

clamp_low :

Location at which to store the first clamp status

clamp_high :

Location at which to store the second clamp status

get_indices ()

void                get_indices                         (const Reflection *refl,
                                                         signed int *h,
                                                         signed int *k,
                                                         signed int *l);

refl :

A Reflection

h :

Location at which to store the 'h' index of the reflection

k :

Location at which to store the 'k' index of the reflection

l :

Location at which to store the 'l' index of the reflection

get_symmetric_indices ()

void                get_symmetric_indices               (const Reflection *refl,
                                                         signed int *hs,
                                                         signed int *ks,
                                                         signed int *ls);

This function gives the symmetric indices, that is, the "real" indices before squashing down to the asymmetric reciprocal unit. This may be useful if the list is indexed according to the asymmetric indices, but you still need access to the symmetric version. This happens during post-refinement.

refl :

A Reflection

hs :

Location at which to store the 'h' index of the reflection

ks :

Location at which to store the 'k' index of the reflection

ls :

Location at which to store the 'l' index of the reflection

get_intensity ()

double              get_intensity                       (const Reflection *refl);

refl :

A Reflection

Returns :

The intensity of the reflection.

get_redundancy ()

int                 get_redundancy                      (const Reflection *refl);

The redundancy of the reflection is the number of measurements that have been made of it. Note that a redundancy of zero may have a special meaning, such as that the reflection was impossible to integrate. Note further that each reflection in the list has its own redundancy, even if there are multiple copies of the reflection in the list. The total number of reflection measurements should always be the sum of the redundancies in the entire list.

refl :

A Reflection

Returns :

the number of measurements of this reflection.

get_esd_intensity ()

double              get_esd_intensity                   (const Reflection *refl);

refl :

A Reflection

Returns :

the standard error in the intensity measurement (as returned by get_intensity()) for this reflection.

get_phase ()

double              get_phase                           (const Reflection *refl,
                                                         int *have_phase);

refl :

A Reflection

have_phase :

Place to store a non-zero value if the phase is set, or NULL.

Returns :

the phase for this reflection.

get_mean_bg ()

double              get_mean_bg                         (const Reflection *refl);

refl :

A Reflection

Returns :

the mean background level for this reflection.

get_peak ()

double              get_peak                            (const Reflection *refl);

refl :

A Reflection

Returns :

the peak height (value of the highest pixel, before background subtraction) for this reflection.

get_temp1 ()

double              get_temp1                           (const Reflection *refl);

The temporary values can be used according to the needs of the calling program.

refl :

A Reflection

Returns :

the first temporary value for this reflection.

get_temp2 ()

double              get_temp2                           (const Reflection *refl);

The temporary values can be used according to the needs of the calling program.

refl :

A Reflection

Returns :

the second temporary value for this reflection.

set_detector_pos ()

void                set_detector_pos                    (Reflection *refl,
                                                         double exerr,
                                                         double fs,
                                                         double ss);

refl :

A Reflection

exerr :

The excitation error for this reflection

fs :

The fast scan offset of the reflection

ss :

The slow scan offset of the reflection

set_partiality ()

void                set_partiality                      (Reflection *refl,
                                                         double p);

set_lorentz ()

void                set_lorentz                         (Reflection *refl,
                                                         double L);

Set the Lorentz factor for the reflection. To "scale up" a partial reflection, divide by this multiplied by the partiality.

refl :

A Reflection

L :

The Lorentz factor for the reflection.

set_partial ()

void                set_partial                         (Reflection *refl,
                                                         double r1,
                                                         double r2,
                                                         double p,
                                                         double clamp_low,
                                                         double clamp_high);

This function is used during post refinement (in conjunction with get_partial()) to get access to the details of the partiality calculation.

refl :

A Reflection

r1 :

The first excitation error

r2 :

The second excitation error

p :

The partiality

clamp_low :

The first clamp status

clamp_high :

The second clamp status

set_intensity ()

void                set_intensity                       (Reflection *refl,
                                                         double intensity);

Set the intensity for the reflection.

refl :

A Reflection

intensity :

The intensity for the reflection.

set_redundancy ()

void                set_redundancy                      (Reflection *refl,
                                                         int red);

The redundancy of the reflection is the number of measurements that have been made of it. Note that a redundancy of zero may have a special meaning, such as that the reflection was impossible to integrate. Note further that each reflection in the list has its own redundancy, even if there are multiple copies of the reflection in the list. The total number of reflection measurements should always be the sum of the redundancies in the entire list.

refl :

A Reflection

red :

New redundancy for the reflection

set_esd_intensity ()

void                set_esd_intensity                   (Reflection *refl,
                                                         double esd);

refl :

A Reflection

esd :

New standard error for this reflection's intensity measurement

set_phase ()

void                set_phase                           (Reflection *refl,
                                                         double phase);

refl :

A Reflection

phase :

New phase for the reflection

set_mean_bg ()

void                set_mean_bg                         (Reflection *refl,
                                                         double mean_bg);

refl :

A Reflection

mean_bg :

New peak height for the reflection

set_peak ()

void                set_peak                            (Reflection *refl,
                                                         double peak);

refl :

A Reflection

peak :

New peak height for the reflection

set_symmetric_indices ()

void                set_symmetric_indices               (Reflection *refl,
                                                         signed int hs,
                                                         signed int ks,
                                                         signed int ls);

This function gives the symmetric indices, that is, the "real" indices before squashing down to the asymmetric reciprocal unit. This may be useful if the list is indexed according to the asymmetric indices, but you still need access to the symmetric version. This happens during post-refinement.

refl :

A Reflection

hs :

The 'h' index of the reflection

ks :

The 'k' index of the reflection

ls :

The 'l' index of the reflection

set_temp1 ()

void                set_temp1                           (Reflection *refl,
                                                         double temp);

The temporary values can be used according to the needs of the calling program.

refl :

A Reflection

temp :

New temporary value for the reflection

set_temp2 ()

void                set_temp2                           (Reflection *refl,
                                                         double temp);

The temporary values can be used according to the needs of the calling program.

refl :

A Reflection

temp :

New temporary value for the reflection

copy_data ()

void                copy_data                           (Reflection *to,
                                                         const Reflection *from);

This function is used to copy the data (which is everything listed above in the list of getters and setters, apart from the indices themselves) from one reflection to another. This might be used when creating a new list from an old one, perhaps using the asymmetric indices instead of the raw indices for the new list.

to :

Reflection to copy data into

from :

Reflection to copy data from

num_reflections ()

int                 num_reflections                     (RefList *list);

list :

A RefList

Returns :

the number of reflections in list.

tree_depth ()

int                 tree_depth                          (RefList *list);

If the depth of the tree is more than about 20, access to the list will be slow. This should never happen.

list :

A RefList

Returns :

the depth of the RB-tree used internally to represent list.

lock_reflection ()

void                lock_reflection                     (Reflection *refl);

Acquires a lock on the reflection.

refl :

A Reflection

unlock_reflection ()

void                unlock_reflection                   (Reflection *refl);

Releases a lock on the reflection.

refl :

A Reflection

GET_H()

#define GET_H(serial) ((((serial) & 0x3ff00000)>>20)-512)

GET_K()

#define GET_K(serial) ((((serial) & 0x000ffc00)>>10)-512)

GET_L()

#define GET_L(serial) (((serial) & 0x000003ff)-512)

SERIAL()

#define SERIAL(h, k, l) ((((h)+512)<<20) + (((k)+512)<<10) + ((l)+512))