diff --git a/README.rst b/README.rst index b105b956..58b8fe36 100644 --- a/README.rst +++ b/README.rst @@ -107,8 +107,8 @@ version using :: USING PDFmorph ------------------------------------------------------------------------ -For detailed instructions and full tutorial, consult our -`online documentation `_. +For detailed instructions and full tutorial, consult the user manual +on our `website `. Once the required software, including PDFmorph is all installed, open up a terminal and check installation has worked properly by running :: diff --git a/doc/manual/acknowledgements.texinfo b/doc/manual/acknowledgements.texinfo new file mode 100644 index 00000000..3b5533c8 --- /dev/null +++ b/doc/manual/acknowledgements.texinfo @@ -0,0 +1,15 @@ +The PDFmorph app was developed by the Billinge group at Columbia University. +The examples in the tutorial part of the manual were made possible by data +collected by Soham Banerjee at Brookhaven National Laboratory, +Benjamin Frandsen during his PhD at Columbia Unversity, +and Long Yang from Tonji University. + +The DiffPy development team is the set of all contributors to DiffPy projects. +Each member of the development team maintains copyright on their individual +contributions to the code base. For a detailed contribution history of +@code{PDFmorph}, see the git logs at @url{https://github.com/diffpy/diffpy.pdfmorph}. + +For more information about the application, please visit +@url{https://www.diffpy.org/diffpy.pdfmorph}. +Report any bugs to diffpy-users@@googlegroups.com or submit +an issue to @url{https://github.com/diffpy/diffpy.pdfmorph/issues}. diff --git a/doc/manual/disclaimer.texinfo b/doc/manual/disclaimer.texinfo new file mode 100644 index 00000000..107d2b55 --- /dev/null +++ b/doc/manual/disclaimer.texinfo @@ -0,0 +1,10 @@ +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND +ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE +FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER +CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/doc/manual/images/ex_tutorial_bar.png b/doc/manual/images/ex_tutorial_bar.png new file mode 100644 index 00000000..260b0a7e Binary files /dev/null and b/doc/manual/images/ex_tutorial_bar.png differ diff --git a/doc/manual/images/ex_tutorial_download.png b/doc/manual/images/ex_tutorial_download.png new file mode 100644 index 00000000..db05fcb2 Binary files /dev/null and b/doc/manual/images/ex_tutorial_download.png differ diff --git a/doc/manual/images/ex_tutorial_params.png b/doc/manual/images/ex_tutorial_params.png new file mode 100644 index 00000000..1e8f42cf Binary files /dev/null and b/doc/manual/images/ex_tutorial_params.png differ diff --git a/doc/manual/images/ex_tutorial_shape_download.png b/doc/manual/images/ex_tutorial_shape_download.png new file mode 100644 index 00000000..0b8c748c Binary files /dev/null and b/doc/manual/images/ex_tutorial_shape_download.png differ diff --git a/doc/manual/images/ex_tutorial_shape_sphere_zoomed.png b/doc/manual/images/ex_tutorial_shape_sphere_zoomed.png new file mode 100644 index 00000000..22a5c74a Binary files /dev/null and b/doc/manual/images/ex_tutorial_shape_sphere_zoomed.png differ diff --git a/doc/manual/images/ex_tutorial_stretch.png b/doc/manual/images/ex_tutorial_stretch.png new file mode 100644 index 00000000..6e8181ee Binary files /dev/null and b/doc/manual/images/ex_tutorial_stretch.png differ diff --git a/doc/manual/images/ex_tutorial_temp.png b/doc/manual/images/ex_tutorial_temp.png new file mode 100644 index 00000000..c9bdedc3 Binary files /dev/null and b/doc/manual/images/ex_tutorial_temp.png differ diff --git a/doc/manual/images/qs_tutorial_download.png b/doc/manual/images/qs_tutorial_download.png new file mode 100644 index 00000000..30c99b09 Binary files /dev/null and b/doc/manual/images/qs_tutorial_download.png differ diff --git a/doc/manual/images/qs_tutorial_morphed.png b/doc/manual/images/qs_tutorial_morphed.png new file mode 100644 index 00000000..96458a59 Binary files /dev/null and b/doc/manual/images/qs_tutorial_morphed.png differ diff --git a/doc/manual/images/qs_tutorial_scaled.png b/doc/manual/images/qs_tutorial_scaled.png new file mode 100644 index 00000000..ff50a254 Binary files /dev/null and b/doc/manual/images/qs_tutorial_scaled.png differ diff --git a/doc/manual/images/qs_tutorial_unmorphed.png b/doc/manual/images/qs_tutorial_unmorphed.png new file mode 100644 index 00000000..1747d318 Binary files /dev/null and b/doc/manual/images/qs_tutorial_unmorphed.png differ diff --git a/doc/manual/pdfmorph.pdf b/doc/manual/pdfmorph.pdf new file mode 100644 index 00000000..7ea99f6b Binary files /dev/null and b/doc/manual/pdfmorph.pdf differ diff --git a/doc/manual/pdfmorph.texinfo b/doc/manual/pdfmorph.texinfo new file mode 100644 index 00000000..c7c69b08 --- /dev/null +++ b/doc/manual/pdfmorph.texinfo @@ -0,0 +1,1090 @@ +\input texinfo @c -*-texinfo-*- + +@documentencoding UTF-8 + +@ifnottex +@macro smallskip{} +@vskip 6pt +@end macro + +@macro medskip{} +@vskip 12pt +@end macro + +@macro bigskip{} +@vskip 24pt +@end macro +@end ifnottex + +@macro EquationMark{} +@html + +@end html +@end macro + +@macro ScreenShot{f,ext} +@center @image{\f\, 5.5in,,\ext\} +@end macro + +@macro ReleaseDate{} +June 2024 +@end macro + +@exampleindent 2 + +@c start of header +@setfilename pdfmorph +@settitle PDFmorph, release 1.0.0, @ReleaseDate{} +@c end of header + +@c Part 1: copying +@copying +Copyright 2009-2024, Board of Trustees of Columbia University in the city of New York. +@end copying + +@c Part 2: title +@titlepage + +@title PDFmorph user guide +@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 + +@page +@vskip 0pt plus 1filll +@c @insertcopying + +@ifhtml +@node acknowledgments +@end ifhtml +@heading Acknowledgments +@cindex acknowledgments +@include acknowledgements.texinfo + + +@page +@vskip 0pt plus 1filll +@majorheading Preface +@heading Redistribution +@include redistribution.texinfo + + +@heading Disclaimer +@include disclaimer.texinfo + +@end titlepage + + +@c Part 3: content +@contents + + +@c Make menu if html +@ifhtml + +@node Top +@top + + +@menu +* Introduction:: +* Installation:: +* Tutorials:: +* Available morphs:: +* PDFmorph options:: +* Index:: +@end menu + +@end ifhtml + +@page +@vskip 0pt plus 1filll +@node Introduction, Installation, Top, Top +@chapter Introduction +@cindex introduction + +@code{PDFmorph} is a Python package that increases the insight researchers can +obtain by comparing measured atomic pair distribution functions (PDFs) in a +model-independent way. It was originally designed to help a researcher +answer a question: "Has my material undergone a phase transition between +these two measurements?" + +A common approach to compare two PDFs is to plot the difference curve below +the two PDFs. However, a significant signal can be seen in the difference curve +due to benign effects such as thermal expansion (peak shifts), increased thermal +motion (peak broadening), or a change in scale due to differences in the incident +flux when computing the PDFs for example. Other commonly-used dissimilarity metrics +such as the weighted Rietveld reliability factor @math{R_W} are also inflated by +these effects. @code{PDFmorph} does its best to correct for these benign effects +prior to computing the @math{R_W} and plotting the difference curve. + +To use @code{PDFmorph}, supply one PDF as the "target" (suggested to the one collected +under higher temperature) and a second PDF to be morphed. The user can choose from +a list of morphs to apply, which includes "stretching" (scaling the @math{r}-axis, +the abscissa, to simulate isotropic expansion/compression), "smearing" (peak broadening +by convlution with a Gaussian), and "scaling" (scaling the ordinate axis). By default, +@code{PDFmorph} will refine the intensity of the morphs to best match the morphed to +the target PDF. All morphed PDFs generated by @code{PDFmorph} can easily be saved and +exported (see the @code{--save} option in @ref{PDFmorph options}). + +@code{PDFmorph} includes other morphs including those that factor in nanoparticle +shape effects. For a full list of available morphs, see @ref{Available morphs}. +For a quick tutorial on using @code{PDFmorph}, see @ref{Quick start tutorial}. +For a full list of command-line options, see @ref{PDFmorph options}. + +Finally, we note that though @code{PDFmorph} could be used on other spectra, +it has not been extensively tested beyond the PDF. + +@page +@vskip 0pt plus 1filll +@node Installation, Tutorials, Introduction, Top +@chapter Installation +@cindex installation + +@menu +* Availability:: +* Requirements:: +* Installation instructions:: +@end menu + +@node Availability, Requirements, Installation, Installation +@section Availability +@cindex availability + +@code{PDFmorph} is open source and distributed under the BSD license. +It runs on Windows, Mac OS, Linux, and all major Unix systems. +The source code is freely available at @url{https://github.com/diffpy/diffpy.pdfmorph}. + +If you come accross any bugs in the application, please open an +@url{https://github.com/diffpy/diffpy.pdfmorph/issues, issue} or email +diffpy-dev@@googlegroups.com. + +@node Requirements, Installation instructions, Availability, Installation +@section Requirements +@cindex requirements + +@code{PDFmorph} is currently run from the command-line, so it is recommended that users +first familiarize themselves with their operating system's command-line interface. + +@code{PDFmorph} currently requires Python 3.10 or higher to run. It also makes use of +the following third party libraries: +@itemize @bullet +@item @url{https://numpy.org, NumPy} - Python's fast scientific computing library +@item @url{https://matplotlib.org, Matplotlib} - Python plotting library +@item @url{https://scipy.org, SciPy} - Python's technical computing library +@item @url{https://www.diffpy.org/diffpy.utils, diffpy.utils} +- @url{https://www.diffpy.org, DiffPy} general utility functions +@end itemize +These dependencies will be installed automatically if you use the conda installation +procedure described in the following section (@ref{Installation instructions}). + +@node Installation instructions, , Requirements, Installation +@section Installation instructions +@cindex installation instrunctions + +We recommend installing the package and its dependencies using conda. +Miniconda, a minimal installer for conda, can be downloaded +@url{https://docs.anaconda.com/free/miniconda, here}. +Once Miniconda is installed, run @code{conda} on the command-line + to test that it has been installed properly. + +To create and activate a conda environment to use @code{PDFmorph}, run the following command. +@example +conda create -n pdfmorph_env python=3 --yes +conda activate pdfmorph_env +@end example + +A conda environment must be active to use the packages within. +In future sessions, make sure to run @code{conda activate pdfmorph_env} to activate the +environment before interacting with the @code{PDFmorph} program. + +Once active, you can install @code{PDFmorph} into your environment from the +@url{https://conda-forge.org, conda-forge} channel of Anaconda packages by running +@example +conda config --add channels conda-forge +conda install diffpy.pdfmorph +@end example +This installation only needs to be done once. The next time you activate the environment, +these packages will already be installed. To see a list of all installed packages within +an environment, run +@example +conda list +@end example + +When you are finished with the session, exit the environment by running +@example +conda deactivate pdfmorph_env +@end example + +If you do not wish to use conda to install, @code{PDFmorph} is also available on the +@url{https://pypi.org, Python Package Index} or can be installed from source +at @url{https://github.com/diffpy/diffpy.pdfmorph}. Note that these installation +methods will require you to first install the dependencies listed in the previous section +(@ref{Requirements}). + +@page +@vskip 0pt plus 1filll +@node Tutorials, Available morphs, Installation, Top +@chapter Tutorials +@cindex tutorials + +@menu +* Quick start tutorial:: +* Extra tutorials:: +@end menu + +This section includes a quick start tutorial to acquaint users with the core +features of @code{PDFmorph}. Also included are a few extra tutorials +covering some more specific @code{PDFmorph} functionalities. + +Before you start this tutorial, make sure you have installed all necessary software +and dependencies (@ref{Installation instructions}). If you are looking for a full +summary of @code{PDFmorph} command-line options, see @ref{PDFmorph options} or +run @code{pdfmorph --help} in a @code{PDFmorph}-equipped @code{conda} environment. + +@node Quick start tutorial, Extra tutorials, Tutorials, Tutorials +@section Quick start tutorial +@cindex quick start tutorial + +In this tutorial, we will demonstrate how to use @code{PDFmorph} to compare two PDFs +measured from the same material at different temperatures. The morphs showcased include +"stretch", "scale", and "smear". Throughout this tutorial, entries surrounded by angle +brackets @code{<>} represent placeholder names. The user is free to use their own names +in stead of those provided. + +@enumerate +@item Open your terminal (Linux and MacOS) or Command Prompt (Windows). +@item If not already active, activate your @code{conda} environment with @code{PDFmorph} installed using +@example +conda activate +@end example +@itemize +@item See @ref{Installation} for how to set up a @code{conda} environment with @code{PDFmorph} installed. +@item If you need to list your available @code{conda} environments, run +@example +conda env list +@end example +@end itemize +@item Create a directory to store the tutorial PDF files using +@example +mkdir +@end example +and enter the directory with the @code{cd} command +@example +cd +@end example +@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}. +@itemize +@item The files in this dataset were collected by Soham Banerjee at Brookhaven National Laboratory in Upton, +New York. Note that these files have a @code{.gr} extension, indicating that they are measured PDFs. +The @code{.cgr} file extension indicates a calculated PDF such as those generated by the +@url{https://www.diffpy.org/products/pdfgui.html, PDFgui} program. +@item Each file is PDF data collected on Iridium Telluride with 20% Rhodium Doping @math{IrRhTe_2} at different +temperatures with the first file (01) collected at @math{10K} and the last (44) at @math{300K}. +The samples increase in temperature as their numbers increase. The "C" in their names indicates that they +have undergone cooling. +@end itemize +@item Enter the @code{tutorialData} directory using the @code{cd} command and +find the data labeled @code{darkSub_rh20_C_##.gr} within this directory. +@float Figure,fig3.1-1 +@ScreenShot{images/qs_tutorial_download,png} +@caption{Entering the @code{tutorialData} directory and searching +for the PDF data (Linux Terminal Output).} +@end float +@item Let us try try using the @code{PDFmorph} program to plot two PDFs against each other. +Type the following command into the command-line +@example +pdfmorph darkSub_rh20_C_01.gr darkSub_rh20_C_44.gr +@end example +Underneath the two PDFs, we can see a substantial difference curve and large @math{R_W} value of @math{0.407} +@float Figure,fig3.1-2 +@ScreenShot{images/qs_tutorial_unmorphed,png} +@caption{Using @code{PDFmorph} to compare two PDFs without morphing.} +@end float +@item Now, we will start the morphing process. +@itemize +@item Note that the morphs will apply only to the first PDF provided (which will be +@code{darkSub_rh20_C_01.gr} in our case). We will henceforth refer to the first PDF as the "morphed" +and the second (unmorphed) PDF as the "target". Our goal will be to apply morphs to see if we can reduce the +difference between the morphed and target PDFs. +@item In this tutorial, we will apply the scale factor, Gaussian smear, and stretch morphs. +To learn more about why we wish to apply these three morphs in particular, +see @ref{Temperature-related morphs}. +@end itemize +@item We will begin by applying a scaling factor of @math{2} by typing the command +@example +pdfmorph darkSub_rh20_C_01.gr darkSub_rh20_C_44.gr --scale=2 -a +@end example +Now, the difference is much larger @math{R_W=1.457}. We should modify our initial value +for the scaling factor until we see a reduction in @math{R_W}. We can try @math{0.9} +@example +pdfmorph darkSub_rh20_C_01.gr darkSub_rh20_C_44.gr --scale=0.9 -a +@end example +and see that the difference has dropped to @math{R_W=0.351}, lower than when comparing the unmorphed PDF. +For @code{PDFmorph} to optimize the scale factor, drop the @code{-a} option +@example +pdfmorph darkSub_rh20_C_01.gr darkSub_rh20_C_44.gr --scale=0.9 +@end example +Given a reasonable initial guess, @code{PDFmorph} will find the optimal value for each morph. +In this example, @code{PDFmorph} should display @code{scale=0.799025} meaning it has found this +to be the optimal value for the scale factor. The difference @math{R_W=0.330} has further decreased. +@itemize +@item The @code{-a} option prevents @code{PDFmorph} from refining the morph. +It is the choice of the user whether or not to run values before removing @code{-a} when analyzing data with +@code{PDFmorph}. By including it, you can attempt to manually move towards convergence before allowing the +program to optimize by removing it; when including it, you may reach a highly optimized value on the first +guess or diverge greatly. +@end itemize +@float Figure,fig3.1-3 +@ScreenShot{images/qs_tutorial_scaled,png} +@caption{@code{PDFmorph} has found an optimal value (minimizes @math{R_W}) for the scale factor.} +@end float +@item Now we will add on a Gaussian smear morph with an initial smear factor of @math{0.5}. The absolute value +of the smear factor is the standard deviation of the Gaussian that is convoluted with the morphed PDF. +@example +pdfmorph darkSub_rh20_C_01.gr darkSub_rh20_C_44.gr --scale=0.8 \ +--smear=0.5 -a +@end example +@itemize +@item The @code{\} in the above command is only used to break our long command into multiple lines for readability +on this document. In your Terminal/Command Prompt, you can write the entire command in a single line. +@end itemize +We have tailored our initial scale factor to be close to the optimal value given by @code{PDFmorph}, +but we should see that the @math{R_W=0.897} has increased substantially due to the smear factor. Remove the +@math{-a} from above and run it again to refine the smear factor. +@itemize +@item Note that the warnings that the Terminal/Command Prompt displays are largely numerical in nature and +do not indicate a physically irrelevant guess. These are somewhat superficial and in most cases can be ignored. +@end itemize +After refining, we should see that @math{R_W} has dropped back to @math{0.330}, and the optimized smear factor is +quite small (@code{smear = 0.002940}) indicating that the smear has hardly had an effect on our PDF. +To see an effect, restrict the @code{rmin} and @code{rmax} values by typing +@example +pdfmorph darkSub_rh20_C_01.gr darkSub_rh20_C_44.gr --scale=0.8 \ +--smear=0.5 --rmin=1.5 --rmax=30 +@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 @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 +pdfmorph darkSub_rh20_C_01.gr darkSub_rh20_C_44.gr --scale=0.8 \ +--smear=-0.84138 --rmin=1.5 --rmax=30 -a +@end example +and +@example +pdfmorph darkSub_rh20_C_01.gr darkSub_rh20_C_44.gr --scale=0.8 \ +--smear=+0.84138 --rmin=1.5 --rmax=30 -a +@end example +give the exact same results. +@end itemize +@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 \ +--smear=-0.84 --stretch=0.5 --rmin=1.5 --rmax=30 -a +@end example +Again, the @math{R_W} has increased. Before letting @code{PDFmorph} refine automatically, +try seeing which direction (higher or lower) the initial stretch factor should go to decrease +@math{R_W}. If you cannot, type +@example +pdfmorph darkSub_rh20_C_01.gr darkSub_rh20_C_44.gr --scale=0.8 \ +--smear=-0.84 --stretch=0.005 --rmin=1.5 --rmax=30 -a +@end example +to observe a decreased difference and remove the @code{-a} to get the optimized +stretch factor of @code{stretch=0.001762} and smaller @math{R_W=0.117}. +We have reached the optimal fit for our PDF! +@float Figure,fig3.1-4 +@ScreenShot{images/qs_tutorial_morphed,png} +@caption{The optimal fit after applying the scale, smear, and stretch morphs.} +@end float +@item To save your new morphed PDF as a file named @code{morph.gr}, use the save command +@example +pdfmorph darkSub_rh20_C_01.gr darkSub_rh20_C_44.gr --scale=0.8 \ +--smear=-0.84 --stretch=0.005 --rmin=1.5 --rmax=30 \ +--save=morph.gr +@end example +Type @code{ls} to confirm a new file named @code{morph.gr} has been saved. +@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. +@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 +the @url{https://www.diffpy.org/diffpy.pdfmorph/tutorialfiles.html, +extra tutorial data @code{additionalData.zip}} before proceeding. + +@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 +whether a phase change has occured. PDFmorph currently allows users to morph a PDF +against all files in a selected directory and plot resulting @math{R_W} values from each morph. +It is advised that the lowest temperature PDF be that morphed and the higher temperature PDFs +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{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. 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 +@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{ = } 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 +@item Finally, let us save all the morphed PDFs into a directory named @code{savedMorphs}. +@example +pdfmorph SrFe2As2_150K.gr . --scale=1 --stretch=0 --multiple \ +--sort-by=temperature --plot-parameter=stretch \ +--save=savedMorphs +@end example +Entering the directory with @code{cd} and viewing its contents with @code{ls}, +we see a file named @code{Morph_Reference_Table.txt} with data about the input morph +parameters and refined output parameters and a directory named @code{Morphs} containing +all the morphed PDFs. See the @code{--save-names-file} option to see how you can +set the names for these saved morphs! +@end enumerate + +@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} where @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 +@chapter Available morphs +@cindex available morphs + +@menu +* Temperature-related morphs:: +* Shape-related morphs:: +@end menu + +In this section, we detail the available morphs and the theory behind when they can +(and should) be applied. For specifics on how to use these options in @code{PDFmorph}, +check out @ref{PDFmorph options} and the @ref{Tutorials}. + +@node Temperature-related morphs, Shape-related morphs, Available morphs, Available morphs +@section Temperature-related morphs +@cindex temperature-related morphs + +Comparing two PDFs of the same material measured at different temperatures can produce large +@math{R_W}s and signals in the difference curves. Though this can be due to a structural phase +transition across the measurements, structure-preserving changes such as isotropic expansion/compression +and thermal peak broadening/thinning can produce just as large @math{R_W} values. + +The following morph options are related to our discussion: +@itemize +@item @code{--stretch=STRETCH} - Stretch the abscissa by a factor @math{1+@code{STRETCH}}. +@item @code{--scale=SCALE} - Scale the plotted function by a factor @code{SCALE}. +@item @code{--smear=SMEAR} - Broaden the PDF peaks with a Gaussian smear of width (standard deviation) +@code{SMEAR}. +@end itemize + +@node Isotropic expansion, Thermal broadening, Temperature-related morphs, Temperature-related morphs +@subsection Isotropic expansion +@cindex isotropic expansion + +The effects of isotropic expansion/compression can be accounted for by scaling and stretching the PDF. +To prove this, we will make use of the (total) radial distribution function (RDF), denoted @math{R(r)}. +This function is related to the PDF through +@displaymath +G(r) = {R(r) \over r} - 4 \pi r \rho_0 \gamma_0(r), +@end displaymath +where @math{\rho_0} is the atomic number density the and @math{\gamma_0(r)} is the nanoparticle form factor +(see @ref{Shape-related morphs}). A partial RDF @math{R_i(r)} is defined such that @math{R_i(r)dr} gives +the number of atoms in the spherical shell bounded by @math{r} and @math{r + dr} centered at atom @math{i}. +The total RDF for an atomic system is the average of the partial RDFs of each atom in the system +@footnote{Farrow, C.L. and Billinge, S.J.L. (2009), Relationship between the atomic pair distribution +function and small-angle scattering: implications for modeling of nanoparticles. Acta Cryst. A, 65: 232-239. +@url{https://doi.org/10.1107/S0108767309009714}}. +@displaymath +R(r) = {1 \over @#\;atoms}\sum^{atoms}_{i} R_i(r). +@end displaymath +Therefore, the integral of the RDF from @math{a} to @math{b} gives the number of atomic pairs per atom with +a separation distance between @math{a} and @math{b}. + +When a material expands isotropically by a factor @math{\alpha}, all distances between pairs of atoms +increase by a factor of @math{\alpha} (expansion by a factor of @math{0 < \alpha < 1} is considered compression). +Therefore, the number of atomic pairs with separation distance between @math{a} and @math{b} before the expansion +should equal the number of atomic pairs with separation distance between @math{\alpha a} and @math{\alpha b} after. +Defining @math{R(r)} to be the RDF pre-expansion and @math{R'(r)} to be that post-expansion, +@displaymath +\int_a^b R(r)dr = \int_{\alpha a}^{\alpha b} R'(r)dr. +@end displaymath +A change of variables tells us +@displaymath +\int_a^b R(r)dr = \int_{\alpha a}^{\alpha b} {R(r/\alpha) \over \alpha}dr, +@end displaymath +and since these relations hold for all choices of @math{a \leq b}, +@displaymath +R'(r) = {R(r/\alpha) \over \alpha}. +@end displaymath + +The corresponding PDFs are +@displaymath +G(r) = {R(r) \over r} - 4\pi r\rho_0\gamma_0(r) +@end displaymath +pre-expansion, and +@displaymath +G'(r) = {R'(r) \over r} - 4\pi r \rho'_0\gamma'_0(r) = {{R(r/\alpha)} \over {\alpha r}} - 4\pi r \rho'_0\gamma'_0(r) +@end displaymath +post-expansion. Due to the expansion, the volume of the material has increased by @math{\alpha^3}, while the total number +of atoms remains the same, meaning +@displaymath +\rho'_0 = {1 \over \alpha^3}\rho_0, +@end displaymath +and the nanoparticle form function is scaled +@displaymath +\gamma_0'(r) = \gamma_0(r/\alpha) +@end displaymath +(see the bottom of @ref{Shape-related morphs}). + +Finally, we can conclude that the PDF after expansion follows +@displaymath +G'(r) = {{R(r/\alpha)} \over {\alpha r}} - 4\pi r {{\rho_0} \over {\alpha^3}} \gamma_0(r / \alpha) += {{G(\alpha r)} \over \alpha^2}, +@end displaymath +which is the original PDF scaled by a factor @math{1/\alpha^2} and stretched by @math{\alpha}. + +@node Thermal broadening, , Isotropic expansion, Temperature-related morphs +@subsection Thermal broadening +@cindex thermal broadening + +Peaks in the radial distribution functions (see @ref{Isotropic expansion}) obtained from measured PDFs have +approximately Gaussian shapes due to Debye-Waller effects. The variance of each peak is the mean square +atomic displacement factor (ADP), denoted @math{@={u^2}} which can depend on dynamic (temperature-dependent) +and static factors. Models, such as the Debye model, generally separate the two: @math{@={u^2} = +A(T) + A_{static}}, where @math{A(T)} increases with temperature. + +When a material consists of atoms with similar masses, the @math{A(T)} at each peak is approximately the +same at a fixed temperature (motivated below). Therefore, an increase in temperature only serves to increase +the ADP (and thus the variance of each Gaussian peak) by some fixed constant @math{\zeta^2}. +@code{PDFmorph} simulates this effect by converting the morphed PDF into an RDF, +convolving the RDF with a Gaussian of variance @math{\zeta^2} centered at @math{r=0}, +and converting back to a PDF. The convolution step increases the variance of each peak by @math{\zeta^2} exactly +@footnote{Bromiley, P. (2003). Products and Convolutions of Gaussian Distributions.}. + +Using the Debye model @footnote{Dinnebier, R.E. and Billinge, S.J.L. (2018). Overview and principles of +powder diffraction. In International Tables for Crystallography (eds C.P. Brock, T. Hahn, H. Wondratschek, +U. Müller, U. Shmueli, E. Prince, A. Authier, V. Kopský, D.B. Litvin, E. Arnold, D.M. Himmel, M.G. Rossmann, +S.R. Hall, B. McMahon, M.I. Aroyo, C.J. Gilmore, J.A. Kaduk, H. Schenk, C.J. Gilmore, J.A. Kaduk and H. Schenk). +@url{https://doi.org/10.1107/97809553602060000935}}, we can motivate the statement that @math{A(T)} is +similar for a material composed of similar-mass atoms. The model shows +@displaymath +A(T) = {{3h^2T^2} \over {4\pi^2Mk_B\theta_D^3}}\int_0^{\theta_D/T} {{x} \over {e^x - 1}} dx ++ {{3h^2} \over {16\pi^2Mk_B\theta_D}}, +@end displaymath +where @math{M} is the mass of the oscillating atom, +@math{\theta_D} is the Debye temperature of the (crystal) material, and @math{h} and @math{k_B} are Planck's +constant and Boltzmann's constant respectively. Thus, when the @math{M} for each atom is similar, +@math{A(T)} is also similar. Note also that @math{A(T)} is monotonically increasing +as a function of temperature. + +@node Shape-related morphs, , Temperature-related morphs, Available morphs +@section Shape-related morphs +@cindex shape-related morphs + +The shape and size of a nanoparticle can affect its electronic and optical properties +@footnote{Singh, M., Goyal, M., & Devlal, K. (2018). Size and shape effects on the band gap of semiconductor +compound nanomaterials. Journal of Taibah University for Science, 12(4), 470–475. +@url{https://doi.org/10.1080/16583655.2018.1473946}}. +@code{PDFmorph} contains tools to help a researcher identify the shape and size of a nanoparticle PDF given a PDF of a +bulk sample. The researcher should select a shape-related morph (listed below) associated with a particular shape and +provide the bulk sample PDF as the morphed PDF and nanoparticle PDF as the target. @code{PDFmorph} will then multiply the +nanoparticle form factor @math{\gamma(r)} for that particular shape to the bulk PDF and refine the parameters +(e.g. the radius for a spherical shape) to best match the target. Significant difference curve signals or @math{R_W}s +indicate large deviations from the desired shape, while small signals allow the user to extract size parameters +(e.g. the radius of the sphere) from the fit. + +This approach has been used to estimate diameters of spherical CdSe nanoparticles consistent +with those obtained from transmission electron microscopy, ultraviolet-visible spectroscopy, and photoluminescense +measurements @footnote{Masadeh, A. S., Božin, E. S., Farrow, C. L., Paglia, G., Juhas, P., Billinge, S. J. L., Karkamkar, +A., & Kanatzidis, M. G. (2007). Quantitative size-dependent structure and strain determination of CdSe nanoparticles +using atomic pair distribution function analysis. Phys. Rev. B, 76(11), 115413. +@url{https://doi.org/10.1103/PhysRevB.76.115413}}. + +The available shape morphs are listed below: +@itemize +@item @code{--radius=RADIUS} - Multiply the PDF by the nanoparticle form factor for a sphere of radius @code{RADIUS}. +If used with @code{--pradius}, multiply the PDF by the nanoparticle form factor for a spheroid of equitorial radius +@code{RADIUS} and polar radius @code{PRADIUS}. +@itemize +@item The sphere form factor was computed by Kodama et al. @footnote{Kodama, K., Iikubo, S., Taguchi, T., & +Shamoto, S. (2006). Finite size effects of nanoparticles on the atomic pair distribution functions. +Acta Crystallographica Section A, 62(6), 444–453. @url{https://doi.org/10.1107/S0108767306034635}}. +@end itemize +@item @code{--pradius=PRADIUS} - Multiply the PDF by the nanoparticle form factor for a spheroid of equitorial radius +@code{RADIUS} and polar radius @code{PRADIUS}. +@itemize +@item The spheroid form factor was computed by Lei et al. @footnote{Lei, M., de Graff, A. M. R., Thorpe, M. F., Wells, +S. A., & Sartbaeva, A. (2009). Uncovering the intrinsic geometry from the atomic pair distribution function of +nanomaterials. Phys. Rev. B, 80(2), 024118. @url{https://doi.org/10.1103/PhysRevB.80.024118}}. +@end itemize +@item @code{--iradius=IRADIUS} - Divide the PDF by the nanoparticle form factor for a sphere of radius @code{IRADIUS}. +If used with @code{--ipradius}, divide the PDF by the nanoparticle form factor for a spheroid of equitorial radius +@code{IRADIUS} and polar radius @code{IPRADIUS}. +@item @code{--ipradius=IPRADIUS} - Divide the PDF by the nanoparticle form factor for a spheroid of equitorial radius +@code{IRADIUS} and polar radius @code{IPRADIUS}. +@end itemize + +In the rest of this section, we will detail how the nanoparticle form factor is computed. +We first need to define the shape function @math{s\vec{r}}, which is @math{1} within the nanoparticle and +@math{0} outside. The unaveraged particle form factor @math{\gamma_0(\vec{r})} is the autocorrelation +of this shape function averaged over the nanoparticle volume @math{V}. +@displaymath +\gamma_0(\vec{r}) = {1 \over V} \int \int \int s(\vec{r}')s(\vec{r}'+\vec{r})d\vec{r}'. +@end displaymath +In this manual, we refer to the angle-averaged version, denoted @math{\gamma_0(r)}, as the nanoparticle form factor. +@displaymath +\gamma_0(r) = {{\int d\phi \int d\theta \sin(\theta)r^2\gamma_0(\vec{r})} \over {\int d\phi \int d\theta r^2\sin(\theta)}}. +@end displaymath +This form factor is particularly useful as one can approximate the nanoparticle PDF @math{G_{nano}(r)} +by multiplying the proper nanoparticle form factor with the bulk PDF @math{G_{bulk}(r)} +@footnote{Farrow, C.L. and Billinge, S.J.L. (2009), Relationship between the atomic pair distribution function and +small-angle scattering: implications for modeling of nanoparticles. Acta Cryst. A, 65: 232-239. +@url{https://doi.org/10.1107/S0108767309009714}} +as follows +@displaymath +G_{nano}(r) = \gamma(r)G_{bulk}(r). +@end displaymath + +Finally, an important property of the nanoparticle form factor @math{\gamma_0(r)} that we use in @ref{Isotropic expansion} +is that, after undergoing isotropic expansion by a factor @math{\alpha}, the new form factor @math{\gamma'(r)} is a stretched +version of the original form factor: @math{\gamma'_0(r) = \gamma_0(r / \alpha)}. To show this, consider the new shape function +@math{s'(\alpha \vec{r}) = s(\vec{r})} as each point @math{\vec{r}} pre-expansion is mapped to a point @math{\alpha\vec{r}} +post-expansion. The volume of the nanoparticle also increases by a factor @math{\alpha^3}, so +@displaymath +\gamma'_0(\vec{r}) = {1 \over {\alpha^3 V}} \int \int \int s'(\vec{r}')s'(\vec{r}'+\vec{r})d\vec{r}'. +@end displaymath +Aplying a change of variables @math{\vec{r}' \rightarrow \vec{r}' / \alpha} gives +@displaymath +\gamma'_0(\vec{r}) = {1 \over {\alpha^3 V}} \int \int \int s'(\alpha \vec{r}')s'(\alpha \vec{r}'+\vec{r})\alpha^3d\vec{r}', +@end displaymath +and substituting @math{s'(\alpha \vec{r}) = s(\vec{r})} gives +@displaymath +\gamma'_0(\vec{r}) = {1 \over V} \int \int \int s(\vec{r}')s(\vec{r}'+\vec{r}/\alpha)d\vec{r}' += \gamma_0(\vec{r} / \alpha). +@end displaymath +Taking the angle-averaged integrals gives the desired relation @math{\gamma'_0(r) = \gamma'_0(r/\alpha)}. + +@page +@vskip 0pt plus 1filll +@node PDFmorph options, Index, Available morphs, Top +@chapter PDFmorph options +@cindex pdfmorph options + +In this section we describe all the options available to use in the +@code{PDFmorph} program. Without options, the @code{PDFmorph} program +is run with the command +@example +pdfmorph +@end example +@noindent where morphs will be applied to the morphed PDF in attempt to minimize +the residual with the target PDF. + +@noindent @code{-h, --help} +@* @indent Show a brief summary of all the options listed in this section. + +@noindent @code{-V, --version} +@* @indent Show the program version (does not run the program). + +@noindent @code{-s NAME, --save=NAME} +@* @indent Save the morphed PDF into a file named @code{NAME}. You can use +@code{-} to save to @code{stdout} instead. +When you have the @code{--multiple} tag enabled, multiple morphed PDFs are +generated. Using this command with the @code{--multiple} tag will save all +these morphs into a directory named @code{NAME} as well as a @code{.txt} +file summary of refined morph parameters (if applicable) and @math{R_W} +for each morph done. To specify names for each saved PDF file, use the +@code{--save-names-file} option. + +@noindent @code{-v, --verbose} +@* @indent Increase the amount of information saved to the file(s) generated +by @code{--save}. Without this option enabled, only the morphed PDF table will be +saved (the table of @math{r} and corresponding @math{G(r)} values). When enabled, +information about the input and refined morph parameters (when applicable) and +the @math{R_W} and Pearson correlation coefficient will be saved as parameters +above the PDF table. + +@noindent @code{--rmin=RMIN} +@* @indent The minimum @math{r}-value to use for PDF comparisons and manipulations. + +@noindent @code{--rmax=RMAX} +@* @indent The maximum @math{r}-value to use for PDF comparisons and manipulations. + +@noindent @code{--pearson} +@* @indent When enabled, refinement will seek only to maximize the Pearson correlation +coefficient between the two PDFs. + +@noindent @code{--addpearson} +@* @indent When enabled, refinement will seek to both maximize the Pearson correlation +coefficient and minimize the residual between the two PDFs. + +@noindent @titlefont{Morphs and manipulations} + +These options select the morphs and manipulations that are to be applied to +the morphed PDF. The passed values will be refined unlesss specifically excluded with the +@code{--apply} or @code{--exclude} options. If no morphs are selected, the morphed PDF will +be unchanged and plotted against the target PDF. + +@noindent @code{-a, --apply} +@* @indent Apply the morph but do not refine the morph parameter value. +When this is not enabled, @code{PDFmorph} will automatically refine the +morph parameters for all morph options below. + +@noindent @code{-x MORPH, --exclude=MORPH} +@* @indent Do not refine the morph named @code{MORPH}. Note that the input @code{MORPH} +must be lower case and match exactly the name of the morph option that you wish not to refine. +For example, running +@example +pdfmorph --scale=2 --smear=0.1 --exclude=scale +@end example +@noindent will scale the morphed PDF by exactly @math{2}, but will refine the +parameter @math{0.1} for smear. However, @code{--exclude=Scale} will not stop +@code{--scale=2} from being refined. + +@noindent @code{--scale=SCALE} +@* @indent Apply a scale factor @code{SCALE} to the function being plotted. For instance, +scaling @math{G(r)} by @code{SCALE} will return @math{@code{SCALE}*G(r)}. + +@noindent @code{--smear=SMEAR} +@* @indent Smear the PDF peaks with a Gaussian of width (standard deviation) @math{abs(@code{SMEAR})}. +This input can be negative, but will have the same effect as its absolute value. This function is designed +only for use on PDFs. This operation assumes the RDF (see @ref{Available morphs}) peaks are approximately +Gaussian and works by converting the PDF to an RDF, convoluting a Gaussian of width @code{SMEAR} with the RDF, +and converting back to the PDF. This conversion requires a parameter @code{BASELINESLOPE} which will be +refined if not provided by the user in the @code{--slope} option. + +@noindent @code{--stretch} +@* @indent Stretch the function being plotted along the abscissa by a factor of @math{1 + @code{STRETCH}}. +For example, if the original function is @math{G(r)}, the stretch returns @math{g(r/(1+@code{STRETCH}))}. +The returned PDF will always only be defined between @code{RMIN} and @code{RMAX} (see @code{--rmin} +and @code{--rmax}). The @code{STRETCH} coefficient must be larger than @math{-1} and values in the +range @math{(-1, 0)} will compress the function and set the remaining portion of the function up to +@code{RMAX} as zero. + +@noindent @code{--slope=BASELINESLOPE} +@* @indent The slope of the baseline used when applying the smear factor. Unless excluded using @code{--apply} +or @code{--exclude}, it will be refined whenever @code{--smear} is used, even if @code{--smear} is not being refined. +The equation @math{@code{BASELINESLOPE}=4 \pi r \rho_0 \gamma_0)} can be used if the atomic number density +@math{\rho_0} and the nanoparticle form factor @math{\gamma_0} is known for the morphed PDF. + +@noindent @code{--qdamp=QDAMP} +@* @indent Dampen the PDF by a factor @code{QDAMP}. A limited @math{Q}-resolution of the diffractometer +requires us to apply a Gaussian dampening envelope centered at @math{r=0} with width (standard deviation) +@code{QDAMP}. This envelop is directly multiplied to the PDF. + +@noindent @code{--radius=RADIUS} +@* @indent Apply the nanoparticle form factor @math{\gamma_0} for a sphere of radius @code{RADIUS}. +If @code{PRADIUS} is also specified, instead apply the characteristic function of a spheroid with +equitorial radius @code{RADIUS} and polar radius @code{PRADIUS}. + +@noindent @code{--pradius=PRADIUS} +@* @indent If @code{RADIUS} is also specified, see @code{--radius}. Otherwise, apply the characteristic +function of a sphere with radius @code{PRADIUS}. + +@noindent @code{--iradius=IRADIUS} +@* @indent Apply the inverse characteristic function @math{1/\gamma_0} of a sphere of radius @code{IRADIUS}/ +If @code{IPRADIUS} is also specified, instead apply the characteristic function of a spheroid with +equitorial radius @code{IRADIUS} and polar radius @code{PRADIUS}. + +@noindent @code{--ipradius=IPRADIUS} +@* @indent If @code{IRADIUS} is also specified, see @code{--iradius}. Otherwise, apply the characteristic +function of a sphere with radius @code{IPRADIUS}. + +@noindent @titlefont{@b{Plot options}} + +These options control plotting. The morphed and target PDFs will be plotted against each other with a +difference curve shown below. The following changes occur when @code{--multiple} is enabled. +(1) The @math{R_W} for each morphed PDF compared to the target will be plotted unless +another parameter is specified by @code{--plot-parameter}. (2) The plot will be a bar chart +where the abscissa names are the file names of the target PDFs unless otherwise specified by +@code{--sort-by}. If the parameter given to @code{--sort-by} has numerical value, the plot +will be a line chart; otherwise, a bar chart the parameter values as the abscissa names will +be plotted. By default, ASCII sort order is used for the bar chart abscissa names, but +@code{--reverse} can be used to reverse the order. + +@noindent @code{-n, --noplot} +@* @indent Do not display a plot if enabled. Otherwise, show a plot. + +@noindent @code{--mlabel=MLABEL} +@* @indent Set the label for the morphed PDF to @code{MLABEL} on the plot. If not specified, +the morphed file name will be used as the label. + +@noindent @code{--tlabel=TLABEL} +@* @indent Set the label for the target PDF to @code{TLABEL} on the plot. If not specified, +the target file name will be used as the label. + +@noindent @code{--pmin=PMIN} +@* @indent The minimum @math{r}-value (abscissa) to plot. If not specified, @code{RMIN} will be used. + +@noindent @code{--pmax=PMAX} +@* @indent @indent The maximum @math{r}-value (abscissa) to plot. If not specified, @code{RMAX} will be used. + +@noindent @code{--maglim=MAGLIM} +@* @indent The function @math{G(r)} will be magnified by @code{MAG} for @math{r>@code{MAGLIM}}. This may +be useful as PDF amplitude can get very small for large @math{r}. No magnification will take place if +@code{--maglim} is not specified. + +@noindent @code{--mag=MAG} +@* @indent See @code{--maglim}. No magnification will take place if @code{--maglim} is not specified. + +@noindent @code{--lwidth=LWIDTH} +@* @indent Set the line thickness of the plotted curves. If not specified, it will default to @math{1.5}. + +@noindent @titlefont{@b{Multiple morphs}} + +@code{PDFmorph} allows one to morph one PDF against multiple different targets when @code{--multiple} +is enabled. See @code{-s} and the description under "Plot options" for how saving and plotting +change when @code{--multiple} is enabled. + +@noindent @code{--multiple} +@* @indent Changes usage of @code{PDFmorph} to +@example +pdfmorph +@end example +@noindent where the PDF in the file @code{MORPHED_FILE} will be morphed with each (PDF) file +in the directory @code{TARGET_DIRECTORY} as the target. Files in @code{TARGET_DIRECTORY} will +be sorted in ASCII sort order order unless a sorting parameter is specified by @code{sort-by}. + +@noindent @code{--sort-by=FIELD} +@* @indent Used with @code{--multiple}. Sort the files in @code{TARGET_DIRECTORY} by some parameter +named @code{FIELD}. Parameters can be specified within each target PDF file by lines of the form +@code{ = } in the header (anywhere above the @math{r} versus @math{G(r)} +data table). @code{PDFmorph} will attempt to find a parameter named @code{FIELD} using a +case-insensitive search. Numerical @code{PARAM_VALUE} will be sorted in ascending order and +non-numerical ones will be sorted in ASCII sort order. + +@noindent @code{--reverse} +@* @indent Used with @code{--multiple}. Sort the files in @code{TARGET_DIRECTORY} in reverse +ASCII sort order. If a parameter is given by @code{--sort-by}, reverse the order given by +@code{--sort-by}. + +@noindent @code{--serial-file=SERIALFILE} +@* @indent Used with @code{--multiple} and @code{--sort-by}. Look for @code{FIELD} in a serial +file named @code{SERIALFILE} instead. Only serial file types supported by +@url{https://www.diffpy.org/diffpy.utils, diffpy.utils} such as @code{.json} are allowed. + +@noindent @code{--save-names-file=NAMESFILE} +@* @indent Used with @code{--multiple} and @code{-s}. Specify names for each manipulated PDF when +saving using a serial file named @code{NAMESFILE}. The format of @code{NAMESFILE} should be +as follows: (1) Each target PDF file name is an entry in @code{NAMESFILE}. (2) For each entry, +there should be a key @code{save_morph_as} whose value specified the name to save the manipulated +PDF as. An example @code{.json} @code{NAMESFILE} is below. +@example +@{ + "target1.gr": @{ + "save_morph_as": "name.extension" + @}, + "target2.gr": @{ + "save_morph_as": "another_name.extension", + "other_information": "[optional]" + @}, + "target3.gr": @{ + "SaVe_MoRph_As": "this_also_works.extension", + "note": "Capitalization does NOT matter. This is case insensitive." + @} +@} +@end example +@noindent Only serial file types supported by @url{https://www.diffpy.org/diffpy.utils, diffpy.utils} +such as @code{.json} are allowed. + +@noindent @code{--plot-parameter=PLOTPARAM} +@* @indent Used with @code{--multiple} and when plotting is enabled. Choose a parameter @code{PLOTPARAM} +to plot for each morph. When not specified, the @math{R_W} values for each morphed PDF compared to the +target PDFs will be plotted. This option is not case sensitive meaning @code{--plot-parameter=Scale} and +@code{--plot-parameter=scale} will both cause the parameter @code{scale} to be plotted. + +@c End TexInfo file +@node Index, Top +@unnumbered Index + +@printindex cp + +@bye diff --git a/doc/manual/redistribution.texinfo b/doc/manual/redistribution.texinfo new file mode 100644 index 00000000..03169398 --- /dev/null +++ b/doc/manual/redistribution.texinfo @@ -0,0 +1,13 @@ +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are met: + +@itemize +@item Redistributions of source code must retain the above copyright notice, this +list of conditions and the following disclaimer. +@item Redistributions in binary form must reproduce the above copyright notice, +this list of conditions and the following disclaimer in the documentation +and/or other materials provided with the distribution. +@item Neither the names of COLUMBIA UNIVERSITY, MICHIGAN STATE UNIVERSITY nor the +names of their contributors may be used to endorse or promote products +derived from this software without specific prior written permission. +@end itemize diff --git a/doc/manual/source/index.rst b/doc/manual/source/index.rst index 1b477cb1..b42c3f2b 100644 --- a/doc/manual/source/index.rst +++ b/doc/manual/source/index.rst @@ -35,7 +35,8 @@ the plotted PDFs. Finally, we note that though ``PDFmorph`` should work on other spectra that are not PDFs, it has not been extensively tested beyond the PDF. -To get started, please go to the :ref:`quick_start`. +To get started, please download our :download:`user manual <../pdfmorph.pdf>` +or visit the :ref:`quick_start`. Authors ------- diff --git a/doc/manual/source/quickstart.rst b/doc/manual/source/quickstart.rst index 57fc97a5..b69791fd 100644 --- a/doc/manual/source/quickstart.rst +++ b/doc/manual/source/quickstart.rst @@ -4,7 +4,8 @@ PDFmorph Tutorial ################# Welcome! This will be a quick tutorial to accquaint users with PDFmorph -and some of what it can do. +and some of what it can do. For a more detailed tutorial, check out +our :download:`user manual <../pdfmorph.pdf>`. As we described in the README and installation instructions, please make sure that you are familiar with working with your command line terminal diff --git a/tutorial/PDFmorph_manual.pdf b/tutorial/PDFmorph_manual.pdf new file mode 100644 index 00000000..7ea99f6b Binary files /dev/null and b/tutorial/PDFmorph_manual.pdf differ