Difference between revisions of "Simulation"

From Horace
Jump to: navigation, search
 
(12 intermediate revisions by the same user not shown)
Line 13: Line 13:
 
</pre>
 
</pre>
  
<code>win</code> is the input dataset or array of datasets (sqw or dnd type) for which you wish to perform a simulation.
+
*<code>win</code> is the input dataset or array of datasets (sqw or dnd type) for which you wish to perform a simulation.
  
<code>myfunc</code> is the name of a user-defined function to calculate the intensity at the points in the dataset(s). The function must be of the form <code>y = mfunc(x1, x2, ..., xn, pars)</code>, e.g. <code>y = gauss2d(x1, x2, [amplitude, centre1, centre2, width1, width2, background])</code> and accept equal sized arrays that contain the x1, x2, ... values.
+
*<code>myfunc</code> is the name of a user-defined function to calculate the intensity at the points in the dataset(s). The function must be of the form <code>y = mfunc(x1, x2, ..., xn, p)</code>, e.g. <code>y = gauss2d(x1, x2, [amplitude, centre1, centre2, width1, width2, background])</code> and accept equal sized arrays that contain the x1, x2, ... values. <code>p</code> can be a row-vector containing the parameters needed by the function.
  
<code>p</code> can be a row-vector containing the parameters needed by the function. More generally it is a cell array containing information for the function <code>myfunc</code>.
+
The optional keyword <code>'all'</code> is used if you wish to calculate the intensity from the function over the whole domain covered by the input dataset. In other words, your dataset may contain gaps due to the trajectory of the detectors through reciprocal space, but you may wish to simulate the scattering even in the gaps. This option applies in the case of dnd objects, but not sqw objects.
  
The optional keyword <code>'all'</code> is used if you wish to calculate the intensity from the function over the whole domain covered by the input dataset. In other words, your dataset may contain gaps due to the trajectory of the detectors through reciprocal space, but you may wish to simulate the scattering even in the gaps.
 
  
 
==sqw_eval==
 
==sqw_eval==
Line 28: Line 27:
 
</pre>
 
</pre>
  
The syntax for <code>sqw</code> is almost identical to that of <code>func_eval</code>. The only difference is the form of the function required <code>my_sqw_func</code>.
+
The syntax for <code>sqw_eval</code> is almost identical to that of <code>func_eval</code>. The only difference is the form of the function required <code>my_sqw_func</code>, which '''must''' be of the form
 
+
<code>my_sqw_func</code> '''must''' be of the form  
+
  
 
<pre>
 
<pre>
Line 37: Line 34:
  
  
where <code>qh, qk, ql, en</code> area arrays that contain the co-ordinates in h, k, l and energy of every point in the dataset, irrespective of the dimensionality of that dataset. As before, <code>p</code> is a row-vector containing the parameters required by the function. Note that the output <code>weight</code> can take two possible forms. Normally it will be an array the same size as the input coordinates <code>qh, qk, ql, en</code>, however if there is more than one dispersion relation (e.g. from multiple domains) then <code>weight</code> can also be a cell array, where each element is an array the same size as <code>qh, qk, ql, en</code>.
+
where <code>qh, qk, ql, en</code> area arrays that contain the co-ordinates in h, k, l and energy of every point in the dataset, irrespective of the dimensionality of that dataset. As before, <code>p</code> is a row-vector containing the parameters required by the function. These could be the values of exchange constants, intensity scale factor, or temperature, for example.
  
 
One would generally use <code>sqw_eval</code> in preference to <code>func_eval</code> if, for example, one had a model of the spin-wave cross-section for magnetic scattering.
 
One would generally use <code>sqw_eval</code> in preference to <code>func_eval</code> if, for example, one had a model of the spin-wave cross-section for magnetic scattering.
 
  
  
Line 54: Line 50:
 
</pre>
 
</pre>
  
The output dataset (or cell array of data sets), <code>wdisp</code>, will retain only the Q axes, and the signal array(s) will contain the values of energy along the Q axes. If the dispersion relation returns the spectral weight, this will be placed in the error array (actually the square of the spectral weight is put in the error array). In the case when the dispersion has been calculated on a plane in momentum (i.e. wdisp is IX_datset_2d) then the plot function
+
The output dataset (or array of data sets), <code>wdisp</code>, will retain only the Q axes, and the signal array(s) will contain the values of energy along the Q axes. If the dispersion relation returns the spectral weight, this will be placed in the error array (actually the square of the spectral weight is put in the error array). In the case when the dispersion has been calculated on a plane in momentum (i.e. wdisp is IX_datset_2d) then the plot function
  
<code>ps2</code> (for plot_surface2)
+
<code>ds2</code> (for draw surface from two arrays)
  
 
<pre>
 
<pre>
ps2(wdisp)
+
ds2(wdisp)
 
</pre>
 
</pre>
  
Line 69: Line 65:
 
plot(my_qe_slice)
 
plot(my_qe_slice)
  
ploc(wdisp)
+
ploc(wdisp)       % for plot line on current
 
</pre>
 
</pre>
  
Note that in the above there must not be a ''keep'' command between plotting the QE slice and plotting the dispersion, since the <code>ploc</code> command works on the ''current'' figure.
+
Note that in the above there must not be a ''keep'' command between plotting the Q-E slice and plotting the dispersion, since the <code>ploc</code> command works on the ''current'' figure.
  
 
The dispersion relation is calculated at the bin centres (that is, the individual pixel information in a sqw input object is not used).
 
The dispersion relation is calculated at the bin centres (that is, the individual pixel information in a sqw input object is not used).
  
If the function that calculates dispersion relations produces more than one branch (i.e. the output of <code>dispreln</code> is a cell array of arrays), then in the case of a single input dataset the output will be an array
+
If the function that calculates dispersion relations produces more than one branch (i.e. the output of <code>dispreln</code> is a cell array of arrays), then in the case of a single input dataset the output will be an array of datasets, one for each branch. If the input is an array of datasets, then only the first dispersion branch will be returned, so there is one output dataset per input dataset.
of datasets, one for each branch. If the input is an array of datasets, then only the first dispersion branch will be returned, so there is one output dataset per input dataset.
+
  
 
Input:
 
Input:
  
<code>win</code> Dataset that provides the axes and points for the calculation. If one of the plot axes is energy transfer, then the output dataset
+
<code>win</code> Dataset (or array of datasets) that provides the axes and points for the calculation. If one of the plot axes is energy transfer, then the output dataset
 
will have dimensionality one less than the input dataset.
 
will have dimensionality one less than the input dataset.
  
 
<code>dispreln</code> Handle to function that calculates the dispersion relation w(Q). Must have form:
 
<code>dispreln</code> Handle to function that calculates the dispersion relation w(Q). Must have form:
<code>w = dispreln (qh,qk,ql,p)<code>
+
<code>w = dispreln (qh,qk,ql,p)</code>, or <code>[w,s] = dispreln (qh,qk,ql,p)</code>
  
where,
+
where
  
<code>qh,qk,ql<code> Arrays containing the coordinates of a set of points in reciprocal lattice units
+
*<code>qh,qk,ql</code> Arrays containing the coordinates of a set of points in reciprocal lattice units
  
<code>p</code> Vector of parameters needed by dispersion function , e.g. [A,js,gam] as intensity, exchange, lifetime
+
*<code>p</code> Vector of parameters needed by dispersion function , e.g. [A,js,gam] as intensity, exchange, lifetime
  
<code>w</code> Array of corresponding energies, or, if more than one dispersion relation, a cell array of arrays.
+
*<code>w</code> Array of corresponding energies, or, if more than one dispersion relation, a cell array of arrays.
  
The more general form is:
+
*<code>s</code> Array of corresponding spectral weights, or, if more than one dispersion relation, a cell array of arrays.
  
<code>w = dispreln (qh,qk,ql,p,c1,c2,..)</code>
+
The more general form is: <code>w = dispreln (qh,qk,ql,p,c1,c2,..)</code>, or <code>[w,s] = dispreln (qh,qk,ql,p,c1,c2,..)</code>
  
where,
+
where
  
<code>p</code> Typically a vector of parameters that we might want to fit in a least-squares algorithm
+
*<code>p</code> Typically a vector of parameters that we might want to fit in a least-squares algorithm
  
<code>c1,c2,...</code> Other constant parameters e.g. file name for look-up table
+
*<code>c1,c2,...</code> Other constant parameters e.g. file name for look-up table
  
<code>p</code> Arguments needed by the function. Most commonly, a vector of parameter values e.g. [A,js,gam] as intensity, exchange, lifetime. If a more general
+
<code>p</code> Arguments needed by the function that calculates the dispersion relation(s). Most commonly, a vector of parameter values e.g. [A,js,gam] as intensity, exchange, lifetime. If a more general set of parameters is required by the dispersion relation function, then package these into a cell array {p, c1, c2, ...}.
set of parameters is required by the function, then package these into a cell array and pass that as pars. In the example above then pars = {p, c1, c2, ...}
+
  
  
Line 124: Line 118:
  
 
<pre>
 
<pre>
wout = disp2sqw_eval(win,dispreln,pars,fwhh,<Optional input parameters>)
+
wout = disp2sqw_eval(win,@dispreln,pars,fwhh,<Optional input parameters>)
 
</pre>  
 
</pre>  
  
<code>win</code> is the input dataset (sqw or dnd)
+
<code>win</code> is the input dataset (sqw or dnd) or array of datasets
  
<code>dispreln</code> is a function of the form <code>[omega,s] = dispreln (qh,qk,ql,p)</code>, or more generally <code>[w,s] = dispreln (qh,qk,ql,p,c1,c2,..)</code>, where in addition to the coordinates <code>qh, qk, ql</code> and model input parameters <code>p</code>, some extra information contained in the data structures (cell arrays, vectors, structure arrays, etc) <code>c1, c2, ...</code> is supplied. The outputs <code>omega</code> and <code>s</code> are the dispersion and spectral weight respectively. These are cell arrays of arrays if there is more than one branch of the dispersion.
+
<code>dispreln</code> is a function of the form <code>[w,s] = dispreln (qh,qk,ql,p)</code>, or more generally <code>[w,s] = dispreln (qh,qk,ql,p,c1,c2,..)</code>, where in addition to the coordinates <code>qh, qk, ql</code> and model input parameters <code>p</code>, some extra information contained in the data structures (cell arrays, vectors, structure arrays, etc) <code>c1, c2, ...</code> is supplied. The outputs <code>w</code> and <code>s</code> are the dispersion and spectral weight respectively. These are cell arrays of arrays if there is more than one branch of the dispersion.
  
 
<code>pars</code> is the input parameters to the function. If this is just <code>p</code> then <code>pars = p</code>, but if extra parameters are required then <code>pars = {p, c1, c2, ...}</code>, i.e. <code>pars</code> is a cell array.
 
<code>pars</code> is the input parameters to the function. If this is just <code>p</code> then <code>pars = p</code>, but if extra parameters are required then <code>pars = {p, c1, c2, ...}</code>, i.e. <code>pars</code> is a cell array.
Line 143: Line 137:
 
The output is:
 
The output is:
  
<code>wout</code> - Output dataset or cell array of datasets
+
<code>wout</code> - Output dataset or array of datasets
 +
 
  
 
==dispersion_plot==
 
==dispersion_plot==
Line 150: Line 145:
 
   
 
   
 
<pre>
 
<pre>
dispersion_plot(rlp,dispreln,pars)
+
dispersion_plot(rlp,@dispreln,pars)
  
dispersion_plot(lattice,rlp,dispreln,pars)
+
dispersion_plot(lattice,rlp,@dispreln,pars)
 
   
 
   
 
dispersion_plot(...,'dispersion') % plot dispersion only
 
dispersion_plot(...,'dispersion') % plot dispersion only
Line 174: Line 169:
 
<code>rlp</code> Array of reciprocal lattice points, e.g. [0,0,0; 0,0,1; 0,-1,1; 1,-1,1; 1,0,1; 1,0,0];
 
<code>rlp</code> Array of reciprocal lattice points, e.g. [0,0,0; 0,0,1; 0,-1,1; 1,-1,1; 1,0,1; 1,0,0];
 
   
 
   
<code>dispreln</code> Handle to function (e.g. <code>@my_function</code>) that calculates the dispersion relation w(Q) and spectral weight, S(Q).
+
<code>@dispreln</code> Handle to a Matlab function <code>dispreln</code>) that calculates the dispersion relation w(Q) and spectral weight, S(Q).
 
The most commonly used form is:
 
The most commonly used form is:
  
Line 181: Line 176:
 
where,
 
where,
  
<code>qh,qk,ql</code>    Arrays containing the coordinates of a set of points in reciprocal lattice units
+
*<code>qh,qk,ql</code>    Arrays containing the coordinates of a set of points in reciprocal lattice units
  
<code>p</code>          Vector of parameters needed by dispersion function e.g. [A,js,gam] as intensity, exchange, lifetime
+
*<code>p</code>          Vector of parameters needed by dispersion function e.g. [A,js,gam] as intensity, exchange, lifetime
  
<code>w</code>          Array of corresponding energies, or, if more than one dispersion relation, a cell array of arrays.
+
*<code>w</code>          Array of corresponding energies, or, if more than one dispersion relation, a cell array of arrays.
  
<code>s</code>          Array of spectral weights, or, if more than one dispersion relation, a cell array of arrays.
+
*<code>s</code>          Array of spectral weights, or, if more than one dispersion relation, a cell array of arrays.
 
   
 
   
 
The more general form is:
 
The more general form is:
Line 195: Line 190:
 
where,
 
where,
  
<code>p</code>          Typically a vector of parameters that we might want to fit in a least-squares algorithm
+
*<code>p</code>          Typically a vector of parameters that we might want to fit in a least-squares algorithm
  
<code>c1,c2,...</code>  Other constant parameters e.g. file name for look-up table.
+
*<code>c1,c2,...</code>  Other constant parameters e.g. file name for look-up table.
 
      
 
      
<code>pars</code>        Arguments needed by the function. Most commonly, a vector of parameter values e.g. [A,js,gam] as intensity, exchange, lifetime. If a more general set of parameters is required by the function, then package these into a cell array and pass that as pars. In the exampleabove then pars = {p, c1, c2, ...}
+
<code>pars</code>        Arguments needed by the function that calculates the dispersion relation. Most commonly, a vector of parameter values e.g. [A,js,gam] as intensity, exchange, lifetime. If a more general set of parameters is required by the function, then package these into a cell array and pass that as pars. In the example above then pars = {p, c1, c2, ...}
 
   
 
   
 
   
 
   
Line 224: Line 219:
 
==disp2sqw_plot==
 
==disp2sqw_plot==
  
Generate a plot of a dispersion relation (a subset of <code>dispersion_plot</code>)
+
Generate an Q-E intensity plot for a dispersion relation along a path in reciprocal space. The function is very closely related to <code>dispersion_plot</code>), and most of the input arguments and options are the same for the two functions.
  
 
<pre>
 
<pre>
disp2sqw_plot(rlp,dispreln,pars,ebins,fwhh)
+
disp2sqw_plot(rlp,@dispreln,pars,ebins,fwhh)
</pre>
+
  
OR
+
disp2sqw_plot(lattice,rlp,@dispreln,pars,ebins,fwhh)
 +
 +
disp2sqw_plot(...,'labels',{'G','X',...})  % customised labels at the positions of the rlp
 +
 
 +
disp2sqw_plot(...,'ndiv',n)  % plot with number of points per interval other than the default
 +
 +
weight=disp2sqw_plot(...)  % output IX_dataset_2d with spectral weight
 +
 
 +
weight=disp2sqw_plot(...,'noplot') % output array without plotting
  
<pre>
 
weight=disp2sqw_plot(lattice,rlp,dispreln,pars,ebins,fwhh,'ndiv',n,'noplot')
 
 
</pre>
 
</pre>
 +
 +
The inputs are as follows:
  
<code>rlp</code> is an array of reciprocal lattice points between which the dispersion relation will be calculated - e.g. <code>[0,0,0; 0,0,1; 0,-1,1; 1,-1,1; 1,0,1; 1,0,0]</code>.
+
<code>lattice</code> [optional] Lattice parameters [a,b,c,alpha,beta,gamma]  (Angstrom, degrees). Default is [2*pi,2*pi,2*pi,90,90,90]
 +
 +
<code>rlp</code> Array of reciprocal lattice points, e.g. [0,0,0; 0,0,1; 0,-1,1; 1,-1,1; 1,0,1; 1,0,0];
 +
 +
<code>@dispreln</code> Handle to a Matlab function <code>dispreln</code>) that calculates the dispersion relation w(Q) and spectral weight, S(Q).
 +
The most commonly used form is:
  
<code>dispreln</code>  is a handle to a function that calculates the dispersion relation w(Q) and spectral weight, s(Q). It must have the following form:
+
<code>[w,s] = dispreln (qh,qk,ql,p)</code>
  
<pre>
+
where,
[w,sfact] = dispreln (qh,qk,ql,p)
+
</pre>
+
  
where <code>qh,qk,ql,</code> are arrays containing the coordinates of a set of points in reciprocal lattice units, <code>p</code>is a vector of parameters needed by dispersion function. The output <code>w</code> is an array of corresponding energies, or, if more than one dispersion relation is called, a cell array of arrays. <code>sfact</code> is the correspondent to <code>w</code> array of structure factors (see below).
+
*<code>qh,qk,ql</code>   Arrays containing the coordinates of a set of points in reciprocal lattice units
  
<code>pars</code> are the parameters <code>p</code> mentioned above.
+
*<code>p</code>           Vector of parameters needed by dispersion function e.g. [A,js,gam] as intensity, exchange, lifetime
  
<code>ebins</code> gives the energy grid on which the dispersion will be plotted. Is given by a vector of the form <code>[energy_lo,step,energy_hi]</code>.
+
*<code>w</code>           Array of corresponding energies, or, if more than one dispersion relation, a cell array of arrays.
  
<code>fwhh</code> is a scalar which gives the width of Gaussian broadening in energy applied to the dispersion relation - i.e. a very crude way of approximating the effect of resolution.
+
*<code>s</code>           Array of spectral weights, or, if more than one dispersion relation, a cell array of arrays.
 +
 +
The more general form is:
 +
                   
 +
<code>[w,s] = dispreln (qh,qk,ql,p,c1,c2,..)</code>
  
There are some additional optional inputs and outputs.
+
where,
  
<code>'noplot'</code> can be used when an output object is specified, and you do not wish to plot it.
+
*<code>p</code>           Typically a vector of parameters that we might want to fit in a least-squares algorithm
  
<code>'ndiv'</code> is a scalar specifying the number of points between adjacent q-points in the list <code>rlp</code>.
+
*<code>c1,c2,...</code>   Other constant parameters e.g. file name for look-up table.
 +
   
 +
<code>pars</code>        Arguments needed by the function that calculates the dispersion relation. Most commonly, a vector of parameter values e.g. [A,js,gam] as intensity, exchange, lifetime. If a more general set of parameters is required by the function, then package these into a cell array and pass that as pars. In the example above then pars = {p, c1, c2, ...}
 +
 +
<code>ebins</code>      Defines the energy bin centres: a three-vector [ecentre_lo, bin_width, ecentre_hi]
 +
 
 +
<code>fwhh</code>        Full width half height of broadening applied to the dispersion to produce the intensity map
 +
 +
The keyword options (which can be abbreviated to single letter) are:
 +
 +
<code>'labels'</code>    Tick labels to place at the positions of the Q points in argument rlp. e.g. {'G','X','M','R'}. By default the labels are character representations of rlp, e.g. {0,0,0; 0.5,0,0; 0.5,0.5,0; 0.5,0.5,0.5} becomes {'0,0,0', '0.5,0,0', '0.5,0.5,0', '0.5,0.5,0.5'}
 +
 +
<code>'ndiv'</code>   Number of points into which to divide the interval between two r.l.p. (default=100)
 +
 +
<code>'noplot'</code>    Do not plot, just return the output IX_dataset_1d (see below)
 +
 +
 +
The output is as follows:   
 +
 +
<code>weight</code>      IX_dataset_2d containing the spectra weight. The x-axis is the distance in Ang^-1 along the path described
  
The output <code>weight</code> is a generic Herbert IX_dataset_2d object corresponding to the Q-E dispersion plot.
 
  
 
The image intensity, as the function of '''Q''' along the rlp path alonx x-axis and the energy transfer along y-axis is determined by the equation:
 
The image intensity, as the function of '''Q''' along the rlp path alonx x-axis and the energy transfer along y-axis is determined by the equation:
Line 265: Line 292:
 
where
 
where
 
         sig = fwhh/sqrt(log(256));
 
         sig = fwhh/sqrt(log(256));
 
See example of script to plot dispersion [http://horace.isis.rl.ac.uk/Script_for_making_simulations#Plotting_dispersion here.]
 

Latest revision as of 17:45, 18 January 2019

There are a variety of simulation tools available in Horace, so that if you have a theoretical model to describe your data you can simulate the results for the specific data points that you measured.

IMPORTANT When simulating an S(Q,w) model (see sqw_eval below), bear in mind the difference between what is calculated for equivalent dnd and sqw datasets. See FAQ.


func_eval

This evaluates a user-supplied function at the x, y, z, ... values of an n-dimensional dataset, or array of datasets. The syntax is as follows:

wout = func_eval(win, @myfunc, p);
wout = func_eval(win, @myfunc, p, 'all');
  • win is the input dataset or array of datasets (sqw or dnd type) for which you wish to perform a simulation.
  • myfunc is the name of a user-defined function to calculate the intensity at the points in the dataset(s). The function must be of the form y = mfunc(x1, x2, ..., xn, p), e.g. y = gauss2d(x1, x2, [amplitude, centre1, centre2, width1, width2, background]) and accept equal sized arrays that contain the x1, x2, ... values. p can be a row-vector containing the parameters needed by the function.

The optional keyword 'all' is used if you wish to calculate the intensity from the function over the whole domain covered by the input dataset. In other words, your dataset may contain gaps due to the trajectory of the detectors through reciprocal space, but you may wish to simulate the scattering even in the gaps. This option applies in the case of dnd objects, but not sqw objects.


sqw_eval

wout = sqw_eval(win, @my_sqw_func, p);
wout = sqw_eval(win, @my_sqw_func, p, 'all');

The syntax for sqw_eval is almost identical to that of func_eval. The only difference is the form of the function required my_sqw_func, which must be of the form

weight = my_sqw_func(qh, qk, ql, en, p)


where qh, qk, ql, en area arrays that contain the co-ordinates in h, k, l and energy of every point in the dataset, irrespective of the dimensionality of that dataset. As before, p is a row-vector containing the parameters required by the function. These could be the values of exchange constants, intensity scale factor, or temperature, for example.

One would generally use sqw_eval in preference to func_eval if, for example, one had a model of the spin-wave cross-section for magnetic scattering.


dispersion

Calculate dispersion relation for dataset or array of datasets.

wdisp = dispersion (win, dispreln, p)            % dispersion only

[wdisp,weight] = dispersion (win, dispreln, p)   % dispersion and spectral weight

The output dataset (or array of data sets), wdisp, will retain only the Q axes, and the signal array(s) will contain the values of energy along the Q axes. If the dispersion relation returns the spectral weight, this will be placed in the error array (actually the square of the spectral weight is put in the error array). In the case when the dispersion has been calculated on a plane in momentum (i.e. wdisp is IX_datset_2d) then the plot function

ds2 (for draw surface from two arrays)

ds2(wdisp)

will plot a surface with the z axis as energy and coloured according to the spectral weight.

If you wish to overplot a dispersion relation on top of, for example, a Q-E slice from your data, then you would use:

plot(my_qe_slice)

ploc(wdisp)       % for plot line on current 

Note that in the above there must not be a keep command between plotting the Q-E slice and plotting the dispersion, since the ploc command works on the current figure.

The dispersion relation is calculated at the bin centres (that is, the individual pixel information in a sqw input object is not used).

If the function that calculates dispersion relations produces more than one branch (i.e. the output of dispreln is a cell array of arrays), then in the case of a single input dataset the output will be an array of datasets, one for each branch. If the input is an array of datasets, then only the first dispersion branch will be returned, so there is one output dataset per input dataset.

Input:

win Dataset (or array of datasets) that provides the axes and points for the calculation. If one of the plot axes is energy transfer, then the output dataset will have dimensionality one less than the input dataset.

dispreln Handle to function that calculates the dispersion relation w(Q). Must have form: w = dispreln (qh,qk,ql,p), or [w,s] = dispreln (qh,qk,ql,p)

where

  • qh,qk,ql Arrays containing the coordinates of a set of points in reciprocal lattice units
  • p Vector of parameters needed by dispersion function , e.g. [A,js,gam] as intensity, exchange, lifetime
  • w Array of corresponding energies, or, if more than one dispersion relation, a cell array of arrays.
  • s Array of corresponding spectral weights, or, if more than one dispersion relation, a cell array of arrays.

The more general form is: w = dispreln (qh,qk,ql,p,c1,c2,..), or [w,s] = dispreln (qh,qk,ql,p,c1,c2,..)

where

  • p Typically a vector of parameters that we might want to fit in a least-squares algorithm
  • c1,c2,... Other constant parameters e.g. file name for look-up table

p Arguments needed by the function that calculates the dispersion relation(s). Most commonly, a vector of parameter values e.g. [A,js,gam] as intensity, exchange, lifetime. If a more general set of parameters is required by the dispersion relation function, then package these into a cell array {p, c1, c2, ...}.


The output is:

wdisp Output dataset or array of datasets. Output is always dnd-type. The output dataset (or array of data sets) will retain only the Q axes, the the signal array(s) will contain the values of energy along the Q axes, and the error array will contain the square of the spectral weight. If the function that calculates dispersion relations produces more than one branch, then in the case of a single input dataset the output will be an array of datasets, one for each branch. If the input is an array of datasets, then only the first dispersion branch will be returned, so there is one output dataset per input dataset.

weight Mirror output: the signal is the spectral weight, and the error array contains the square of the frequency.

e.g. If win is a 2D dataset with Q and E axes, then wdisp is a 1D dataset with just the Q axis


disp2sqw_eval

Similar to sqw_eval, but takes as the input function a routine that calculates both the dispersion and the spectral weight, and only requires as its inputs h, k, l and some model parameters.

wout = disp2sqw_eval(win,@dispreln,pars,fwhh,<Optional input parameters>)

win is the input dataset (sqw or dnd) or array of datasets

dispreln is a function of the form [w,s] = dispreln (qh,qk,ql,p), or more generally [w,s] = dispreln (qh,qk,ql,p,c1,c2,..), where in addition to the coordinates qh, qk, ql and model input parameters p, some extra information contained in the data structures (cell arrays, vectors, structure arrays, etc) c1, c2, ... is supplied. The outputs w and s are the dispersion and spectral weight respectively. These are cell arrays of arrays if there is more than one branch of the dispersion.

pars is the input parameters to the function. If this is just p then pars = p, but if extra parameters are required then pars = {p, c1, c2, ...}, i.e. pars is a cell array.

fwhh is the full-width half-height of Gaussian broadening applied to dispersion relation.

The optional inputs are:

'all' - Requests that the calculated sqw be returned over the whole of the domain of the input dataset. If not given, then the function will be returned only at those points of the dataset that contain data. Applies only to input with no pixel information - it is ignored if full sqw object.

'ave' - Requests that the calculated sqw be computed for the average values of h,k,l of the pixels in a bin, not for each pixel individually. Reduces cost of expensive calculations. Applies only to the case of sqw object with pixel information - it is ignored if dnd type object.

The output is:

wout - Output dataset or array of datasets


dispersion_plot

Plot dispersion relation or array of dispersion relations along a path in reciprocal space. It can be called in the following ways, with or without outputs, as below:

dispersion_plot(rlp,@dispreln,pars)

dispersion_plot(lattice,rlp,@dispreln,pars)
 
dispersion_plot(...,'dispersion') % plot dispersion only

dispersion_plot(...,'weight') % plot spectral weight only
 
dispersion_plot(...,'labels',{'G','X',...})  % customised labels at the positions of the rlp

dispersion_plot(...,'ndiv',n)   % plot with number of points per interval other than the default
 
[wdisp,weight]=dispersion_plot(...)  % output arrays of IX_dataset_1d with dispersion and spectral weight

[wdisp,weight]=dispersion_plot(...,'noplot') % output arrays without plotting

The inputs are as follows:

lattice [optional] Lattice parameters [a,b,c,alpha,beta,gamma] (Angstrom, degrees). Default is [2*pi,2*pi,2*pi,90,90,90]

rlp Array of reciprocal lattice points, e.g. [0,0,0; 0,0,1; 0,-1,1; 1,-1,1; 1,0,1; 1,0,0];

@dispreln Handle to a Matlab function dispreln) that calculates the dispersion relation w(Q) and spectral weight, S(Q). The most commonly used form is:

[w,s] = dispreln (qh,qk,ql,p)

where,

  • qh,qk,ql Arrays containing the coordinates of a set of points in reciprocal lattice units
  • p Vector of parameters needed by dispersion function e.g. [A,js,gam] as intensity, exchange, lifetime
  • w Array of corresponding energies, or, if more than one dispersion relation, a cell array of arrays.
  • s Array of spectral weights, or, if more than one dispersion relation, a cell array of arrays.

The more general form is:

[w,s] = dispreln (qh,qk,ql,p,c1,c2,..)

where,

  • p Typically a vector of parameters that we might want to fit in a least-squares algorithm
  • c1,c2,... Other constant parameters e.g. file name for look-up table.

pars Arguments needed by the function that calculates the dispersion relation. Most commonly, a vector of parameter values e.g. [A,js,gam] as intensity, exchange, lifetime. If a more general set of parameters is required by the function, then package these into a cell array and pass that as pars. In the example above then pars = {p, c1, c2, ...}


The keyword options (which can be abbreviated to single letter) are:

'dispersion' Only plot the dispersion relation(s). The default is to plot and/or return dispersion, and weight if available

'weight' Only plot the spectral weight(s). The default is to plot and/or return dispersion, and weight if available

'labels' Tick labels to place at the positions of the Q points in argument rlp. e.g. {'G','X','M','R'}. By default the labels are character representations of rlp, e.g. {0,0,0; 0.5,0,0; 0.5,0.5,0; 0.5,0.5,0.5} becomes {'0,0,0', '0.5,0,0', '0.5,0.5,0', '0.5,0.5,0.5'}

'ndiv' Number of points into which to divide the interval between two r.l.p. (default=100)

'noplot' Do not plot, just return the output IX_dataset_1d (see below)


The outputs are as follows

wdisp Array of IX_dataset_1d containing dispersion, one per dispersion relation. The x-axis is the distance in Ang^-1 along the path described

weight Array of IX_dataset_1d with corresponding spectral weight, one per dispersion relation


disp2sqw_plot

Generate an Q-E intensity plot for a dispersion relation along a path in reciprocal space. The function is very closely related to dispersion_plot), and most of the input arguments and options are the same for the two functions.

disp2sqw_plot(rlp,@dispreln,pars,ebins,fwhh)

disp2sqw_plot(lattice,rlp,@dispreln,pars,ebins,fwhh)
 
disp2sqw_plot(...,'labels',{'G','X',...})  % customised labels at the positions of the rlp

disp2sqw_plot(...,'ndiv',n)   % plot with number of points per interval other than the default
 
weight=disp2sqw_plot(...)  % output IX_dataset_2d with spectral weight

weight=disp2sqw_plot(...,'noplot') % output array without plotting

The inputs are as follows:

lattice [optional] Lattice parameters [a,b,c,alpha,beta,gamma] (Angstrom, degrees). Default is [2*pi,2*pi,2*pi,90,90,90]

rlp Array of reciprocal lattice points, e.g. [0,0,0; 0,0,1; 0,-1,1; 1,-1,1; 1,0,1; 1,0,0];

@dispreln Handle to a Matlab function dispreln) that calculates the dispersion relation w(Q) and spectral weight, S(Q). The most commonly used form is:

[w,s] = dispreln (qh,qk,ql,p)

where,

  • qh,qk,ql Arrays containing the coordinates of a set of points in reciprocal lattice units
  • p Vector of parameters needed by dispersion function e.g. [A,js,gam] as intensity, exchange, lifetime
  • w Array of corresponding energies, or, if more than one dispersion relation, a cell array of arrays.
  • s Array of spectral weights, or, if more than one dispersion relation, a cell array of arrays.

The more general form is:

[w,s] = dispreln (qh,qk,ql,p,c1,c2,..)

where,

  • p Typically a vector of parameters that we might want to fit in a least-squares algorithm
  • c1,c2,... Other constant parameters e.g. file name for look-up table.

pars Arguments needed by the function that calculates the dispersion relation. Most commonly, a vector of parameter values e.g. [A,js,gam] as intensity, exchange, lifetime. If a more general set of parameters is required by the function, then package these into a cell array and pass that as pars. In the example above then pars = {p, c1, c2, ...}

ebins Defines the energy bin centres: a three-vector [ecentre_lo, bin_width, ecentre_hi]

fwhh Full width half height of broadening applied to the dispersion to produce the intensity map

The keyword options (which can be abbreviated to single letter) are:

'labels' Tick labels to place at the positions of the Q points in argument rlp. e.g. {'G','X','M','R'}. By default the labels are character representations of rlp, e.g. {0,0,0; 0.5,0,0; 0.5,0.5,0; 0.5,0.5,0.5} becomes {'0,0,0', '0.5,0,0', '0.5,0.5,0', '0.5,0.5,0.5'}

'ndiv' Number of points into which to divide the interval between two r.l.p. (default=100)

'noplot' Do not plot, just return the output IX_dataset_1d (see below)


The output is as follows:

weight IX_dataset_2d containing the spectra weight. The x-axis is the distance in Ang^-1 along the path described


The image intensity, as the function of Q along the rlp path alonx x-axis and the energy transfer along y-axis is determined by the equation:

       weight(energy)= sfact.*exp(-(w(Q,p)-energy).^2/(2*sig.^2))./(sig*sqrt(2*pi));

where

       sig = fwhh/sqrt(log(256));