Merge pull request #129 from sbillinge/docs

sbillinge · web-flow · commit c2a5d7af7ece · 2025-01-13T19:51:11.000-05:00
doc: edited and cleaned docs for 1.5.0 release
diff --git a/README.rst b/README.rst
@@ -35,15 +35,21 @@
 .. |Tracking| image:: https://img.shields.io/badge/issue_tracking-github-blue
         :target: https://github.com/diffpy/diffpy.pdffit2/issues
 
-PDFfit2 - real space structure refinement to atomic pair distribution function
+PDFfit2 - real space structure refinement of the atomic pair distribution function
 
-The diffpy.pdffit2 package provides functions for calculation and
-refinement of atomic Pair Distribution Function (PDF) from crystal
-structure model.  It is used as a computational engine by PDFgui.  All
-refinements possible in PDFgui can be done with diffpy.pdffit2,
+The diffpy.pdffit2 package provides functions for the calculation and
+refinement of atomic Pair Distribution Functions (PDF) from crystal
+structure models.  It is used as a computational engine by PDFgui. All
+refinements possible in PDFgui can be done by writing python scripts
+directly with diffpy.pdffit2,
 although less conveniently and with a fair knowledge of Python.
-The package includes an extension for the interactive `IPython
-<http://ipython.org>`__ shell, which tries to mimic the old PDFFIT
+However, we recommend using `diffpy-cmi
+<https://www.diffpy.org/products/diffpycmi/index.html>`_ for carrying
+out more advanced, python-scripted refinements of nanostructure.
+
+The PDFfit2 package includes an extension for the interactive `IPython
+<http://ipython.org>`_ shell, these days commonly used within
+Jupyter notebooks, which tries to mimic the old PDFFIT
 program.  To start IPython with this extension and also with plotting
 functions enabled, use ::
 
diff --git a/doc/source/examples.rst b/doc/source/examples.rst
@@ -14,13 +14,23 @@ Files needed:
 Example 1: Calculate PDF of FCC nickel
 ======================================
 
-The first example shows how to calculates the PDF for FCC nickel and saves the resulting data to a file and plot it using matplotlib.
+The first example shows how to calculate the PDF for FCC nickel and save the resulting data
+to a file and plot it using matplotlib.
 
-1. Imports the PdfFit class from the diffpy.pdffit2 module::
+1. Import the ``PdfFit`` class from the ``diffpy.pdffit2`` module
+
+.. code-block:: python
 
     from diffpy.pdffit2 import PdfFit
 
-2. Create a PDF calculator object and assigned to the variable ``P``. Make sure the ``Ni.stru`` file is in the same directory as the script and you've cd to the directory, load structure file. Then allocate and configure PDF calculation and run the calculation::
+2. Create a PDF calculator object and assign it to the variable ``P``.
+Make sure the ``Ni.stru`` file is in the same directory as the script (or specify
+the relative path to where it resides)
+and you are currently in this directory. Then use ``read_struct`` to read the structure
+file, ``alloc`` to configure the PDF
+calculation, and then use ``calc`` to carry out the the calculation.
+
+.. code-block:: python
 
     # create new PDF calculator object
     P = PdfFit()
@@ -39,11 +49,15 @@ The first example shows how to calculates the PDF for FCC nickel and saves the r
     P.alloc(radiation_type, qmax, qdamp, rmin, rmax, npts)
     P.calc()
 
-3. Save the refined result::
+3. Save the calculated PDF.
+
+.. code-block:: python
 
     P.save_pdf(1, "Ni_calculation.cgr")
 
-4. We can also plot it using matplotlib::
+4. We can also plot it using matplotlib
+
+.. code-block:: python
 
     import matplotlib.pyplot as plt
 
@@ -59,19 +73,27 @@ The first example shows how to calculates the PDF for FCC nickel and saves the r
     # display plot window, this must be the last command in the script
     plt.show()
 
-The scripts can be downloaded :download:`here <examples/Ni_calculation.py>`.
+The scripts used in this example can be
+downloaded :download:`here <examples/Ni_calculation.py>`.
 
 =======================================
 Example 2: Performing simple refinement
 =======================================
 
-The second example shows how to perform simple refinement of Ni structure to the experimental x-ray PDF. The example uses the same data files as the first example.
+The second example shows how to perform a simple refinement of the Ni structure to
+the experimental x-ray PDF. The example uses the same data files as the first example.
+
+1. Import the PdfFit class from the diffpy.pdffit2 module
 
-1. Imports the PdfFit class from the diffpy.pdffit2 module::
+.. code-block:: python
 
     from diffpy.pdffit2 import PdfFit
 
-2. Create a PDF calculator object and assigned to the variable ``pf``. Load experimental x-ray PDF data and nickel structure file::
+2. Create a PDF calculator object and assign it to the variable ``pf``.
+Load the experimental x-ray PDF data using ``read_data`` and also load
+the nickel structure file.
+
+.. code-block:: python
 
     # Create new PDF calculator object.
     pf = PdfFit()
@@ -84,7 +106,13 @@ The second example shows how to perform simple refinement of Ni structure to the
     # Load nickel structure, must be in PDFFIT or DISCUS format
     pf.read_struct("Ni.stru")
 
-3. Configure refinement and refine::
+3. Configure the refinement, assigning structural parameters to variables.  For more
+information on how to do this correctly, please read the PDFgui documentation.
+Set initial values for the variables using ``setpar``.
+Finally, you can configure the range over which to refine (``pdfrange``) and
+run the refinement (``refine``).
+
+.. code-block:: python
 
     # Refine lattice parameters a, b, c.
     # Make them all equal to parameter @1.
@@ -118,13 +146,18 @@ The second example shows how to perform simple refinement of Ni structure to the
     pf.pdfrange(1, 1.5, 19.99)
     pf.refine()
 
-4. Save the refined result::
+4. Save the refined result. ``save_struct`` saves the new, refined, structure to a
+``.stru`` format file.  ``save_res`` saves the outputs in a structured text file.
+
+.. code-block:: python
 
     pf.save_pdf(1, "Ni_refinement.fgr")
     pf.save_struct(1, "Ni_refinement.rstr")
     pf.save_res("Ni_refinement.res")
 
-5. We can also plot it using matplotlib::
+5. We can also plot it using matplotlib
+
+.. code-block:: python
 
     import matplotlib.pyplot as plt
     import numpy
@@ -149,4 +182,4 @@ The second example shows how to perform simple refinement of Ni structure to the
     # display plot window, this must be the last command in the script
     plt.show()
 
-The scripts can be downloaded :download:`here <examples/Ni_refinement.py>`.
+The scripts can be downloaded from :download:`here <examples/Ni_refinement.py>`.
diff --git a/doc/source/index.rst b/doc/source/index.rst
@@ -9,13 +9,19 @@ diffpy.pdffit2 - PDFfit2 - real space structure refinement program.
 | Software version |release|.
 | Last updated |today|.
 
-The diffpy.pdffit2 package provides functions for calculation and
-refinement of atomic Pair Distribution Function (PDF) from crystal
-structure model.  It is used as a computational engine by PDFgui. All
-refinements possible in PDFgui can be done with diffpy.pdffit2,
+The diffpy.pdffit2 package provides functions for the calculation and
+refinement of atomic Pair Distribution Functions (PDF) from crystal
+structure models.  It is used as a computational engine by PDFgui. All
+refinements possible in PDFgui can be done by writing python scripts
+directly with diffpy.pdffit2,
 although less conveniently and with a fair knowledge of Python.
-The package includes an extension for the interactive `IPython
-<http://ipython.org>`_ shell, which tries to mimic the old PDFFIT
+However, we recommend using `diffpy-cmi
+<https://www.diffpy.org/products/diffpycmi/index.html>`_ for carrying
+out more advanced, python-scripted refinements of nanostructure.
+
+The PDFfit2 package includes an extension for the interactive `IPython
+<http://ipython.org>`_ shell, these days commonly used within
+Jupyter notebooks, which tries to mimic the old PDFFIT
 program.  To start IPython with this extension and also with plotting
 functions enabled, use ::
 
@@ -30,19 +36,26 @@ statements.
 Authors
 =======
 
-This code was derived from the first PDFFIT program by Thomas Proffen.
+This code was derived from the first `PDFFIT
+<https://doi.org/10.1107/S0021889899003532>`_ program written by Thomas Proffen
+and Simon Billinge, which was a FORTRAN implementation of the original
+"Real-space Rietveld" code
+written by Simon Billinge (Billinge, S. J. L. “Real-space Rietveld: full profile structure refinement of the atomic pair distribution
+function”. In: Local Structure from Diffraction. Ed. by S. J. L. Billinge and M. F. Thorpe. New York:
+Plenum, 1998, p. 137).
 The sources were converted to C++ by Jacques Bloch and then extensively hacked,
 extended and purged from most glaring bugs by Chris Farrow and Pavol Juhas.
 This code is currently maintained as part of the DiffPy project to create
 python modules for structure investigations from diffraction data.
 
 The DiffPy team is located in the Billinge-group at the Applied Physics
 and Applied Mathematics Department of the Columbia University in New York.
-Previous significant contributors to this code were
+Previous significant contributors to this code were made by
 
    Pavol Juhas,  Chris Farrow, Jacques Bloch, Wenduo Zhou
 
-For a detailed list of contributors see
+with more recent contributions from Billinge-group members.
+For a more detailed list of contributors see
 https://github.com/diffpy/diffpy.pdffit2/graphs/contributors.
 
 
@@ -62,7 +75,7 @@ in your publication:
 Installation
 ============
 
-See the `README <https://github.com/diffpy/diffpy.pdffit2#installation>`_
+Please see the `README <https://github.com/diffpy/diffpy.pdffit2#installation>`_
 file included with the distribution.
 
 =================
diff --git a/doc/source/license.rst b/doc/source/license.rst
@@ -17,7 +17,7 @@ the following paper in your publication:
         in crystals (https://stacks.iop.org/0953-8984/19/335219), *J. Phys.: Condens. Matter*, 19, 335219 (2007)
 
 Copyright 2006-2007, Board of Trustees of Michigan State University,
-Copyright 2008-2024, Board of Trustees of Columbia University in the
+Copyright 2008-|year|, Board of Trustees of Columbia University in the
 city of New York.  (Copyright holder indicated in each source file).
 
 For more information please visit the project web-page:
diff --git a/news/docs.rst b/news/docs.rst
@@ -0,0 +1,23 @@
+**Added:**
+
+* <news item>
+
+**Changed:**
+
+* Documentation brought up to date
+
+**Deprecated:**
+
+* <news item>
+
+**Removed:**
+
+* <news item>
+
+**Fixed:**
+
+* <news item>
+
+**Security:**
+
+* <news item>
diff --git a/src/diffpy/pdffit2/pdffit.py b/src/diffpy/pdffit2/pdffit.py
@@ -12,7 +12,7 @@
 # See LICENSE.txt for license information.
 #
 ##############################################################################
-"""PdfFit class for fitting pdf data to a model."""
+"""PdfFit class for fitting a structural model to PDF data."""
 
 from __future__ import print_function
 
@@ -104,7 +104,7 @@ def _convertCallable(var):
 
 
 class PdfFit(object):
-    """Class for PdfFit.
+    """Class for handling PdfFit calculations and refinements.
 
     Attributes
     ----------
