spectrum.h File Reference

Data Structures
struct	gaussian

Typedefs
typedef struct _spectrum	Spectrum

Functions
Spectrum *	spectrum_new (void)
void	spectrum_free (Spectrum *s)
Spectrum *	spectrum_load (const char *filename)
void	spectrum_set_gaussians (Spectrum *s, struct gaussian *gs, int n_gauss)
int	spectrum_get_num_gaussians (Spectrum *s)
struct gaussian	spectrum_get_gaussian (Spectrum *s, int n)
void	spectrum_set_pdf (Spectrum *s, double *kcens, double *heights, int nbins)
void	spectrum_get_range (Spectrum *s, double *kmin, double *kmax)
double	spectrum_get_density_at_k (Spectrum *s, double k)
Spectrum *	spectrum_generate_tophat (double wavelength, double bandwidth)
Spectrum *	spectrum_generate_gaussian (double wavelength, double bandwidth)
Spectrum *	spectrum_generate_sase (double wavelength, double bandwidth, double spike_width, gsl_rng *rng)
Spectrum *	spectrum_generate_twocolour (double wavelength, double bandwidth, double separation)

Detailed Description

Data structure representing a radiation spectrum

Typedef Documentation

Spectrum

typedef struct _spectrum Spectrum

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

Function Documentation

spectrum_free()

void spectrum_free

(

Spectrum *

s

)

Parameters

s	A Spectrum

Frees a Spectrum.

spectrum_generate_gaussian()

Spectrum * spectrum_generate_gaussian	(	double	wavelength,
		double	bandwidth
	)

Parameters

wavelength	Wavelength in metres
bandwidth	Bandwidth as a fraction

Generates a Gaussian spectrum centered on 'wavelength', where the standard deviation of the Gaussian is bandwidth divided by wavelength (bandwidth fraction times k value).

Returns

A newly-allocated Spectrum, or NULL on error.

spectrum_generate_sase()

Spectrum * spectrum_generate_sase	(	double	wavelength,
		double	bandwidth,
		double	spike_width,
		gsl_rng *	rng
	)

Parameters

wavelength	Wavelength in metres
bandwidth	Bandwidth as a fraction of wavelength
spike_width	The width of the SASE spikes, as a fraction of wavelength
rng	A GSL random number generator

Generates a SASE spectrum centered on 'wavelength', with 15 spikes of width spike_width divided by wavelength (i.e. spike_width times k value). The spikes will be distributed within a width of k values of bandwidth divided by wavelength (bandwidth times k-value).

Note that CrystFEL is not an undulator simulation program. This function just simulates a rough idea of the kind of spiky spectrum resulting from the SASE process.

Returns

A newly-allocated Spectrum, or NULL on error.

spectrum_generate_tophat()

Spectrum * spectrum_generate_tophat	(	double	wavelength,
		double	bandwidth
	)

Parameters

wavelength	Wavelength in metres
bandwidth	Bandwidth as a fraction

Generates a top-hat spectrum centered on 'wavelength', where the width of the flat top is bandwidth/wavelength

Returns

A newly-allocated Spectrum, or NULL on error.

spectrum_generate_twocolour()

Spectrum * spectrum_generate_twocolour	(	double	wavelength,
		double	bandwidth,
		double	separation
	)

Parameters

wavelength	Wavelength in metres
bandwidth	Bandwidth as a fraction of wavelength
separation	Separation between peak centres, in m^-1

Generates a two-colour spectrum with Gaussian peaks centered at wavenumbers 1/wavelength ± separation/2. Each peak will have a standard deviation of bandwidth divided by wavelength (bandwidth fraction times k value).

Returns

A newly-allocated Spectrum, or NULL on error.

spectrum_get_density_at_k()

double spectrum_get_density_at_k	(	Spectrum *	s,
		double	k
	)

Parameters

s	A Spectrum
k	A wavenumber (in 1/metres)

Retrieves the spectral density at wavenumber k. This is a sample from a probability density function, so to calculate the "amount of intensity" from this, you'll need to multiply the value by a small width of k.

Returns

The density at k.

spectrum_get_gaussian()

struct gaussian spectrum_get_gaussian	(	Spectrum *	s,
		int	n
	)

Parameters

s	A Spectrum
n	The index number of the required Gaussian

Returns The n-th Gaussian in the spectrum. The Gaussians are returned in descending order of integrated intensity, indexed from zero.

If n is greater than or equal to the number of Gaussians in the spectrum, or if the spectrum is not represented as Gaussians, the returned Gaussian will have zero area.

Returns

The n-th Gaussian.

spectrum_get_num_gaussians()

int spectrum_get_num_gaussians

(

Spectrum *

s

)

Parameters

s	A Spectrum

Returns

The number of Gaussians in the spectrum, or zero if s is not currently represented as Gaussians.

spectrum_get_range()

void spectrum_get_range	(	Spectrum *	s,
		double *	kmin,
		double *	kmax
	)

Parameters

s	A Spectrum
kmin	Location to store minimum k value
kmax	Location to store maximum k value

Sets kmin and kmax to the range of k values in the spectrum. If the spectrum is represented as Gaussians, the range returned will be enough to contain at least 5 sigmas of all the Gaussians.

The values will be returned in units of 1/m.

spectrum_load()

Spectrum * spectrum_load

(

const char *

filename

)

Parameters

filename

Filename for the input file

Loads the spectrum from \s filename. Currently, only the ESRF spectrum file format is supported.

Returns

A newly allocated Spectrum, or NULL on error.

spectrum_new()

Spectrum * spectrum_new

(

void

)

Create a new Spectrum.

Returns

The new spectrum, or NULL on failure.

spectrum_set_gaussians()

void spectrum_set_gaussians	(	Spectrum *	s,
		struct gaussian *	gs,
		int	n_gauss
	)

Parameters

s	A Spectrum
gs	Pointer to array of gaussian structures
n_gauss	Number of Gaussians in gs

Sets the spectrum in terms of a sum of Gaussians.

The spectral density function will be normalised, so only the relative areas under the curves are relevant.

The input array will be copied, so you can safely free it after calling this function.

spectrum_set_pdf()

void spectrum_set_pdf	(	Spectrum *	s,
		double *	kvals,
		double *	heights,
		int	n
	)

Parameters

s	A Spectrum
kvals	Pointer to array of k values (in 1/m);
heights	Pointer to array of spectral density samples
n	Number of samples

Sets the spectrum in terms of samples of the probability density function. The spectral density function will be normalised. The spectrum can have a non-zero value only for k values in the range [kmin,kmax] (exclusive interval), where kmin and kmax are the smallest and largest values in kvals.

The input arrays will be copied, so you can safely free them after calling this function.