SrMise Documentation

Software version 0.5.2.

Last updated July 01, 2015.

Tool for unbiased peak extraction from atomic pair distribution functions.

The diffpy.srmise package is an implementation of the ParSCAPE algorithm for peak extraction from atomic pair distribution functions (PDFs). It is designed to function even when a priori knowledge of the physical sample is limited, utilizing the Akaike Information Criterion (AIC) to estimate whether peaks are statistically justified relative to alternate models. Three basic use cases are anticipated for diffpy.srmise. The first is peak fitting a user-supplied collections of peaks. The second is peak extraction from a PDF with no (or only partial) user-supplied peaks. The third is an AIC-driven multimodeling analysis where the output of multiple diffpy.srmise trials are ranked.

The framework for peak extraction defines peak-like clusters within the data, extracts a single peak within each cluster, and iteratively combines nearby clusters while performing a recursive search on the residual to identify occluded peaks. Eventually this results in a single global cluster containing many peaks fit over all the data. Over- and underfitting are discouraged by use of the AIC when adding or removing (during a pruning step) peaks. Termination effects, which can lead to physically spurious peaks in the PDF, are incorporated in the mathematical peak model and the pruning step attempts to remove peaks which are fit better as termination ripples due to another peak.

Where possible, diffpy.srmise provides physically reasonable default values for extraction parameters. However, the PDF baseline should be estimated by the user before extraction, or by performing provisional peak extraction with varying baseline parameters. The package defines a linear (crystalline) baseline, arbitrary polynomial baseline, a spherical nanoparticle baseline, and an arbitrary baseline interpolated from a list of user-supplied values. In addition, PDFs with accurate experimentally-determined uncertainties are necessary to provide the most reliable results, but historically such PDFs are rare. In the absence of accurate uncertainties an ad hoc uncertainty must be specified.

Disclaimer

If you use this program to do productive scientific research that
leads to publication, we ask that you acknowledge use of the
program by citing the following paper in your publication:

    L. Granlund, S.J.L. Billinge, P.M. Duxbury, Algorithm for
    systematic peak extraction from atomic pair distribution
    functions, Acta Crystallographica A 71(4), 392-409 (2015).
    doi:10.1107/S2053273315005276

Copyright 2014-2015, Board of Trustees of Michigan State University

For more information please visit the diffpy web-page at
    http://www.diffpy.org
or email Luke Granlund at luke.r.granlund@gmail.com, or Prof. Simon
Billinge at sb2896@columbia.edu.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:

  * Redistributions of source code must retain the above copyright
    notice, this list of conditions and the following disclaimer.

  * Redistributions in binary form must reproduce the above copyright
    notice, this list of conditions and the following disclaimer in the
    documentation and/or other materials provided with the distribution.

  * Neither the name of the copyright holder nor the names of its
    contributors may be used to endorse or promote products derived from
    this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY COPYRIGHT HOLDER "AS IS". COPYRIGHT
HOLDER EXPRESSLY DISCLAIMS ANY AND ALL WARRANTIES AND CONDITIONS,
EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY, TITLE, FITNESS, ADEQUACY OR
SUITABILITY FOR A PARTICULAR PURPOSE, AND ANY WARRANTIES OF FREEDOM
FROM INFRINGEMENT OF ANY DOMESTIC OR FOREIGN PATENT, COPYRIGHTS,
TRADE SECRETS OR OTHER PROPRIETARY RIGHTS OF ANY PARTY. IN NO EVENT
SHALL COPYRIGHT HOLDER BE LIABLE TO ANY PARTY FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE OR RELATING TO
THIS AGREEMENT, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
SrMise incorporates source code from diffpy.pdfgui in the file
pdfdataset.py. The PDFgui license is reproduced in full below.
===================================================================

This program is part of the DiffPy and DANSE open-source projects
and is available subject to the conditions and terms laid out
below.

If you use this program to do productive scientific research that
leads to publication, we ask that you acknowledge use of the
program by citing the following paper in your publication:

    C. L. Farrow, P. Juhas, J. W. Liu, D. Bryndin, E. S. Bozin,
    J. Bloch, Th. Proffen and S. J. L. Billinge, PDFfit2 and
    PDFgui: computer programs for studying nanostructure in
    crystals, J. Phys.: Condens.  Matter 19, 335219 (2007)

Copyright 2006-2007, Board of Trustees of Michigan State
University, Copyright 2008-2009, 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:
    http://www.diffpy.org/
or email Prof. Simon Billinge at sb2896@columbia.edu

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:

  * Redistributions of source code must retain the above copyright
    notice, this list of conditions and the following disclaimer.

  * Redistributions in binary form must reproduce the above copyright
    notice, this list of conditions and the following disclaimer in the
    documentation and/or other materials provided with the distribution.

  * Neither the name of the copyright holder nor the names of its
    contributors may be used to endorse or promote products derived from
    this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY COPYRIGHT HOLDER "AS IS". COPYRIGHT
HOLDER EXPRESSLY DISCLAIMS ANY AND ALL WARRANTIES AND CONDITIONS,
EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY, TITLE, FITNESS, ADEQUACY OR
SUITABILITY FOR A PARTICULAR PURPOSE, AND ANY WARRANTIES OF FREEDOM
FROM INFRINGEMENT OF ANY DOMESTIC OR FOREIGN PATENT, COPYRIGHTS,
TRADE SECRETS OR OTHER PROPRIETARY RIGHTS OF ANY PARTY. IN NO EVENT
SHALL COPYRIGHT HOLDER BE LIABLE TO ANY PARTY FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE OR RELATING TO
THIS AGREEMENT, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Acknowledgments

Developers

diffpy.srmise is developed and maintained by

SrMise (diffpy.srmise) authors:

Luke Granlund

The source code of pdfdataset.py was derived from diffpy.pdfgui.

Installation

See the README.rst file included with the distribution.

API

Detailed API documentation will be available in a future version of diffpy.srmise.