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
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 *	find_refl (const RefList *list, signed int h, signed int k, signed int l)

Reflection *	next_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_contributions *	get_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)

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)

const Reflection *	first_refl_const (const RefList list, RefListIterator *piter)

const Reflection *	next_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

list	A RefList
h	The 'h' index of the reflection
k	The 'k' index of the reflection
l	The '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

refl	Reflection
list	A RefList

Adds refl to list.

◆ copy_data()

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

Parameters

to	Reflection to copy data into
from	Reflection 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

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

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

list	A RefList to iterate over
piter	Address 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

list	A RefList to iterate over
piter	Address 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

refl	Reflection

Returns: the reflection's contribution list

◆ get_detector_pos()

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

Parameters

refl	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_esd_intensity()

double get_esd_intensity ( const Reflection * refl )

Parameters

refl	Reflection

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

refl	Reflection

Returns: the excitation error (in m^-1) for this reflection

◆ get_flag()

int get_flag ( const Reflection * refl )

Parameters

refl	Reflection

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

refl	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_intensity()

double get_intensity ( const Reflection * refl )

Parameters

refl	Reflection

Returns: The intensity of the reflection.

◆ get_khalf()

double get_khalf ( const Reflection * refl )

get_khalf

Parameters

refl	Reflection

Returns: the wavenumber at the centre of the reflection

◆ get_kpred()

double get_kpred ( const Reflection * refl )

Parameters

refl	Reflection

Returns: the wavenumber which should be used for prediction of this reflection

◆ get_lorentz()

double get_lorentz ( const Reflection * refl )

Parameters

refl	Reflection

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

refl	Reflection

Returns: the mean background level for this reflection.

◆ get_panel_number()

int get_panel_number ( const Reflection * refl )

Parameters

refl	Reflection

Returns: panel number (index in detgeom/DataTemplate structure) which the reflection appears on

◆ get_partiality()

double get_partiality ( const Reflection * refl )

Parameters

refl	Reflection

Returns: The partiality of the reflection. See get_lorentz().

◆ get_peak()

double get_peak ( const Reflection * refl )

Parameters

refl	Reflection

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

refl	Reflection
have_phase	Place 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

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

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

refl	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

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

refl	Reflection

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

refl	Reflection

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

refl	Reflection

Acquires a lock on the reflection.

◆ next_found_refl()

Reflection * next_found_refl ( Reflection * refl )

Parameters

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

refl	A reflection
iter	A 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

refl	A reflection
iter	A 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

list A RefList

Returns: the number of reflections in list.

◆ reflection_free()

void reflection_free ( Reflection * refl )

Parameters

refl	The reflection to free.

Destroys an individual reflection.

◆ reflection_new()

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

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

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

reflist	Reflection list
notes_add	Notes 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

list	The reflection list to free.

Destroys a reflection list.

◆ reflist_get_notes()

const char * reflist_get_notes ( RefList * reflist )

Parameters

reflist Reflection 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

refl	Reflection
contribs	Pointer 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

refl	Reflection
fs	The fast scan offset of the reflection
ss	The slow scan offset of the reflection

◆ set_esd_intensity()

void set_esd_intensity	(	Reflection *	refl,
		double	esd
	)

Parameters

refl	Reflection
esd	New standard error for this reflection's intensity measurement

◆ set_exerr()

void set_exerr	(	Reflection *	refl,
		double	exerr
	)

Parameters

refl	Reflection
exerr	The excitation error for the reflection

◆ set_flag()

void set_flag	(	Reflection *	refl,
		int	flag
	)

Parameters

refl	A Reflection
flag	New flag value
flag	is 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

refl	Reflection
intensity	The intensity for the reflection.

Set the intensity for the reflection.

◆ set_khalf()

void set_khalf	(	Reflection *	refl,
		double	khalf
	)

Parameters

refl	Reflection
khalf	The 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

refl	Reflection
kpred	The 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

refl	Reflection
L	The 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

refl	Reflection
mean_bg	New peak height for the reflection

◆ set_panel_number()

void set_panel_number	(	Reflection *	refl,
		int	pn
	)

Parameters

refl	Reflection
pn	Panel number (index in detgeom/DataTemplate structure) of the panel on which the reflection appears.

◆ set_partiality()

void set_partiality	(	Reflection *	refl,
		double	p
	)

Parameters

refl	Reflection
p	The partiality for the reflection.

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

◆ set_peak()

void set_peak	(	Reflection *	refl,
		double	peak
	)

Parameters

refl	Reflection
peak	New peak height for the reflection

◆ set_phase()

void set_phase	(	Reflection *	refl,
		double	phase
	)

Parameters

refl	Reflection
phase	New phase for the reflection

◆ set_redundancy()

void set_redundancy	(	Reflection *	refl,
		int	red
	)

Parameters

refl	Reflection
red	New 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

refl	Reflection
hs	The 'h' index of the reflection
ks	The 'k' index of the reflection
ls	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.

◆ set_temp1()

void set_temp1	(	Reflection *	refl,
		double	temp
	)

Parameters

refl	A Reflection
temp	New 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

refl	A Reflection
temp	New 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

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

refl	Reflection

Releases a lock on the reflection.

Data Structures

Macros

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ Reflection

◆ RefList

◆ RefListIterator

Function Documentation

◆ add_refl()

◆ add_refl_to_list()

◆ copy_data()

◆ find_refl()

◆ first_refl()

◆ first_refl_const()

◆ get_contributions()

◆ get_detector_pos()

◆ get_esd_intensity()

◆ get_exerr()

◆ get_flag()

◆ get_indices()

◆ get_intensity()

◆ get_khalf()

◆ get_kpred()

◆ get_lorentz()

◆ get_mean_bg()

◆ get_panel_number()

◆ get_partiality()

◆ get_peak()

◆ get_phase()

◆ get_redundancy()

◆ get_symmetric_indices()

◆ get_temp1()

◆ get_temp2()

◆ lock_reflection()

◆ next_found_refl()

◆ next_refl()

◆ next_refl_const()

◆ num_reflections()

◆ reflection_free()

◆ reflection_new()

◆ reflist_add_notes()

◆ reflist_free()

◆ reflist_get_notes()

◆ reflist_new()

◆ set_contributions()

◆ set_detector_pos()

◆ set_esd_intensity()

◆ set_exerr()

◆ set_flag()

◆ set_intensity()

◆ set_khalf()

◆ set_kpred()

◆ set_lorentz()

◆ set_mean_bg()

◆ set_panel_number()

◆ set_partiality()

◆ set_peak()

◆ set_phase()

◆ set_redundancy()

◆ set_symmetric_indices()

◆ set_temp1()

◆ set_temp2()

◆ tree_depth()

◆ unlock_reflection()