Changeset 4664 for trunk/help/gsasII.html

Timestamp:

Nov 29, 2020 8:41:57 PM (2 years ago)

Author:

toby

Message:

pretty up Controls panel; add & update help

File:

• trunk/help/gsasII.html (modified) (3 diffs)

trunk/help/gsasII.html

@@ -3677 +3677 @@
 
 <p class=MsoNormal style='margin-left:.5in'><span style='mso-fareast-font-family:
-"Times New Roman"'>This window provides the main controls for the refinement
-calculations in GSAS-II. Two of the main refinement tools are the <span
-class=SpellE>fortran</span> MINPACK <span class=SpellE>lmdif</span> and <span
-class=SpellE>lmder</span> algorithms wrapped in python as provided in the <span
-class=SpellE>Scipy</span> package and a third one is a python version utilizing
-only the <span class=SpellE>numpy</span> package. The purpose is to </span>minimize
+"Times New Roman"'>This window provides the main controls and a few
+global parameters for GSAS-II.
+
+<h5 style='margin-left:.5in'><span
+style='mso-fareast-font-family:"Times New Roman"'>
+What can I do here?</span></h5>
+<p style='margin-left:0.75in'>On this page, there are three or four sets of
+controls. The first is for how refinements operate.
+</p>
+<A name="RefineType"></A>
+<DL style='margin-left:1.0in'>
+  <DT><B>Refinement type</B></DT>
+  <DD>This determines how refinements are performed. The choices
+    are:</DD>
+    <UL style='margin-left:0.25in'>
+      <LI><U>analytic Hessian</U>: This is the default option and is usually
+      the most useful. It uses as custom-developed least-squares
+      minimizer that uses singular-value decomposition (SVD) to reduce the
+      errors caused by correlated variables and the
+      Levenberg-Marquardt algorithm to down-weight the off-diagonal
+      Hessian terms when refinements fail to lower χ<sup>2</sup>. 
+      <LI><u>analytic Jacobian</u>: This uses a numpy-provided <I>leastsq</I>
+      minimizer, which not applicable for larger
+      problems as it requires
+      much more memory than the Hessian routines. This because it
+      creates a Jacobian matrix is shaped N x M (N parameters x M
+      observations) and uses that to create the N x N Hessian. The
+      "Hessian" minimizers create the Hessian matrix directly.
+      <LI><u>numeric</u>: This also uses the numpy <I>leastsq</I>
+      minimizer, and is also not applicable for larger
+      problems. Unlike, the "analytic Jacobian", numerical derivates
+      are computed for derivatives rather than analytical derivatives
+      that are coded directly into GSAS-II. This will be slower than
+      the analytical derivatives and will converge more slowly. It is
+      typically used for code development to check the accuracy of the
+      analytical derivative formulations. 
+      <LI><u>Hessian SVD</u>: This is very similar to <U>analytic
+      Hessian</U> but does not include the Levenberg-Marquardt
+      algorithm. It can be faster, but is more prone to
+      diverge when severe correlation is present.
+    </UL>
+<p style='margin-left:0.25in'>
+Note that the Jacobian refinement tools are the Fortran
+MINPACK <I>lmdif</I > and <I>lmder</I> algorithms wrapped in python as
+provided in the <span class=SpellE>Scipy</span> package. The
+Hessian routines are were developed for GSAS-II based on routines in
+numpy and scipy and using the material in Numerical Recipes (Press, Flannery, <span class=SpellE>Teulosky</span>
+&amp; <span class=SpellE>Vetterling</span>) for the <span
+class=SpellE>Levenberg</span>-Marquardt. 
+The purpose is to </span>minimize
 the sum of the squares of M<span style='mso-fareast-font-family:"Times New Roman"'>
 nonlinear functions in N variables by a modification of the <span class=SpellE>Levenberg</span>-Marquardt
@@ -3688 +3732 @@
 routines were written by </span>Burton S. <span class=SpellE>Garbow</span>,
 Kenneth E. <span class=SpellE>Hillstrom</span>, Jorge J. More (Argonne National
-Laboratory, 1980). The python/numpy version was developed by us based on the
-material in Numerical Recipes (Press, Flannery, <span class=SpellE>Teulosky</span>
-&amp; <span class=SpellE>Vetterling</span>) for the <span class=SpellE>Levenberg</span>-Marquardt
-algorithm and is the default.<span style='mso-fareast-font-family:"Times New Roman"'><o:p></o:p></span></p>
-
-<h5 style='margin-left:.5in'><span
-style='mso-fareast-font-family:"Times New Roman"'>
-What can I do here?</span></h5>
-
-<p class=MsoListParagraphCxSpFirst style='margin-left:1.0in;mso-add-space:auto;
-text-indent:-.25in;mso-list:l22 level1 lfo9'><![if !supportLists]><span
-style='mso-fareast-font-family:"Times New Roman"'><span style='mso-list:Ignore'>1.<span
-style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; </span></span></span><![endif]><span
-style='mso-fareast-font-family:"Times New Roman"'>Select whether the refinement
-uses ‘analytic Jacobian’, ‘analytic Hessian’ or ‘numeric’ derivatives. The last
-is slower and perhaps a bit less accurate, but may be needed if the analytic
-functions are not fully developed. The Jacobian matrix is shaped N x M
-(parameters x observations) and is much larger than the Hessian matrix which is
-shaped M x M (parameters x parameters). Generally use ‘analytic Hessian’ for
-routine work.<o:p></o:p></span></p>
-
-<p class=MsoListParagraphCxSpMiddle style='margin-left:1.0in;mso-add-space:
-auto;text-indent:-.25in;mso-list:l22 level1 lfo9'><![if !supportLists]><span
-style='mso-fareast-font-family:"Times New Roman"'><span style='mso-list:Ignore'>2.<span
-style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; </span></span></span><![endif]><span
-style='mso-fareast-font-family:"Times New Roman"'>Select ‘Min delta-M/M’ for
-convergence; the refinement will stop when the change in the minimization
-function is less than this value. Set Min delta-M/M = 1.0 to force just a
-single cycle to be performed. A value less than 10<sup>-4</sup> (the default)
-generally gives no better result. The allowed range is 10<sup>-9</sup> to 1.0.<o:p></o:p></span></p>
-
-<p class=MsoListParagraphCxSpMiddle style='margin-left:1.0in;mso-add-space:
-auto;text-indent:-.25in;mso-list:l22 level1 lfo9'><![if !supportLists]><span
-style='mso-fareast-font-family:"Times New Roman"'><span style='mso-list:Ignore'>3.<span
-style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; </span></span></span><![endif]><span
-style='mso-fareast-font-family:"Times New Roman"'>If ‘analytic Jacobean’ is
-chosen then select ‘Initial shift factor’ for the first cycle of refinement.
-This value is modified by the least squares routine. The allowed range is 10<sup>-5</sup>
-to 100. Smaller values may be needed if your initial refinement trials
-immediately diverge, however make sure your starting parameter values are
-‘reasonable’. The selected default (=1.0) normally gives good performance.<o:p></o:p></span></p>
-
-<p class=MsoListParagraphCxSpMiddle style='margin-left:1.0in;mso-add-space:
-auto;text-indent:-.25in;mso-list:l22 level1 lfo9'><![if !supportLists]><span
-style='mso-fareast-font-family:"Times New Roman"'><span style='mso-list:Ignore'>4.<span
-style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; </span></span></span><![endif]><span
-style='mso-fareast-font-family:"Times New Roman"'>If ‘analytic Hessian’ is
-chosen then select ‘Max cycles’, the maximum number of least squares cycles to
-be performed. Least squares cycles are determined by the number of times a new
-Hessian matrix is computes; the <span class=SpellE>Levenberg</span>-Marquardt
-algorithm may compute the function several times between cycles as it finds the
-optimal value of the Marquardt coefficient. Choices are given in the pull down
-selection; the default is 3 cycles.<o:p></o:p></span></p>
-
-<p class=MsoListParagraphCxSpLast style='margin-left:1.0in;mso-add-space:auto;
-text-indent:-.25in;mso-list:l22 level1 lfo9'><![if !supportLists]><span
-style='mso-fareast-font-family:"Times New Roman"'><span style='mso-list:Ignore'>5.<span
-style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; </span></span></span><![endif]><span
-style='mso-fareast-font-family:"Times New Roman"'>Select data for sequential
-refinement; the data sets may be done in ‘reverse order’. <o:p></o:p></span></p>
+Laboratory, 1980).
+</p>
+  <DT><B>Min delta-M/M</B></DT>
+  <DD>This determines when convergence is recognized;
+    the refinement will stop when the change in the minimization
+    function is less than this value. Set Min delta-M/M = 1.0 to force just a
+single cycle to be performed. The default is 0.001. A value less than
+    10<sup>-4</sup> causes the refinement to cycle with no meaningful
+    improvement since shifts become a small fraction of the
+    parameter's uncertainties. Set Min delta-M/M = 1.0 to force
+    refinement to stop after a single refinement.
+    The allowed range is 10<sup>-9</sup> to 1.0.
+  </DD>
+  <DT><B>Max cycles</B></DT>
+  <DD>This determines the maximum number of refinement cycles that
+    will be performed. This is only available with the "Hessian" minimizers.</DD>
+  <DT><B>Initial lambda</B></DT>
+  <DD>Note that here λ is the Marquardt coefficient, which when large
+    down-weights the significance of the off-diagonal terms in the
+    Hessian. Thus, when λ is large, the refinement is effectively one of
+    steepest-descents, where correlation between variables is
+    ignored. Note that steepest-descents minimization is typically
+    slow and may not always find the local minimum.
+    This is only available with the "analytical Hessian" minimizer.
+  </DD>
+  <DT><B>SVD zero tolerance</B></DT>
+  <DD>This determines the level where SVD considers values to be the
+    same. Default is 10<sup>-6</sup>. Make larger to where problems occur due to correlation. This is only available with the "Hessian" minimizers.
+  </DD>
+  <DT><B>Initial shift factor</B></DT>
+  <DD>?
+  </DD>
+</DL>
+  <A name="SingleXtlSettings"></A>
+<p style='margin-left:0.75in'>A set of controls is provided for
+control of single-crystal refinements. 
+These only appear when single crystal (HKLF) histograms are present
+in the project. 
+</p>
+<DL style='margin-left:1.0in'>
+  <DT><B>Refine HKLF as F^2?</B></DT>
+  <DD>When checked, refinements are against F<sup>2</sup> rather than
+    |F|. 
+  </DD>
+  <DT><B>Min obs/sig</B></DT>
+  <DD>?
+  </DD>
+  <DT><B>Min extinct.</B></DT>
+  <DD>?
+  </DD>
+  <DT><B>Max delt-F/sig</B></DT>
+  <DD>?
+  </DD>
+  <DT><B>Max d-spacing</B></DT>
+  <DD>Reflections with d-space values larger than this value are ignored. 
+  </DD>
+  <DT><B>Min d-spacing</B></DT>
+  <DD>Reflections with d-space values smaller than this value are ignored. 
+  </DD>
+  
+</DL>
+
+  <A name="SequentialSettings"></A>
+<p style='margin-left:0.75in'>A set of controls is for
+sequential refinement. Settings here determine if "normal" or "sequential"
+refinement is performed. If no datasets are selected, then all "used"
+histograms are included in one combined refinement. However, if any
+number histogram are selected used here, then a
+sequential refinement is performed, where a fit is made to each
+histogram in turn. Only the first item below is shown in "normal" mode.
+</p>
+<DL style='margin-left:1.0in'>
+  <DT><B>Select datasets/Reselect Datasets</B></DT>
+  <DD>This brings up a menu where histograms can be selected, which
+    potentially switches between a normal and a sequential refinement.
+    If one or more histograms are selected, a sequential
+    refinement is used. If none are selected, then the refinement be
+    set as "normal". The button is labeled "Select" when in normal refinement
+    mode and "Reselect" in sequential refinement mode. 
+    </DD>
+  <DT><B>Reverse order?</B></DT>
+  <DD>Normally, in a sequential histograms are fit in the order they
+    are in the data tree (which can be reordered by dragging tree
+    items),
+    but when this option is selected, the sequential fit is performed
+    with the last tree entry first.
+  </DD>
+  <DT><B>Copy results to next histogram?</B></DT>
+  <DD>When this option is selected, the fitted parameters from each
+    refinement are copied to the next histogram, so that the starting
+    point for each refinement will be the results from fitting the
+    previous. This works well for parametric experiments where
+    parameters such as the lattice parameters change gradually over
+    the course of successive measurements. 
+    This option is usually used only for the initial refinement after
+    a sequential fit is started and the setting is reset once that
+    refinement is completed. For subsequent refinements, it is usually
+    better to start with the results from the previous fit.
+  </DD>
+  <DT><B>Clear previous seq. results</B></DT>
+  <DD>When this button is pressed, the "Sequential Results" entry
+    with the results from the last sequential fit is deleted from the
+    tree. 
+  </DD>
+</DL>
 
 <h4 style='margin-left:0.25in'><a
@@ -7443 +7532 @@
 <hr size=2 width="100%" align=center>
 
-<!-- hhmts start -->Last modified: Sat Nov 21 12:25:40 CST 2020 <!-- hhmts end -->
+<!-- hhmts start -->Last modified: Sun Nov 29 20:05:28 CST 2020 <!-- hhmts end -->
 
 </div>