removed paragraph indexing; renumbered figures

doc/index.rst

@@ -2,13 +2,11 @@
 HiSPoD
 ======
 
-`HiSPoD <https://github.com/decarlof/HiSPoD>`_ is developed for polychromatic 
-x-ray diffraction of polycrystalline samples. 
+`HiSPoD <https://github.com/HiSPoD/HiSPoD>`_ is a Matlab® 
+program developed for simulating and analyzing undulator 
+white-beam diffraction patterns from polycrystalline samples.
 
-We kindly request that you cite the following article :cite:`cite:01` 
-if you use HiSPoD.
-
-HiSPoD documentation is at `url <http://hispod.readthedocs.org/>`_.
+We kindly request that you cite :cite:`cite:01` if you use *HiSPoD*.
 
 Features
 --------

doc/source/about.rst

@@ -2,7 +2,9 @@
 About
 =====
 
-*HiSPoD* is a Matlab® program developed for simulating and analyzing undulator white-beamdiffraction patterns from polycrystalline samples.
+`HiSPoD <https://github.com/HiSPoD/HiSPoD>`_ is a Matlab® 
+program developed for simulating and analyzing undulator 
+white-beam diffraction patterns from polycrystalline samples.
 
 .. contents:: Contents:
    :local:

doc/source/manual/appendix.rst

@@ -1,3 +1,3 @@
-VII. Appendix=============7.1 Diffraction simulation--------------------------The simulation of a white-beam diffraction pattern from a known materialstarts from the calculation of monochromatic beam diffraction patternsfor the specific detector location, *I(θ,E)*. Then these mono-beamdiffraction patterns are integrated over the entire energy range withweighting factor being the flux of photons with different energy, F(E).where E\ :sub:`1` and E\ :sub:`2` are typically 1 keV and 60 keV,respectively. To improve the calculation speed, discrete diffractionpeaks are considered, meaning that *I(θ,E)* is normally replaced by aseries of I\ :sub:`hkl`\ (θ,E). Equation above then becomesIn our simulations, the diffraction peak shape is described using thepseudo-Voigt function.Essentially, the white-beam diffraction intensity at a given scatteringangle is the convolution of the input diffraction intensity of differentatomic planes with the energy spectrum of the x-rays.|image24|Figure 7.1: Simulation of white-beam diffraction7.2 How to obtain the sample absorption file--------------------------------------------    **Option 1**: Ask the beamline scientists for it. If users are not    confident to calculate the attenuation curve, asking the beamline    scientists is always the best choice. Provide sample parameters    including chemical formula, mass density, and thickness. For    example, sample Al\ :sub:`2`\ O\ :sub:`3`, density of 3.95    g/cm\ :sup:`3`, thickness 500 µm.    **Option 2**: Use the web tool of The Center of X-Ray Optics    (http://henke.lbl.gov/optical_constants/). Calculate the x-ray    transmission for a solid with procedure shown below and in Fig. 7.2.-  Fill in sample information-  Select energy range-  Click “Submit Request” to do the calculation. Another window will   then pop up with the plot-  Click “data file here” to show the values-  Copy the data (without the sample info lines), and save it as a   \*.txt file    Note that this online tool can only calculate the transmission for    energy ranging from 0-30 keV, which often not suffice for white-beam    experiments.|image25|Figure 7.2: Calculate x-ray transmission at the website of CXRO    **Option 3**: Self calculate based on the x-ray mass attenuation    coefficients from NIST. At NIST webpage    (http://physics.nist.gov/PhysRefData/XrayMassCoef/tab3.html), the    attenuation coefficients (*µ/ρ*) are provided for elements from    Hydrogen to Uranium. The x-ray attenuation *T* is calculated as:    where *µ/ρ* is value directly from the webpage, *ρ* is the mass    density of the sample, and *t* is the sample thickness.    For compounds, the attenuation coefficients will simply be the    weighted-sum of each element.    where *w\ :sub:`i`* is the weight (or mass) fraction of element *i.*    For example of Al\ :sub:`2`\ O\ :sub:`3`, density 3.95    g/cm\ :sup:`3`, thickness 500 µm, and for x-ray energy 10 keV. The    mass coefficient of the sample will be:    cm\ :sup:`2`/g    The attenuation will then be:7.3 Some comparisons to guide the usage---------------------------------------1) Scaling factor: 4 vs 2 vs 1   Always, the larger the scaling factor, the faster the processing   time, yet the smaller the resolution. For the example shown in Fig.   7.3, the simulation time for scaling factor 4, 2, and 1 are 11 min,   1.5 min, and 14 sec, respectively. (Note the CPU is Intel i7, 3.4   GHz) Clearly, the small peak at 48° can only be visualized in the   patterns with scaling factor 2 and 1. The effect of scaling factor on   the analysis of experiment data is not as obvious, as the   signal-to-noise ratio of single-pulse diffraction patterns is rather   low and radially averaging is more related to the parameters “Points”   and “Q res”. For image with dimension of about 1k x 1k, the scaling   factor of 2 may be a good option.|image26|Figure 7.3: Effect of scaling factor2) Direct beam position: wrong vs rightFigure 7.4 show the overlap of diffraction rings with the referencepeaks in cases of wrong and correct direct beam position input. Thecorrect parameters should satisfy all other data, either same samplewith different undulator gap (i.e. energy spectrum) or other samples.For this specific example in Fig. 7.4, all the diffraction rings aregenerated by the 1\ :sup:`st` harmonic energy, so they are all labeled,but this is not always the case. Figure 7.5 show the data from anotherundulator gap, in which some diffraction rings are generated by2\ :sup:`nd` harmonic energy. Users may simply input the photon energyused for labeling in the “E1 (keV)” space.|image27|Figure 7.4: Effect of direction beam locating on calculation of q map|image28|Figure 7.5: Reference peaks corresponds to 1st and 2nd harmonic energies3) Pointes and Q res: rough vs smooth plotsSmooth plot looks good, but may lose some structure information due tothe over averaging.|image29|Figure 7.6: Rough and smooth (yet low-resolution) 1D plots4) Region of interest: without ROI vs with ROIThis is not necessary if all the pixels on the detector functionproperly.|image30|Figure 7.7: Effect of ROI on the 1D plot
+Appendix=============Diffraction simulation----------------------The simulation of a white-beam diffraction pattern from a known materialstarts from the calculation of monochromatic beam diffraction patternsfor the specific detector location, *I(θ,E)*. Then these mono-beamdiffraction patterns are integrated over the entire energy range withweighting factor being the flux of photons with different energy, F(E).where E\ :sub:`1` and E\ :sub:`2` are typically 1 keV and 60 keV,respectively. To improve the calculation speed, discrete diffractionpeaks are considered, meaning that *I(θ,E)* is normally replaced by aseries of I\ :sub:`hkl`\ (θ,E). Equation above then becomesIn our simulations, the diffraction peak shape is described using thepseudo-Voigt function.Essentially, the white-beam diffraction intensity at a given scatteringangle is the convolution of the input diffraction intensity of differentatomic planes with the energy spectrum of the x-rays.|image24|Figure 23: Simulation of white-beam diffractionHow to obtain the sample absorption file----------------------------------------    **Option 1**: Ask the beamline scientists for it. If users are not    confident to calculate the attenuation curve, asking the beamline    scientists is always the best choice. Provide sample parameters    including chemical formula, mass density, and thickness. For    example, sample Al\ :sub:`2`\ O\ :sub:`3`, density of 3.95    g/cm\ :sup:`3`, thickness 500 µm.    **Option 2**: Use the web tool of The Center of X-Ray Optics    (http://henke.lbl.gov/optical_constants/). Calculate the x-ray    transmission for a solid with procedure shown below and in Fig. 24.-  Fill in sample information-  Select energy range-  Click “Submit Request” to do the calculation. Another window will   then pop up with the plot-  Click “data file here” to show the values-  Copy the data (without the sample info lines), and save it as a   \*.txt file    Note that this online tool can only calculate the transmission for    energy ranging from 0-30 keV, which often not suffice for white-beam    experiments.|image25|Figure 24: Calculate x-ray transmission at the website of CXRO    **Option 3**: Self calculate based on the x-ray mass attenuation    coefficients from NIST. At NIST webpage    (http://physics.nist.gov/PhysRefData/XrayMassCoef/tab3.html), the    attenuation coefficients (*µ/ρ*) are provided for elements from    Hydrogen to Uranium. The x-ray attenuation *T* is calculated as:    where *µ/ρ* is value directly from the webpage, *ρ* is the mass    density of the sample, and *t* is the sample thickness.    For compounds, the attenuation coefficients will simply be the    weighted-sum of each element.    where *w\ :sub:`i`* is the weight (or mass) fraction of element *i.*    For example of Al\ :sub:`2`\ O\ :sub:`3`, density 3.95    g/cm\ :sup:`3`, thickness 500 µm, and for x-ray energy 10 keV. The    mass coefficient of the sample will be:    cm\ :sup:`2`/g    The attenuation will then be:Some comparisons to guide the usage-----------------------------------1) Scaling factor: 4 vs 2 vs 1   Always, the larger the scaling factor, the faster the processing   time, yet the smaller the resolution. For the example shown in Fig.   25, the simulation time for scaling factor 4, 2, and 1 are 11 min,   1.5 min, and 14 sec, respectively. (Note the CPU is Intel i7, 3.4   GHz) Clearly, the small peak at 48° can only be visualized in the   patterns with scaling factor 2 and 1. The effect of scaling factor on   the analysis of experiment data is not as obvious, as the   signal-to-noise ratio of single-pulse diffraction patterns is rather   low and radially averaging is more related to the parameters “Points”   and “Q res”. For image with dimension of about 1k x 1k, the scaling   factor of 2 may be a good option.|image26|Figure 25: Effect of scaling factor2) Direct beam position: wrong vs rightFigure 26 show the overlap of diffraction rings with the referencepeaks in cases of wrong and correct direct beam position input. Thecorrect parameters should satisfy all other data, either same samplewith different undulator gap (i.e. energy spectrum) or other samples.For this specific example in Fig. 26, all the diffraction rings aregenerated by the 1\ :sup:`st` harmonic energy, so they are all labeled,but this is not always the case. Figure 27 show the data from anotherundulator gap, in which some diffraction rings are generated by2\ :sup:`nd` harmonic energy. Users may simply input the photon energyused for labeling in the “E1 (keV)” space.|image27|Figure 26: Effect of direction beam locating on calculation of q map|image28|Figure 27: Reference peaks corresponds to 1st and 2nd harmonic energies3) Pointes and Q res: rough vs smooth plotsSmooth plot looks good, but may lose some structure information due tothe over averaging.|image29|Figure 28: Rough and smooth (yet low-resolution) 1D plots4) Region of interest: without ROI vs with ROIThis is not necessary if all the pixels on the detector functionproperly.|image30|Figure 29: Effect of ROI on the 1D plot
 
 .. |image24| image:: figures/image25.png.. |image25| image:: figures/image26.png.. |image26| image:: figures/image27.png.. |image27| image:: figures/image28.png.. |image28| image:: figures/image29.png.. |image29| image:: figures/image30.png.. |image30| image:: figures/image31.png

doc/source/manual/correlate.rst

@@ -1,3 +1,3 @@
-V. Correlate simulation with experiment data============================================*HiSPoD* doesn’t have a function to automatically fit the 1D diffractionintensity profiles. The curve fitting function here is a direct overlayof the experiment data and simulated results. If strain information isdesired, manually adjust the lattice parameter until the simulationmatches the experiment data perfectly. A typical procedure to correlatethe simulation with data is described below:1) Input or load experiment parameters and sample structure information.2) Load diffraction data, energy spectrum, and absorption file.3) Define ROI, and Calculate q map.4) Get I(tth) of data.5) Simulate “Realistic” diffraction pattern.6) Get I(tth) of simulation.7) Click “Overlay I(tth)” button in the “Tools” module. A message window   will pop up telling users to get the noise level. Click “OK” to   proceed. In the diffraction pattern, circle out a region (typically   at the detector corners that are outside the scintillator) to collect   the mean detector noise, and double-click to confirm. Another message   window will pop up with instructions on how to define the background.   Click “OK” to proceed. The 1D intensity profile of the experiment   data will show up, in which multiple points need to be selected to   define the background. Here the background (i.e. combination of the   tail part of the transmission beam, air scattering and others) is   assumed to follow the exponential decay function. Double-click the   last point to confirm.|image20|Figure 5.1: Define noise and background8) Once the background is defined, two windows with diffraction plots   will pop up, as Fig. 5.2. The first plot shows the data and the   defined background. The second figure shows the data and simulation   in two formats. The left one with noise and background, and the right   one without.|image21|Figure 5.2: Overlay diffraction data and simulation9) Repeat step (10) if the fitting needs to be improved.10) For two-phase samples, adjust the content of each phase and re-do the    simulation to get the best fitting result.11) For some samples with fine grains, the diffraction peaks will be    largely broadened. To achieve a better curve fitting, the “Curve fit”    function could be used. The “eta” and “sigma” parameters to the right    of the button need user inputs. It’s assumed that the diffraction    peak shape profile, if using monochromatic x-ray, can be described    using pseudo-Voigt function, in which eta and sigma are two key    parameters. “eta” is a parameter tuning the contribution of Gaussian    and Lorentzian broadening in the Voigt function; “sigma” describes    the peak width. (details in Appendix). After conducting previous    steps of “Overlay I(tth)”, click “Curve fit” button. A message window    with instruction will show up. Click “OK” to proceed. The figure with    I(tth) curve will appear. Click two points on the figure to narrow    down angle range for further fitting. The diffraction peak(s) within    this range will be fitted. Double click the second point to confirm.    Then another window will pop up, providing two options for curve    fitting: one option is to match the maximum intensities of the data    and simulation; the second option is to calculate standard deviation    between the data and the simulation, and tune the scaling factor in    order to minimize the deviation. For a good fitting, these two    options yield very similar results.|image22|Figure 5.3: Quantitative curve fitting
+Correlate simulation with experiment data=========================================*HiSPoD* doesn’t have a function to automatically fit the 1D diffractionintensity profiles. The curve fitting function here is a direct overlayof the experiment data and simulated results. If strain information isdesired, manually adjust the lattice parameter until the simulationmatches the experiment data perfectly. A typical procedure to correlatethe simulation with data is described below:1) Input or load experiment parameters and sample structure information.2) Load diffraction data, energy spectrum, and absorption file.3) Define ROI, and Calculate q map.4) Get I(tth) of data.5) Simulate “Realistic” diffraction pattern.6) Get I(tth) of simulation.7) Click “Overlay I(tth)” button in the “Tools” module. A message window   will pop up telling users to get the noise level. Click “OK” to   proceed. In the diffraction pattern, circle out a region (typically   at the detector corners that are outside the scintillator) to collect   the mean detector noise, and double-click to confirm. Another message   window will pop up with instructions on how to define the background.   Click “OK” to proceed. The 1D intensity profile of the experiment   data will show up, in which multiple points need to be selected to   define the background. Here the background (i.e. combination of the   tail part of the transmission beam, air scattering and others) is   assumed to follow the exponential decay function. Double-click the   last point to confirm.|image20|Figure 19: Define noise and background8) Once the background is defined, two windows with diffraction plots   will pop up, as Fig. 20. The first plot shows the data and the   defined background. The second figure shows the data and simulation   in two formats. The left one with noise and background, and the right   one without.|image21|Figure 20: Overlay diffraction data and simulation9) Repeat step (10) if the fitting needs to be improved.10) For two-phase samples, adjust the content of each phase and re-do the    simulation to get the best fitting result.11) For some samples with fine grains, the diffraction peaks will be    largely broadened. To achieve a better curve fitting, the “Curve fit”    function could be used. The “eta” and “sigma” parameters to the right    of the button need user inputs. It’s assumed that the diffraction    peak shape profile, if using monochromatic x-ray, can be described    using pseudo-Voigt function, in which eta and sigma are two key    parameters. “eta” is a parameter tuning the contribution of Gaussian    and Lorentzian broadening in the Voigt function; “sigma” describes    the peak width. (details in Appendix). After conducting previous    steps of “Overlay I(tth)”, click “Curve fit” button. A message window    with instruction will show up. Click “OK” to proceed. The figure with    I(tth) curve will appear. Click two points on the figure to narrow    down angle range for further fitting. The diffraction peak(s) within    this range will be fitted. Double click the second point to confirm.    Then another window will pop up, providing two options for curve    fitting: one option is to match the maximum intensities of the data    and simulation; the second option is to calculate standard deviation    between the data and the simulation, and tune the scaling factor in    order to minimize the deviation. For a good fitting, these two    options yield very similar results.|image22|Figure 21: Quantitative curve fitting
 
 .. |image20| image:: figures/image21.png.. |image21| image:: figures/image22.png.. |image22| image:: figures/image23.png