libcrystfel  0.10.1
Data Structures | Macros | Typedefs | Functions
reflist.h File Reference

Data Structures

struct  reflection_contributions
 

Macros

#define SERIAL(h, k, l)   ((((h)+512)<<20) + (((k)+512)<<10) + ((l)+512))
 
#define GET_H(serial)   ((((serial) & 0x3ff00000)>>20)-512)
 
#define GET_K(serial)   ((((serial) & 0x000ffc00)>>10)-512)
 
#define GET_L(serial)   (((serial) & 0x000003ff)-512)
 

Typedefs

typedef struct _reflist RefList
 
typedef struct _reflection Reflection
 
typedef struct _reflistiterator RefListIterator
 

Functions

RefListreflist_new (void)
 
void reflist_free (RefList *list)
 
Reflectionreflection_new (signed int h, signed int k, signed int l)
 
void reflection_free (Reflection *refl)
 
Reflectionfind_refl (const RefList *list, signed int h, signed int k, signed int l)
 
Reflectionnext_found_refl (Reflection *refl)
 
void get_detector_pos (const Reflection *refl, double *fs, double *ss)
 
int get_panel_number (const Reflection *refl)
 
double get_partiality (const Reflection *refl)
 
double get_khalf (const Reflection *refl)
 
double get_kpred (const Reflection *refl)
 
double get_exerr (const Reflection *refl)
 
double get_lorentz (const Reflection *refl)
 
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_temp1 (const Reflection *refl)
 
double get_temp2 (const Reflection *refl)
 
double get_esd_intensity (const Reflection *refl)
 
double get_phase (const Reflection *refl, int *have_phase)
 
double get_peak (const Reflection *refl)
 
double get_mean_bg (const Reflection *refl)
 
int get_flag (const Reflection *refl)
 
struct reflection_contributionsget_contributions (const Reflection *refl)
 
void copy_data (Reflection *to, const Reflection *from)
 
void set_detector_pos (Reflection *refl, double fs, double ss)
 
void set_panel_number (Reflection *refl, int pn)
 
void set_kpred (Reflection *refl, double kpred)
 
void set_khalf (Reflection *refl, double khalf)
 
void set_exerr (Reflection *refl, double exerr)
 
void set_partiality (Reflection *refl, double p)
 
void set_lorentz (Reflection *refl, double L)
 
void set_intensity (Reflection *refl, double intensity)
 
void set_redundancy (Reflection *refl, int red)
 
void set_temp1 (Reflection *refl, double temp)
 
void set_temp2 (Reflection *refl, double temp)
 
void set_esd_intensity (Reflection *refl, double esd)
 
void set_phase (Reflection *refl, double phase)
 
void set_peak (Reflection *refl, double peak)
 
void set_mean_bg (Reflection *refl, double mean_bg)
 
void set_symmetric_indices (Reflection *refl, signed int hs, signed int ks, signed int ls)
 
void set_flag (Reflection *refl, int flag)
 
void set_contributions (Reflection *refl, struct reflection_contributions *contribs)
 
Reflectionadd_refl (RefList *list, signed int h, signed int k, signed int l)
 
void add_refl_to_list (Reflection *refl, RefList *list)
 
Reflectionfirst_refl (RefList *list, RefListIterator **piter)
 
Reflectionnext_refl (Reflection *refl, RefListIterator *iter)
 
const Reflectionfirst_refl_const (const RefList *list, RefListIterator **piter)
 
const Reflectionnext_refl_const (const Reflection *refl, RefListIterator *iter)
 
int num_reflections (RefList *list)
 
int tree_depth (RefList *list)
 
void lock_reflection (Reflection *refl)
 
void unlock_reflection (Reflection *refl)
 
const char * reflist_get_notes (RefList *reflist)
 
void reflist_add_notes (RefList *reflist, const char *notes_add)
 

Detailed 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.

Typedef Documentation

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

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

◆ RefListIterator

typedef struct _reflistiterator RefListIterator

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

Function Documentation

◆ add_refl()

Reflection* add_refl ( RefList list,
signed int  h,
signed int  k,
signed int  l 
)
Parameters
listA RefList
hThe 'h' index of the reflection
kThe 'k' index of the reflection
lThe 'l' index of the reflection

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.

Returns
The newly created reflection, or NULL on failure.

◆ add_refl_to_list()

void add_refl_to_list ( Reflection refl,
RefList list 
)
Parameters
reflReflection
listA RefList

Adds refl to list.

◆ copy_data()

void copy_data ( Reflection to,
const Reflection from 
)
Parameters
toReflection to copy data into
fromReflection to copy data 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.

◆ find_refl()

Reflection* find_refl ( const RefList list,
signed int  h,
signed int  k,
signed int  l 
)
Parameters
listThe reflection list to search in
hThe 'h' index to search for
kThe 'k' index to search for
lThe 'l' index to search for

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.

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

◆ first_refl()

Reflection* first_refl ( RefList list,
RefListIterator **  piter 
)
Parameters
listA RefList to iterate over
piterAddress at which to store a RefListIterator

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.

Returns
the first reflection in the list.

◆ first_refl_const()

const Reflection* first_refl_const ( const RefList list,
RefListIterator **  piter 
)
Parameters
listA RefList to iterate over
piterAddress at which to store a RefListIterator

As first_refl(), except returns a const Reflection. Use this when you don't need to modify any of the reflections.

Returns
the first reflection in the list.

◆ get_contributions()

struct reflection_contributions* get_contributions ( const Reflection refl)
Parameters
reflReflection
Returns
the reflection's contribution list

◆ get_detector_pos()

void get_detector_pos ( const Reflection refl,
double *  fs,
double *  ss 
)
Parameters
reflReflection
fsLocation at which to store the fast scan offset of the reflection
ssLocation at which to store the slow scan offset of the reflection

◆ get_esd_intensity()

double get_esd_intensity ( const Reflection refl)
Parameters
reflReflection
Returns
the standard error in the intensity measurement (as returned by get_intensity()) for this reflection.

◆ get_exerr()

double get_exerr ( const Reflection refl)
Parameters
reflReflection
Returns
the excitation error (in m^-1) for this reflection

◆ get_flag()

int get_flag ( const Reflection refl)
Parameters
reflReflection

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

Returns
the flag for this reflection.

◆ get_indices()

void get_indices ( const Reflection refl,
signed int *  h,
signed int *  k,
signed int *  l 
)
Parameters
reflReflection
hLocation at which to store the 'h' index of the reflection
kLocation at which to store the 'k' index of the reflection
lLocation at which to store the 'l' index of the reflection

◆ get_intensity()

double get_intensity ( const Reflection refl)
Parameters
reflReflection
Returns
The intensity of the reflection.

◆ get_khalf()

double get_khalf ( const Reflection refl)

get_khalf

Parameters
reflReflection
Returns
the wavenumber at the centre of the reflection

◆ get_kpred()

double get_kpred ( const Reflection refl)
Parameters
reflReflection
Returns
the wavenumber which should be used for prediction of this reflection

◆ get_lorentz()

double get_lorentz ( const Reflection refl)
Parameters
reflReflection
Returns
The Lorentz factor for the reflection. To "scale up" a partial reflection, divide by this multiplied by the partiality.

◆ get_mean_bg()

double get_mean_bg ( const Reflection refl)
Parameters
reflReflection
Returns
the mean background level for this reflection.

◆ get_panel_number()

int get_panel_number ( const Reflection refl)
Parameters
reflReflection
Returns
panel number (index in detgeom/DataTemplate structure) which the reflection appears on

◆ get_partiality()

double get_partiality ( const Reflection refl)
Parameters
reflReflection
Returns
The partiality of the reflection. See get_lorentz().

◆ get_peak()

double get_peak ( const Reflection refl)
Parameters
reflReflection
Returns
the peak height (value of the highest pixel, before background subtraction) for this reflection.

◆ get_phase()

double get_phase ( const Reflection refl,
int *  have_phase 
)
Parameters
reflReflection
have_phasePlace to store a non-zero value if the phase is set, or NULL.
Returns
the phase for this reflection.

◆ get_redundancy()

int get_redundancy ( const Reflection refl)
Parameters
reflReflection

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.

Returns
the number of measurements of this reflection.

◆ get_symmetric_indices()

void get_symmetric_indices ( const Reflection refl,
signed int *  hs,
signed int *  ks,
signed int *  ls 
)
Parameters
reflReflection
hsLocation at which to store the 'h' index of the reflection
ksLocation at which to store the 'k' index of the reflection
lsLocation at which to store the 'l' index of the reflection

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.

◆ get_temp1()

double get_temp1 ( const Reflection refl)
Parameters
reflReflection

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

Returns
the first temporary value for this reflection.

◆ get_temp2()

double get_temp2 ( const Reflection refl)
Parameters
reflReflection

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

Returns
the second temporary value for this reflection.

◆ lock_reflection()

void lock_reflection ( Reflection refl)
Parameters
reflReflection

Acquires a lock on the reflection.

◆ next_found_refl()

Reflection* next_found_refl ( Reflection refl)
Parameters
reflA reflection returned by find_refl() or next_found_refl()

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

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

◆ next_refl()

Reflection* next_refl ( Reflection refl,
RefListIterator iter 
)
Parameters
reflA reflection
iterA RefListIterator

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

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

◆ next_refl_const()

const Reflection* next_refl_const ( const Reflection refl,
RefListIterator iter 
)
Parameters
reflA reflection
iterA RefListIterator

As next_refl(), except returns a const Reflection. Use this when you don't need to modify any of the reflections.

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

◆ num_reflections()

int num_reflections ( RefList list)
Parameters
listA RefList
Returns
the number of reflections in list.

◆ reflection_free()

void reflection_free ( Reflection refl)
Parameters
reflThe reflection to free.

Destroys an individual reflection.

◆ reflection_new()

Reflection* reflection_new ( signed int  h,
signed int  k,
signed int  l 
)
Parameters
hThe h index of the new reflection
kThe k index of the new reflection
lThe l index of the new reflection

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

◆ reflist_add_notes()

void reflist_add_notes ( RefList reflist,
const char *  notes_add 
)
Parameters
reflistReflection list
notes_addNotes to add

Appends the string notes_add to the notes field for reflist. The notes will be stored in the reflection list file by, e.g., write_reflist(), and are meant to be for humans to read. Possible uses include making a record of the command line arguments used to create the reflection list.

◆ reflist_free()

void reflist_free ( RefList list)
Parameters
listThe reflection list to free.

Destroys a reflection list.

◆ reflist_get_notes()

const char* reflist_get_notes ( RefList reflist)
Parameters
reflistReflection list
Returns
the notes field for reflist, or NULL if there are no notes. See reflist_add_notes() for more details.

◆ reflist_new()

RefList* reflist_new ( void  )

Creates a new reflection list.

Returns
the new reflection list, or NULL on error.

◆ set_contributions()

void set_contributions ( Reflection refl,
struct reflection_contributions contribs 
)
Parameters
reflReflection
contribsPointer to the contribution list

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

◆ set_detector_pos()

void set_detector_pos ( Reflection refl,
double  fs,
double  ss 
)
Parameters
reflReflection
fsThe fast scan offset of the reflection
ssThe slow scan offset of the reflection

◆ set_esd_intensity()

void set_esd_intensity ( Reflection refl,
double  esd 
)
Parameters
reflReflection
esdNew standard error for this reflection's intensity measurement

◆ set_exerr()

void set_exerr ( Reflection refl,
double  exerr 
)
Parameters
reflReflection
exerrThe excitation error for the reflection

◆ set_flag()

void set_flag ( Reflection refl,
int  flag 
)
Parameters
reflA Reflection
flagNew flag value
flagis an integer value which can be used according to the needs of the calling program.

◆ set_intensity()

void set_intensity ( Reflection refl,
double  intensity 
)
Parameters
reflReflection
intensityThe intensity for the reflection.

Set the intensity for the reflection.

◆ set_khalf()

void set_khalf ( Reflection refl,
double  khalf 
)
Parameters
reflReflection
khalfThe wavenumber at which the reflection should be predicted

Sets the wavenumber at the centre of the reflection.

◆ set_kpred()

void set_kpred ( Reflection refl,
double  kpred 
)
Parameters
reflReflection
kpredThe wavenumber at which the reflection should be predicted

Sets the wavenumber at which the reflection should be predicted. Used by predict_to_res() and update_predictions()

◆ set_lorentz()

void set_lorentz ( Reflection refl,
double  L 
)
Parameters
reflReflection
LThe Lorentz factor for the reflection.

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

◆ set_mean_bg()

void set_mean_bg ( Reflection refl,
double  mean_bg 
)
Parameters
reflReflection
mean_bgNew peak height for the reflection

◆ set_panel_number()

void set_panel_number ( Reflection refl,
int  pn 
)
Parameters
reflReflection
pnPanel number (index in detgeom/DataTemplate structure) of the panel on which the reflection appears.

◆ set_partiality()

void set_partiality ( Reflection refl,
double  p 
)
Parameters
reflReflection
pThe partiality for the reflection.

Set the partiality for the reflection. See set_lorentz().

◆ set_peak()

void set_peak ( Reflection refl,
double  peak 
)
Parameters
reflReflection
peakNew peak height for the reflection

◆ set_phase()

void set_phase ( Reflection refl,
double  phase 
)
Parameters
reflReflection
phaseNew phase for the reflection

◆ set_redundancy()

void set_redundancy ( Reflection refl,
int  red 
)
Parameters
reflReflection
redNew redundancy for the reflection

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.

◆ set_symmetric_indices()

void set_symmetric_indices ( Reflection refl,
signed int  hs,
signed int  ks,
signed int  ls 
)
Parameters
reflReflection
hsThe 'h' index of the reflection
ksThe 'k' index of the reflection
lsThe 'l' index of the reflection

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.

◆ set_temp1()

void set_temp1 ( Reflection refl,
double  temp 
)
Parameters
reflA Reflection
tempNew temporary value for the reflection

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

◆ set_temp2()

void set_temp2 ( Reflection refl,
double  temp 
)
Parameters
reflA Reflection
tempNew temporary value for the reflection

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

◆ tree_depth()

int tree_depth ( RefList list)
Parameters
listA RefList

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

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

◆ unlock_reflection()

void unlock_reflection ( Reflection refl)
Parameters
reflReflection

Releases a lock on the reflection.