doc: simon refresh of manual and docs (#256)

* intermediate commit of new tutorial

* news

Author: sbillinge

doc/source/tutorial.rst

@@ -17,51 +17,114 @@ Input files:
     1. Ni-xray.gr - experimental X-ray PDF data
     2. Ni.stru - Ni f.c.c. structure in PDFfit format
 
+This manual will help you to get started with ``PDFgui``.  We strongly recommend that that you refer to
+the book `Atomic pair distribution function analysis: a primer` by Simon J. L. Billinge, Kirsten Jensen
+Soham Banerjee, Emil S. Bozin, Benjamin A. Frandsen, Maxwell W. Terban and Robert J. Koch, Oxford:
+Oxford University Press, 2024. URL: https://global.oup.com/academic/product/atomicpair-distribution-function-analysis-9780198885801?cc=us&lang=en&
+for much more extensive and detailed descriptions of carrying out fits with PDFgui (and the related program diffpy-cmi).
+
 Procedure:
 
-1. Open a terminal and type ``pdfgui`` to start the program.
+1. Open ``pdfgui``. Instructions for doing this depend on your system, but an example would be
+   to open a terminal, activate your pdfgui conda environment, and type ``pdfgui`` at the prompt,
+   or to double-click a project file on windows.
 
 2. Create a new Fit:
-    1. Select "FITTING" in the left-most vertical tab.
-    2. Click right mouse button in the left panel and choose "New Fit" in the pop-up menu.
+    1. In the GUI locate the ``Fit Tree`` panel.  In the default layout it is at the top left of the page.
+    2. With your mouse on that panel, right-click the mouse and select "New Fit" from the pop-up menu.
+    3. By default, your fit will be called ``Fit 1``. To give it a more meaningful name, left
+       click the ``Fit 1`` name. It should open an editable box and you can type in a name for your
+       fit such as "Fit of Ni structure to Ni data"
+    4. Note, an alternative workflow to create a new fit is to find ``New fit`` under the ``Fits`` dropdown menu.
 
 3. Load structure model:
-    1. Place the cursor of the mouse onto the title of the Fit, click the right button and choose "Insert Phase" in the pop-up menu.
-    2. Click the "Open" button and load the `Ni.stru` file.
+    1. Carefully place your cursor on to the title of the Fit and right-click. Select "Insert Phase" from the pop-up menu.
+    2. Click the "Open" button and navigate to and load the ``Ni.stru`` file that you downloaded.  You could select
+       valid structure model file, a ``.stru`` or a ``.cif`` file.
+    3. Note, an alternative workflow for adding structural models is to select ``New Phase`` from the ``Phases`` dropdown menu.
+
+   If you select the Phase in the ``Fit Tree`` by left clicking on it, you will see in the
+   right panel 3 tabs, ``Configure`` ``Constraints``, ``Results``.  Feel free to click one
+   these tabs and look inside.  The Configure panel has the initial inputs from the loaded str or cif file,
+   The ``Constraints`` panel will hold the constraints we will set up for our fits, it should be empty now,
+   and the results tab will contain the results of any fit.
 
-   The right panel has 3 tabs for the initial configuration, constraints panel for expressing structure properties as functions of tunable parameters, and Results panel for refined structure.
+   Note that what you see on the right is "Context Dependent", it depends on what you have selected on the left.
+   By selecting a phase on the left, the tabs on the right contain information about that phase, and so on.
 
 4. Load experimental PDF data:
-    1. Select the title of "Fit 1", click the right button and choose "Insert Data Set" in the pop-up menu.
-    2. Load the `Ni-xray.gr` file.
+    1. As before, hover over your cursor over the title of your fit and right-click.  This time select
+       ``Insert Data Set`` from the pop-up menu.
+    2. Navigate to and load the `Ni-xray.gr` file that you downloaded.
 
-   Again, the right panel shows 3 tabs for properties of this dataset.
+   Again, the right panel shows 3 tabs, now for properties of this dataset.
 
 5. Define what is refined:
     1. Click on the `Ni-xray.gr` data and select the "Constraints" tab.
-    2. Type ``@1`` into "Scale Factor" edit box.
+    2. Type ``@1`` into the "Scale Factor" edit box.
     3. Select the `Ni.stru` phase and its "Constraints" tab.
     4. Fill "a", "b", "c" boxes with ``@5``.
 
-   A refined variable can be expressed as a math expression:
+   Here we are defining "variables" that will be refined and giving them names
+   variable "@1", "@5", etc. and linking them to model parameters by typing them
+   in the text-box associated with the parameter.  So by typing ``@1`` in the
+   data "Scale-Factor" text box we are saying that we are logically assigning the constraint
+   equation ``data.scale_factor = variable("@1")``.
+
+   When we assign the three parameters ``a``, ``b`` and ``c`` to the same variable,
+   ``@5``, we are implicitly ensuring that the refinement will respect
+   the cubic symmetry of the nickel structure and that ``a = b = c``, because the
+   three parameters are assigned to the same variable, so however much ``a``
+   is changed in the refinement, ``b`` and ``c`` will be changed by the same amount.
+   Note that the variable ensures that changes to ``a``, ``b`` and ``c`` are always
+   the same, so we have to also ensure that the initial values of ``a``, ``b`` and ``c``
+   are the same as each other to ensure that the structure is cubic and remains so.
+
+   PDFgui allows us to express more complex constraint equations than
+   simply assigning a parameter to a variable.
+   In general, we can type into be Constraints tab text box any math expression:
    ``f(@n1, @n2, @n3, ...)`` where
-   ``@n1`` stands for fitted parameter and
+   ``@n1`` stands for the fitted parameter, where it is understood that
    ``n1, n2, ...`` are arbitrary positive integers.
-   This allows simple linking of related variables - for example, since
-   cell lengths a, b, c are all expressed as ``@5``, the refined structure will remain cubic.
+   This allows simple linking of related variables.  For example, if we want to allow a
+   crystallographic site to contain either Ni or Pt, we don't know how much Ni or Pt is
+   on the site, but we want it to be always fully occupied, we could create two lattice
+   site entries with the same fractional coordinates, with one assigned Ni as the element and the other
+   assigned Pt as the element. Then we could assign the Ni occupancy as ``@100``.  Then
+   typing ``1-@100`` into the constraint text box of the Pt occupancy ensures that however
+   much the occupancy of the Ni site goes down in a refinement, the occupancy of the Pt on that
+   same site goes up by the same amount.  This ensures full occupancy of that site, as long
+   as the initial occupancies of the Ni and Pt added up to 1.
 
 6. Start the refinement:
-    1. Select "Fit 1" in the left panel.  The parameters panel shows a list of used parameters and their initial values.
-    2. Click the "gear" icon on the toolbar and watch the fit progress in the terminal window.
+    1. Select the fit to run by left clicking the title of the fit in the ``Fit Tree`` panel.
+       The ``Parameters`` panel on the right shows a list of variables that you have defined
+       and their initial values.  Each one also has a check-box that allows you to fix them
+       (prevent them from varying in the subsequent refinement).  Unchecked boxes mean the variable
+       will be refined.
+    2. When you are satisfied with the configuration, click the "gear" icon on the toolbar
+       and watch the fit progress in the terminal window.
 
 7. Plot the results:
-    1. Select "PLOTTING" in the left-most vertical tab.
-    2. Select the `Ni-xray.gr` dataset.
-    3. Select "r" as the X plotting variable.
-    4. Hold down shift and select "Gcalc" and "Gtrunc" as the Y plotting variables.
-    5. Click "Plot" button.
+    1. Select the data in the fit (in this case the `Ni-xray.gr` dataset) by left clicking it.
+    2. Click the ``plot`` icon in the toolbar.  This is the icon that looks a bit like a PDF
+       to the right of the Gear and the red/grey X.
+
+    A new window pops up with the plots. It will show the data in blue, the best-fit model
+    curve in red, and offset below, the difference curve in green.  The offset of the difference
+    curve appears at a default value of ``-5.0``.  You can make your plot more pretty and meaningful
+    by typing a different offset into the ``offset`` text box and hitting ``Plot`` again.
+
+    It is possible to configure the plot in the ``Plot Control`` panel in the GUI.
+    In the default layout it will be at the lower-left of the GUI panel.
+
+    1. To plot the fit (as was done above) elect "r" as the X plotting variable.
+    2. Hold down shift and select "Gcalc" and "Gtrunc" as the Y plotting variables.
+    3. Click the "Plot" button.
+
+    This panel allows more plotting options for advanced cases such as plotting the values
+    of parameters refined across multiple fits to extract temperature dependent information.
 
-   A new window pops up with plots.  You can try out the buttons in the toolbar below.
 
 8. Save your project for later use.
 

news/docs2501.rst

@@ -0,0 +1,23 @@
+**Added:**
+
+* <news item>
+
+**Changed:**
+
+* Refreshed tutorial manual and brought documentation up to date
+
+**Deprecated:**
+
+* <news item>
+
+**Removed:**
+
+* <news item>
+
+**Fixed:**
+
+* <news item>
+
+**Security:**
+
+* <news item>