Skip to content

Commit 9a3e01b

Browse files
chiahaoliuchiahaoliu
committed
DOC: add pdfgetx v2.1.0 user manual to source
1 parent 14b2dad commit 9a3e01b

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

50 files changed

+20962
-5
lines changed

Diff for: ‎products/pdfgetx.rst

+5-5
Original file line numberDiff line numberDiff line change
@@ -70,11 +70,11 @@ Documentation
7070
Version 2.1.0 - latest
7171
----------------------
7272

73-
* `installation instructions <../doc/pdfgetx/2.0.0/install.html>`__
74-
* `user manual <../doc/pdfgetx/2.0.0/index.html>`__,
75-
`printable manual <../doc/pdfgetx/2.0.0/PDFgetXN3_manual.pdf>`__
76-
* `tutorial files <../doc/pdfgetx/2.0.0/pdfgetxn3-examples.zip>`__
77-
* `release notes <../doc/pdfgetx/2.0.0/release.html>`__
73+
* `installation instructions <../doc/pdfgetx/2.1.0/install.html>`__
74+
* `user manual <../doc/pdfgetx/2.1.0/index.html>`__,
75+
`printable manual <../doc/pdfgetx/2.1.0/PDFgetXNS3_manual.pdf>`__
76+
* `tutorial files <../doc/pdfgetx/2.1.0/pdfgetxn3-examples.zip>`__
77+
* `release notes <../doc/pdfgetx/2.1.0/release.html>`__
7878

7979
Version 2.0.0
8080
-------------

Diff for: ‎static_root/doc/pdfgetx/2.1.0/PDFgetXNS3_manual.pdf

588 KB
Binary file not shown.

Diff for: ‎static_root/doc/pdfgetx/2.1.0/_images/nickelfqgr.png

69.8 KB
Loading

Diff for: ‎static_root/doc/pdfgetx/2.1.0/_images/nickelfqgrnoisy.png

69.7 KB
Loading

Diff for: ‎static_root/doc/pdfgetx/2.1.0/_images/tunenickelfqgr.png

85.9 KB
Loading

Diff for: ‎static_root/doc/pdfgetx/2.1.0/_images/tunenickelt4gr.png

77.6 KB
Loading

Diff for: ‎static_root/doc/pdfgetx/2.1.0/_images/twothetazerofit.svgz

80.5 KB
Binary file not shown.

Diff for: ‎static_root/doc/pdfgetx/2.1.0/_sources/files.rst.txt

+102
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
Files used in PDF extraction
2+
========================================================================
3+
4+
.. include:: abbreviations.txt
5+
.. _my-configfile:
6+
.. program:: pdfgetx3
7+
8+
Configuration file
9+
------------------------------------------------------------------------
10+
11+
Configuration files may define the PDF processing parameters.
12+
By default, the :program:`pdfgetx3` program attempts to read
13+
:file:`.pdfgetx3.cfg` file from the user HOME directory,
14+
then :file:`.pdfgetx3.cfg` and :file:`pdfgetx3.cfg` files
15+
from the current working directory.
16+
If configuration file has a different name, it needs to be specified
17+
with the :option:`-c, --config <-c>` option.
18+
The :program:`pdfgetn3` program works in the same way,
19+
except it checks for configuration files
20+
:file:`~/.pdfgetn3.cfg`, :file:`.pdfgetn3.cfg` and :file:`pdfgetn3.cfg`.
21+
22+
The easiest way of creating a configuration file is to generate
23+
a template content using the :option:`--createconfig` option as ::
24+
25+
pdfgetx3 --createconfig=test.cfg
26+
27+
and then change the generated test.cfg file in your favorite text
28+
editor. The configuration file follows a simple "varname=value" syntax,
29+
any lines starting with "#" are ignored as comments.
30+
31+
The configuration file has several sections marked as ``[SECTIONNAME]``.
32+
The ``[DEFAULT]`` section is mandatory and it contains the default
33+
global settings. Any other sections are optional and they are applied
34+
only when selected with the :option:`-s, --section <-s>` option on the
35+
command line. Thus ::
36+
37+
pdfgetx3 --config=test.cfg --section=nacl
38+
39+
would read the parameters from the ``[nacl]`` section after reading the
40+
defaults. Having several sections in the configuration
41+
file is useful when there are multiple measurements that share most of
42+
the parameters, but differ in a few of them, for example in chemical
43+
composition. The configuration file can then contain sections per each
44+
sample that define only the composition, while all other parameters are
45+
specified just once in the global DEFAULT section.
46+
47+
48+
Input files
49+
------------------------------------------------------------------------
50+
51+
PDFgetX3 and PDFgetN3 accept input powder diffraction data
52+
in the form of two-column text file,
53+
where the first column x is either the scattering angle
54+
|twotheta| in degrees, momentum transfer *Q* in inverse nanometers or *Q*
55+
in inverse ångströms. The second column y contains the corresponding
56+
scattered intensities normalized per unit solid angle. The actual type
57+
of the x-values is identified by the :confval:`dataformat` parameter.
58+
The input files may contain header with comments or metadata, and the
59+
actual data are read from the first long section of numerical values.
60+
61+
The input files are usually passed as command-line arguments to
62+
:program:`pdfgetx3` or :program:`pdfgetn3` programs and must be paths
63+
accessible from the current working directory.
64+
65+
Input files can be also defined by setting the :confval:`inputfile`
66+
value in the configuration file. The :option:`-d, --datapath <-d>`
67+
option can be then used to provide additional data directories to
68+
search for these inputs and for the :confval:`backgroundfile`.
69+
This is to support configuration files located in a different
70+
directory than the data.
71+
72+
When the :option:`--find <-f>` option is active, the pdfgetx3 arguments
73+
are understood as filename patterns and the input files are found
74+
in the current or specified directory.
75+
76+
77+
Output files
78+
------------------------------------------------------------------------
79+
80+
PDFgetX3 and PDFgetN3 can produce up to four different output data files:
81+
82+
* .iq -- |IQ|, the background-corrected
83+
intensities sampled on a regular *Q*-space grid in inverse ångströms,
84+
85+
* .sq -- |SQ|, the total scattering structure function,
86+
with intensities normalized by average scattering factors and
87+
corrected by a polynomial fit,
88+
89+
* .fq -- |FQ|, the reduced structure function equal to *Q*\ (|SQ| - 1),
90+
91+
* .gr -- |Gr|, the resultant PDF, where the first column is the
92+
separation *r* in ångströms and the second is the function *G* in
93+
Å\ :sup:`-2`.
94+
95+
You can specify what output files should be produced by setting the
96+
:confval:`outputtypes` parameter in the configuration file or by
97+
passing the :option:`-t, --outputtypes <-t>` on the command line.
98+
99+
The header of all output files contains the parameter values that were
100+
used in the calculation and thus it is by itself a valid configuration
101+
file. When passed as an argument to the :option:`--config <-c>` option,
102+
the PDFgetX3 will reproduce the previous calculation.

Diff for: ‎static_root/doc/pdfgetx/2.1.0/_sources/index.rst.txt

+38
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
.. PDFgetX3 documentation master file, created by
2+
sphinx-quickstart on Tue Sep 21 18:35:11 2010.
3+
You can adapt this file completely to your liking,
4+
but it should at least contain the root `toctree` directive.
5+
6+
########################################################################
7+
diffpy.pdfgetx
8+
########################################################################
9+
10+
User manual for PDFgetX3, PDFgetN3, PDFgetS3 and Python package diffpy.pdfgetx.
11+
12+
| Release |release|
13+
| |today|
14+
15+
========================================================================
16+
Table of contents
17+
========================================================================
18+
19+
20+
.. toctree::
21+
:maxdepth: 2
22+
23+
intro
24+
install
25+
quick-start
26+
tutorial
27+
files
28+
interact
29+
options
30+
plotdata
31+
release
32+
33+
========================================================================
34+
Indices
35+
========================================================================
36+
37+
* :ref:`genindex`
38+
* :ref:`search`

Diff for: ‎static_root/doc/pdfgetx/2.1.0/_sources/install.rst.txt

+135
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
Installation
2+
========================================================================
3+
4+
.. include:: abbreviations.txt
5+
6+
Software requirements
7+
------------------------------------------------------------------------
8+
9+
This software is written in Python programming language, therefore
10+
you must have Python 3.7, 3.6, 3.5, 3.4 or 2.7 installed. In addition,
11+
the following third-party Python libraries are also required:
12+
13+
* pip - Python package installer
14+
* setuptools - tools for installing Python packages
15+
* six - Python 2 and 3 compatibility library
16+
* NumPy - library for scientific computing with Python
17+
* matplotlib - Python plotting library
18+
* IPython - enhanced interactive Python shell
19+
20+
Standard Python releases can be obtained from
21+
https://www.python.org/downloads.
22+
The third-party libraries can be found at the
23+
`Python Package Index <https://pypi.org>`__
24+
or using any Internet search engine.
25+
26+
Another more convenient option is to obtain one of the science-oriented
27+
Python distributions such as
28+
`Anaconda Python`_,
29+
`Enthought Canopy <https://www.enthought.com/>`_ or
30+
`PythonXY <https://python-xy.github.io/>`_,
31+
These distributions already include all the necessary libraries, so the
32+
required Python software can be all installed in one step.
33+
34+
On Linux operating systems the third-party libraries are usually
35+
included in a system software repository. For example on an
36+
Ubuntu Linux computer the software dependencies can be all installed
37+
with a single shell command ::
38+
39+
sudo apt-get install \
40+
python3-pip python3-setuptools python3-six \
41+
python3-numpy python3-matplotlib ipython3
42+
43+
This may be, of course, as well accomplished using the GUI
44+
driven Synaptic package manager. Other Linux
45+
distributions may use different software management tools,
46+
but the names of the necessary packages should be very similar
47+
to those above.
48+
49+
On Windows operating system, it may be necessary to add the
50+
``C:\Python37`` directory and the scripts directory
51+
``C:\Python37\Scripts`` to the system :envvar:`!PATH`. Some Python
52+
distributions already do so as a part of their installation process. The
53+
easiest way to check is to start the :program:`Command Prompt`, type
54+
there ``python`` and see if this starts the Python interpreter.
55+
56+
57+
Installation
58+
------------------------------------------------------------------------
59+
60+
The diffpy.pdfgetx software is distributed as a Python wheel file,
61+
which can be obtained from the
62+
`Columbia Technology Ventures
63+
<http://innovation.columbia.edu/technologies/m11-120>`__.
64+
Once all the required software is in
65+
place, start the command prompt on Windows or a Unix terminal on Linux
66+
or Mac, navigate to the directory that contains the wheel file and
67+
execute the following command::
68+
69+
pip install ./diffpy.pdfgetx-VERSION.whl
70+
71+
Here VERSION needs to be replaced to match the actual filename. It is
72+
critical that pip installer is from a supported Python version otherwise
73+
the program would not work. On Linux and Mac operating systems the installation may need to run with root user privileges, for example, by prepending ``sudo`` to the command line above. If root access is not available, use the ``pip install`` options :option:`!--user` or :option:`!--prefix` to install the software to a user-writable directory.
74+
75+
The package provides three programs for PDF conversion, :program:`pdfgetx3`, :program:`pdfgetn3` and :program:`pdfgets3`. To check if they are correctly installed run ::
76+
77+
pdfgetx3 --version
78+
pdfgetn3 --version
79+
pdfgets3 --version
80+
81+
This should display the software version, which should agree
82+
with the VERSION string in the wheel package name.
83+
The installation also includes a :program:`plotdata`
84+
command for an easy plotting of text data files. To verify
85+
if plotdata works, run the ``plotdata --version`` command.
86+
Finally, a comprehensive test of the installed software can
87+
be executed using ::
88+
89+
python -m diffpy.pdfgetx.tests.run
90+
91+
.. note::
92+
93+
Older versions of diffpy.pdfgetx use Python egg format
94+
instead of Python wheel.
95+
To install these use the easy_install command as follows::
96+
97+
python -m easy_install ./diffpy.pdfgetx-VERSION.egg
98+
99+
.. index:: %pdfgetx3 IPython magic
100+
.. index:: %pdfgetn3 IPython magic
101+
.. index:: %pdfgets3 IPython magic
102+
103+
IPython magic command
104+
------------------------------------------------------------------------
105+
106+
These instructions are intended for `IPython`_ users who would like to
107+
integrate PDFgetX3, PDFgetN3 and PDFgetS3 into their IPython environment. If
108+
you don't plan to customize IPython in such way you can safely skip
109+
this paragraph.
110+
111+
When pdfgetx3 or pdfgetn3 or pdfgets3 is run in interactive mode, it start
112+
IPython interactive shell and define an extra ``%pdfgetx3``, ``%pdfgetn3`` and ``%pdfgets3`` magic commands within the IPython session. The IPython
113+
magic commands are not valid Python code, but work in a similar
114+
fashion as standard shell commands. The ``%pdfgetx3``, ``%pdfgetn3`` and ``%pdfgets3`` magics can be thus used with the same options and arguments as if run from the shell. This is useful for processing more files, while
115+
preserving all plots or variables that were already created
116+
in an IPython session.
117+
118+
The ``%pdfgetx3``, ``%pdfgetn3`` and ``%pdfgets3`` magic commands can be defined
119+
permanently so they are available in all IPython sessions. To set
120+
this up
121+
122+
#. find the ``profile_default/ipython_config.py`` file and open it
123+
in a text editor. If that file does not exists,
124+
create it first by executing ::
125+
126+
ipython profile create
127+
128+
#. navigate to the paragraph that contains the
129+
:py:data:`!c.InteractiveShellApp.extensions` and add there
130+
the following line ::
131+
132+
c.InteractiveShellApp.extensions = ['diffpy.pdfgetx.ipy_magics']
133+
134+
There must be no leading indent, i.e., the text must start at the
135+
very first column.

0 commit comments

Comments
 (0)