redo Create Instrument Parameter File tutorial migrating from HTML to MD; updates to how-to files

Author: briantoby

MDhelp/docs/powderpeaks.md

@@ -2,15 +2,22 @@
 <a name="PWDR_Peak_List"></a>
 #  PWDR **Peak List** subdata tree item (Powder Diffraction)
 
-The Peak List data tree entry is used to fit diffraction peaks at refined or user-supplied positions (not generated from a unit cell). Peak positions and intensities may be selected for individual refinement. Gaussian ($\sigma^2$) and Lorentzian (\(\Gamma\)) peak widths may be varied individually or the values may be generated from the the appropriate profile terms in the Instrument Parameters tree item (U, V & W for \(\sigma^2\); X & Y for \(\Gamma\)): Note that the Gaussian full-width at half-maximum is given by 
+The Peak List data tree entry is used to fit diffraction peaks at refined or user-supplied positions (not generated from a unit cell). Peak positions and intensities may be selected for individual refinement. There are four modes available here for treatment of peak widths: 
+1) Gaussian ($\sigma^2$) and Lorentzian (\(\Gamma\)) peak widths may be varied individually, 
+2) the width values may be generated from the the appropriate profile terms in the Instrument Parameters tree item (U, V & W for \(\sigma^2\); X & Y for \(\Gamma\)), where those terms may optionally be refined. 
+3) It is possible to mix refinement of XY terms and fit a few individual  (\(\Gamma\)) peak widths, but this is not possible with the UVW terms. When any individual ($\sigma^2$) peak widths are fit, it is not possible to refine the U, V or W terms. Note that when individual widths are refined, the fitted values override the values that would be generated from the UVW/XY terms, except as noted in the next mode.
+4)It is possible to turn off the setting of individual (\(\sigma^2\) or \(\Gamma\) peak width values) peak width  If  are refined, then those value(s) in the table are used as the refinement starting point. If values are not refined, then normally the unvaried widths are determined from the appropriate Instrument Parameters profile terms and are placed in the table prior to fitting. When the "Gen unvaried widths" menu item is turned off, the unvaried peak with values are not computed from the Instrument Parameters; this must be turned on  (the default mode) to vary Instrument Parameters.
 
-$$FWHM = \sqrt{8 * \ln 2 * \sigma^ 2}$$
+Note that the Gaussian full-width at half-maximum is given by 
 
-while \(\Gamma\) is the Lorentzian FWHM. The \(\sigma^2\) values (peak variances) are in units of centidegrees\(^2\) (centidegrees are degrees*100) for CW data or microseconds\(^2\) for TOF data; \(\Gamma\) has units of centidegrees or microseconds. 
+$$FWHM = \sqrt{8 * \ln 2 * \sigma^ 2}$$
 
-If individual \(\sigma^2\) or \(\Gamma\) values are refined, then those value(s) in the table are used as the refinement starting point. If values are not refined, then normally the unvaried widths are determined from the appropriate Instrument Parameters profile terms and are placed in the table prior to fitting. This behavior can be overridden by changing the "**Gen unvaried widths**" mode entry in the menu ([see below](#GenUnvariedWidths)) so that fixed values can be specified.
+while \(\Gamma\) is the Lorentzian FWHM. The \(\sigma^2\) values (peak variances) are in units of centidegrees\(^2\) (centidegrees are degrees*100) for CW data or microseconds\(^2\) for TOF data; \(\Gamma\) has units of centidegrees or microseconds. Except in very unusual circumstances, instrumental broadening is Gaussian and will be a slowly-changing function of Q and sample broadening is strictly Lorentzian and while this may be only a function of Q, it can vary from peak to peak if the sample is a mixture of phases, or anisotropic peak broadening is present. Thus, it makes sense to fit Gaussian widths only using the U, V & W terms and indeed the software will not allow those terms to be varied if 
+*any* 
+individual peak \(\sigma^2\) terms are varied as this usage would not make sense physically. 
+This is different for X & Y and individual peak \(\Gamma\) values. The refinement of X & Y, while fitting of *some* individual peak \(\Gamma\) values is allowed and this can make sense physically, but note that one should have a sufficient number of peaks that are not being fit individually and these peaks should be distributed over a wide range in Q when X & Y are fit simultaneously.
 
-For peak fitting, the background is generated using the parameters in the Background data tree entry. Also, the range of data used in the fit is set from the Limits tree item. In both cases these are the same values that are used in Rietveld fits. Note that optionally the parameters on the Background and in the Instrument Parameters tree items may be refined during peak fitting, but in the case of U, V & W, there must be a sufficient number of reflections with unvaried \(\sigma^2\) and likewise for X & Y and  \(\Gamma\).  "Gen unvaried widths" must be selected to vary Instrument Parameters.
+For peak fitting, the background is generated using the parameters in the Background data tree entry. Also, the range of data used in the fit is set from the Limits tree item. In both cases these are the same values that are used in Rietveld fits. Note that optionally the parameters on the Background and in the Instrument Parameters tree items may be refined during peak fitting, but in the case of U, V & W, these values cannot be refined if any individual \(\sigma^2\) values are fit. 
 
 <H3 style="color:blue;font-size:1.1em">What can I do here?</H3>
 
@@ -65,11 +72,11 @@ For all actions involving mouse clicks such as those below, be sure that the Zoo
 
 * You can add peaks to the Peak list using the mouse on the plot by: position the cursor pointer onto a cross for an observed point and pressing the left mouse button. The selected peak will be added to the Peak List in the appropriate position to keep peaks sorted and a blue vertical line will be plotted on that position. We recommend that you begin picking peaks from the right side of the pattern; that way the tool tip won't be in your way as you select peaks.
 * You can delete peaks using the mouse on the plot by positioning the pointer on the blue line for the peak to be deleted and then pressing the right mouse button. The blue line should vanish, and the corresponding peak will be removed from the Peak List.
-* You can move a Peak List item using the mouse on the plot by: position the pointer on the blue line for the peak you wish to move and then hold the left mouse button down, dragging the line to the desired position. When the mouse button is released, the peak line will be drawn in the new position.
+* You can move a Peak List item using the mouse on the plot: position the pointer on the blue line for the peak you wish to move and then hold the left mouse button down, dragging the line to the desired position. When the mouse button is released, the peak line will be drawn in the new position.
 * The fit limits can be changed from the plot either here or in the Limits data tree. Change the upper and lower Tmin/Tmax values by clicking on the appropriate vertical line and dragging it to the right or left.
 * Highlight each peak in the list successively using the "d" keyboard key to move down the list or "u" to move up the list. 
 
 
 ### "**Extra Peak**" Mode
 
-When working with full-pattern fits, it is sometimes useful to pay attention only to the peaks that are not being indexed and fit by the full pattern fit. One reason for this may be to learn more about a phase that is not currently being fit or with magnetic scattering, one may have fit the chemical ("nuclear") structure and one needs to identify the additional peaks that are seen below a magnetic phase transition in order to understand the lowered symmetry of the magnetic lattice, or similarly to explore lowering of symmetry as a phase transitions to the symmetry of a subgroup, perhaps as the temperaure is lower or as ions order due to a compositional change. In "Extra Peak mode", individual peak fitting is performed not on the diffraction data, but rather on the difference between the observed pattern and that computed from the full pattern fitting. A separate peak list is kept for these "extra peaks". This "Extra Peak Mode" can be entered either from pressing the button labeled "Switch to In "Extra Peak mode", or by using the checkmark menu button in the "Peak Fitting" menu labeled "Add impurity/subgrp/magnetic peaks."
+When working with full-pattern fits, it is sometimes useful to pay attention only to the peaks that are not being indexed and fit by the full pattern fit. One reason for this may be to learn more about a phase that is not currently being fit or with magnetic scattering, one may have fit the chemical ("nuclear") structure and one needs to identify the additional peaks that are seen at a temperature below a magnetic phase transition in order to understand the lowered symmetry of the magnetic lattice. Similarly one may wish to explore a phase transition lowering of symmetry. In "Extra Peak mode", individual peak fitting is performed not on the diffraction data, but rather on the "difference curve," the observed pattern with the computed pattern subtracted. A separate peak list is kept for these "extra peaks". This "Extra Peak Mode" can be entered either from pressing the button labeled "Switch to In "Extra Peak mode", or by using the checkmark menu button in the "Peak Fitting" menu labeled "Add impurity/subgrp/magnetic peaks."

MDtutorials/.gitignore

@@ -1,3 +1,2 @@
 docs/
-mkdocs.yml
 requirements.txt