Skip to content

Latest commit

 

History

History
187 lines (136 loc) · 8.11 KB

TUTORIAL.rst

File metadata and controls

187 lines (136 loc) · 8.11 KB
Raw

PDFmorph Tutorial

Welcome! This will be a quick tutorial to accquaint users with PDFmorph and some of what it can do.

As we described in the README and installation instructions, please make sure that you are familiar with working with your command line terminal before using this application.

Before you've started this tutorial, please ensure that you've installed all necessary software and dependencies.

Basic PDFmorph Workflow

  1. Open your Terminal or Command Prompt.

  2. It it's not active already, activate your PDFmorph-equipped conda environment by typing in

    source activate <pdfmorph_env>

    on Linux or activate <pdfmorph_env> on Windows.

    • If you need to list your available conda environments, run the command conda info --envs or conda env list
  • Run the pdfmorph --help command and read over the info on that page for a brief overview of some of what we will explore in this tutorial.

3. Using the mkdir command, create a directory where you'll store the tutorial PDF files and use the cd command to change into that directory. You can download the tutorial files :download:`here <tests/testdata/tutorialData.zip`. Then, cd into the tutorialData directory.

  • The files in this dataset were collected by Soham Banerjee at Brookhaven National Laboratory in Upton, New York.
  • The files are PDF data collected on Iridium Telluride with 20% Rhodium Doping (IrRhTe2) with the first file (01) collected at 10K and the last (44) at 300K. The samples increase in temperature as their numbers increase. The "C" in their names indicates that they have undergone cooling.
  • 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, sich as those generated by the PDFgui program.

  1. First, we will run the PDFmorph application without any morphing and only using one PDF. Type the following command into your Command Line

        pdfmorph darkSub_rh20_C_01.gr darkSub_rh20_C_01.gr

This should produce two PDF curves which are congruent, resulting
in a flat green line underneath them.

  2. Now, we will see PDFmorph run with two different PDFs and no morphing. Type the following command into your command line

    pdfmorph darkSub_rh20_C_01.gr darkSub_rh20_C_44.gr

    Without morphing, the difference Rw = 0.407. This indicates that the two PDFs vary drastically.

    • While running the pdfmorph command, it is important to remember that the first PDF file argument you provide (in this case, darkSub_rh20_C_01.gr) is the PDF which will get morphed, while the second PDF file argument you provide (here, darkSub_rh20_C_44.gr) is the PDF which acts as the model and does not get morphed. Hereinafter, we will refer to the first PDF argument as the "morph" and the second as the "target", as the PDFmorph display does.

  3. 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. Begin by typing the command

    pdfmorph --scale=2 -a darkSub_rh20_C_01.gr darkSub_rh20_C_44.gr

    Now, the difference Rw = 1.457, a significant increase from our value previously. We must modify our initial value for the scaling factor and do so until we see a reduction in the difference Rw from the unmorphed value. Type

    pdfmorph --scale=0.9 -a darkSub_rh20_C_01.gr darkSub_rh20_C_44.gr

    The difference Rw is now 0.351, lower than our unmorphed example's value. To see PDFmorph optimize the scale factor, simply drop -a from the command and type

    pdfmorph --scale=0.9 darkSub_rh20_C_01.gr darkSub_rh20_C_44.gr

    PDFmorph, given a reasonable initial guess, will use find the optimal value for each morphing feature. Here, we see that PDFmorph displays scale = 0.799025 in the command prompt, meaning that it has found this to be the most optimal value for the scale factor. The difference Rw = 0.330, indicating a better fit than our reasonable initial guess.

    • It is the choice of the user whether or not to run values before removing -a when analyzing data with PDFmorph. By including it, you allow the possibility to 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. In this tutorial, we will use it every time to check for convergence.

  4. Now, we will examine the Gaussian smearing factor. We provide an initial guess by typing

    pdfmorph --scale=0.8 --smear=0.5 -a darkSub_rh20_C_01.gr darkSub_rh20_C_44.gr

    And viewing the results. We've tailored our scale factor to be close to the value given by PDFmorph, but see that the difference Rw has increased substantially due to our smear value. One approach, as described above, is to remove the -a from the above command and run it again.

    • Note: 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.

    We see that this has had hardly any effect on our PDF. To see an effect, we restrict the rmin and rmax values to reflect relevant data range by typing

    pdfmorph --scale=0.8 --smear=0.5 --rmin=1.5 --rmax=30 darkSub_rh20_C_01.gr darkSub_rh20_C_44.gr

    Now, we see that the difference Rw = 0.204 and that the optimized smear=-0.084138.

    • We restricted the r values because some of the Gaussian smear effects are only visible in a fixed r range. We chose this r range by noting where most of our relevant data was that was not exponentially decayed by instrumental shortcomings.

    We are getting closer to an acceptably close fit to our data!

  5. Finally, we will examine the stretch factor. Provide an initial guess by typing

    pdfmorph --scale=0.8 --smear=-0.08 --stretch=0.5 --rmin=1.5 --rmax=30 -a darkSub_rh20_C_01.gr darkSub_rh20_C_44.gr

    And noting that the difference has increased. Before continuing, see if you can see which direction (higher or lower) our initial estimate for the stretch factor needs to go and then removing the -a to check optimized value!

    If you cannot, type

    pdfmorph --scale=0.8 --smear=-0.08 --stretch=0.005 --rmin=1.5 --rmax=30 -a darkSub_rh20_C_01.gr darkSub_rh20_C_44.gr

    to observe decreased difference and then remove -a to see the optimized --stretch=0.001762. We have now reached the optimal fit for our PDF!

  6. 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 provided in this tutorial are unique to it, so be cautious about your choices and made sure that they remain physically relevant.

Enjoy the software!

Bug Reports

Please enjoy using our software! If you come across any bugs in the application, please report them to diffpy-dev@googlegroups.com