RefList

RefList — The fast reflection list

Functions

RefList * reflist_new ()
void reflist_free ()
Reflection * reflection_new ()
void reflection_free ()
Reflection * add_refl ()
void add_refl_to_list ()
Reflection * first_refl ()
Reflection * next_refl ()
Reflection * find_refl ()
Reflection * next_found_refl ()
void get_detector_pos ()
struct panel * get_panel ()
double get_partiality ()
double get_lorentz ()
void get_partial ()
void get_indices ()
void get_symmetric_indices ()
double get_intensity ()
int get_redundancy ()
double get_esd_intensity ()
double get_phase ()
double get_mean_bg ()
double get_peak ()
double get_temp1 ()
double get_temp2 ()
int get_flag ()
void set_detector_pos ()
void set_panel ()
void set_partiality ()
void set_lorentz ()
void set_partial ()
void set_intensity ()
void set_redundancy ()
void set_esd_intensity ()
void set_phase ()
void set_mean_bg ()
void set_peak ()
void set_symmetric_indices ()
void set_temp1 ()
void set_temp2 ()
void set_flag ()
void copy_data ()
int num_reflections ()
int tree_depth ()
void lock_reflection ()
void unlock_reflection ()
#define GET_H()
#define GET_K()
#define GET_L()
#define SERIAL()

Types and Values

typedef RefList
typedef Reflection
typedef RefListIterator

Includes

#include "reflist.h"

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.

Functions

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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 .

Parameters

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.

Parameters

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().

Parameters

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.

Parameters

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.

Parameters

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_detector_pos ()

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

Parameters

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_panel ()

struct panel *
get_panel (const Reflection *refl);

Parameters

refl

A Reflection

 

Returns

the panel which the reflection appears on


get_partiality ()

double
get_partiality (const Reflection *refl);

Parameters

refl

A Reflection

 

Returns

The partiality of the reflection. See get_lorentz().


get_lorentz ()

double
get_lorentz (const Reflection *refl);

Parameters

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 *rlow,
             double *rhigh,
             double *p);

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

Parameters

refl

A Reflection

 

rlow

Location at which to store the "low" excitation error

 

rhigh

Location at which to store the "high" excitation error

 

p

Location at which to store the partiality

 

get_indices ()

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

Parameters

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.

Parameters

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);

Parameters

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.

Parameters

refl

A Reflection

 

Returns

the number of measurements of this reflection.


get_esd_intensity ()

double
get_esd_intensity (const Reflection *refl);

Parameters

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);

Parameters

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);

Parameters

refl

A Reflection

 

Returns

the mean background level for this reflection.


get_peak ()

double
get_peak (const Reflection *refl);

Parameters

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.

Parameters

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.

Parameters

refl

A Reflection

 

Returns

the second temporary value for this reflection.


get_flag ()

int
get_flag (const Reflection *refl);

The integer flag value can be used according to the needs of the calling program.

Parameters

refl

A Reflection

 

Returns

the flag for this reflection.


set_detector_pos ()

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

Parameters

refl

A Reflection

 

fs

The fast scan offset of the reflection

 

ss

The slow scan offset of the reflection

 

set_panel ()

void
set_panel (Reflection *refl,
           struct panel *p);

Note that the pointer will be stored, not the contents of the structure.

Parameters

refl

A Reflection

 

p

Pointer to the panel structure on which the reflection appears

 

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.

Parameters

refl

A Reflection

 

L

The Lorentz factor for the reflection.

 

set_partial ()

void
set_partial (Reflection *refl,
             double rlow,
             double rhigh,
             double p);

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

Parameters

refl

A Reflection

 

rlow

The "low" excitation error

 

rhigh

The "high" excitation error

 

p

The partiality

 

set_intensity ()

void
set_intensity (Reflection *refl,
               double intensity);

Set the intensity for the reflection.

Parameters

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.

Parameters

refl

A Reflection

 

red

New redundancy for the reflection

 

set_esd_intensity ()

void
set_esd_intensity (Reflection *refl,
                   double esd);

Parameters

refl

A Reflection

 

esd

New standard error for this reflection's intensity measurement

 

set_phase ()

void
set_phase (Reflection *refl,
           double phase);

Parameters

refl

A Reflection

 

phase

New phase for the reflection

 

set_mean_bg ()

void
set_mean_bg (Reflection *refl,
             double mean_bg);

Parameters

refl

A Reflection

 

mean_bg

New peak height for the reflection

 

set_peak ()

void
set_peak (Reflection *refl,
          double peak);

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

refl

A Reflection

 

temp

New temporary value for the reflection

 

set_flag ()

void
set_flag (Reflection *refl,
          int flag);

flag is an integer value which can be used according to the needs of the calling program.

Parameters

refl

A Reflection

 

flag

New flag value

 

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.

Parameters

to

Reflection to copy data into

 

from

Reflection to copy data from

 

num_reflections ()

int
num_reflections (RefList *list);

Parameters

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.

Parameters

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.

Parameters

refl

A Reflection

 

unlock_reflection ()

void
unlock_reflection (Reflection *refl);

Releases a lock on the reflection.

Parameters

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))

Types and Values

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.