Merge pull request #173 from ycexiao/rm_texinfo

docs: move manual to online doc

Author: sbillinge

AUTHORS.rst

@@ -1,5 +1,5 @@
 Authors
-=======
+========
 
 Billinge Group and community contributors.
 

doc/source/images/ex_tutorial_bar.png

@@ -39,12 +39,11 @@ the plotted PDFs.
 Finally, we note that though ``diffpy.morph`` should work on other spectra
 that are not PDFs, it has not been extensively tested beyond the PDF.
 
-To get started, please download our :download:`user manual  <../manual/diffpy.morph.pdf>`
-or visit the :ref:`quick_start`.
+To get started, please visit the :ref:`quick_start`.
 
-=======
+========
 Authors
-=======
+========
 
 ``diffpy.morph`` is developed by members of the Billinge Group at
 Columbia University and Brookhaven National Laboratory including
@@ -72,9 +71,9 @@ Table of contents
    release
    Package API <api/diffpy.morph>
 
-=======
+========
 Indices
-=======
+========
 
 * :ref:`genindex`
 * :ref:`search`

doc/source/images/ex_tutorial_temp.png

@@ -4,8 +4,13 @@ diffpy.morph Tutorial
 #####################
 
 Welcome! This will be a quick tutorial to accquaint users with ``diffpy.morph``
-and some of what it can do. For a more detailed tutorial, check out
-our :download:`user manual <../manual/diffpy.morph.pdf>`.
+and some of what it can do. To see more details and definitions about
+the morphs please see the publication describing ``diffpy.morph``.
+
+To be published:
+
+*
+
 
 As we described in the README and installation instructions, please make
 sure that you are familiar with working with your command line terminal
@@ -14,6 +19,11 @@ before using this application.
 Before you've started this tutorial, please ensure that you've installed
 all necessary software and dependencies.
 
+In this tutorial, we will demonstrate how to use ``diffpy.morph`` to compare
+two
+PDFs measured from the same material at different temperatures.
+The morphs showcased include "stretch", "scale", and "smear".
+
 Basic diffpy.morph Workflow
 ===========================
 
@@ -51,7 +61,8 @@ Basic diffpy.morph Workflow
        * Note that these files have the ``.gr`` extension, which
          indicates that they are measured PDFs. The ``.cgr`` file
          extension indicates that a file is a calculated PDF, such as
-         those generated by the `PDFgui <https://www.diffpy.org/products/pdfgui.html>`_
+         those generated by the
+	 `PDFgui <https://www.diffpy.org/products/pdfgui.html>`_
          program.
 
     4. First, we will run the ``diffpy.morph`` application without any morphing
@@ -81,6 +92,12 @@ Basic diffpy.morph Workflow
          and the second as the "target", as the ``diffpy.morph`` display
          does.
 
+    .. figure:: images/qs_tutorial_unmorphed.png
+       :align: center
+       :figwidth: 100%
+
+       Using ``diffpy.morph`` to compare two different PDFs without morphing.
+
     6. Now, we will start the morphing process, which requires us to
        provide initial guesses for our scaling factor, Gaussian smear,
        and stretch, separately. We will start with the scaling factor.
@@ -117,6 +134,12 @@ Basic diffpy.morph Workflow
          In this tutorial, we will use it every time to check
          for convergence.
 
+    .. figure:: images/qs_tutorial_scaled.png
+       :align: center
+       :figwidth: 100%
+
+       ``diffpy.morph`` found an optimal value for the scale factor.
+
     7. Now, we will examine the Gaussian smearing factor. We provide an
        initial guess by typing ::
 
@@ -168,6 +191,12 @@ Basic diffpy.morph Workflow
        the optimized ``--stretch=0.001762``. We have now reached
        the optimal fit for our PDF!
 
+    .. figure:: images/qs_tutorial_morphed.png
+       :align: center
+       :figwidth: 100%
+
+       The optimal fit after applying the scale, smear, and stretch morphs.
+
     9. Now, try it on your own! If you have personally collected or
        otherwise readily available PDF data, try this process to see if
        you can morph your PDFs to one another. Many of the parameters
@@ -197,41 +226,94 @@ at various temperatures to determine whether a phase change has occurred.
 ``diffpy.morph`` currently allows users to morph a PDF against all files in a
 selected directory and plot resulting :math:`R_w` values from each morph.
 
-1. Within the ``additionalData`` directory, ``cd`` into the ``morphMultiple`` directory.
-   Inside, you will find multiple PDFs of :math:`SrFe_2As_2` measured at various temperatures.
-   These PDFs are from `"Atomic Pair Distribution Function Analysis: A primer" <https://github.com/Billingegroup/pdfttp_data/>`_.
-2. Let us start by getting the Rw of ``SrFe2As2_150K.gr`` compared to all other files in the
-   directory. Run ::
+1. Within the ``additionalData`` directory, ``cd`` into the
+   ``morphsequence`` directory. Inside, you will find multiple PDFs of
+   :math:`SrFe_2As_2` measured at various temperatures. These PDFs are
+   from `"Atomic Pair Distribution Function Analysis: A primer"
+   <https://global.oup.com/academic/product/
+   atomic-pair-distribution-function-analysis-9780198885801>`_.
+
+2. Let us start by getting the Rw of ``SrFe2As2_150K.gr`` compared to
+   all other files in the directory. Run ::
 
        diffpy.morph SrFe2As2_150K.gr . --multiple-targets
 
-   The multiple tag indicates we are comparing PDF file (first input) against all PDFs in
-   a directory (second input). Our choice of file was ``SeFe2As2_150K.gr``
-   and directory was the cwd, which should be ``morphMultiple``.
-3. After running this, we get chart of Rw values for each target file. However, this chart can
-   be a bit confusing to interpret. To get a more understandable plot, run ::
+   The multiple tag indicates we are comparing PDF file (first input)
+   against all PDFs in a directory (second input). Our choice of file
+   was ``SeFe2As2_150K.gr`` and directory was the cwd, which should be
+   ``morphsequence``.::
+
+       diffpy.morph SrFe2As2_150K.gr . --multiple-targets --sort-by=temperature
+
+.. figure:: images/ex_tutorial_bar.png
+   :align: center
+   :figwidth: 100%
+
+   Bar chart of :math:`R_W` values for each target file. Target files are
+   listed in ASCII sort order.
+
+3. After running this, we get chart of Rw values for each target file.
+   However, this chart can be a bit confusing to interpret. To get a
+   more understandable plot, run ::
 
        diffpy.morph SrFe2As2_150K.gr . --multiple-targets --sort-by=temperature
 
-   This plots the Rw against the temperature parameter value provided at the top of each file.
-   Parameters are entries of the form ``<parameter_name> = <parameter_value>`` and are located
-   above the ``r`` versus ``gr`` table in each PDF file.
-4. Between 192K and 198K, the Rw has a sharp increase, indicating that we may have a phase change.
-   To confirm, let us now apply morphs onto ``SrFe2As2_150K.gr`` with all other files in ``morphMultiple``
-   as targets ::
+   This plots the Rw against the temperature parameter value provided
+   at the top of each file. Parameters are entries of the form
+   ``<parameter_name> = <parameter_value>`` and are located above
+   the ``r`` versus ``gr`` table in each PDF file.::
+
+     # SrFe2As2_150K.gr
+     [PDF Parameters]
+     temperature = 150
+     wavelength = 0.1
+     ...
+
+.. figure:: images/ex_tutorial_temp.png
+   :align: center
+   :figwidth: 100%
+
+   The :math:`R_W` plotted against the temperature the target PDF was
+   measured at.
+
+4. Between 192K and 198K, the Rw has a sharp increase, indicating that
+   we may have a phase change. To confirm, let us now apply morphs
+   onto `` SrFe2As2_150K.gr`` with all other files in
+   ``morphsequence`` as targets ::
 
        diffpy.morph --scale=1 --stretch=0 SrFe2As2_150K.gr . --multiple-targets --sort-by=temperature
 
-   Note that we are not applying a smear since it takes a long time to apply and does not significantly
-   change the Rw values in this example.
+   Note that we are not applying a smear since it takes a long time to
+   apply and does not significantly change the Rw values in this example.
+
 5. We should now see a sharper increase in Rw between 192K and 198K.
+
 6. Go back to the terminal to see optimized morphing parameters from each morph.
-7. On the morph with ``SrFe2As2_192K.gr`` as target, ``scale = 0.972085`` and ``stretch = 0.000508``
-   and with ``SrFe2As2_198K.gr`` as target, ``scale = 0.970276`` and ``stretch = 0.000510``.
-   These are very similar, meaning that thermal lattice expansion (accounted for by ``stretch``)
-   is not occurring. This, coupled with the fact that the Rw significantly increases suggests
-   a phase change in this temperature regime. (In fact, :math:`SrFe_2As_2` does transition from
-   orthorhombic at lower temperature to tetragonal at higher temperature!)
+
+7. On the morph with ``SrFe2As2_192K.gr`` as target, ``scale =
+   0.972085`` and ``stretch = 0.000508`` and with ``SrFe2As2_198K.gr``
+   as target, ``scale = 0.970276`` and ``stretch = 0.000510``. These
+   are very similar, meaning that thermal lattice expansion (accounted
+   for by ``stretch``) is not occurring. This, coupled with the fact
+   that the Rw significantly increases suggests a phase change in this
+   temperature regime. (In fact, :math:`SrFe_2As_2` does transition
+   from orthorhombic at lower temperature to tetragonal at higher
+   temperature!). More sophisticated analysis can be done with
+   `PDFgui <https://www.diffpy.org/products/pdfgui.html>`_.
+
+8. Finally, let us save all the morphed PDFs into a directory
+   named ``saved-morphs``. ::
+
+     diffpy.morph SrFe2As2_150K.gr . --scale=1 --stretch=0 --multiple-targets \
+     --sort-by=temperature --plot-parameter=stretch \
+     --save=saved-morphs
+
+   Entering the directory with ``cd`` and viewing its contents with
+   ``ls``, we see a file named ``morph-reference-table.txt`` with data
+   about the input morph parameters and re- fined output parameters
+   and a directory named ``morphs`` containing all the morphed
+   PDFs. See the ``--save-names-file`` option to see how you can set
+   the names for these saved morphs!
 
 Nanoparticle Shape Effects
 --------------------------
@@ -240,56 +322,80 @@ A nanoparticle's finite size and shape can affect the shape of its PDF.
 We can use ``diffpy.morph`` to morph a bulk material PDF to simulate these shape effects.
 Currently, the supported nanoparticle shapes include: spheres and spheroids.
 
-* Within the ``additionalData`` directory, ``cd`` into the ``morphShape`` subdirectory.
-  Inside, you will find a sample Ni bulk material PDF ``Ni_bulk.gr``.
-  This PDF is from `"Atomic Pair Distribution Function Analysis: A primer" <https://github.com/Billingegroup/pdfttp_data/>`_.
+* Within the ``additionalData`` directory, ``cd`` into the
+  ``morphShape`` subdirectory. Inside, you will find a sample Ni bulk
+  material PDF ``Ni_bulk.gr``. This PDF is from `"Atomic Pair
+  Distribution Function Analysis:
+  A primer" <https://global.oup.com/academic/product/
+   atomic-pair-distribution-function-analysis-9780198885801>`_.
   There are also multiple ``.cgr`` files with calculated Ni nanoparticle PDFs.
 
-* Let us apply various shape effect morphs on the bulk material to reproduce these calculated PDFs.
+* Let us apply various shape effect morphs on the bulk material to
+  reproduce these calculated PDFs.
 
     * Spherical Shape
-        1. The ``Ni_nano_sphere.cgr`` file contains a generated spherical nanoparticle with unknown radius.
-           First, let us plot ``Ni_blk.gr`` against ``Ni_nano_sphere.cgr`` ::
+        1. The ``Ni_nano_sphere.cgr`` file contains a generated
+	   spherical nanoparticle with unknown radius. First, let us
+	   plot ``Ni_blk.gr`` against ``Ni_nano_sphere.cgr`` ::
 
                diffpy.morph Ni_bulk.gr Ni_nano_sphere.cgr
 
            Despite the two being the same material, the Rw is quite large.
            To reduce the Rw, we will apply spherical shape effects onto the PDF.
-           However, in order to do so, we first need the radius of the spherical nanoparticle.
-        2. To get the radius, we can first observe a plot of ``Ni_nano_sphere.cgr`` ::
+           However, in order to do so, we first need the radius of the
+	   spherical nanoparticle.
+
+        2. To get the radius, we can first observe a plot of
+	   ``Ni_nano_sphere.cgr`` ::
 
                diffpy.morph Ni_nano_sphere.cgr Ni_nano_sphere.cgr
 
-        3. Nanoparticles tend to have broader peaks at r-values larger than the particle size,
-           corresponding to the much weaker correlations between molecules.
-           On our plot, beyond r=22.5, peaks are too broad to be visible,
-           indicating our particle size to be about 22.4.
-           The approximate radius of a sphere would be half of that, or 11.2.
-        4. Now, we are ready to perform a morph applying spherical effects. To do so, we use the ``--radius`` parameter ::
+        3. Nanoparticles tend to have broader peaks at r-values larger
+	   than the particle size, corresponding to the much weaker
+	   correlations between molecules. On our plot, beyond r=22.5,
+	   peaks are too broad to be visible, indicating our particle
+	   size to be about 22.4. The approximate radius of a sphere
+	   would be half of that, or 11.2.::
 
                diffpy.morph Ni_bulk.gr Ni_nano_sphere.cgr --radius=11.2 -a
 
-        5. We can see that the Rw value has significantly decreased from before. Run without the ``-a`` tag to refine ::
+
+        4. Now, we are ready to perform a morph applying spherical
+	   effects. To do so, we use the ``--radius`` parameter ::
+
+               diffpy.morph Ni_bulk.gr Ni_nano_sphere.cgr --radius=11.2 -a
+
+        5. We can see that the Rw value has significantly decreased
+	   from before. Run without the ``-a`` tag to refine ::
 
                diffpy.morph Ni_bulk.gr Ni_nano_sphere.cgr --radius=11.2
 
-        6. After refining, we see the actual radius of the nanoparticle was closer to 12.
+        6. After refining, we see the actual radius of the
+	   nanoparticle was closer to 12.
+
     * Spheroidal Shape
-        1. The ``Ni_nano_spheroid.cgr`` file contains a calculated spheroidal Ni nanoparticle.
-           Again, we can begin by plotting the bulk material against our nanoparticle ::
+
+        1. The ``Ni_nano_spheroid.cgr`` file contains a calculated
+	   spheroidal Ni nanoparticle. Again, we can begin by plotting
+	   the bulk material against our nanoparticle ::
 
                diffpy.morph Ni_bulk.gr Ni_nano_spheroid.cgr
 
-        2. Inside the ``Ni_nano_spheroid.cgr`` file, we are given that the equatorial radius is 12 and polar radius is 6.
-           This is enough information to define our spheroid. To apply spheroid shape effects onto our bulk, run ::
+        2. Inside the ``Ni_nano_spheroid.cgr`` file, we are given that
+	   the equatorial radius is 12 and polar radius is 6. This is
+	   enough information to define our spheroid. To apply
+	   spheroid shape effects onto our bulk, run ::
 
                diffpy.morph Ni_bulk.gr Ni_nano_spheroid.cgr --radius=12 --pradius=6 -a
 
-           Note that the equatorial radius corresponds to the ``--radius`` parameter and polar radius to ``--pradius``.
+           Note that the equatorial radius corresponds to the
+	   ``--radius`` parameter and polar radius to ``--pradius``.
+
         3. Remove the ``-a`` tag to refine.
 
-There is also support for morphing from a nanoparticle to a bulk. When applying the inverse morphs,
-it is recommended to set ``--rmax=psize`` where ``psize`` is the longest diameter of the nanoparticle.
+There is also support for morphing from a nanoparticle to a bulk. When
+applying the inverse morphs, it is recommended to set ``--rmax=psize``
+where ``psize`` is the longest diameter of the nanoparticle.
 
 Bug Reports
 ===========

doc/source/images/qs_tutorial_morphed.png

@@ -0,0 +1,23 @@
+**Added:**
+
+* manual information is added into online docs.
+
+**Changed:**
+
+* <news item>
+
+**Deprecated:**
+
+* <news item>
+
+**Removed:**
+
+* manual.
+
+**Fixed:**
+
+* <news item>
+
+**Security:**
+
+* <news item>