Changeset 4668 for trunk

Timestamp:

Dec 2, 2020 11:39:06 AM (12 months ago)

Author:

toby

Message:

updates to refinement options

File:

• trunk/help/gsasII.html (modified) (10 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 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>
+"Times New Roman"'>This window provides access to the controls that
+determine how GSAS-II performs minimizations as well as few
+global parameters for GSAS-II. Note that many other customization
+settings are set as <A Href=#Preferences>configuration variables</a>
+in the Preferences menu. (See the 
+<a
+href="https://gsas-ii.readthedocs.io/en/latest/GSASIIutil.html#module-config_example">
+Programmer's documentation</a> for a description of those.)
+</P>
+
+<p style='margin-left:0.75in'><U>Refinement Controls:</u><i> These
+controls determine how refinements are performed. The first determines
+the computational engine used to minimize the structure. 
+</i></p>
+
 <A name="RefineType"></A>
 <DL style='margin-left:1.0in'>
@@ -3693 +3699 @@
     <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
+      the most useful. It uses a 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
+      Levenberg-Marquardt algorithm to up-weight 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
+      minimizer, which not applicable for 
+      problem with a large number of histograms 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.
+      creates a Jacobian matrix that is shaped N x M (N parameters x M
+      observations) while the Hessian methods create a Jacobian matrix
+      only each histogram. 
       <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
+      problems. Unlike, the "analytic Jacobian", numerical derivatives
+      are computed rather than use the analytical derivatives
       that are coded directly into GSAS-II. This will be slower than
-      the analytical derivatives and will converge more slowly. It is
+      the analytical derivatives and will is often less accurate which
+      results in slower convergence. It is
       typically used for code development to check the accuracy of the
       analytical derivative formulations. 
@@ -3716 +3723 @@
       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.
+      diverge when severe correlation is present. It is possible that
+      it might be better for single-crystal refinements. 
     </UL>
 <p style='margin-left:0.25in'>
@@ -3735 +3743 @@
 </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>
+  <DD>A refinement will stop when the change in the minimization function
+    (M=Σ[w(Io-Ic)<sup>2</sup>])
+    is less than this value.  The allowed range is 10<sup>-9</sup> to
+    1.0, with a default of 0.001. A value of 
+    1.0 stops the refinement after a single cycle. Values less than
+    10<sup>-4</sup> cause refinements to continue even if there is
+    no meaningful improvement. 
+  </DD><P></P>
   <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>
+    will be performed. This is only available with the "Hessian" minimizers.</DD><P></P>
   <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
+  <DD>Note that here λ is the Marquardt coefficient, where a weight of
+    1+λ is applied to the diagonal elements of the Hessian. When λ is
+    large, this 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
@@ -3756 +3763 @@
     slow and may not always find the local minimum.
     This is only available with the "analytical Hessian" minimizer.
-  </DD>
+  </DD><P></P>
   <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>
+  </DD><P></P>
   <DT><B>Initial shift factor</B></DT>
-  <DD>?
-  </DD>
+  <DD>A “damping multiplier” applied during the first refinement
+    cycle, for Jacobean/numeric refinements only. 
+    Should be in interval (0.1, 100). See the
+    <A href="https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.leastsq.html">SciPy leastsq docs</A>
+    for more information. 
+  </DD><P></P>
 </DL>
   <A name="SingleXtlSettings"></A>
-<p style='margin-left:0.75in'>A set of controls is provided for
+<p style='margin-left:0.75in'><U>Single Crystal:</u><i> 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. 
+in the project. </i>
 </p>
 <DL style='margin-left:1.0in'>
@@ -3775 +3786 @@
   <DD>When checked, refinements are against F<sup>2</sup> rather than
     |F|. 
-  </DD>
+  </DD><P></P>
   <DT><B>Min obs/sig</B></DT>
-  <DD>?
-  </DD>
+  <DD>Conventional cutoff for single crystal refinements as to what reflections
+    should be considered observed, typical values are 2.0 (2σ) or 3.0 (3σ).
+  </DD><P></P>
   <DT><B>Min extinct.</B></DT>
-  <DD>?
-  </DD>
+  <DD>(needs further work)
+  </DD><P></P>
   <DT><B>Max delt-F/sig</B></DT>
-  <DD>?
-  </DD>
+  <DD>Removes reflections that are very poorly fit. Should be used
+    only with extreme care, since poorly-fit reflections could be an
+    indication that the structure is wrong. 
+  </DD><P></P>
   <DT><B>Max d-spacing</B></DT>
   <DD>Reflections with d-space values larger than this value are ignored. 
-  </DD>
+  </DD><P></P>
   <DT><B>Min d-spacing</B></DT>
   <DD>Reflections with d-space values smaller than this value are ignored. 
-  </DD>
+  </DD><P></P>
   
 </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 style='margin-left:0.75in'><U>Sequential Settings:</u><i>
+A set of controls is for
+sequential refinement. Settings here determine if a "normal" or "sequential"
+refinement is performed. If no datasets are selected here, then all 
+histograms linked to phases in the project and that are flagged as
+"used" are included in one potentially large (combined)
+refinement. However, if any
+number of histograms are selected here, then a
+sequential refinement is performed, where a fit is made to the
+structural model(s) fitting each selected 
+histogram in turn. Only the first item below is shown in "normal" mode. </i>
 </p>
 <DL style='margin-left:1.0in'>
@@ -3811 +3829 @@
     set as "normal". The button is labeled "Select" when in normal refinement
     mode and "Reselect" in sequential refinement mode. 
-    </DD>
+    </DD><P></P>
   <DT><B>Reverse order?</B></DT>
   <DD>Normally, in a sequential histograms are fit in the order they
@@ -3818 +3836 @@
     but when this option is selected, the sequential fit is performed
     with the last tree entry first.
-  </DD>
+  </DD><P></P>
   <DT><B>Copy results to next histogram?</B></DT>
   <DD>When this option is selected, the fitted parameters from each
@@ -3830 +3848 @@
     refinement is completed. For subsequent refinements, it is usually
     better to start with the results from the previous fit.
-  </DD>
+  </DD><P></P>
   <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>
+  </DD><P></P>
 </DL>
+<p style='margin-left:0.75in'><U>Global Settings:</u><i>
+This is a location for parameters that apply to an entire project.
+At present there is only one. </i>
+</p>
+<DL style='margin-left:1.0in'>
+  <DT><B>CIF Author</B></DT>
+  <DD>The value provided here is used when creating a CIF of an
+    entire project. 
+  </DD><P></P>
+</DL>
+
+<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'>This offers a place to change how
+GSAS-II performs refinements, but has no specific menu commands or
+graphics.
+</p>
 
 <h4 style='margin-left:0.25in'><a
@@ -7532 +7568 @@
 <hr size=2 width="100%" align=center>
 
-<!-- hhmts start -->Last modified: Sun Nov 29 20:05:28 CST 2020 <!-- hhmts end -->
+<!-- hhmts start -->Last modified: Wed Dec  2 11:04:42 CST 2020 <!-- hhmts end -->
 
 </div>