Class PdfFit

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.

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 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

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_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_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

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

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

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
    accomodate calculation
    pdffit.unassignedError when space for calculation has not been
    allocated

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 = 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

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 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_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 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_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 fit-specific data to a string.

Raises:
    pdffit2.unassignedError if there is no refinement data to save

Returns: string containing contents of save file

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.

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(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

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

ip    -- phase to display

Raises: pdffit2.unassignedError if the phase is undefined

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))

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

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))

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))

getrw() --> Get normalized total error of the fit rw.

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

Return float.

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.

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. Afterwords, they will reflect the fit range.

Raises: pdffit2.unassignedError if no data exists

Returns: List of equidistance r-points used in 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() --> 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. Afterwords, they will reflect the fit range.

Raises: pdffit2.unassignedError if no data exists

Returns: List of data points, equidistant in r.

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. Afterwords, they will reflect the fit range.

Raises: pdffit2.unassignedError if no data exists

Returns: List of data points, equidistant in r.

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_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.

getpar(par) --> Get value of parameter.

Raises: ValueError if parameter does not exists

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) --> 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

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

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

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

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

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

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

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

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

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

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

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_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) --> 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 lenghts within given bounds
ddij : list of bond legnth 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.

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

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_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.

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.

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
    ValueError if element is not known.

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

Raises: pdffit2.unassignedError if no atoms exist

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

Use setphase to bring a specific phase in focus.

Return integer.

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

Use setdata to bring a specific dataset in focus.

Return integer.

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.

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'

u11(i) --> Get reference to U(1,1) for atom i.

U is the anisotropic thermal factor tensor.

u22(i) --> Get reference to U(2,2) for atom i.

U is the anisotropic thermal factor tensor.

u33(i) --> Get reference to U(3,3) for atom i.

U is the anisotropic thermal factor tensor.

u12(i) --> Get reference to U(1,2) for atom i.

U is the anisotropic thermal factor tensor.

u13(i) --> Get reference to U(1,3) for atom i.

U is the anisotropic thermal factor tensor.

u23(i) --> Get reference to U(2,3) for atom i.

U is the anisotropic thermal factor tensor.

pscale() --> Get reference to pscale.

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

sratio() --> Get reference to sigma ratio.

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

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

dscale() --> Get reference to dscale.

The data scale factor.

qdamp() --> Get reference to qdamp.

Qdamp controls PDF damping due to instrument Q-resolution.

qbroad() --> Get reference to qbroad.

Quadratic peak broadening factor.

spdiameter() --> Get reference to spdiameter (phase property).

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

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.

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.

x.__init__(...) initializes x; see help(type(x)) for signature

Overrides: object.__init__

(inherited documentation)