expand help on constraints & restraints & misc.

Author: briantoby

MDhelp/docs/commontreeitems.md

@@ -44,7 +44,7 @@ This window provides access to the controls that determine how GSAS-II performs
     * **Min delta-M/M** - A refinement will stop when the change in the minimization function, *M*,  \( (M=\sum[w(I_o-I_c)^2]) \) is less than this value. The allowed range is \(10^{-9}\) 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^{-4}\) cause refinements to continue even if there is no meaningful improvement.
     * **Max cycles** - This determines the maximum number of refinement cycles that will be performed. This is used only with the "analytical Hessian" and "Hessian SVD" minimizers.
     * **Initial lambda** - 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 ignored. Note that steepest-descents minimization is typically slow and may not always find the local minimum. This is only used when with the "analytical Hessian" minimizer is selected.
-    * **SVD zero tolerance** - This determines the level where SVD considers deivative values to be the same. Default is \(10^{-6}\). Make this larger when problems occur due to correlation. This is used only with the "analytical Hessian" and "Hessian SVD" minimizers.
+    * **SVD zero tolerance** - This determines the level where SVD considers derivative values to be the same. Default is \(10^{-6}\). Make this larger when problems occur due to correlation. This is used only with the "analytical Hessian" and "Hessian SVD" minimizers.
     * **Initial shift factor** - This provides an initial scaling ("damping") for the first cycle of refinement. Only available for "analytic Jacobian" and "numeric" minimizers. 
 
 2. **Single Crystal Refinement Settings**: 
@@ -152,7 +152,9 @@ Also included when sequential refinement is selected is a menu button labeled "S
 <a name="Restraints"></a>
 ## Restraints
 
-This window shows the restraints to be used in a refinement for each phase (if more than one). It is organized into several tabbed pages, one page for each type of restraint. Restraints are developed for an individual phase and act as additional observations to be "fitted" during the refinement.
+This window shows the restraints to be used in a refinement for each phase (if more than one). It is organized into several tabbed pages, one page for each type of restraint. Restraints are developed for an individual phase and act as additional observations to be "fitted" during the refinement. 
+
+Note that a restraint "pushes" a refinement towards a target value, but does not require that to happen (unlike a constraint). The strength of the "push" is dependent on the weighting factor and the "esd" used on the target value. The ideal use of a restraint is for an aspect of a structure that is not well-determined by the data. In this case, when the weighting of a restraint is dropped, the value of the restrained parameter may move considerably from the target value, but the quality of the fit (noted by the Rietveld plot, R-factor, reduced $\chi^2$, etc.) is not expected to change very much. If one places a restraint that is not consistent with the model (*e.g.* is wrong), then the fit will improve significantly as the weight is decreased. Such feedback is not possible with a constraint. 
 
 <H3 style="color:blue;font-size:1.1em">What can I do here?</H3>
 
@@ -171,6 +173,15 @@ This window shows the restraints to be used in a refinement for each phase (if m
     * **Change esd** - this changes the 'esd' value for selected restraints; a dialog box will appear asking for the new value.
     * **Delete restraints** - this deletes selected restraints from the list. A single click in the blank box in the upper left corner of the table will select/deselect all restraints.
 
+### Restraint types
+
+* **Bond**: Defines restraints with a target distance between pairs of atoms (which are typically bonded, but this is not required). Atom pairs to be restrained are set by performing a search and then selecting the pairs to be used. 
+* **Angle**:  Defines restraints with a target angle for a set of three atoms. Atoms to be used are located via a search and selection. 
+* **Plane**: Used to restrain selected atoms to be approximately co-planar. This is most commonly used for macromolecular crystallography. 
+* **Chiral**: Defines a chiral volume restraint. This is unlikely to be used other than for macromolecular crystallography. 
+* **Chem. Comp.**: This is of use when "Frac" parameters (atom occupancies) are refined. This option allows a variety of different types of restraints to be created. More than one chemical composition restraint can be defined for a phase. Examples of how this might be used would be to "push" refinement towards an expected composition, to encourage charge balance or to conserve valences. 
+* **General**: This allows a quantity to be restrained that is computed from a user-supplied equation, based on GSAS-II parameters. Thus, one can create any type of restraint that is desired. This restraint is used by supplying a Python equation and then to define which GSAS-II parameter is associated with each variable in the Python equation. One also supplies the target value for the restraint. Note that it is possible to use externally defined functions that contain "if" statements, which allows restraints that enforce minimum or maximum quantities rather than target values to be defined. 
+
 <a name="Rigidbodies"></a>
 <a name="Rigid_bodies"></a>
 ## Rigid bodies

MDhelp/docs/index.md

@@ -2,14 +2,18 @@
 <a name="HelpIntro"></a> 
 # Help for GSAS-II
 
-This and the subsequent web pages provide documentation for the
-GSAS-II graphical user interface (GUI). The information is organized
+This and the web pages referenced below, provide documentation for use
+of the GSAS-II graphical user interface (GUI). The information is organized
 largely to follow the different sections of the GUI and is usually
-accessed via the "Help" features in GSAS-II. Help on specific sections
-of GSAS-II can be accessed from the yellow "?" button in the upper
-right corner of the data window. Access to specific help information 
-is also offered on the graphics
-window and in other locations of the program. 
+accessed via the "Help" features in GSAS-II: Help on specific sections
+of GSAS-II can be accessed from the "?" button (yellow on some computers) in the upper
+right corner of the data window, or from the Help command. The GSAS-II
+graphics window and in other locations of the program also offer
+access to context-specific help information.
+
+A single file containing all GSAS-II web pages is available [as a PDF
+document](https://advancedphotonsource.github.io/GSAS-II-tutorials/docs/GSASII-help.pdf)
+(note: ~100 pages, please don't print it.)
 
 <a name="Index"></a> 
 An index on the topics covered in these help pages is given below. 
@@ -21,8 +25,8 @@ An index on the topics covered in these help pages is given below.
     3. [Graphics Window](./applicationwindow.md#Plots)
     4. [Console Window](./applicationwindow.md#Console)
 3. [Main menu contents](./mainmenu.md)
-4. Data tree entries and their use ([overview](./datatree.md))
-    1. [Universal data tree](./commontreeitems.md) items 
+4. [Data tree entries: overview](./datatree.md)
+    1. [Universal data tree items](./commontreeitems.md) 
         * [Notebook](./commontreeitems.md#Notebook) 
         * [Controls and settings](./commontreeitems.md#Controls) 
         * [Covariance and fit results](./commontreeitems.md#Covariance) 

MDhelp/docs/mainmenu.md

@@ -61,7 +61,9 @@ Finally, move to the atoms tab where atoms can be inserted or imported. Note tha
 
 * **Setup PDFs** - This is the first step in computing a pair distribution function (PDF). This creates the controls for each powder pattern selected in the dialog box, but does not compute the PDF, which must be done from [PDF tree entries](./pairdistribution.md). See [PDF Controls](./pairdistribution.md#PDF_Controls)  for information on the PDF input.
 
-* **View LS parms** - This shows a dialog box where the status and value of every parameter used in your project can be viewed. The parameter names are of the form `p:h:name:id` where 'p' is the phase index, 'h' is the histogram index and 'id' is the item index (for atoms). 'name' indicates the type of parameter, as [defined in developer's docs](https://gsas-ii.readthedocs.io/en/latest/objvarorg.html#parameter-names-in-gsas-ii). Indexes all begin with '0' (zero). The total number of refined parameters is shown at the top of the list. Optionally only those parameters that are refined can be viewed. The "Ref" column shows a "R" for parameters that are refined; a "C" for parameters where values are generated from a constraint. If shown as blank, the parameter value is fixed. Clicking on a row of the table brings up a window where parameter limits may be set. One may set a lower limit value, an upper limit value or both. When a parameter value refines to value outside the limit, the parameter is set to that limit value and the refinement flag for the parameter is subsequently ignored. 
+* **View LS parms** - This shows a dialog box where the status and value of every parameter used in your project can be viewed. The parameter names are of the form `p:h:name:id` where 'p' is the phase index, 'h' is the histogram index and 'id' is the item index (for atoms). 'name' indicates the type of parameter, as [defined in developer's docs](https://gsas-ii.readthedocs.io/en/latest/objvarorg.html#parameter-names-in-gsas-ii). Indexes all begin with '0' (zero). The total number of refined parameters is shown at the top of the list. Optionally only those parameters that are refined can be viewed. The "Ref" column shows a "R" for parameters that are refined; a "C" for parameters where values are generated from a constraint. If shown as blank, the parameter value is fixed. 
+
+    Clicking on a row of the table brings up a window where **parameter limits** may be set. One may set a lower limit value, an upper limit value or both. When a parameter value refines to value outside the limit, the parameter is set to that limit value and the refinement flag for the parameter is subsequently ignored. 
 
     !!! Note
         Note that for atom positions, the variables associated with coordinate values (named as `p::Aw:n`, where p is the phase number, n is the atom number and w is x, y or z) is not a refinable parameter, but the shift in the value is. The refined parameters are 'p::dAw:n'. The reason this is done is that by treating an atom position as (Ax+dAx,Ay+dAy,Az+dAz) where the “d” values indicate shifts from the starting position. Shifts are refined rather than the x, y, or z values as this this simplifies symmetry constraints. As an example, suppose we have an atom on a symmetry constrained site, `x,1/2-x,z`. The process needed to enforce this symmetry constraint, so that if x moves positively y has to move negatively by the same amount would be messy. With refinement of shifts, all we need to do is constrain the dAy to be equal to the negative of dAx (`0::dAy:n = -1 * 0::dAx:n` ).