Skip to content

Commit 5aae78d

Browse files
Sparks29032Sparks29032
committed
Restore non-api files
1 parent ad597ce commit 5aae78d

File tree

2 files changed

+305
-0
lines changed

2 files changed

+305
-0
lines changed

‎doc/source/quickstart.rst‎

Lines changed: 297 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,297 @@
1+
.. _quick_start:
2+
3+
PDFmorph Tutorial
4+
#################
5+
6+
Welcome! This will be a quick tutorial to accquaint users with PDFmorph
7+
and some of what it can do. For a more detailed tutorial, check out
8+
our :download:`user manual <../pdfmorph.pdf>`.
9+
10+
As we described in the README and installation instructions, please make
11+
sure that you are familiar with working with your command line terminal
12+
before using this application.
13+
14+
Before you've started this tutorial, please ensure that you've installed
15+
all necessary software and dependencies.
16+
17+
Basic PDFmorph Workflow
18+
=======================
19+
20+
1. Open your Terminal or Command Prompt.
21+
22+
2. If it's not active already, activate your PDFmorph-equipped
23+
conda environment by typing in ::
24+
25+
conda activate <pdfmorph_env>
26+
27+
28+
* If you need to list your available conda environments,
29+
run the command ``conda info --envs`` or
30+
``conda env list``
31+
32+
* Run the ``pdfmorph --help`` command and read over the
33+
info on that page for a brief overview of some of what we will
34+
explore in this tutorial.
35+
36+
3. Using the ``mkdir`` command, create a directory where you'll
37+
store the tutorial PDF files and use the ``cd`` command to change
38+
into that directory. You can download the tutorial files
39+
:download:`here <../../../tutorial/tutorialData.zip>`.
40+
Then, ``cd`` into the ``tutorialData`` directory.
41+
42+
* The files in this dataset were collected by Soham Banerjee
43+
at Brookhaven National Laboratory in Upton, New York.
44+
45+
* The files are PDF data collected on Iridium Telluride with
46+
20% Rhodium Doping (IrRhTe2) with the first file (01) collected
47+
at 10K and the last (44) at 300K. The samples increase in
48+
temperature as their numbers increase. The "C" in their names
49+
indicates that they have undergone cooling.
50+
51+
* Note that these files have the ``.gr`` extension, which
52+
indicates that they are measured PDFs. The ``.cgr`` file
53+
extension indicates that a file is a calculated PDF, such as
54+
those generated by the `PDFgui <https://www.diffpy.org/products/pdfgui.html>`_
55+
program.
56+
57+
4. First, we will run the PDFmorph application without any morphing
58+
and only using one PDF. Type the following command into your
59+
command line ::
60+
61+
pdfmorph darkSub_rh20_C_01.gr darkSub_rh20_C_01.gr
62+
63+
This should produce two PDF curves which are congruent, resulting
64+
in a flat green line underneath them.
65+
66+
5. Now, we will see PDFmorph run with two different PDFs and no
67+
morphing. Type the following command into your command line ::
68+
69+
pdfmorph darkSub_rh20_C_01.gr darkSub_rh20_C_44.gr
70+
71+
Without morphing, the difference Rw = 0.407. This indicates that
72+
the two PDFs vary drastically.
73+
74+
* While running the ``pdfmorph`` command, it is important
75+
to remember that the first PDF file argument you provide
76+
(in this case, ``darkSub_rh20_C_01.gr``) is the PDF which
77+
will get morphed, while the second PDF file argument you
78+
provide (here, ``darkSub_rh20_C_44.gr``) is the PDF which
79+
acts as the model and does not get morphed. Hereinafter,
80+
we will refer to the first PDF argument as the "morph"
81+
and the second as the "target", as the PDFmorph display
82+
does.
83+
84+
6. Now, we will start the morphing process, which requires us to
85+
provide initial guesses for our scaling factor, Gaussian smear,
86+
and stretch, separately. We will start with the scaling factor.
87+
Begin by typing the command ::
88+
89+
pdfmorph --scale=2 -a darkSub_rh20_C_01.gr darkSub_rh20_C_44.gr
90+
91+
Now, the difference Rw = 1.457, a significant increase from our
92+
value previously. We must modify our initial value for the
93+
scaling factor and do so until we see a reduction in the
94+
difference Rw from the unmorphed value. Type ::
95+
96+
pdfmorph --scale=0.9 -a darkSub_rh20_C_01.gr darkSub_rh20_C_44.gr
97+
98+
The difference Rw is now 0.351, lower than our unmorphed
99+
example's value. To see PDFmorph optimize the scale factor,
100+
simply drop ``-a`` from the command and type ::
101+
102+
pdfmorph --scale=0.9 darkSub_rh20_C_01.gr darkSub_rh20_C_44.gr
103+
104+
PDFmorph, given a reasonable initial guess, will use find the
105+
optimal value for each morphing feature. Here, we see that
106+
PDFmorph displays ``scale = 0.799025`` in the command prompt,
107+
meaning that it has found this to be the most optimal value for
108+
the scale factor. The difference Rw = 0.330, indicating a
109+
better fit than our reasonable initial guess.
110+
111+
* It is the choice of the user whether or not to run values
112+
before removing ``-a`` when analyzing data with PDFmorph.
113+
By including it, you allow the possibility to move towards
114+
convergence before allowing the program to optimize by
115+
removing it; when including it, you may reach a highly
116+
optimized value on the first guess or diverge greatly.
117+
In this tutorial, we will use it every time to check
118+
for convergence.
119+
120+
7. Now, we will examine the Gaussian smearing factor. We provide an
121+
initial guess by typing ::
122+
123+
pdfmorph --scale=0.8 --smear=0.5 -a darkSub_rh20_C_01.gr darkSub_rh20_C_44.gr
124+
125+
And viewing the results. We've tailored our scale factor to be
126+
close to the value given by PDFmorph, but see that the difference
127+
Rw has increased substantially due to our smear value. One
128+
approach, as described above, is to remove the ``-a`` from the
129+
above command and run it again.
130+
131+
* Note: The warnings that the Terminal/Command Prompt
132+
displays are largely numerical in nature and do not
133+
indicate a physically irrelevant guess. These are somewhat
134+
superficial and in most cases can be ignored.
135+
136+
We see that this has had hardly any effect on our PDF. To see
137+
an effect, we restrict the ``rmin`` and ``rmax`` values to
138+
reflect relevant data range by typing ::
139+
140+
pdfmorph --scale=0.8 --smear=0.5 --rmin=1.5 --rmax=30 darkSub_rh20_C_01.gr darkSub_rh20_C_44.gr
141+
142+
Now, we see that the difference Rw = 0.204 and that the optimized
143+
``smear=-0.084138``.
144+
145+
* We restricted the r values because some of the Gaussian
146+
smear effects are only visible in a fixed r range. We
147+
chose this r range by noting where most of our relevant
148+
data was that was not exponentially decayed by
149+
instrumental shortcomings.
150+
151+
We are getting closer to an acceptably close fit to our data!
152+
153+
8. Finally, we will examine the stretch factor. Provide an intial
154+
guess by typing ::
155+
156+
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
157+
158+
And noting that the difference has increased. Before continuing,
159+
see if you can see which direction (higher or lower) our initial
160+
estimate for the stretch factor needs to go and then removing
161+
the ``-a`` to check optimized value!
162+
163+
If you cannot, type ::
164+
165+
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
166+
167+
to observe decreased difference and then remove ``-a`` to see
168+
the optimized ``--stretch=0.001762``. We have now reached
169+
the optimal fit for our PDF!
170+
171+
9. Now, try it on your own! If you have personally collected or
172+
otherwise readily available PDF data, try this process to see if
173+
you can morph your PDFs to one another. Many of the parameters
174+
provided in this tutorial are unique to it, so be cautious about
175+
your choices and made sure that they remain physically relevant.
176+
177+
Enjoy the software!
178+
179+
.. Additional PDFmorph Functionality/Exploration
180+
.. ---------------------------------------------
181+
.. TODO include undoped PDF example
182+
Extra Tutorials
183+
===============
184+
PDFmorph has some more functionalities not showcased in the basic workflow above
185+
(see `pdfmorph --help` for an overview of these functionalities).
186+
Tutorials for these additional functionalities are included below. Additional
187+
files for these tutorials can be downloaded
188+
:download:`here <../../../tutorial/additionalData.zip>`.
189+
190+
Performing Multiple Morphs
191+
--------------------------
192+
193+
It may be useful to morph a PDF against multiple targets:
194+
for example, you may want to morph a PDF against multiple PDFs measured
195+
at various temepratures to determine whether a phase change has occured.
196+
PDFmorph currently allows users to morph a PDF against all files in a
197+
selected directory and plot resulting :math:`R_w` values from each morph.
198+
199+
1. Within the ``additionalData`` directory, ``cd`` into the ``morphMultiple`` directory.
200+
Inside, you will find multiple PDFs of :math:`SrFe_2As_2` measured at various temperatures.
201+
These PDFs are from `"Atomic Pair Distribution Function Analysis: A primer" <https://github.com/Billingegroup/pdfttp_data/>`_.
202+
2. Let us start by getting the Rw of ``SrFe2As2_150K.gr`` compared to all other files in the
203+
directory. Run ::
204+
205+
pdfmorph SrFe2As2_150K.gr . --multiple
206+
207+
The multiple tag indicates we are comparing PDF file (first input) against all PDFs in
208+
a directory (second input). Our choice of file was ``SeFe2As2_150K.gr``
209+
and directory was the cwd, which should be ``morphMultiple``.
210+
3. After running this, we get chart of Rw values for each target file. However, this chart can
211+
be a bit confusing to interpret. To get a more understandable plot, run ::
212+
213+
pdfmorph SrFe2As2_150K.gr . --multiple --sort-by=temperature
214+
215+
This plots the Rw against the temperature parameter value provided at the top of each file.
216+
Parameters are entries of the form ``<parameter_name> = <parameter_value>`` and are located
217+
above the ``r`` versus ``gr`` table in each PDF file.
218+
4. Between 192K and 198K, the Rw has a sharp increase, indicating that we may have a phase change.
219+
To confirm, let us now apply morphs onto ``SrFe2As2_150K.gr`` with all other files in ``morphMultiple``
220+
as targets ::
221+
222+
pdfmorph --scale=1 --stretch=0 SrFe2As2_150K.gr . --multiple --sort-by=temperature
223+
224+
Note that we are not applying a smear since it takes a long time to apply and does not significantly
225+
change the Rw values in this example.
226+
5. We should now see a sharper increase in Rw between 192K and 198K.
227+
6. Go back to the terminal to see optimized morphing parameters from each morph.
228+
7. On the morph with ``SrFe2As2_192K.gr`` as target, ``scale = 0.972085`` and ``stretch = 0.000508``
229+
and with ``SrFe2As2_198K.gr`` as target, ``scale = 0.970276`` and ``stretch = 0.000510``.
230+
These are very similar, meaning that thermal lattice expansion (accounted for by ``stretch``)
231+
is not occurring. This, coupled with the fact that the Rw significantly increases suggests
232+
a phase change in this temperature regime. (In fact, :math:`SrFe_2As_2` does transition from
233+
orthorhombic at lower temperature to tetragonal at higher temperature!)
234+
235+
Nanoparticle Shape Effects
236+
--------------------------
237+
238+
A nanoparticle's finite size and shape can affect the shape of its PDF.
239+
We can use PDFmorph to morph a bulk material PDF to simulate these shape effects.
240+
Currently, the supported nanoparticle shapes include: spheres and spheroids.
241+
242+
* Within the ``additionalData`` directory, ``cd`` into the ``morphShape`` subdirectory.
243+
Inside, you will find a sample Ni bulk material PDF ``Ni_bulk.gr``.
244+
This PDF is from `"Atomic Pair Distribution Function Analysis: A primer" <https://github.com/Billingegroup/pdfttp_data/>`_.
245+
There are also multiple ``.cgr`` files with calculated Ni nanoparticle PDFs.
246+
247+
* Let us apply various shape effect morphs on the bulk material to reproduce these calculated PDFs.
248+
249+
* Spherical Shape
250+
1. The ``Ni_nano_sphere.cgr`` file contains a generated spherical nanoparticle with unknown radius.
251+
First, let us plot ``Ni_blk.gr`` against ``Ni_nano_sphere.cgr`` ::
252+
253+
pdfmorph Ni_bulk.gr Ni_nano_sphere.cgr
254+
255+
Despite the two being the same material, the Rw is quite large.
256+
To reduce the Rw, we will apply spherical shape effects onto the PDF.
257+
However, in order to do so, we first need the radius of the spherical nanoparticle.
258+
2. To get the radius, we can first observe a plot of ``Ni_nano_sphere.cgr`` ::
259+
260+
pdfmorph Ni_nano_sphere.cgr Ni_nano_sphere.cgr
261+
262+
3. Nanoparticles tend to have broader peaks at r-values larger than the particle size,
263+
corresponding to the much weaker correlations between molecules.
264+
On our plot, beyond r=22.5, peaks are too broad to be visible,
265+
indicating our particle size to be about 22.4.
266+
The approximate radius of a sphere would be half of that, or 11.2.
267+
4. Now, we are ready to perform a morph applying spherical effects. To do so, we use the ``--radius`` parameter ::
268+
269+
pdfmorph Ni_bulk.gr Ni_nano_sphere.cgr --radius=11.2 -a
270+
271+
5. We can see that the Rw value has significantly decreased from before. Run without the ``-a`` tag to refine ::
272+
273+
pdfmorph Ni_bulk.gr Ni_nano_sphere.cgr --radius=11.2
274+
275+
6. After refining, we see the actual radius of the nanoparticle was closer to 12.
276+
* Spheroidal Shape
277+
1. The ``Ni_nano_spheroid.cgr`` file contains a calculated spheroidal Ni nanoparticle.
278+
Again, we can begin by plotting the bulk material against our nanoparticle ::
279+
280+
pdfmorph Ni_bulk.gr Ni_nano_spheroid.cgr
281+
282+
2. Inside the ``Ni_nano_spheroid.cgr`` file, we are given that the equatorial radius is 12 and polar radius is 6.
283+
This is enough information to define our spheroid. To apply spheroid shape effects onto our bulk, run ::
284+
285+
pdfmorph Ni_bulk.gr Ni_nano_spheroid.cgr --radius=12 --pradius=6 -a
286+
287+
Note that the equitorial radius corresponds to the ``--radius`` parameter and polar radius to ``--pradius``.
288+
3. Remove the ``-a`` tag to refine.
289+
290+
There is also support for morphing from a nanoparticle to a bulk. When applying the inverse morphs,
291+
it is recommended to set ``--rmax=psize`` where ``psize`` is the longest diameter of the nanoparticle.
292+
293+
Bug Reports
294+
===========
295+
296+
Please enjoy using our software! If you come accross any bugs in the
297+
application, please report them to diffpy-users@googlegroups.com.

‎doc/source/tutorialfiles.rst‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
Download Tutorial Files Here
2+
############################
3+
4+
Quick start tutorial data:
5+
:download:`tutorialData.zip <../../tutorial/tutorialData.zip>`
6+
7+
Extra tutorial data:
8+
:download:`additionalData.zip <../../tutorial/additionalData.zip>`

0 commit comments

Comments
 (0)