phase tabs separated and revised; comments in README

Author: briantoby

MDhelp/README.md

@@ -15,13 +15,25 @@ additional links that need to be added:
       95 docs/others.md 
       10 docs/datatree.md
      207 docs/commontreeitems.md
-
-In progress (being broken up into sections by tab):
-
-     629 docs/phase.md 
-
-
-These files have had only minor editing. A few need to be broken up:
+      32 docs/phaseRB.md
+      51 docs/phaseRMC.md
+      81 docs/phaseatoms.md
+      70 docs/phasedata.md
+      64 docs/phasedrawatoms.md
+      14 docs/phasedrawopts.md
+      11 docs/phasedysnomia.md
+      96 docs/phasegeneral.md
+      27 docs/phaseisodistort.md
+      25 docs/phaselayers.md
+      25 docs/phasemappeaks.md
+      13 docs/phasemcsa.md
+      25 docs/phaseoverview.md
+      20 docs/phasepawley.md
+     128 docs/phasetexture.md
+      12 docs/phasewave.md
+
+These files have had only minor editing. histgramtree.md should
+probably be broken up:
 
      170 docs/cluster.md
      445 docs/histgramtree.md
@@ -39,3 +51,6 @@ Needs more work: menu commands not described or well described in
 atoms, draw atoms & draw options. Should also describe the settings on
 draw options. Also, how does one expand a drawing to multiple cells? I
 always forget that trick!
+
+Texture: are there places where capital greek letters should be used
+to differentiate symbols (\Phi vs \phi) orientation angles?

MDhelp/docs/index.md

@@ -15,15 +15,20 @@ An index on the topics covered in these help pages is given below.
 <a name="Index"></a>
 
 1. [Tutorials](./preface.md)  
+
 2. [GSAS-II GUI Organization](./applicationwindow.md)
     1. [Data Tree](./applicationwindow.md#Data_tree)  
     1. [Data Window](./applicationwindow.md#Data_frame)  
     1. [Graphics Window](./applicationwindow.md#Plots)  
     1. [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
+    
     2. [Phase Data Tree items (overview)](./phaseoverview.md) 
+    
         * [General Phase tab](./phasegeneral.md)  
         * [Data Phase tab](./phasedata.md) 
         * [Atoms Phase tab](./phaseatoms.md) 
@@ -32,7 +37,8 @@ An index on the topics covered in these help pages is given below.
         * [RB Models tab](./phaseRB.md)
         * [Texture tab](./phasetexture.md)
         * [Map Peaks tab](./phasemappeaks.md)
-        * [Pawley tab](./phasepawley.md)
+        * [Pawley tab](./phasepawley.md) 
+        * [Layers tab](./phaselayers.md)
         * [Wave Data tab](./phasewave.md)
         * [MC/SA tab](./phasemcsa.md)
         * [RMC tab](./phaseRMC.md)

MDhelp/docs/phase.md

@@ -0,0 +1,32 @@
+<a name="Phase-RB_Models"></a>
+# **RB Models** phase tab
+
+A rigid body is a collection of atoms that is treated as a group in GSAS-II. The position and orientation of the group can be refined and some other simplified parameters can also be varied, such as dihedral angles. Use of a rigid body requires two actions. First the rigid body must be defined for the project, see the [Rigid bodies tree item](./commontreeitems.md#Rigidbodies) for details on that. Then the rigid body must be inserted into a phase, which is done here, from the phases's RB Models tab. In this process, a number of parameters are defined for each body that determine how the rigid body is placed in the cell: the location in the cell for the rigid body origin, a rotation angle and orientation vector. These can be modified while being visualized, using the mouse by holding down the Alt key. 
+
+<H3 style="color:blue;font-size:1.1em">What can I do here?</H3>
+
+A rigid body can be inserted into a phase using the "Locate & Insert Rigid Body" command in the "Edit Body" menu.
+
+Once a body has been inserted into a structure, this tab provides access to the rigid body placement parameters, as well controls that determine how the rigid body is refined. Note that the selected rigid body can be positioned and oriented in the unit cell by holding down the Alt key (option on Mac) while "dragging" the mouse (moving the mouse while holding a mouse button down.) Dragging the mouse without the Alt key repositions the view of the cell.
+
+<H3 style="color:blue;font-size:1.1em">What can I do with the plot?</H3>
+
+Use of the mouse buttons when viewing a crystal structure changes the view of the structure. On a Mac with a one-button mouse, [some alternate actions must be used](./others.md#MacOS).
+
+* **Left drag**: Holding down left button rotates axes around screen x & y
+* **Right drag**: Holding down right button translates the fractional coordinates assigned to the viewpoint (which is kept at the center of the plot). The structure will appear to translate. The viewpoint can also be entered directly in the Draw Options.
+* **Middle drag**: Holding down center button rotates axes around screen z (direction perpendicular to screen).
+* **Mouse Wheel**: Rotating the scroll wheel changes "camera distance" (zoom in/out).
+
+Use of the Alt key causes the above mouse movements to reposition the rigid body rather than change the view of the crystal structure. This can be done when the rigid body is being added to a model or later by selecting the body.
+
+When the rigid body is being initially inserted into a structure, both the rigid body and the crystal structure are displayed. The rigid body will be displayed with a "Balls-and-Sticks" model but bonds will be drawn in green. It is useful to plan for this by preselecting the atoms in the Draw Atoms list and to have atoms displayed as "Sticks" or "Balls-and-Sticks" etc. so that it is easy to differentiate positions of atoms already in the model from the new rigid body location.
+
+When the rigid body has already been placed in the model, the rendering of the structure works a bit differently. As the rigid body is repositioned via Alt+mouse drag, all atoms in the Draw Atoms array are deleted and only the atoms in the asymmetric unit are displayed. The mode used to draw them will depend on the selection made on this window; (the default selection is "Balls-and-Sticks".) When the mouse button is released, if the "Fill cell" option is selected, the symmetry replicants of the atoms in the asymmetric falling inside the unit cell are placed into the Draw Atoms array.
+
+Actions to reposition the rigid body in either mode are:
+
+* **Alt+Left drag**: Holding Alt (Opt on Mac) while dragging the mouse with the left button down rotates the rigid body around screen x & y axes
+* **Alt+Middle drag**: Holding Alt while dragging the mouse with the middle button down rotates the rigid body around screen z (out of screen) axis. On the Mac hold down the Alt and Command buttons together.
+* **Alt+Right drag**: Holding Alt while dragging the mouse with the right button down (use Control+Opt on Mac with a single-button mouse) translates the rigid body in the screen x & y directions (rotate the plot to see and move in the rigid body in the third direction.) Selecting the "Lock" checkbox next to the origin location, or unselecting the "Refine?" button locks the origin from being changed via mouse dragging when the location should be fixed by symmetry.
+

MDhelp/docs/phaseRB.md

@@ -0,0 +1,51 @@
+<a name="Phase-RMC"></a>
+# **RMC** phase tab
+
+This tab is used for access to three different programs, [RMCProfile](#rmcprofile), [fullrmc](#fullrmc) and [PDFfit](#pdffit),
+that are used for fitting structural models to pair distribution functions (PDF).
+RMCProfile and fullrmc are "big box" modelling routines and PDFfit is a "small box" modelling routine. 
+Select the program you wish to use from radio button at the top of the window. Three
+different windows are displayed depending on that selection. 
+
+[Tutorials](https://advancedphotonsource.github.io/GSAS-II-tutorials/tutorials.html) for using RMCProfile and PDFfit can be accessed from the Tutorials menu item in the GSAS-II Help menu. These routines all run as stand-alone applications which are initiated by GSAS-II. When finished, GSAS-II processes their output files to update parameters that are within the GSAS-II project. The two big box routines can have very long running times; they run as separate console programs. GSAS-II is active while they are running and can "interrogate" them for intermediate results. PDFfit has a short running time and GSAS-II is "locked out" until it finishes; its result can be examined after.
+
+<H3 style="color:blue;font-size:1.1em">What can I do here?</H3>
+
+**Operations** Menu –
+
+   * **Setup RMC** – this builds the input files and python script (if needed) for running the selected PDF modeling program.
+   * **Execute** – this executes the chosen program in a new console which will vanish when finishes (after a "press any key" command). When finished, GSAS-II will extract results and place them in appropriate places in the project.
+   * **Stop run** – only valid for fullrmc; stops the RMC run & saves progress so it can be continued later.
+   * **Plot** – this displays the resulting graphical output from the PDF modeling run. For RMCProfile and fullrmc this can be 5 or more plots, for PDFfit it is only the observed and calculated G(r) plot with a difference curve.
+
+For each program, the setup page is similar. There is a block for "metadata" items for your convenience; they have no impact on the calculations. Next is timing controls for the big box programs (PDFfit has none). Then is structural information and finally the data section for the patterns to be fitted. The big box programs are for only single runs while PDFfit can be used to process a sequence of G(r) data collected as a function of, e.g., temperature (giving Sequential PDFfit2 results).
+
+<a name="fullrmc"></a>
+### fullrmc
+
+The fullrmc program is a large-box pair distribution function modeling library developed by Bachir Aoun [Fullrmc, a Rigid Body Reverse Monte Carlo Modeling Package Enabled with Machine Learning and Artificial Intelligence", B. Aoun, Jour. Comp. Chem. (2016), 37, 1102-1111. [DOI: 10.1002/jcc.24304](https://doi.org/10.1002/jcc.24304)]. Extensive information about fullrmc is found, including a number of explanatory videos, along with older source code on GitHub: [https://bachiraoun.github.io/fullrmc/](https://bachiraoun.github.io/fullrmc/). Note that the GSAS-II implementation is not compatible with the open-source version of fullrmc, but rather the new version 5.0 must be used, which is distributed as a compiled versions for 64-bit Intel-compatible processors running Windows, Linux and MacOS from website [https://github.com/bachiraoun/fullrmc/tree/master/standalones](https://github.com/bachiraoun/fullrmc/tree/master/standalones). Note that an even newer and more powerful version of fullrmc is available for cloud computing by subscription at [https://fullrmc.com](https://fullrmc.com). 
+
+When fullrmc is selected in this tab, GSAS-II will locate an executable for fullrmc using the [GSAS-II configuration variable](./others.md#config)  `fullrmc_exec`, which if defined points to a Python image with fullrmc. Otherwise GSAS-II will look in the following places, in the order specified, for a Python image for a file named `fullrmc5*64bit` (MacOS or Linux) or `fullrmc5*.exe` (Windows):
+
+1. The location where GSAS-II is installed,
+2. The location where Python is installed,
+3. The location where the GSAS-II binaries are found,
+4. the current default location
+5. and all directories in the system path. 
+
+<a name="rmcprofile"></a>
+### RMCProfile
+The [RMCProfile program](http://rmcprofile.org/) fits large-box atomic models to x-ray & neutron PDF and S(Q) "data" as well as other types of observations. 
+When RMCProfile is selected in this tab, GSAS-II will see if an RMCProfile
+executable can located using the [GSAS-II configuration variable](./others.md#config)  `rmcprofile_exec`, which if defined should have the name of the RMCProfile program. If that is not defined, the following locations are searched:
+
+1. The location where GSAS-II is installed,
+2. The location where Python is installed,
+3. The location where the GSAS-II binaries are found,
+4. the current default location
+5. and all directories in the system path. 
+
+<a name="pdffit"></a>
+### PDFfit2
+The [PDFfit2](https://www.diffpy.org/diffpy.pdffit2/) program fits small-box atomic models to x-ray & neutron PDFs.
+When PDFfitis selected in this tab, GSAS-II will see if PDFfit2 can be loaded as a package in the current Python installation (use of PDFfit2 in this manner is not recommended as this invites conflicts in the packages used by GSAS-II and PDFfit2) if that fails, GSAS-II will attempt to use a Python executable for PDFfit2 using the [GSAS-II configuration variable](./others.md#config)  `pdffit_exec`, which if defined points to a Python image with PDFfit2fullrmc. Optionally, if the Python installation used with GSAS-II uses conda (which is the case for the [gsas2main installer](https://advancedphotonsource.github.io/GSAS-II-tutorials/install.html#gsas2main-installer)), GSAS-II can download and install a separate conda environment with PDFfit2 installed. 

MDhelp/docs/phaseRMC.md

@@ -63,7 +63,7 @@ graphics window's structure drawing that is marked by crossing , red, green and
 <a name="Phase-mouse-plotopts"></a>
 <H3 style="color:blue;font-size:1.1em">What can I do with the plot?</H3>
 
-A drawing of the crystal structure will be displayed in the [Graphics Window](./applicationwindow.md#Plots) only if the [Draw Options](./phasedrawopts.md) or [Draw Atoms](./phasedrawatoms.md) tab has been visited first prior to selecting the Atoms tab. When back at the Atoms tab, the following actions and keypress commands are available, when use of the mouse buttons changes the view of the structure and can be used to select atoms. On MacOS and a one-button mouse, [some alternate actions must be used](./others.md#MacOS)
+A drawing of the crystal structure will be displayed in the [Graphics Window](./applicationwindow.md#Plots) only if the [Draw Options](./phasedrawopts.md) or [Draw Atoms](./phasedrawatoms.md) tab has been visited first prior to selecting the Atoms tab. When back at the Atoms tab, the following actions and keypress commands are available, when use of the mouse buttons changes the view of the structure and can be used to select atoms. On a Mac with a one-button mouse, [some alternate actions must be used](./others.md#MacOS)
 
 * **Left drag**: Holding down left button rotates axes around screen x & y
 * **Right drag**: Holding down right button translates the fractional coordinates assigned to the viewpoint (which is kept at the center of the drawing). The structure will appear to translate. The viewpoint can also be entered directly in the [Draw Options](./phasedrawopts.md)..

MDhelp/docs/phaseatoms.md

@@ -41,7 +41,8 @@ For single crystal data, the only parameters are scale, extinction and disordere
 * **Hydrostatic/elastic strain** – This shifts the lattice constants for the contribution of a phase into a histogram. The values are added to the [reciprocal lattice parameter tensor terms](http://gsas-ii.readthedocs.io/en/latest/GSASIIutil.html#gsasiilattice-unit-cell-computations). They must be refined in sequential refinements or where the lattice constants are slightly different in different histograms (as an example see the [Combined X-ray/CW-neutron refinement of \(\rm PbSO_4\) tutorial](https://advancedphotonsource.github.io/GSAS-II-tutorials/CWCombined/Combined%20refinement.htm). But these values and the phase's lattice parameters (on the General tab) should not be refined at the same time. When the values are non-zero, the lattice constants after application of these strain tensor terms is shown. 
 
 <a name="Phase-Preferred_orientation"></a>
-* <a id="preferred_orientation"></a>**Preferred Orientation** – Preferred orientation (texture) can be treated in one of two different sections of GSAS-II, either the Preferred Orientation correction here in the Data tab, or the "[Texture](#TBD)" tab, depending on what is desired. 
+<a name="preferred_orientation"></a>
+* **Preferred Orientation** – Preferred orientation (texture) can be treated in one of two different sections of GSAS-II, either the Preferred Orientation correction here in the Data tab, or the "[Texture](#TBD)" tab, depending on what is desired. 
 The Preferred Orientation correction here is typically used for crystallographic studies, where intensity corrections are desired to repair for undesired texture in the sample, while the Texture tab is used for studies where the goal is to characterize preferred orientation in a sample.
 
     The preferred orientation correction, here in the Phase/Data tab, can apply one of two different types of intensity corrections. One is to apply a cylindrical (wire symmetry) spherical harmonics orientational distribution function and the other is a simpler,   single-parameter model, known as **March-Dollase**. Note either of these is applied to only a single histogram.

MDhelp/docs/phasedata.md

@@ -0,0 +1,11 @@
+<a name="Phase-Dysnomia"></a>
+# **Dysnomia** phase tab
+
+This is displayed if the **Use Dysnomia** box in the General tab is checked. [Dysnomia](https://doi.org/10.1017/S088571561300002X) is a maximum entropy method for improving Fourier density maps. The Dysnomia tab provides access to controls used in its operation.
+
+<H3 style="color:blue;font-size:1.1em">What can I do here?</H3>
+
+* **Operations** menu –
+    * **Load from Dysnomia file** – as previously saved set of controls.
+    * **Save Dysnomia file** – saves data needed to run Dysnomia
+    * **Run Dysnomia** – execute the routine from GSAS-II (not a separate console). Replaces existing map with one improved by maximum entropy.

MDhelp/docs/phasedysnomia.md

@@ -0,0 +1,27 @@
+<a name="Phase-ISODISTORT"></a>
+# **ISODISTORT** phase tab
+
+This displays the setup for using the web-based application, [ISODISTORT](https://iso.byu.edu/iso/isodistort.php), to identify the possible mode distortions of a parent structure. To use it you must be connected to the internet. Two ISODISTORT Methods are supported in GSAS-II: 
+
+ * Method 1: identifies all possible subgroups that result from simple mode distortions that are associated with a single irreducible representation. 
+ * Method 4: is more useful in that it finds the mode decomposition of a parent structure to give a specified distorted structure and is set up to find only atom displacement modes. 
+
+See help pages for [ISODISTORT](https://iso.byu.edu/iso/isodistort.php) for more information. The ultimate product of using ISODISTORT is a special CIF file with constraints describing the mode distortions; this is imported into GSAS-II to form a new phase with these constraints.
+
+<H3 style="color:blue;font-size:1.1em">What can I do here?</H3>
+
+If this is a freshly created phase (not an imported ISODISTORT CIF) then you can choose the Method (4 is default) and select parent structure and distorted child structure (for Method 4).
+
+If you chose Method 1 & run ISODISTORT, a table of possible substructures is displayed; a CIF file with mode distortion constraints can be produced from your selection. The table can be filtered by crystal class.
+
+If this is a phase imported from an ISODISTORT CIF file, the mode displacements are shown with sliders to allow visualization of the displacements in a drawing of the crystal structure (prepare this first before trying a slider). A structure refinement using this phase will employ the mode distortions as constraints on the atom coordinates; there should be as many as there are free variable coordinates in the structure. The values (in Å) represent the largest atom shift associated with the mode; shown is a list of atom coordinates affected by each mode.
+
+* **Operations** menu –
+
+    * **Run ISODISTORT** – run this from the web site with the controls as shown.
+    * **Make cif file** – active after table from Method 1 is displayed; generate CIF file by ISODISTORT web site with mode distortion constraints.
+    * **Make PDFfit phase** – active when mode distortions are shown. Makes new phase specific for fitting PDF data via PDFfit2.
+    * **Show modes** – active when mode distortions are shown. Displays mode names & values.
+    * **Show relationships** - active when mode distortions are shown. Displays constraint equations associated with mode distortions.
+
+