forked from diffpy/diffpy.pdfgui
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathpdfgui.texinfo
1946 lines (1630 loc) · 85.9 KB
/
pdfgui.texinfo
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
\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
<!-- EquationMark -->
@end html
@end macro
@macro ScreenShot{f}
@center @image{\f\, 5in}
@end macro
@macro ReleaseDate{}
May 2023
@end macro
@exampleindent 2
@c start of header
@setfilename pdfgui
@settitle PDFgui user guide, release 2.0, @ReleaseDate{}
@c @setcontentsaftertitlepage
@c end of header
@c Part 1: copying
@copying
Up to the release 1.1.2 (February 2017) the copyright was held by
the institutions that hosted the work as follows:
Copyright 2006-2007, Board of Trustees of Michigan State University,
Copyright 2008-2012, Board of Trustees of Columbia University in the
city of New York.
Copyright 2013, Brookhaven National Laboratory (Copyright holder
indicated in each source file).
@end copying
@c Part 2: title
@titlepage
@title PDFgui user guide
@subtitle 2.0 release
@subtitle @ReleaseDate{}
@author C. L. Farrow, P. Juhás, J. W. Liu, D. Bryndin, E. S. Božin,
@author J. Bloch, Th. Proffen, and S. J. L. Billinge
@page
@vskip 0pt plus 1filll
@c @insertcopying
@c HTML needs node to make index link, but PDF format does not like it.
@ifhtml
@node acknowledgments
@end ifhtml
@heading Acknowledgments
@cindex acknowledgments
@include acknowledgements.texinfo
@page
@vskip 0pt plus 1filll
@majorheading Preface
@heading Using PDFgui and PDFfit2
@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::
* Quick start::
* Examples and tutorials::
* Extras::
* PDFgui reference sheets::
* Index::
@end menu
@end ifhtml
@page
@vskip 0pt plus 1filll
@node Introduction, PDFfit2, Top
@chapter Introduction
@cindex introduction
PDFgui is a graphical interface built on the PDFfit2 engine, which is a program
and programming library for real-space refinement of crystal structures based
on the atomic pair distribution function (PDF) method. PDFgui organizes fits
and simplifies many data analysis tasks, such as configuring and plotting
multiple fits. PDFfit2 is capable of fitting a theoretical three dimensional
structure to atomic pair distribution function data and is ideal for nanoscale
investigations. The fit system accounts for lattice constants, atomic positions
and anisotropic atomic displacement parameters, correlated atomic motion, and
experimental factors that may affect the data. The atomic positions and thermal
coefficients can be constrained to follow symmetry requirements of an arbitrary
space group. The PDFfit2 engine is written in C++ and accessible via Python,
allowing it to inter-operate with other Python programs.
@menu
* PDFfit2::
* PDFgui::
* Availability::
* Installation::
* What is new::
* Community::
@end menu
@node PDFfit2, PDFgui, Introduction, Introduction
@section PDFfit2
@cindex PDFfit2
PDFfit2 is a major upgrade to PDFfit, and inherits many of its
features. PDFfit is capable of fitting a theoretical three-dimensional
structure to an experimentally determined PDF. It can simultaneously
fit multiple structures, accounting for different structural phases
in a material. PDFfit has a constraint system that allows expressing
structure variables as simple functions of fitted parameters. PDFfit
structure variables include lattice constants, data and phase scale
factors, atomic site occupation, anisotropic atomic displacement
parameters (ADPs), and atomic vibrational correlations. PDFfit has a built-in
FORTRAN-style command language that understands simple FOR loops and
some built in arithmetic functions.
The original PDFfit was written in FORTRAN-77, which imposes some
limitations on the program. For example, it uses fixed-size arrays
for internal storage. This precludes the analysis of structures with
large cells without modifying the code. Though the constraint system
is powerful, it requires that a constraint equation be accompanied
by its first derivative. This places the burden of determining the
derivatives on the user, which can introduce errors that lead to
instability in the convergence. Furthermore, the code is monolithic,
not easily extensible and hard to integrate with external programs.
The primary focus of PDFfit2 development was to remedy the limitations of
PDFfit while extending its functionality. The old PDFfit engine has been
completely rewritten in C++, and many bugs have been fixed. The new engine
uses dynamic memory allocation so that the size of the structure or extent
of the fit-range of the PDF is limited only by the physical memory available.
The constraint system has also been upgraded. The program @i{automatically}
computes the analytical derivatives of the constraints that are required by
the minimization routine. This simplifies user input and reduces the
possibility of errors. In addition, new fitting parameters for handling
dynamic atomic correlations and experimental resolution have been introduced
as well.
Instead of rewriting the PDFfit command interpreter, which is used
to define the fitting problem and to control and run the refinement,
its functions are carried out using the Python language
(@url{https://www.python.org}). Python is a powerful, cross-platform,
open-source interpreted programming language (i.e., it does not need
to be compiled to run, similar to scripting) that emphasizes
object-oriented and modular design. PDFfit2 scripts written in
Python syntax take the place of PDFfit macros and the Python
interpreter can handle everything that the old interpreter could,
and more. Using Python as an interpreter allows PDFfit2 to be
combined with and enhanced by other Python libraries. We make use
of this capability with PDFgui as described below.
@c @node NODE-NAME, NEXT, PREVIOUS, UP
@node PDFgui, Availability, PDFfit2, Introduction
@section PDFgui
@cindex PDFgui
The PDFfit2 engine can be used either directly from the Python command line, or
as part of larger and more complex software applications. The first application
built on PDFfit2 is PDFgui, a graphical environment for PDF fitting.
@subsection Design principles
PDFgui has been designed to provide users with an easy-to-use yet powerful
interface for fitting structure models to PDF data. It makes use of an
object-oriented architecture, which makes it highly extensible and
maintainable. This allows for powerful usability features such as real-time
plotting. PDFgui has been designed with multitasking in mind. It is
multi-threaded so that the work being done by the PDFfit2 engine does not
interfere with the tasks of the user interface.
PDFgui is written in the Python programming language. Python features a relaxed
and friendly syntax, supports ``write once, run anywhere'' portability, and has
extensive libraries and modules for virtually every task. Software codes
written in a variety of programming languages can be bound into Python, which
allows them to be used together. Python is becoming a popular choice in the
scientific computation community.
PDFgui's interface is built using wxPython (@url{https://www.wxpython.org}), the
Python package for wxWidgets, a mature cross-platform GUI library. Graphical
applications written in wxPython provide a look and feel native to the platform
on which they are run. PDFgui is designed to run on Windows, Mac OS, Linux,
and all major Unix systems.
@subsection Capabilities
PDFgui contains all of the functionality of PDFfit2 along with additional
enhancements for usability. Mundane tasks are handled by the program and
difficult tasks are made simple. PDFgui can manage multiple fits at once. Each
fit can have multiple experimental data sets and structure models. Fits in a
sequence can call upon other fits for their starting parameters, and configured
fits can be queued to run while the user is away. All the initial, final, and
intermediate data are stored in a platform independent project file that can be
loaded on any computer. All management tasks, such as fit creation,
configuration, modification, and visualization, can be done through the
graphical interface.
PDFgui supports space group operations. Users can define an asymmetric unit
and let PDFgui expand it to a full cell with all symmetry related positions.
PDFgui can also generate symmetry constraints for atom positions and atomic
ADPs. Users just need to specify the space group, and the program will identify
equivalent sites and generate constraint equations for their coordinates and
temperature factors to keep the structure consistent with the symmetry
requirements. This can be done either for all atoms in the structure or for an
arbitrary subset - for example when it is known that only a certain species
show a local distortion. The code for space group definitions was provided by
the Python Macromolecular Library (mmLib,
@url{http://pymmlib.sourceforge.net}). This was extened to include
non-standard space groups using the Computational Crystallography Toolbox
(cctbx, @uref{https://cctbx.github.io}). PDFgui also supports supercell
expansion of a normal unit cell.
PDFgui uses the matplotlib (@url{https://matplotlib.org}) Python
package for 2D plotting of data and results. Matplotlib has a friendly
interface so the user can quickly and easily view the results of a fitting.
PDFgui lets users plot data from a series of fits and plot it against selected
meta-data (temperature, doping, etc.), plot the results of several fits in the
same window, plot the PDF in real time as the fitting is running, plot the
parameters or variables in real time as the refinement evolves, and save plots
in common image formats or export the data to a text file. PDFgui can be
configured to use one of many structure visualization packages, such as AtomEye
(@url{http://li.mit.edu/A/Graphics/A/}) or PyMOL
(@url{https://www.pymol.org}).
PDFgui supports built-in macros for advanced fits. For a set of experimental
data from one system at different temperatures or doping levels, PDFgui can
expand a template fit to a series of related fits. Another PDFgui macro makes
it easy to set up boxcar fits, where the same model is fit over different
r-ranges of the PDF data.
@c @node NODE-NAME, NEXT, PREVIOUS, UP
@node Availability, Installation, PDFgui, Introduction
@section Availability
@cindex availability
PDFfit2 and PDFgui are open source and distributed under a BSD license. They
run on Windows, Mac OS, Linux, and all major Unix systems. The source code is
freely available. For more information please contact Professor Simon Billinge
(@email{sb2896@@columbia.edu}) or consult the web-page
@url{https://www.diffpy.org}. News of updates and releases will be posted at
this website and on the diffpy-users group at
@url{https://groups.google.com/d/forum/diffpy-users}.
@c @node NODE-NAME, NEXT, PREVIOUS, UP
@node Installation, What is new, Availability, Introduction
@section Installation
@cindex installation
PDFgui is included as a part of DiffPy, a suite of Python and C++
libraries for structure analysis from diffraction data. For more
information about DiffPy products visit the project homepage at
@url{https://www.diffpy.org}.
@menu
* Installation for Anaconda Python::
* Configuration of structure viewer::
* Installation from sources::
@end menu
@node Installation for Anaconda Python
@subsection Installation for Anaconda Python
As of version 1.1 PDFgui is distributed as a pre-built package for
@url{https://www.anaconda.com, Anaconda Python}. This method makes it
easier to distribute software updates and also results in the same
installation procedure on all supported platforms.
To install PDFgui, download and install Anaconda for Python 2.7 from
@url{https://www.anaconda.com/download}. When ready open a terminal
application (or @i{Anaconda Command Prompt} on Windows) and use the
@command{conda} package manager to install PDFgui from the ``diffpy''
channel of Anaconda packages
@example
conda config --add channels diffpy
conda install diffpy.pdfgui
@end example
The first command instructs Anaconda system to always check the
``diffpy'' channel for any new software. Such configuration
allows to obtain PDFgui updates using
@example
conda update diffpy.pdfgui
@end example
It is however not strictly necessary to make the ``diffpy''
channel permanent. The same effect can be accomplished by adding the
@w{@option{--channel=diffpy}} option to either of
@w{@command{conda install}} or @w{@command{conda update}} commands.
After installation is complete PDFgui can be started from a terminal by
entering @command{pdfgui} command or on Windows by using the DiffPy
start menu. PDFgui can be also started from the ``Launcher'' program
that is included with Anaconda.
@node Configuration of structure viewer
@subsection Configuration of structure viewer
@cindex visualization setup
PDFgui can visualize 3D structures by displaying them with an external
visualization program. The visualization program needs to
be specified together with a suitable structure format in the
``@w{Edit →} Preferences'' menu in PDFgui. The structure plotting
feature has been tested with the following programs:
@table @emph
@item AtomEye
AtomEye structure viewer, XCFG format @*
@url{http://li.mit.edu/A/Graphics/A/}
@item PyMOL
PyMOL structure viewer, PDB format @*
@url{https://www.pymol.org}
@end table
@noindent
@b{A note for AtomEye users:}
@cindex AtomEye viewer
AtomEye requires its standard output is connected to a terminal.
On Unix this happens when @command{pdfgui} is started from a terminal.
However if you prefer to start PDFgui using a desktop shortcut or via
``Run Application'' dialog of the window manager, you need to put the
following information to the ``Edit → Preferences'' menu of PDFgui.
@example
Structure viewer executable: xterm
Argument string: -iconic -e ATOMEYE %s
Structure format: xcfg
@end example
@noindent
In the above, ATOMEYE is the path to the ATOMEYE executable.
For Cygwin users,
the workaround is to launch the executable from a batch file.
Batch files can only run in a command window on Windows and so
AtomEye's requirements would be for sure satisfied.
In addition the batch file can be used to adjust environment
variables:
@example
atomeye.bat
------------------------------------------------------------------------
set DISPLAY=localhost:0
set PATH=C:\cygwin\bin;C:\cygwin\usr\X11R6\bin;C:\ATOMEYE_DIR;%PATH%
start A.exe %*
------------------------------------------------------------------------
@end example
@noindent
Here @t{ATOMEYE_DIR} needs to be replaced with a proper path. Make sure
that the X-server application included with Cygwin is started.
@node Installation from sources
@subsection Installation from sources
@cindex Git repository
@cindex development
PDFgui sources are available in a public
@url{https://git-scm.com, Git} repository at
@url{https://github.com/diffpy/diffpy.pdfgui}.
Feel free to fork this project on GitHub and contribute. To
use the latest development version clone the Git repository
to your computer and install it in a development mode so that sources
are used directly rather than copied to a system location. It is also
recommended to uninstall the Anaconda package for PDFgui, so that
there is no confusion as to what version is the active one.
Here are the shell commands that would do it:
@example
# Install PDFgui together with software dependencies.
conda install --channel=diffpy diffpy.pdfgui
# Make room for the version from sources. Keep dependencies installed.
conda remove diffpy.pdfgui
# Obtain a clone of the PDFgui Git repository.
git clone https://github.com/diffpy/diffpy.pdfgui.git
# Install PDFgui sources in a development mode.
cd diffpy.pdfgui
python setup.py develop
@end example
To verify that PDFgui is indeed loaded from the local source
repository run
@example
python -m pydoc diffpy.pdfgui
@end example
and check the path displayed in the FILE section. The application
integrity can be verified by executing all builtin tests using
@example
python -m diffpy.pdfgui.tests.rundeps
@end example
Use @command{git pull} to bring your source directory into sync
with the latest updates in the main repository. It is recommend
to afterwards do @command{`setup.py develop} again to refresh
the version metadata associated with the program:
@example
git pull
python setup.py develop
@end example
To revert PDFgui installation from the source-code installation
back to the pre-built Anaconda package do
@example
pip uninstall diffpy.pdfgui
conda install --channel=diffpy diffpy.pdfgui
@end example
@c @node NODE-NAME, NEXT, PREVIOUS, UP
@node What is new
@section What is new
@cindex versions
@cindex whatisnew
@subheading Version 1.1, released March 2016
Improvements and modifications since the last major release
1.0-r3067 from April 2009.
@table @emph
@item Anaconda installer
PDFgui is now distributed as a pre-built package for Anaconda Python.
The program is available for all platforms supported by Anaconda, i.e.,
for 32 and 64-bit Linux, Mac OS X, and for 32 and 64-bit Windows.
@item upgrade for recent GUI libraries
Source codes were updated to work with WX GUI toolkit 2.9 or later.
Fixed blacked-out text fields on Mac OS X. Fixed missing toolbar
in plot-windows on Mac OS X.
@item select atoms menu
Added ``Select Atoms'' context menu to the Phase Configuration and Phase
Constraints panels. This selects atom rows by a range of indices
or by atom type. Added keyboard shortcut @kbd{/} for activating the
atom-selection dialog.
@item small enhancements
Fixed problems with @i{r}-grid interpolation near data boundaries. Allow
use of CIF-defined space groups for symmetry constraints. Use consistent
numbering for parameters created by symmetry constraints. Improved
export data tool in plot windows to group @i{y}-arrays that are on
the same @i{x} grid. Enhanced supercell expansion to also adjust
the coordinate constraints.
@item project moved to GitHub
PDFgui source repository was converted from subversion to a Git repository at
@url{https://github.com/diffpy/diffpy.pdfgui}. Project now uses Git tags
to define software release and version data.
@item Unicode support
Allow accented characters in project filenames and in folder paths
where located. Allow accented characters for naming the fit tree
items. Note that such projects are unlikely to work with older
versions of PDFgui. Fix failure to exit when there is some
uncaught error in the at-exit cleanup functions.
@item PDFgui tests
PDFgui installation now includes built-in tests. Added facility to
test PDFgui and all its DiffPy components. Implemented automated
testing and generation of test coverage reports when sources on
GitHub change.
@item bug fixes
Quite a few. Consult the code history at
@url{https://github.com/diffpy/diffpy.pdfgui/commits}.
@end table
@subheading Version 1.0, released April 2009
This section describes improvements and modifications since the
last beta-release 1.0b.1792 from December 2007.
@table @emph
@item updates and installation
PDFgui can be installed or updated
with a simple run of the easy_install script. easy_install
checks our online code repository for any newer versions and takes
care of their download and installation. It can be also used to
add future DiffPy components as they become available. This should
work for Linux, Mac and Windows.
@item Windows installer
The updated Windows package includes full installation of
Python 2.5 and script for code updates. PDFgui
can be installed under normal Python2.5 tree if it has the
easy_install script.
@item particle shape correction stored with phase
The previous release of PDFgui had
spherical shape correction factors stored with PDF dataset. The
new layout is more logical and allows multi-phase refinements with
separate shape corrections.
@item step shape factor
Defined new shape factor that cuts off the
simulated PDF at user defined r-limit.
@item cumulative Rw
Implemented calculation of cumulative Rw
and option to show it in PDFgui plot window.
@item project post-processing
Implemented new module
@samp{tui} (text user interface) for simple access to the data
in PDFgui project files. The @samp{tui} module can be used
in easy-to-understand Python scripts for arbitrary data extraction
or conversion. It should be useful for project files with large
temperature or compositional series of PDF refinements.
@item structure visualization
PDFgui can now show structures with any external structure viewer,
that accepts structure file as a command-line argument.
@item space group representations
Added 249 space group
representations in non-standard settings. The new representations
were generated using the
@uref{https://cctbx.github.io,cctbx library} and helpful
hints from Ralf W. Grosse-Kunstleve.
@item symmetry constraints
Fixed issues with generation of
symmetry requirements for the ADP tensors.
@item default ADP tensors
PDF contributions are not counted for atoms that have
ADP tensors @i{Uij} equal zero. Atoms are now inserted with
a non-zero @i{Uij} matrix. Added warning when a phase
loaded from file has atoms with zero ADPs.
@item temperature series macro
The temperature series macro was broken for datasets at equal temperature
or when temperature contained decimal point. Improved file
and temperature sorting in the temperature series dialog.
@item journal panel
Fixed shortcut key handling and font size issues.
@item startup option @option{--db-pdb}
The new command-line option starts Python debugger on
PDFgui crash instead of displaying error report dialog.
@item grid interpolation
Fixed problems with r-grid interpolation appearing due to round-off errors.
@item data load on Windows
Windows version could not read PDF datasets with NaN (not-a-number)
values in the dGr column, because NaN is not supported by the Windows
C-library. Added check for NaN-s before converting to float.
@end table
@c @node NODE-NAME, NEXT, PREVIOUS, UP
@node Community, Quick start, Installation, Introduction
@section Community
@cindex Community
@cindex mail-list
@cindex user groups
There are two Google groups for support and development of PDFgui and other
DiffPy software. Visit the links below for message archives or instructions on
subscription and posting.
@table @emph
@item @b{diffpy-users} @url{https://groups.google.com/d/forum/diffpy-users}
Help on usage of PDFgui, PDFfit2 and other DiffPy packages. This group should
become a knowledge base of PDFgui user tips, tricks and troubleshooting. Feel
free to ask your question here.
@item @b{diffpy-dev} @url{https://groups.google.com/d/forum/diffpy-dev}
For discussions about development and changes of PDFgui, PDFfit2 and DiffPy
library in general.
@end table
@page
@vskip 0pt plus 1filll
@c @node NODE-NAME, NEXT, PREVIOUS, UP
@node Quick start, PDFgui layout, Installation, Top
@chapter Quick start
@cindex quick start
In this chapter the PDFgui layout is briefly described, followed by a simple
tutorial example, spanning the GUI functionality and aimed at novice users.
Users familiar with the basics can proceed to @ref{Examples and tutorials}, or
use @ref{PDFgui reference sheets}. All the files used in examples are
available in the source distribution or can be downloaded from the DiffPy
website.
@menu
* PDFgui layout::
* Simple fit::
@end menu
@node PDFgui layout, Simple fit, Quick start, Quick start
@section PDFgui layout
@cindex PDFgui layout
Once PDFgui is invoked, a PDFgui window comes up. Its layout consists of a
``Menu Bar'', a ``Tool Bar'', and a set of four panes. The menu bar contains
drop-down menus that provide various aspects of PDFgui functionality. The tool
bar features icons for commonly used operations: creating a new project,
opening an existing project, saving a project, executing a refinement or
calculation, stopping a refinement or calculation, and making a quick plot. The
four panes consist of the ``Fit Tree'', ``Plot Control'', the``Current Action''
pane, and the ``PDFfit2 Output'' panel. These are all shown in @ref{fig2-01}.
The fit tree is used in setting up a fit protocol. The plot control serves the
user's needs for graphically displaying the fits, as well as various
fit-related parameters. The content of the current action panel changes as the
refinement is being set up. It is a functional panel through which the user
configures the fit attributes, sets the fit constraints, reviews the fit
settings, displays fitting results, and also carries out other setup steps. The
progress of the PDFfit2 refinement engine is displayed in the PDFfit2 output
panel. All panels except the current action panel are dockable windows that can
be dragged across the screen, resized and arranged to accommodate the
individual visual needs of the user. The window layout can also be controlled
via the ``View'' drop-down menu on the menu bar. An important part of the PDFgui
operativity is also conveniently available through mouse operations such as
select and right-click.
@c @node NODE-NAME, NEXT, PREVIOUS, UP
@node Simple fit, Symmetry expansion, PDFgui layout, Quick start
@section Creating a simple fit using a preexisting structure file
@cindex fit configuration
@cindex refinement configuration
The purpose of this example is to familiarize the novice user with the PDFgui
basics. The goal is to create a simple fit of Ni PDF from a preexisting
structure file, associate a dataset with the refinement, configure and execute
a refinement, and display the result. Files to be used in this exercise are
@i{Ni.stru} and @i{Ni-xray.gr} (found in the tutorial directory). To start,
invoke PDFgui by clicking on the icon on your desktop, selecting the program
from your system's program menu, or by typing @command{pdfgui} in a terminal window.
First a new fit needs to be established. In the fit tree right-click the mouse
button, and select @b{New Fit}. This will generate a new fit called ``Fit 1''
in the fit tree. The name of the fit is highlighted and editable, so you need
only to start typing to give the fit a new name. The current action panel will
display the pages that will hold the fit and the results output. Note that the
same action could be achieved by selecting the @b{New Fit} option from the
``Fits'' drop-down menu on the menu bar.
The next step in populating the fit tree is to load a structural model. First,
select the fit icon in the fit tree pane. Then, right-click the mouse, invoking a
drop-down menu. Select @b{Insert Phase}, which will modify the current action
panel. The same action could be performed from the ``Phases'' drop-down menu on
the menu bar by selecting @b{New Phase}. In the current action panel options are
offered to load a structure from a file or to generate it from scratch. In this
exercise a preexisting structure file @i{Ni.stru} is to be loaded.
@float Figure,fig2-01
@ScreenShot{images/fig2-01}
@caption{PDFgui window with fit tree and Plot Control panels to the left and
current action panel to the right. The fit tree panel features the current fit
and the loaded Ni structure which is selected. The current action panel displays
phase configuration within the ``Configure'' tab.}
@end float
@ref{fig2-01} shows the PDFgui appearance at this stage of the exercise. The
current action panel has three tabs, ``Configure'', ``Constraints'', and
``Results'' that could be selected using mouse. These will be returned to
later. The ``Configure'' panel displays configuration information from the
structure file. The top portion contains lattice parameters, phase scale factor,
and a set of parameters intended to be used to account for correlated atomic
motion effects that typically sharpen the nearest neighbor PDF peak. These are
@i{delta1}, @i{delta2}, @i{sratio}, and @i{rcut}. The @i{spdiameter} and
@i{stepcut} parameters include scatterer size effects in the PDF. These
parameters will be described later. The bottom part of the panel contains
standard unit cell content related information such as atomic species, their
fractional coordinates, anisotropic ADPs, and site occupancies.
The next step is to load an experimental data set to be fit. Selected the fit
and right-click to bring up the context menu. From the menu choose @b{Insert
Data Set}. The same action could be performed through the ``Data'' menu on the
menu bar. The current action panel changes accordingly, giving an option for a
data set to be loaded from a file. In this exercise Ni PDF data obtained using
synchrotron x-ray radiation collected at 6-ID-D at the Advanced Photon Source
is used. This is contained in a file @i{Ni-xray.gr}, which is to be loaded.
Note that among the exercise files there is also a file @i{Ni-neutron.gr},
obtained using neutron radiation at the GPPD diffractometer at the IPNS
facility at the Argonne National Laboratory. Both x-ray and neutron datasets
were collected at 300 K.
@float Figure,fig2-02
@ScreenShot{images/fig2-02}
@caption{Appearance of a PDFgui window after a PDF dataset is loaded. The Fit
Tree panel features the current fit, loaded Ni structure, and loaded Ni PDF
dataset, G(r), which is selected. The current action panel displays data set
configuration within the ``Configure'' tab.}
@end float
@ref{fig2-02} shows the PDFgui appearance at this stage of the exercise. The
``Configure'' panel displays configuration information from the data file. It
should be noted that depending on the software used to prepare the experimental
PDF from the raw data, the file may (or may not) contain meta-data reflecting
the experimental conditions and configuration. For example, software PDFgetX2
and PDFgetN, which can be used to prepare PDFs from x-ray and neutron total
scattering experiments respectively, supply meta-data in the header of the data
file. PDFgui reads this information and fills the appropriate fields in the
data set configuration panel. Caution should be exercised by the user to
verify that these data indeed correspond to the experimental conditions. In the
present example, x-ray radiation is used, and so the x-ray selection is turned
on for the scatterer type. The data range, fit range, data scale factor,
maximum Q value used in Fourier transform to obtain the experimental PDF and
the experiment specific parameters are displayed. Parameters describing
experimental resolution effects, Qdamp and Qbroad, and experimental conditions,
such as temperature and doping (used for bookkeeping and for parametric plots)
are also shown. If no meta-data are present in a data file, this information
should be supplied by the user. Note also that the changes occurred at this
stage in the plot control panel, allowing user to plot the data. This is
achieved by selecting @i{r} in the X-choice box and @i{Gobs} (the observed
G(r)) in the Y-list box and then pressing the ``Plot'' button. Since no
fitting has occurred so far, an attempt to plot calculated PDF profile or a
difference yields a blank plot. The data can also be displayed by clicking the
rightmost ``quick-plot'' button in the tool bar.
@float Figure,fig2-03
@ScreenShot{images/fig2-03}
@caption{Adjusting data set related configuration.}
@end float
Having specified the initial structure to be refined, and the data set to be
fit, we proceed to the refinement setup. First we adjust the initial parameters
and variables, and set up the constraints. The adjustments and constraint setup
are done on both the experimental data and the refined structure levels,
toggling between the corresponding ``Configure'' and ``Constraints'' tabs. In
the present example the data related setup will be done first.
Click on the data set node (@i{Ni-xray.gr}) in the fit tree. In @ref{fig2-03}
the ``Data Set Configuration'' panel is shown. We will adjust the fitting
range, as well as other parameters that reflect the experimental conditions.
Since there is no physical information in the region of @i{r} below the nearest
neighbor PDF peak position (as seen in the plot), and since this region is
often affected by noise and experimental artifacts, it is wise to exclude it
from fitting. We therefore set the value of the lower boundary of the fitting
range to 1.7. (Note that the units are Angstroms). In addition, we set
@i{Qdamp} parameter to a more realistic starting value of 0.08. This is an
instrument-dependent parameter is typically obtained through a conventional
calibration process at each PDF experiment using a standard sample such as Ni
or Si. Next, we select the ``Constraints'' tab, and type @i{@@1} into the
``Scale Factor'' edit box. This will assign refinement parameter 1 to the data
scale factor. Note that this is the syntax used for assigning the refinement
parameters in PDFfit2 engine. Similarly, assign parameter 2 to @i{Qdamp} by
inserting @i{@@2} into the appropriate edit box. This is illustrated in Figure
@ref{fig2-04}.
@float Figure,fig2-04
@ScreenShot{images/fig2-04}
@caption{Setting up the refinement parameters and constraints.}
@end float
Further, we set constraints related to the structural model, by selecting the
phase node (@i{Ni.stru}) on the fit tree, adjusting the initial parameter
values if necessary (not done here), and proceeding to the ``Constraints'' tab.
We note that the phase configuration was performed automatically when the
structure file was loaded. We assign the refinement parameter 3 to all three
lattice constants, a, b, and c, reflecting the fact that the structure is
cubic. Isotropic ADPs are assigned to all Ni atoms in the refined cell as
refinement parameter 4. This can conveniently be done by highlighting the
``u11'', ``u22'' and ``u33'' cells for all four atoms, and typing @i{@@4} and
then pressing ``Enter'' on your keyboard. The outcome is shown in Figure
@ref{fig2-05}.
@float Figure,fig2-05
@ScreenShot{images/fig2-05}
@caption{Setting up the refinement parameters and constraints.}
@end float
Note that constrained parameters cannot be adjusted on the ``Configuration''
panel since they are no longer independent. It should also be noted that as a
part of the PDFfit2 syntax a refinement parameter can also be defined as a math
expression @i{f(@@n1,@@n2,@@n3,...)} where @i{@@n1} stands for fitted
parameter, and @i{n1}, @i{n2},... are arbitrary positive integers enumerating
the parameters. This allows simple linking of related variables. For example,
since cell lengths a, b, and c are all expressed as @i{@@3}, the refined
structure will remain cubic. Also note that the enumeration of the parameters
can be arbitrary, enumeration does not have to follow any particular order. The
quantities within a fit that are enumerated with the same number will be
assigned the same parameter, hence caution should be exercised to avoid
unintentional assignment of the same parameter to physically different
quantities. Automatic parameter assignment (see further below) is done in such
a way as to disallow for such situations to happen. If assignment is done in
part manually, in particular for complex setups, it is recommended to verify
that the parameter assignment is done correctly.
@float Figure,fig2-06
@ScreenShot{images/fig2-06}
@caption{Reviewing the fit parameters and conditions.}
@end float
The setup for the present example is now completed. By selecting the fit node
on the fit tree the current action window shows ``Parameters'' tab, which
displays the used refinement parameters for review, @ref{fig2-06}. It shows
the initial values, and allows for updates and for refinement parameters to be
released or fixed depending on whether the corresponding ``Fixed'' box is
unchecked or checked, respectively. The ``Refined'' column, which is currently
empty, will be populated with the refined values of the parameters with the fit
completes. If the initial parameter values are to be changed, using ``Apply
parameters'' button will update the values of the parameters on all relevant
``Configuration'' panels. The refinement is executed by clicking the ``gear''
icon on the tool bar. The refinement can be stopped prematurely by clicking on
the ``stop'' icon on the tool bar. During the refinement the refinement
progress will be directly reported in the PDFfit2 Output panel. This is
illustrated in @ref{fig2-07}.
@float Figure,fig2-07
@ScreenShot{images/fig2-07}
@caption{While the refinement is running, the refinement progress is
displayed in the PDFfit2 Output panel.}
@end float
After the fitting is completed, the fit summary is provided in the ``Results''
tab of the current action panel associated with the fit node. Similarly, if
the ``Results'' tab is displayed when @i{Ni.stru} or @i{Ni-xray.gr} are
selected, values of all corresponding refined parameters for the converged
model are displayed.
If the fit results are acceptable, one or more refined values could be copied
to become new initial parameters for possible further refinement, where
appropriate. This is be done in the ``Parameters'' tab of the fit by
highlighting refined parameters to be copied, right-clicking, and and selecting
@b{Copy Refined To Initial}. This is illustrated in @ref{fig2-08}. Note that
you loose the original starting values when copying values in this way, which
may make it difficult to reproduce the fit.
@float Figure,fig2-08
@ScreenShot{images/fig2-08}
@caption{Updating the set of initial values of refined parameters.}
@end float
The fit can be displayed graphically by clicking at the ``quick plot'' icon on
the tool bar. Alternatively, desired items to be displayed can be selected from
the plot control and plotted on the screen. Depending on whether the structure
or the data are selected on the fit tree, either refined structural parameters
or the experiment related parameters and fit could be plotted. An example of
the fit display is shown in @ref{fig2-09}, and a selected parameter plot vs
iteration step in @ref{fig2-10}. If the plotting window remains open while the
fitting is in progress, the content will be updated after each fit iteration.
@float Figure,fig2-09
@ScreenShot{images/fig2-09}
@caption{An example of PDFgui plotting capabilities: displaying a fit.}
@end float
@float Figure,fig2-10
@ScreenShot{images/fig2-10}
@caption{An example of PDFgui plotting capabilities: displaying a parameter.}
@end float
PDFgui is furnished with ``Journal'' capability, which can be found under the
``View'' menu, and represents a convenient way to archive project-related
notes, as illustrated in @ref{fig2-11}. These notes can be exported as a text
file, or saved along with the entire project for future reference.
@float Figure,fig2-11
@ScreenShot{images/fig2-11}
@caption{Using ``Journal'' feature can be a convenient way for taking notes.}
@end float
The project can be saved at any stage in its present configuration through
choice of @b{Save Project as} or @b{Save Project} as appropriate from the
``File'' drop-down menu. The PDFgui project file has ``ddp'' extension. In
addition to saving a project, various parts of the project, both structure
related and data related, can be exported to external files by making an
appropriate selection from the ``Phases'' and ``Data'' drop-down menus. The
phases (starting or converged) can be saved in one of many formats. The model
PDF profile can be exported through ``Data'' menu and will be saved as a
five-column ``.fgr'' file. The first four columns are @i{r}, @i{G(r)}, @i{dr},
and @i{dG(r)}, and the fifth column is the difference curve between the data
and the model. Note that the model PDF and the difference are only calculated
within the user-specified fitting range.
@page
@vskip 0pt plus 1filll
@c @node NODE-NAME, NEXT, PREVIOUS, UP
@node Examples and tutorials, Symmetry expansion, Simple fit, Top
@chapter Examples and tutorials
@cindex examples
@cindex tutorials
In this chapter we present series of examples and tutorials aimed at users
already comfortable with the GUI, to provide training in advanced GUI features
designed for most common modeling situations, such as building the structure
from scratch, calculating the PDF based on a given structure, linking fits, and
creating and executing a series of fits on a sequence of data sets.
@c @node NODE-NAME, NEXT, PREVIOUS, UP
@menu
* Symmetry expansion::
* Calculating PDF::
* Sequential fitting::
* Nanoparticle structure::
@end menu
@node Symmetry expansion, Calculating PDF, Examples and tutorials, Examples and tutorials
@section Building structure model using crystal symmetry
@cindex create new structure
@cindex symmetry expansion
@c @b{NB: this part either can be kept or replaced, I felt it's kind of useful
@c to have it to define the purpose of the expansion tool. Please read through
@c and decide if needed, or erase it.--
@c It should be noted that PDFfit2 operates within the P1 symmetry framework,
@c and extended unit is traditionally used for refinement with the constraints
@c explicitly set, since PDF is used to obtain structure beyond crystallography.
@c Note that the expansion tool is provided in PDFgui for the convenience of the
@c user, and that the space group information serves the purpose of building the
@c constraints within the P1 framework, rather than maintaining the symmetry.
@c Once the constraints are built the symmetry expansion tool finished its job
@c and its services (and more importantly information typed in) are no longer
@c available to the fitting program. The symmetry can be (and frequently is)
@c broken by the user, hopefully intentionally.}
The purpose of this example is to demonstrate to the user the symmetry
expansion capabilities of PDFgui. The goal is again to create a simple fit of
Ni PDF, but this time from scratch rather than from a preexisting structure
file. The focus will be on the symmetry expansion of the structure, and the
steps that are described earlier in @ref{Simple fit} are left for the user to
recreate. File to be used in this exercise is @i{Ni-xray.gr}. To start, invoke
PDFgui.
To begin, a new fit again needs to be established by right-clicking the mouse
button on the fit tree pane, and selecting @b{New Fit}. This will generate a
new fit called Fit 1 as in the previous example. The next step in populating
the fitting tree is to introduce a structural model. This time a new phase will
be added and the model built up from scratch. Select the fit icon in the Fit
Tree pane. Then right-click the mouse and select @b{Insert Phase}, which will
modify the current action panel. In the current action panel options are
offered to load a structure from a file or to generate it from scratch. Select
``New'' to build up structure from scratch. The Fit Tree will be populated
with a new item ``New Phase''. Rename this phase to ``Ni fcc''. The current
action panel now displays default phase configuration with ``dummy'' values and
no atoms. Edit the lattice parameters and set them to reflect the symmetry, in
this case set the lengths to 3.52 Angstroms and all the angles to 90 degrees.
Pressing ``Tab'' on the keyboard will take you from one form-field to the next.
To introduce new atoms right-click with your mouse onto @i{elem} tab in the
Phase Constraints grid, and select desired number of atoms in the asymmetric
unit via the dialog box that pops up. For the Ni case, select one row only. A
new row will then show up in the table and the name of the element will be
highlighted. Type in @i{Ni} for the element name. It is important that the
element name is typed in correctly, as this is further used to search a