diffpy.pdffit2 package

PDFfit2 - real space structure refinement program.

Submodules

diffpy.pdffit2.output module

Take care of sending engine output to given file-like object.

The output file is stored in local module variable stdout.

diffpy.pdffit2.output.redirect_stdout(dst)

Redirect PDFfit2 standard output to a file-like object dst.

The dst value is stored in module variable stdout.

diffpy.pdffit2.pdffit module

PdfFit class for fitting a structural model to PDF data.

class diffpy.pdffit2.pdffit.PdfFit(create_intro=True)

Bases: object

Class for handling PdfFit calculations and refinements.

stru_files

The list to store structure files.

Type:

list

data_files

The list to store data files.

Type:

list

FCON = {'FCOMP': 2, 'FSQR': 3, 'IDENT': 1, 'USER': 0}

Sctp = {'N': 1, 'X': 0}

add_structure(stru)

add_structure(stru) –> Add new structure to PdfFit instance.

stru – instance of Structure class from diffpy.structure.

No return value. Raises pdffit2.structureError when stru contains unknown atom species.

alloc(stype, qmax, qdamp, rmin, rmax, bin)

Alloc(stype, qmax, qdamp, rmin, rmax, bin) –> Allocate space for a PDF calculation.

The structure from which to calculate the PDF must first be imported with the read_struct() or read_struct_string() method. stype – ‘X’ (xray) or ‘N’ (neutron) qmax – Q-value cutoff used in PDF calculation.

Use qmax=0 to neglect termination ripples.

qdamp – instrumental Q-resolution factor rmin – minimum r-value of calculation rmax – maximum r-value of calculation bin – number of data points in calculation

Raises:

• ValueError for bad input values –

• pdffit.unassignedError when no structure has been loaded –

bang(i, j, k)

Bang(i, j, k) –> Show bond angle defined by atoms i, j, k.

No return value. Use bond_angle() to get the result.

Raises: ValueError if selected atom(s) does not exist

pdffit.unassignedError when no structure has been loaded

blen(*args)

Blen(i, j) –> Show bond length defined by atoms i and j.

i – index of the first atom starting at 1 j – index of the second atom starting at 1

No return value. Use bond_length_atoms() to retrieve result.

Second form:

blen(a1, a2, lb, ub) –> Show sorted lengths of all a1-a2 bonds.

a1 – symbol of the first element in pair or “ALL” a2 – symbol of the second element in pair or “ALL” lb – lower bond length boundary ub – upper bond length boundary

No return value. Use bond_length_types() to retrieve results.

Raises: ValueError if selected atom(s) does not exist

pdffit.unassignedError when no structure has been loaded

bond_angle(i, j, k)

bond_angle(i, j, k) –> bond angle defined by atoms i, j, k. Angle is calculated using the shortest ji and jk lengths with respect to periodic boundary conditions.

i, j, k – atom indices starting at 1

Return a tuple of (angle, angle_error), both values are in degrees.

Raises: ValueError if selected atom(s) does not exist

pdffit.unassignedError when no structure has been loaded

bond_length_atoms(i, j)

bond_length_atoms(i, j) –> shortest distance between atoms i, j. Periodic boundary conditions are applied to find the shortest bond.

i – index of the first atom starting at 1 j – index of the second atom starting at 1

Return a tuple of (distance, distance_error).

Raises: ValueError if selected atom(s) does not exist

pdffit.unassignedError when no structure has been loaded.

bond_length_types(a1, a2, lb, ub)

bond_length_types(a1, a2, lb, ub) –> get all a1-a2 distances.

a1 – symbol of the first element in pair or “ALL” a2 – symbol of the second element in pair or “ALL” lb – lower bond length boundary ub – upper bond length boundary

Return a dictionary of distance data containing

dij : list of bond lengths within given bounds ddij : list of bond length standard deviations ij0 : pairs of atom indices starting from 0 ij1 : pairs of atom indices starting from 1

Raises: ValueError if selected atom(s) does not exist

pdffit.unassignedError when no structure has been loaded.

calc()

Calc() –> Calculate the PDF of the imported structure.

Space for the calculation must first be allocated with the alloc() method.

Raises:

• pdffit2.calculationError when allocated space cannot –

• accommodate calculation –

• pdffit.unassignedError when space for calculation has not been –

• allocated –

constrain(var, par, fcon=None)

Constrain(var, par[, fcon]) –> Constrain a variable to a parameter.

A variable can be constrained to a number or equation string. var – variable to constrain, such as x(1) par – parameter which to constrain the variable. This can be

an integer or an equation string containing a reference to another parameter. Equation strings use standard c++ syntax. The value of a constrained parameter is accessed as @p in an equation string, where p is the parameter. e.g. >>> constrain(x(1), 1) >>> constrain(x(2), “0.5+@1”)

fcon – ‘USER’, ‘IDENT’, ‘FCOMP’, or ‘FSQR’

this is an optional parameter, and I don’t know how it is used!

Raises:

• pdffit2.constraintError if a constraint is bad –

• pdffit2.unassignedError if variable does not yet exist –

• ValueError if variable index does not exist (e.g. lat(7)) –

static delta1()

Delta1() –> Get reference to 1/R peak sharpening factor.

static delta2()

Delta2() –> Reference to (1/R^2) sharpening factor.

The phenomenological correlation constant in the Debye-Waller factor. The (1/R^2) peak sharpening factor.

static dscale()

Dscale() –> Get reference to dscale.

The data scale factor.

fixpar(par)

Fixpar(par) –> Fix a parameter.

Fixed parameters are not fitted in a refinement. Passed parameter can be ‘ALL’, in which case all parameters are fixed.

Raises: pdffit.unassignedError when parameter has not been assigned

freepar(par)

Freepar(par) –> Free a parameter.

Freed parameters are fitted in a refinement. Passed parameter can be ‘ALL’, in which case all parameters are freed.

Raises: pdffit.unassignedError when parameter has not been assigned

getR()

GetR() –> Get r-points used in the fit.

This function should only be called after data has been loaded or calculated. Before a refinement, the list of r-points will reflect the data. Afterwards, they will reflect the fit range.

Raises: pdffit2.unassignedError if no data exists

Returns: List of equidistance r-points used in fit.

get_atom_types(ip=None)

get_atom_types() –> Ordered unique element symbols in the structure.

ip – index of phase to get the elements from (starting from 1)

when ip is not given, use current phase

This function should only be called after a structure has been loaded.

Raises:

pdffit2.unassignedError if no structure exists –

Returns: List of unique atom symbols as they occur in structure.

get_atoms(ip=None)

get_atoms() –> Get element symbols of all atoms in the structure.

ip – index of phase to get the elements from (starting from 1)

when ip is not given, use current phase

This function should only be called after a structure has been loaded.

Raises: pdffit2.unassignedError if no structure exists

Returns: List of atom names in structure.

get_scat(stype, element)

get_scat(stype, element) –> Get active scattering factor for given element. If scattering factor has been changed using set_scat the result may depend on the active phase. When no phase has been loaded, return the standard value.

stype – ‘X’ (xray) or ‘N’ (neutron). element – case-insensitive element symbol such as “Na” or “CL”

Return float.

Raises:

ValueError if element is not known. –

get_scat_string(stype)

get_scat_string(stype) –> Get string with scattering factors of all atoms in the current phase.

stype – ‘X’ (xray) or ‘N’ (neutron).

Raises:

pdffit2.unassignedError if no phase exists –

Returns: string with all scattering factors.

get_structure(ip)

get_structure(ip) –> Get a copy of specified phase data.

ip – index of existing PdfFit phase starting from 1

Return Structure object from diffpy.structure. Raise pdffit2.unassignedError if phase ip is undefined.

getcrw()

Getcrw() –> Get cumulative Rw for the current dataset.

Cumulative Rw is a list of Rw partial sums cost values evaluated against observed PDF data in the error sums evaluated against the r-points in the fit.

Raises: pdffit2.unassignedError if no data exists

Returns: List of crw points, equidistant in r or empty list if the refine function has not been called yet.

getpar(par)

Getpar(par) –> Get value of parameter.

Raises: ValueError if parameter does not exists

getpdf_diff()

Obtain difference between observed and fitted PDF.

This function should only be called after data has been loaded or calculated. Before a refinement, the list of r-points will reflect the data. Afterwards, they will reflect the fit range.

Raises: pdffit2.unassignedError if no data exists

Returns: List of data points, equidistant in r.

getpdf_fit()

getpdf_fit() –> Get fitted PDF.

This function should only be called after a refinement or refinement step has been done.

Raises: pdffit2.unassignedError if no data exists

Returns: List of fitted points, equidistant in r.

getpdf_obs()

getpdf_obs() –> Get observed PDF.

This function should only be called after data has been loaded or calculated. Before a refinement, the list of r-points will reflect the data. Afterwards, they will reflect the fit range.

Raises: pdffit2.unassignedError if no data exists

Returns: List of data points, equidistant in r.

getrw()

Getrw() –> Get normalized total error of the fit rw.

getrw calculates total fit error summed for all datasets in the fit.

Return float.

getvar(var)

Getvar(var) –> Get stored value of a variable.

Raises:

• pdffit2.unassignedError if variable does not yet exist –

• ValueError if variable index does not exist (e.g. lat(7)) –

static intro()

Show introductory message.

static lat(n)

Lat(n) –> Get reference to lattice variable n.

n can be an integer or a string representing the lattice variable. 1 <==> ‘a’ 2 <==> ‘b’ 3 <==> ‘c’ 4 <==> ‘alpha’ 5 <==> ‘beta’ 6 <==> ‘gamma’

num_atoms()

num_atoms() –> Get number of atoms in current phase.

Raises: pdffit2.unassignedError if no atoms exist

num_datasets()

num_datasets() –> Number of datasets loaded in PdfFit instance.

Use setdata to bring a specific dataset in focus.

Return integer.

num_phases()

num_phases() –> Number of phases loaded in PdfFit instance.

Use setphase to bring a specific phase in focus.

Return integer.

static occ(i)

Occ(i) –> Get reference to occupancy of atom i.

pdesel(ip)

Pdesel(ip) –> Exclude phase ip from calculation of total PDF.

pdesel(‘ALL’) excludes all phases from PDF calculation.

Raises: pdffit2.unassignedError if selected phase does not exist

pdfrange(iset, rmin, rmax)

Pdfrange(iset, rmin, rmax) –> Set the range of the fit.

iset – data set to consider rmin – minimum r-value of fit rmax – maximum r-value of fit

Raises: ValueError for bad input values

phase_fractions()

phase_fractions() –> relative phase fractions for current dataset. Convert phase scale factors to relative phase fractions given the scattering type of current dataset.

Return a dictionary of phase fractions with following keys:

“atom” – list of fractions normalized to atom count “stdatom” – errors of atom count fractions “cell” – list of fractions normalized to unit cell count “stdcell” – errors of unit cell count fractions “mass” – list of relative weight fractions “stdmass” – errors of relative weight fractions

Raises: pdffit2.unassignedError if no dataset exists.

static pscale()

Pscale() –> Get reference to pscale.

pscale is the fraction of the total structure that the current phase represents.

psel(ip)

Psel(ip) –> Include phase ip in calculation of total PDF.

psel(‘ALL’) selects all phases for PDF calculation.

Raises: pdffit2.unassignedError if selected phase does not exist

static qbroad()

Qbroad() –> Get reference to qbroad.

Quadratic peak broadening factor.

static qdamp()

Qdamp() –> Get reference to qdamp.

Qdamp controls PDF damping due to instrument Q-resolution.

static rcut()

Rcut() –> Get reference to rcut.

rcut is the value of r below which peak sharpening, defined by the sigma ratio (sratio), applies. rcut cannot be refined.

read_data(data, stype, qmax, qdamp)

read_data(data, stype, qmax, qdamp) –> Read pdf data from file into memory.

data – name of file from which to read data stype – ‘X’ (xray) or ‘N’ (neutron) qmax – Q-value cutoff used in PDF calculation.

Use qmax=0 to neglect termination ripples.

qdamp – instrumental Q-resolution factor

Raises: IOError when the file cannot be read from disk

read_data_lists(stype, qmax, qdamp, r_data, Gr_data, dGr_data=None, name='list')

read_data_lists(stype, qmax, qdamp, r_data, Gr_data, dGr_data = None, name = “list”) –> Read pdf data into memory from lists.

All lists must be of the same length. stype – ‘X’ (xray) or ‘N’ (neutron) qmax – Q-value cutoff used in PDF calculation.

Use qmax=0 to neglect termination ripples.

qdamp – instrumental Q-resolution factor r_data – list of r-values Gr_data – list of G(r) values dGr_data – list of G(r) uncertainty values name – tag with which to label data

Raises: ValueError when the data lists are of different length

read_data_string(data, stype, qmax, qdamp, name='')

read_data_string(data, stype, qmax, qdamp, name = “”) –> Read pdf data from a string into memory.

data – string containing the contents of the data file stype – ‘X’ (xray) or ‘N’ (neutron) qmax – Q-value cutoff used in PDF calculation.

Use qmax=0 to neglect termination ripples.

qdamp – instrumental Q-resolution factor name – tag with which to label data

read_struct(struct)

read_struct(struct) –> Read structure from file into memory.

struct – name of file from which to read structure

Raises:

• pdffit2.calculationError when a lattice cannot be created from the –

• given structure –

• pdffit2.structureError when a structure file is malformed –

• IOError when the file cannot be read from the disk –

read_struct_string(struct, name='')

read_struct_string(struct, name = “”) –> Read structure from a string into memory.

struct – string containing the contents of the structure file name – tag with which to label structure

Raises:

• pdffit2.calculationError when a lattice cannot be created from the –

• given structure –

• pdffit2.structureError when a structure file is malformed –

refine(toler=1e-08)

Refine(toler = 0.00000001) –> Fit the theory to the imported data.

toler – tolerance of the fit

Raises:

• pdffit2.calculationError when the model pdf cannot be calculated –

• pdffit2.constraintError when refinement fails due to bad –

• constraint –

• pdffit2.unassigedError when a constraint used but never initialized –

• using setpar() –

refine_step(toler=1e-08)

refine_step(toler = 0.00000001) –> Run a single step of the fit.

toler – tolerance of the fit

Raises:

• pdffit2.calculationError when the model pdf cannot be calculated –

• pdffit2.constraintError when refinement fails due to bad –

• constraint –

• pdffit2.unassigedError when a constraint used but never initialized –

• using setpar() –

Returns: 1 (0) if refinement is (is not) finished

reset()

Reset() –> Clear all stored fit, structure, and parameter data.

reset_scat(element)

reset_scat(stype, element) –> Reset scattering factors for given element to their standard values. The reset_scat applies only for the current phase.

element – case-insensitive element symbol such as “Na” or “CL” :raises pdffit2.unassignedError if no phase exists: :raises ValueError if element is not known.:

save_dif(iset, fname)

save_dif(iset, fname) –> Save data and fitted PDF difference to file.

iset – data set to save

Raises:

• IOError if file cannot be saved –

• pdffit2.unassignedError if the data set is undefined –

save_dif_string(iset)

save_dif_string(iset) –> Save data and fitted PDF difference to string.

iset – data set to save

Raises:

pdffit2.unassignedError if the data set is undefined –

Returns: string containing contents of save file

save_pdf(iset, fname)

save_pdf(iset, fname) –> Save calculated or fitted PDF to file.

iset – data set to save

Raises:

• IOError if file cannot be saved –

• pdffit2.unassignedError if the data set is undefined –

save_pdf_string(iset)

save_pdf_string(iset) –> Save calculated or fitted PDF to string.

iset – data set to save

Raises:

pdffit2.unassignedError if the data set is undefined –

Returns: string containing contents of save file

save_res(fname)

save_res(fname) –> Save fit-specific data to file.

Raises:

• IOError if file cannot be saved –

• pdffit2.unassignedError if there is no refinement data to save –

save_res_string()

save_res_string() –> Save fit-specific data to a string.

Raises:

pdffit2.unassignedError if there is no refinement data to save –

Returns: string containing contents of save file

save_struct(ip, fname)

save_struct(ip, fname) –> Save structure resulting from fit to file.

ip – phase to save

Raises:

• IOError if file cannot be saved –

• pdffit2.unassignedError if the data set is undefined –

save_struct_string(ip)

save_struct(ip) –> Save structure resulting from fit to string.

ip – phase to save

Raises:

pdffit2.unassignedError if phase ip is undefined. –

Returns: string containing contents of save file

selalias = {'ALL': -1}

selectAll(ip, ijchar)

Configure partial PDF - include all atoms of phase ip as first or second element in pair for distance evaluation.

ip – phase index starting at 1 ijchar – ‘i’ or ‘j’ for first or second in pair

Raises:

• pdffit2.unassignedError if selected phase does not exist –

• ValueError if ijchar is invalid –

selectAtomIndex(ip, ijchar, aidx, flag)

Configure partial PDF - mark the atom of given index in phase ip as included or excluded as a first or second in pair for distance evaluation.

ip – phase index starting at 1 ijchar – ‘i’ or ‘j’ for first or second in pair aidx – integer index of atom starting at 1 flag – bool flag, True for selection, False for exclusion

Raises:

• pdffit2.unassignedError if selected phase does not exist –

• ValueError if atom index or ijchar are invalid –

selectAtomType(ip, ijchar, symbol, flag)

Configure partial PDF - mark the specified atom type in phase ip as included or excluded as a first or second in pair for distance evaluation.

ip – phase index starting at 1 ijchar – ‘i’ or ‘j’ for first or second in pair symbol – element symbol flag – bool flag, True for selection, False for exclusion

Raises:

• pdffit2.unassignedError if selected phase does not exist –

• ValueError for invalid value of ijchar –

selectNone(ip, ijchar)

Configure partial PDF - exclude all atoms of phase ip from first or second element of pair distance evaluation.

ip – phase index starting at 1 ijchar – ‘i’ or ‘j’ for first or second in pair

Raises:

• pdffit2.unassignedError if selected phase does not exist –

• ValueError if ijchar is invalid –

set_scat(stype, element, value)

set_scat(stype, element, value) –> Set custom scattering factor for given element. The new scattering factor applies only for the current phase, in other phases it keeps its default value.

stype – ‘X’ (xray) or ‘N’ (neutron). element – case-insensitive element symbol such as “Na” or “CL” value – new value of scattering factor

No return value.

Raises:

• pdffit2.unassignedError if no phase exists. –

• ValueError if element is not known. –

See also reset_scat, get_scat.

setdata(iset)

Setdata(iset) –> Set the data set in focus.

iset – integer index of data set starting at 1.

Raises: pdffit.unassignedError when data set does not exist

setpar(par, val)

Setpar(par, val) –> Set value of constrained parameter.

val – Either a numerical value or a reference to a variable

Raises:

pdffit2.unassignedError when variable is yet to be assigned –

setphase(ip)

Setphase(ip) –> Switch to phase ip.

ip – index of the phase starting at 1.

All parameters assigned after this method is called refer only to the current phase.

Raises: pdffit.unassignedError when phase does not exist

setvar(var, val)

Setvar(var, val) –> Set the value of a variable.

Raises:

• pdffit2.unassignedError if variable does not yet exist –

• ValueError if variable index does not exist (e.g. lat(7)) –

show_scat(stype)

show_scat(stype) –> Print scattering length for all atoms in the current phase.

stype – ‘X’ (xray) or ‘N’ (neutron).

Raises: pdffit2.unassignedError if no phase exists

show_struct(ip)

show_struct(ip) –> Print structure resulting from fit.

ip – phase to display

Raises: pdffit2.unassignedError if the phase is undefined

static spdiameter()

Spdiameter() –> Get reference to spdiameter (phase property).

Diameter value for the spherical particle PDF correction. Spherical envelope is not applied when spdiameter equals 0.

static sratio()

Sratio() –> Get reference to sigma ratio.

The sigma ratio determines the reduction in the Debye-Waller factor for distances below rcut.

static stepcut()

Stepcut() –> Get reference to stepcut (phase property).

stepcut is cutoff radius for empirical step-function PDF envelope. stepcut can be used to approximate loss of pair correlations in amorphous phase. stepcut cannot be refined.

Step cutoff is not applied when stepcut equals 0.

static u11(i)

U11(i) –> Get reference to U(1,1) for atom i.

U is the anisotropic thermal factor tensor.

static u12(i)

U12(i) –> Get reference to U(1,2) for atom i.

U is the anisotropic thermal factor tensor.

static u13(i)

U13(i) –> Get reference to U(1,3) for atom i.

U is the anisotropic thermal factor tensor.

static u22(i)

U22(i) –> Get reference to U(2,2) for atom i.

U is the anisotropic thermal factor tensor.

static u23(i)

U23(i) –> Get reference to U(2,3) for atom i.

U is the anisotropic thermal factor tensor.

static u33(i)

U33(i) –> Get reference to U(3,3) for atom i.

U is the anisotropic thermal factor tensor.

static x(i)

X(i) –> Get reference to x-value of atom i.

static y(i)

Y(i) –> Get reference to y-value of atom i.

static z(i)

Z(i) –> Get reference to z-value of atom i.

diffpy.pdffit2.ipy_ext module

This module defines functions within IPython session to simulate the old pdffit2 interactive session.

Usage: %load_ext diffpy.pdffit2.ipy_ext

class diffpy.pdffit2.ipy_ext.EasyPDFPlotting(pdffit_instance)

Bases: object

Convenience functions for accessing and plotting PDFfit2 data.

property Gcalc

Calculated PDF data.

property Gdiff

Difference between the observed and simulated PDF.

property Gobs

Observed PDF data.

property r

R-grid for PDF simulation.

showRw()

Plot cumulative Rw.

showfit(offset=None)

Plot observed and simulated PDFs and the difference curve.

offset – offset for the difference curve.

No return value.

diffpy.pdffit2.ipy_ext.load_ipython_extension(ipython)