Tutorials finalized

Author: Sparks29032

doc/manual/images/ex_tutorial_bar.png

@@ -34,7 +34,7 @@ June 2024
 
 @c start of header
 @setfilename pdfmorph
-@settitle PDFmorph, release 1.0, @ReleaseDate{}
+@settitle PDFmorph, release 1.0.0, @ReleaseDate{}
 @c end of header
 
 @c Part 1: copying
@@ -46,7 +46,7 @@ Copyright 2009-2024, Board of Trustees of Columbia University in the city of New
 @titlepage
 
 @title PDFmorph user guide
-@subtitle 1.0 release
+@subtitle 1.0.0 release
 @subtitle @ReleaseDate{}
 @author C. L. Farrow, C. J. Wright, P. Juhás, C.-H. Liu, T. Davis,
 @author S. M. Román, A. Yang, and S. J. L. Billinge
@@ -273,7 +273,8 @@ and enter the directory with the @code{cd} command
 @example
 cd <PDFmorph_tutorial_directory>
 @end example
-@item Download the tutorial files @code{tutorialData.zip} folder (***INSERT LINK***)
+@item Download the @url{https://www.diffpy.org/diffpy.pdfmorph/tutorialfiles.html,
+quick start tutorial files @code{tutorialData.zip}}
 into your current directory and extract the files. After this is done,
 type @code{ls} in the command line to list your current directory contents
 and make sure there is a directory named @code{tutorialData}.
@@ -368,8 +369,8 @@ pdfmorph darkSub_rh20_C_01.gr darkSub_rh20_C_44.gr --scale=0.8 \
 @end example
 The optimized smear factor is now a non-insignificant @code{smear=-0.084138} and @math{R_W=0.204}.
 @itemize
-@item We restricted the @code{r} (abscissa) values because some of the Gaussian smear effects are only
-visible in a fixed @code{r} range. We chose this @code{r} range by noting where most of our relevant
+@item We restricted the @math{r} (abscissa) values because some of the Gaussian smear effects are only
+visible in a fixed @math{r} range. We chose this @math{r} range by noting where most of our relevant
 data was that was not exponentially decayed by instrumental shortcomings.
 @item Also note that a negative smear factor is equivalent to its absolute value. You can see that
 @example
@@ -383,7 +384,7 @@ pdfmorph darkSub_rh20_C_01.gr darkSub_rh20_C_44.gr --scale=0.8 \
 @end example
 give the exact same results.
 @end itemize
-@item Finally, we will examine the stretch morph. The @code{r} axis will be stretched by
+@item Finally, we will examine the stretch morph. The @math{r} axis will be stretched by
 @math{1+s} where @math{s} is the stretch factor.
 @example
 pdfmorph darkSub_rh20_C_01.gr darkSub_rh20_C_44.gr --scale=0.8 \
@@ -406,23 +407,29 @@ We have reached the optimal fit for our PDF!
 @item 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.
-Note that many of the parameters provided in this tutorial are unique to it,
-so be cautious about your choices and made sure that they remain physically relevant.
+Note that many of the parameters provided in this tutorial are unique to it, so be
+cautious about your choices and made sure that they remain physically relevant.
 @end enumerate
 
 @node    Extra tutorials, , Quick start tutorial, Tutorials
 @section Extra tutorials
 @cindex  extra tutorials
+
+@menu
+* Performing multiple morphs::
+* Nanoparticle shape effect::
+@end menu
+
 PDFmorph has some more functionalities not showcased in the basic workflow above
 (run @code{pdfmorph –-help} for an overview of all @code{PDFmorph} functionalities).
 Tutorials for some of these are included below.
 Additional files are used for these tutorials. Please download and extract
-@code{additionalData.zip} (***INSERT LINK***) before proceeding.
+the @url{https://www.diffpy.org/diffpy.pdfmorph/tutorialfiles.html,
+extra tutorial data @code{additionalData.zip}} before proceeding.
 
-@menu
-* Performing multiple morphs
-* Nanoparticle shape effect
-@end menu
+@node    Performing multiple morphs, Nanoparticle shape effect, Extra tutorials, Extra tutorials
+@subsection Performing multiple morphs
+@cindex  performing multiple morphs
 
 It may be useful to morph a PDF against multiple targets: for example, you may want
 to morph a PDF against a sequence of PDFs measured at various temepratures to determine
@@ -432,25 +439,182 @@ It is advised that the lowest temperature PDF be that morphed and the higher tem
 act as targets as the smear morph is only able to account for increases in thermal motion.
 
 @enumerate
-@item Within @code{additionalData}, enter (using @code{cd}) the @code{morphsequence} directory.
+@item Within @code{additionalData}, enter (using @code{cd}) the @code{morphMultiple} directory.
 Inside, you will find multiple PDFs of @math{SrFe_2As_2} measured at various temperatures.
 @itemize
 @item These PDFs come from @url{https://github.com/Billingegroup/pdfttp_data/,
 @emph{Atomic Pair Distribution Function Analysis: A Primer}} by Simon Billinge and
-Kirsten Jensen.
+Kirsten Jensen. Contributions to the dataset have been made by Benjamin Frandsen and
+Long Yang.
+@end itemize
+@float Figure,fig3.2.1-1
+@ScreenShot{images/ex_tutorial_download,png}
+@caption{The files within the @code{morphMultiple} directory.}
+@end float
+@item Let us start by getting the @math{R_W} of @code{SrFe2As2_150K.gr}
+compared to the other, higher-temperature PDFs in the directory. Run
+@example
+pdfmorph SrFe2As2_150K.gr . --multiple
+@end example
+@itemize
+@item The @code{--multiple} tag tells @code{PDFmorph} to compare the morphed file
+@code{SrFe2As2_150K.gr} against all PDFs in a directory. The directory we have
+supplied is @code{.}, which is shorthand for the current working directory.
+In our case, this is the @code{morphMultiple} directory.
 @end itemize
-@item It is generally advisable for the
+@float Figure,fig3.2.1-2
+@ScreenShot{images/ex_tutorial_bar,png}
+@caption{Bar chart of @math{R_W} values for each target file. Target files are
+listed in ASCII sort order.}
+@end float
+@item After running this we get a chart of @math{R_W} values for the morphed file
+compared to each target file. By default, a bar chart is generated. However, this plot
+can be difficult to interpret. We may instead wish to generate a line chart of @math{R_W}
+values against some numerical abscissa such as temperature. At the top of each @code{.gr}
+file in this directory is a list of parameters. These are of the form
+@code{<parameter_name> = <parameter_value>} and are located above the @code{r} versus @code{gr}
+table. Included in these parameters is the temperature at which each PDF was measured at.
+@float Figure,fig3.2.1-3
+@ScreenShot{images/ex_tutorial_params,png}
+@caption{Parameters located at the top of the @code{SrFe2As2_150K.gr} file. Some parameters
+included are temperature, wavelength, and composition.}
+@end float
+@item By running
+@example
+pdfmorph SrFe2As2_150K.gr . --multiple --sort-by=temperature
+@end example
+we can sort the plotted @math{R_W} values by the temperature parameter included within each file.
+@itemize
+@item When the value of the parameter given to @code{--sort-by} is numerical, a line plot is generated.
+@item Otherwise, a bar chart with the parameter values sorted in ASCII sort order is generated.
+You can observe this behavior by using @code{inputfile} as the @code{--sort-by} parameter
+instead of @code{temperature}.
+@end itemize
+@float Figure,fig3.2.1-4
+@ScreenShot{images/ex_tutorial_temp,png}
+@caption{The @math{R_W} plotted against the temperature the target PDF was measured at.}
+@end float
+@item Between @math{192K} and @math{198K}, the @math{R_W} has a sharp change, which may be indicative of
+a phase change. To be more certain, let us apply morphs to take into account isotropic expansion and differences
+in incident flux (stretching and scaling).
+@example
+pdfmorph SrFe2As2_150K.gr . --scale=1 --stretch=0 --multiple \
+--sort-by=temperature
+@end example
+The change in @math{R_W} has become more pronounced.
+@itemize
+@item Note that we are not applying the smear morph in this example as it takes a long time to refine and does
+not significantly change the @math{R_W} values in this example.
+@end itemize
+@item We can also change what is being plotted in the ordinate using @code{--plot-parameter}. In our case,
+it is useful to look at the @code{stretch} factor
+@example
+pdfmorph SrFe2As2_150K.gr . --scale=1 --stretch=0 --multiple \
+--sort-by=temperature --plot-parameter=stretch
+@end example
+We can see that the stretch factor generally increases, but from @math{192K} to @math{198K}, there is no increase.
+This means @code{PDFmorph} found that isotropic lattice expansion due to latent thermal effects (indicated
+by an increase in the stretch factor) does not account for the change in @math{R_W} in this region. This is
+highly suggestive of an alternative source of the dissimilarity such as a phase transition. In fact, there is a structural
+phase transition from orthorhombic below @math{192K} to tetragonal above @math{198K}! More sophisticated analysis
+can be done with @url{https://www.diffpy.org/products/pdfgui, PDFgui}.
+@float Figure,fig3.2.1-5
+@ScreenShot{images/ex_tutorial_stretch,png}
+@caption{The refined stretch factor for each target PDF. There is very little change between @math{192K} and
+@math{198K}.}
+@end float
 @end enumerate
 
-@node    Performing multiple morphs, Nanoparticle shape effect, Extra tutorials, Extra tutorials
-@subsection Performing multiple morphs
-@cindex  performing multiple morphs
-
-
 @node    Nanoparticle shape effect, , Performing multiple morphs, Extra tutorials
 @subsection Nanoparticle shape effect
 @cindex  nanoparticle shape effect
 
+@menu
+* Spherical shape::
+* Spheroidal shape::
+@end menu
+
+A nanoparticle’s finite size and shape can affect the shape of its PDF.
+We can use PDFmorph to morph a bulk material PDF to simulate these shape effects.
+Currently, the supported nanoparticle shapes include only spheres and spheroids.
+
+@itemize
+@item Within the @code{additionalData} directory, @code{cd} into the @code{morphShape}
+subdirectory. Inside, you will find a sample Nickel bulk material PDF @code{Ni_bulk.gr}.
+This PDF comes from @url{https://github.com/Billingegroup/pdfttp_data/,
+@emph{Atomic Pair Distribution Function Analysis: A Primer}}.
+Also in the directory are multiple @code{.cgr}, which are calculated Nickel nanoparticle
+PDFs.
+@float Figure,fig3.2.2-1
+@ScreenShot{images/ex_tutorial_shape_download,png}
+@caption{The files within the @code{morphShape} directory.}
+@end float
+@item In the following sections, we apply shape effect morphs on the bulk material to
+reproduce the calculated PDFs.
+@end itemize
+
+Note that there are also support for morphing a nanoparticle PDF into bulk. For more information
+see @ref{PDFmorph options}. When applying these inverse morphs it is recommended to set
+@code{--rmax=psize} wher @code{psize} is the longest diameter of the nanoparticle as data
+beyond @code{psize} is noise.
+
+@node    Spherical shape, Spheroidal shape, Nanoparticle shape effect, Nanoparticle shape effect
+@subsubsection Spherical shape
+@cindex  spherical shape morph
+
+@enumerate
+@item The @code{Ni_nano_sphere.cgr} file contains a generated spherical nanoparticle with unknown
+radius. First, let us plot @code{Ni_bulk.gr} against @code{Ni_nano_sphere.cgr}.
+@example
+pdfmorph Ni_bulk.gr Ni_nano_sphere.cgr
+@end example
+@item Despite the two being the same material, the @math{R_W} 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.
+@item A nanoparticle cannot have bonds longer than the particle size. Thus, for @math{r}
+beyond the spherical diameter, we expect the PDF amplitude to be close to zero.
+On our plot, the nanoparticle PDF amplitude falls to zero around @math{r=22}.
+Thus, the nanoparticle radius should be about half of that, or around @math{11}.
+@float Figure,fig3.2.2.1-1
+@ScreenShot{images/ex_tutorial_shape_sphere_zoomed,png}
+@caption{The PDF amplitude goes to zero between @math{r=21} and @math{r=22}.}
+@end float
+@item We are ready to perform a morph applying spherical shape effects.
+To do so, we use the @code{--radius} parameter
+@example
+pdfmorph Ni_bulk.gr Ni_nano_sphere.cgr --radius=11 -a
+@end example
+We can see that the @math{R_W} value has decreased significantly from
+@math{R_W = 1.422} to @math{R_W = 0.085232}.
+@item Finally, let us refine by running the same command without the @code{-a} tag.
+The refined radius should be @code{radius=12.183129}.
+@end enumerate
+
+@node    Spheroidal shape, , Spherical shape, Nanoparticle shape effect
+@subsubsection Spheroidal shape
+@cindex  spheroidal shape morph
+
+@enumerate
+@item The @code{Ni_nano_spheroid.cgr} file contains a calculated spheroidal Niickel nanoparticle.
+Again, we can begin by plotting the bulk material against our nanoparticle.
+@example
+pdfmorph Ni_bulk.gr Ni_nano_spheroid.cgr
+@end example
+@item The nanoparticle shape of the calculated PDF is an oblate spheroid with equitorial
+radius of about @math{12} and polar radius of about @math{6} (this information is contained
+within the @code{Ni_nano_spheroid.cgr} file). To apply the spheroidal shape effects onto the
+bulk, run
+@example
+pdfmorph Ni_bulk.gr Ni_nano_spheroid.cgr --radius=12 --pradius=6 -a
+@end example
+@itemize
+@item The @code{--radius} option corresponds to the equitorial radius.
+@item The @code{--pradius} option corresponds to the polar radius.
+@end itemize
+@item Run the same command without @code{-a} to refine. Refining should give
+@code{radius=12.183129} and @code{pradius=6.279252}.
+@end enumerate
+
 @page
 @vskip 0pt plus 1filll
 @node    Available morphs, PDFmorph options, Quick start tutorial, Top