diffpy.srfit.fitbase package

Submodules

diffpy.srfit.fitbase.calculator module

The Calculator for Parameter-aware functions.

Calculator is a functor class for producing a signal from embedded Parameters. Calculators can store Parameters and ParameterSets, Constraints and Restraints. Also, the __call__ function can be overloaded to accept external arguments. Calculators are used to wrap registered functions so that the function’s Parameters are contained in an object specific to the function. A custom Calculator can be added to another RecipeOrganizer with the ‘registerCalculator’ method.

class diffpy.srfit.fitbase.calculator.Calculator(name)[source]

Bases: Operator, ParameterSet

Base class for calculators.

A Calculator organizes Parameters and has a __call__ method that can calculate a generic signal.

name: A name for this organizer.

meta: A dictionary of metadata needed by the calculator.

_calculators: A managed dictionary of Calculators, indexed by name.

_constraints: A set of constrained Parameters. Constraints can be added using the ‘constrain’ methods.

_parameters: A managed OrderedDict of contained Parameters.

_parsets: A managed dictionary of ParameterSets.

_restraints: A set of Restraints. Restraints can be added using the ‘restrain’ or ‘confine’ methods.

_eqfactory: A diffpy.srfit.equation.builder.EquationFactory instance that is used create Equations from string.

args: List of Literal arguments

nin: Number of inputs (<1 means this is variable)

nout: Number of outputs (1)

operation[source]: Function that performs the operation, self.__call__

symbol: Same as name

_value: The value of the Operator.

value: Property for ‘getValue’.

names: Variable names (read only). See getNames.

values: Variable values (read only). See getValues.

nin = -1

nout = 1

operation(*args)[source]

property symbol

diffpy.srfit.fitbase.configurable module

Configurable class.

A Configurable has state of which a FitRecipe must be aware.

class diffpy.srfit.fitbase.configurable.Configurable[source]

Bases: object

Configurable class.

A Configurable has state of which a FitRecipe must be aware.

_configobjs: Set of Configureables in a hierarchy or instances. Messages get passed up the hierarchy to a FitReciple via these objects.

diffpy.srfit.fitbase.constraint module

Constraint class.

Constraints are used by a FitRecipe (and other RecipeOrganizers) to organize constraint equations. They store a Parameter object and an Equation object that is used to compute its value. The Constraint.constrain method is used to create this association.

class diffpy.srfit.fitbase.constraint.Constraint[source]

Bases: Validatable

Constraint class.

Constraints are designed to be stored in only one place. (The holder of the constraint owns it).

par: A Parameter that is the subject of the constraint.

eq: An equation whose evaluation is used to set the value of the constraint.

constrain(par, eq)[source]

Constrain a Parameter according to an Equation.

The parameter will be set constant once it is constrained. This will keep it from being constrained multiple times.

Raises a ValueError if par is const.

unconstrain()[source]: Clear the constraint.

update()[source]: Update the parameter according to the equation.

diffpy.srfit.fitbase.fitcontribution module

FitContribution class.

FitContributions generate a residual function for a FitRecipe. A FitContribution associates an Equation for generating a signal, optionally one or more ProfileGenerators or Calculators that help in this, and a Profile that holds the observed and calculated signals.

See the examples in the documentation for how to use a FitContribution.

class diffpy.srfit.fitbase.fitcontribution.FitContribution(name)[source]

Bases: ParameterSet

FitContribution class.

FitContributions organize an Equation that calculates the signal, and a Profile that holds the signal. ProfileGenerators and Calculators can be used as well. Constraints and Restraints can be created as part of a FitContribution.

name: A name for this FitContribution.

profile: A Profile that holds the measured (and calculated) signal.

_calculators: A managed dictionary of Calculators, indexed by name.

_constraints: A set of constrained Parameters. Constraints can be added using the ‘constrain’ methods.

_generators: A managed dictionary of ProfileGenerators.

_parameters: A managed OrderedDict of parameters.

_restraints: A set of Restraints. Restraints can be added using the ‘restrain’ method.

_parsets: A managed dictionary of ParameterSets.

_eqfactory: A diffpy.srfit.equation.builder.EquationFactory instance that is used to create constraints and restraints from string

_eq: The FitContribution equation that will be optimized.

_reseq: The residual equation.

_xname: Name of the x-variable

_yname: Name of the y-variable

_dyname: Name of the dy-variable

names: Variable names (read only). See getNames.

values: Variable values (read only). See getValues.

addProfileGenerator(gen, name=None)[source]

Add a ProfileGenerator to be used by this FitContribution.

The ProfileGenerator is given a name so that it can be used as part of the profile equation (see setEquation). This can be different from the name of the ProfileGenerator used for attribute access. FitContributions should not share ProfileGenerator instances. Different ProfileGenerators can share Parameters and ParameterSets, however.

Calling addProfileGenerator sets the profile equation to call the calculator and if there is not a profile equation already.

gen: A ProfileGenerator instance

name: A name for the calculator. If name is None (default), then the ProfileGenerator’s name attribute will be used.

Raises ValueError if the ProfileGenerator has no name. Raises ValueError if the ProfileGenerator has the same name as some other managed object.

evaluate()[source]: Evaluate the contribution equation and update profile.ycalc.

getEquation()[source]

Get math expression string for the active profile equation.

Return normalized math expression or an empty string if profile equation has not been set yet.

getResidualEquation()[source]

Get math expression string for the active residual equation.

Return normalized math formula or an empty string if residual equation has not been configured yet.

residual()[source]

Calculate the residual for this fitcontribution.

When this method is called, it is assumed that all parameters have been assigned their most current values by the FitRecipe. This will be the case when being called as part of a FitRecipe refinement.

The residual is by default an array chiv: chiv = (eq() - self.profile.y) / self.profile.dy The value that is optimized is dot(chiv, chiv).

The residual equation can be changed with the setResidualEquation method.

setEquation(eqstr, ns={})[source]

Set the profile equation for the FitContribution.

This sets the equation that will be used when generating the residual for this FitContribution. The equation will be usable within setResidualEquation as “eq”, and it takes no arguments.

eqstr: A string representation of the equation. Any Parameter registered by addParameter or setProfile, or function registered by setCalculator, registerFunction or registerStringFunction can be can be used in the equation by name. Other names will be turned into Parameters of this FitContribution.

ns: A dictionary of Parameters, indexed by name, that are used in the eqstr, but not registered (default {}).

Raises ValueError if ns uses a name that is already used for a variable.

setProfile(profile, xname=None, yname=None, dyname=None)[source]

Assign the Profile for this FitContribution.

profile: A Profile that specifies the calculation points and that will store the calculated signal.

xname: The name of the independent variable from the Profile. If this is None (default), then the name specified by the Profile for this parameter will be used. This variable is usable within string equations with the specified name.

yname: The name of the observed Profile. If this is None (default), then the name specified by the Profile for this parameter will be used. This variable is usable within string equations with the specified name.

dyname: The name of the uncertainty in the observed Profile. If this is None (default), then the name specified by the Profile for this parameter will be used. This variable is usable within string equations with the specified name.

setResidualEquation(eqstr)[source]

Set the residual equation for the FitContribution.

eqstr: A string representation of the residual. If eqstr is None (default), then the previous residual equation will be used, or the chi2 residual will be used if that does not exist.

Two residuals are preset for convenience, “chiv” and “resv”. chiv is defined such that dot(chiv, chiv) = chi^2. resv is defined such that dot(resv, resv) = Rw^2. You can call on these in your residual equation. Note that the quantity that will be optimized is the summed square of the residual equation. Keep that in mind when defining a new residual or using the built-in ones.

Raises SrFitError if the Profile is not yet defined. Raises ValueError if eqstr depends on a Parameter that is not part of the FitContribution.

diffpy.srfit.fitbase.fithook module

The FitHook class for inspecting the progress of a FitRecipe refinement.

FitHooks are called by a FitRecipe during various times of the residual is evaluation. The default FitHook simply counts the number of times the residual is called, and reports that number every time the residual is calculated. Depending on the verbosity, it will also report the residual and the current variable values.

Custom FitHooks can be added to a FitRecipe with the FitRecipe.setFitHook method.

class diffpy.srfit.fitbase.fithook.FitHook[source]

Bases: object

Base class for inspecting the progress of a FitRecipe refinement.

Can serve as a fithook for the FitRecipe class (see FitRecipe.pushFitHook method.) The methods in this class are called during the preparation of the FitRecipe for refinement, and during the residual call. See the class methods for a description of their purpose.

postcall(recipe, chiv)[source]

This is called within FitRecipe.residual, after the calculation.

recipe: The FitRecipe instance

chiv: The residual vector

precall(recipe)[source]

This is called within FitRecipe.residual, before the calculation.

recipe: The FitRecipe instance

reset(recipe)[source]

Reset the hook data.

This is called whenever FitRecipe._prepare is called, which is whenever a configurational change to the fit hierarchy takes place, such as adding a new ParameterSet, constraint or restraint.

diffpy.srfit.fitbase.fitrecipe module

FitRecipe class.

FitRecipes organize FitContributions, variables, Restraints and Constraints to create a recipe of the system you wish to optimize. From the client’s perspective, the FitRecipe is a residual calculator. The residual method does the work of updating variable values, which get propagated to the Parameters of the underlying FitContributions via the variables and Constraints. This class needs no special knowledge of the type of FitContribution or data being used. Thus, it is suitable for combining residual equations from various types of refinements into a single residual.

Variables added to a FitRecipe can be tagged with string identifiers. Variables can be later retrieved or manipulated by tag. The tag name “__fixed” is reserved.

See the examples in the documentation for how to create an optimization problem using FitRecipe.

class diffpy.srfit.fitbase.fitrecipe.FitRecipe(name='fit')[source]

Bases: FitRecipeInterface, RecipeOrganizer

FitRecipe class.

name: A name for this FitRecipe.

fithooks: List of FitHook instances that can pass information out of the system during a refinement. By default, the is populated by a PrintFitHook instance.

_constraints: A dictionary of Constraints, indexed by the constrained Parameter. Constraints can be added using the ‘constrain’ method.

_oconstraints: An ordered list of the constraints from this and all sub-components.

_calculators: A managed dictionary of Calculators.

_contributions: A managed OrderedDict of FitContributions.

_parameters: A managed OrderedDict of parameters (in this case the parameters are varied).

_parsets: A managed dictionary of ParameterSets.

_eqfactory: A diffpy.srfit.equation.builder.EquationFactory instance that is used to create constraints and restraints from string

_restraintlist: A list of restraints from this and all sub-components.

_restraints: A set of Restraints. Restraints can be added using the ‘restrain’ or ‘confine’ methods.

_ready: A flag indicating if all attributes are ready for the calculation.

_tagmanager: A TagManager instance for managing tags on Parameters.

_weights: List of weighing factors for each FitContribution. The weights are multiplied by the residual of the FitContribution when determining the overall residual.

_fixedtag: “__fixed”, used for tagging variables as fixed. Don’t use this tag unless you want issues.

names: Variable names (read only). See getNames.

values: Variable values (read only). See getValues.

fixednames: Names of the fixed refinable variables (read only).

fixedvalues: Values of the fixed refinable variables (read only).

bounds: Bounds on parameters (read only). See getBounds.

bounds2: Bounds on parameters (read only). See getBounds2.

addContribution(con, weight=1.0)[source]

Add a FitContribution to the FitRecipe.

con: The FitContribution to be stored.

Raises ValueError if the FitContribution has no name Raises ValueError if the FitContribution has the same name as some other managed object.

addParameterSet(parset)[source]

Add a ParameterSet to the hierarchy.

parset: The ParameterSet to be stored.

Raises ValueError if the ParameterSet has no name. Raises ValueError if the ParameterSet has the same name as some other managed object.

addVar(par, value=None, name=None, fixed=False, tag=None, tags=[])[source]

Add a variable to be refined.

par: A Parameter that will be varied during a fit.

value: An initial value for the variable. If this is None (default), then the current value of par will be used.

name: A name for this variable. If name is None (default), then the name of the parameter will be used.

fixed: Fix the variable so that it does not vary (default False).

tag: A tag for the variable. This can be used to retrieve, fix or free variables by tag (default None). Note that a variable is automatically tagged with its name and “all”.

tags: A list of tags (default []). Both tag and tags can be applied.

Returns:: ParameterProxy (variable) for the passed Parameter.
Return type:: vars

Raises ValueError if the name of the variable is already taken by another managed object. Raises ValueError if par is constant. Raises ValueError if par is constrained.

property bounds

property bounds2

boundsToRestraints(sig=1, scaled=False)[source]

Turn all bounded parameters into restraints.

The bounds become limits on the restraint.

sig: The uncertainty on the bounds (scalar or iterable, default 1).

scaled: Scale the restraints, see restrain.

clearFitHooks()[source]: Clear the FitHook sequence.

constrain(par, con, ns={})[source]

Constrain a parameter to an equation.

Note that only one constraint can exist on a Parameter at a time.

This is overloaded to set the value of con if it represents a variable and its current value is None. A constrained variable will be set as fixed.

par: The Parameter to constrain.

con: A string representation of the constraint equation or a Parameter to constrain to. A constraint equation must consist of numpy operators and “known” Parameters. Parameters are known if they are in the ns argument, or if they are managed by this object.

ns: A dictionary of Parameters, indexed by name, that are used in the eqstr, but not part of this object (default {}).

Raises ValueError if ns uses a name that is already used for a variable. Raises ValueError if eqstr depends on a Parameter that is not part of the FitRecipe and that is not defined in ns. Raises ValueError if par is marked as constant.

delVar(var)[source]

Remove a variable.

Note that constraints and restraints involving the variable are not modified.

var: A variable of the FitRecipe.

Raises ValueError if var is not part of the FitRecipe.

fix(*args, **kw)[source]

Fix a parameter by reference, name or tag.

A fixed variable is not refined. Variables are free by default.

This method accepts string or variable arguments. An argument of “all” selects all variables. Keyword arguments must be parameter names, followed by a value to assign to the fixed variable.

Raises ValueError if an unknown Parameter, name or tag is passed, or if a tag is passed in a keyword.

property fixednames: names of the fixed refinable variables

property fixedvalues: values of the fixed refinable variables

free(*args, **kw)[source]

Free a parameter by reference, name or tag.

A free variable is refined. Variables are free by default. Constrained variables are not free.

This method accepts string or variable arguments. An argument of “all” selects all variables. Keyword arguments must be parameter names, followed by a value to assign to the fixed variable.

Raises ValueError if an unknown Parameter, name or tag is passed, or if a tag is passed in a keyword.

getBounds()[source]

Get the bounds on variables in a list.

Returns a list of (lb, ub) pairs, where lb is the lower bound and ub is the upper bound.

getBounds2()[source]

Get the bounds on variables in two lists.

Returns lower- and upper-bound lists of variable bounds.

getFitHooks()[source]: Get the sequence of FitHook instances.

getNames()[source]: Get the names of the variables in a list.

getValues()[source]: Get the current values of the variables in a list.

isFree(var)[source]: Check if a variable is fixed.

newVar(name, value=None, fixed=False, tag=None, tags=[])[source]

Create a new variable of the fit.

This method lets new variables be created that are not tied to a Parameter. Orphan variables may cause a fit to fail, depending on the optimization routine, and therefore should only be created to be used in constraint or restraint equations.

name: The name of the variable. The variable will be able to be used by this name in restraint and constraint equations.

value: An initial value for the variable. If this is None (default), then the variable will be given the value of the first non-None-valued Parameter constrained to it. If this fails, an error will be thrown when ‘residual’ is called.

fixed: Fix the variable so that it does not vary (default False). The variable will still be managed by the FitRecipe.

tag: A tag for the variable. This can be used to fix and free variables by tag (default None). Note that a variable is automatically tagged with its name and “all”.

tags: A list of tags (default []). Both tag and tags can be applied.

Returns the new variable (Parameter instance).

popFitHook(fithook=None, index=-1)[source]

Remove a FitHook by index or reference.

fithook: FitHook instance to remove from the sequence. If this is None (default), default to index.

index: Index of FitHook instance to remove (default -1).

Raises ValueError if fithook is not None, but is not present in the sequence. Raises IndexError if the sequence is empty or index is out of range.

pushFitHook(fithook, index=None)[source]

Add a FitHook to be called within the residual method.

The hook is an object for reporting updates, or more fundamentally, passing information out of the system during a refinement. See the diffpy.srfit.fitbase.fithook.FitHook class for the required interface. Added FitHooks will be called sequentially during refinement.

fithook: FitHook instance to add to the sequence

index: Index for inserting fithook into the list of fit hooks. If this is None (default), the fithook is added to the end.

removeParameterSet(parset)[source]

Remove a ParameterSet from the hierarchy.

Raises ValueError if parset is not managed by this object.

residual(p=[])[source]

Calculate the vector residual to be optimized.

Parameters:

p – The list of current variable values, provided in the same order as the ‘_parameters’ list. If p is an empty iterable (default), then it is assumed that the parameters have already been updated in some other way, and the explicit update within this function is skipped.
each (The residual is by default the weighted concatenation of)
residual (FitContribution's)
array (plus the value of each restraint. The)
returned
chiv (denoted)
that (is such)
dot(chiv
restraints. (chiv) = chi^2 +)

scalarResidual(p=[])[source]

Calculate the scalar residual to be optimized.

Parameters:

p – The list of current variable values, provided in the same order as the ‘_parameters’ list. If p is an empty iterable (default), then it is assumed that the parameters have already been updated in some other way, and the explicit update within this function is skipped.
each (The residual is by default the weighted concatenation of)
residual (FitContribution's)
array (plus the value of each restraint. The)
returned
chiv (denoted)
that (is such)
dot(chiv
restraints. (chiv) = chi^2 +)

setWeight(con, weight)[source]: Set the weight of a FitContribution.

unconstrain(*pars)[source]

Unconstrain a Parameter.

This removes any constraints on a Parameter. If the Parameter is also a variable of the recipe, it will be freed as well.

\*pars: The names of Parameters or Parameters to unconstrain.

Raises ValueError if the Parameter is not constrained.

diffpy.srfit.fitbase.fitresults module

The FitResults and ContributionResults classes for storing results of a fit.

The FitResults class is used to display the current state of a FitRecipe. It stores the state, and uses it to calculate useful statistics, which can be displayed on screen or saved to file.

class diffpy.srfit.fitbase.fitresults.ContributionResults(con, weight, fitres)[source]

Bases: object

Class for processing, storing FitContribution results.

This does not store the FitContribution.

y: The FitContribution’s profile over the calculation range (default None).

dy: The uncertainty in the FitContribution’s profile over the calculation range (default None).

x: A numpy array of the calculated independent variable for the FitContribution (default None).

ycalc: A numpy array of the calculated signal for the FitContribution (default None).

residual: The scalar residual of the FitContribution.

chi2: The chi2 of the FitContribution.

cumchi2: The cumulative chi2 of the FitContribution.

rw: The Rw of the FitContribution.

cumrw: The cumulative Rw of the FitContribution.

weight: The weight of the FitContribution in the recipe.

conlocs: The location of the constrained parameters in the FitContribution (see the RecipeContainer._locateManagedObject method).

convals: Values of the constrained parameters.

conunc: Uncertainties in the constraint values.

class diffpy.srfit.fitbase.fitresults.FitResults(recipe, update=True, showfixed=True, showcon=False)[source]

Bases: object

Class for processing, presenting and storing results of a fit.

recipe: The recipe containing the results.

cov: The covariance matrix from the recipe.

conresults: An ordered dictionary of ContributionResults for each FitContribution, indexed by the FitContribution name.

derivstep: The fractional step size for calculating numeric derivatives. Default 1e-8.

varnames: Names of the variables in the recipe.

varvals: Values of the variables in the recipe.

varunc: Uncertainties in the variable values.

showfixed: Show fixed variables (default True).

fixednames: Names of the fixed variables of the recipe.

fixedvals: Values of the fixed variables of the recipe.

showcon: Show constraint values in the output (default False).

connames: Names of the constrained parameters.

convals: Values of the constrained parameters.

conunc: Uncertainties in the constraint values.

residual: The scalar residual of the recipe.

penalty: The penalty to residual from the restraints.

chi2: The chi2 of the recipe.

cumchi2: The cumulative chi2 of the recipe.

rchi2: The reduced chi2 of the recipe.

rw: The Rw of the recipe.

cumrw: The cumulative Rw of the recipe.

messages: A list of messages about the results.

precision: The precision of numeric output (default 8).

_dcon: The derivatives of the constraint equations with respect to the variables. This is used internally.

Each of these attributes, except the recipe, are created or updated when the update method is called.

formatResults(header='', footer='', update=False)[source]

Format the results and return them in a string.

This function is called by printResults and saveResults. Overloading the formatting here will change all three functions.

header: A header to add to the output (default “”)

footer: A footer to add to the output (default “”)

update[source]: Flag indicating whether to call update() (default False).

Returns:: a string containing the formatted results.
Return type:: out

printResults(header='', footer='', update=False)[source]

Format and print the results.

Parameters:

header – A header to add to the output (default “”)
footer – A footer to add to the output (default “”)
update – Flag indicating whether to call update() (default False).

saveResults(filename, header='', footer='', update=False)[source]

Format and save the results.

Parameters:

filename – Name of the save file.
header – A header to add to the output (default “”)
footer – A footer to add to the output (default “”)
update – Flag indicating whether to call update() (default False).

update()[source]: Update the results according to the current state of the recipe.

diffpy.srfit.fitbase.fitresults.initializeRecipe(recipe, results)[source]

Initialize the variables of a recipe from a results file.

This reads the results from file and initializes any variables (fixed or free) in the recipe to the results values. Note that the recipe has to be configured, with variables. This does not reconstruct a FitRecipe.

diffpy.srfit.fitbase.fitresults.recipe: A configured recipe with variables

diffpy.srfit.fitbase.fitresults.results: An open file-like object, name of a file that contains results from FitResults or a string containing fit results.

diffpy.srfit.fitbase.parameter module

Parameter classes.

Parameters encapsulate an adjustable parameter within SrFit.

class diffpy.srfit.fitbase.parameter.Parameter(name, value=None, const=False)[source]

Bases: ParameterInterface, Argument, Validatable

Parameter class.

name: A name for this Parameter.

const: A flag indicating whether this is considered a constant.

_value: The value of the Parameter. Modified with ‘setValue’.

value: Property for ‘getValue’ and ‘setValue’.

constrained: A flag indicating if the Parameter is constrained (default False).

bounds: A 2-list defining the bounds on the Parameter. This can be used by some optimizers when the Parameter is varied. See FitRecipe.getBounds and FitRecipe.boundsToRestraints.

boundRange(lb=None, ub=None)[source]

Set lower and upper bound of the Parameter.

lb: The lower bound for the bounds list.

ub: The upper bound for the bounds list.

Returns:: Returns self so that mutators can be chained.
Return type:: self

boundWindow(lr=0, ur=None)[source]

Create bounds centered on the current value of the Parameter.

lr: The radius of the lower bound (default 0). The lower bound is computed as value - lr.

ur: The radius of the upper bound. The upper bound is computed as value + ur. If this is None (default), then the value of the lower radius is used.

Returns:: Returns self so that mutators can be chained.
Return type:: self

setConst(const=True, value=None)[source]

Toggle the Parameter as constant.

const: Flag indicating if the parameter is constant (default True).

value: An optional value for the parameter (default None). If this is not None, then the parameter will get a new value, constant or otherwise.

Returns:: Returns self so that mutators can be chained.
Return type:: self

setValue(val)[source]

Set the value of the Parameter and the bounds.

val: The value to assign.

lb: The lower bounds for the bounds list. If this is None (default), then the lower bound will not be alterered.

ub: The upper bounds for the bounds list. If this is None (default), then the upper bound will not be alterered.

Returns:: Returns self so that mutators can be chained.
Return type:: self

class diffpy.srfit.fitbase.parameter.ParameterAdapter(name, obj, getter=None, setter=None, attr=None)[source]

Bases: Parameter

An adapter for parameter-like objects.

This class wraps an object as a Parameter. The getValue and setValue methods defer to the data of the wrapped object.

getValue()[source]: Get the value of the Parameter.

setValue(value)[source]: Set the value of the Parameter.

class diffpy.srfit.fitbase.parameter.ParameterProxy(name, par)[source]

Bases: Parameter

A Parameter proxy for another parameter.

This allows for the same parameter to have multiple names.

name: A name for this ParameterProxy. Names should be unique within a RecipeOrganizer and should be valid attribute names.

par: The Parameter this is a proxy for.

boundRange(lb=None, ub=None)[source]

Set lower and upper bound of the Parameter.

lb: The lower bound for the bounds list.

ub: The upper bound for the bounds list.

Returns:: Returns self so that mutators can be chained.
Return type:: self

boundWindow(lr=0, ur=None)[source]

Create bounds centered on the current value of the Parameter.

lr: The radius of the lower bound (default 0). The lower bound is computed as value - lr.

ur: The radius of the upper bound. The upper bound is computed as value + ur. If this is None (default), then the value of the lower radius is used.

Returns:: Returns self so that mutators can be chained.
Return type:: self

property bounds

List of lower and upper bounds of the proxied Parameter.

This can be used by some optimizers when the Parameter is varied. See FitRecipe.getBounds and FitRecipe.boundsToRestraints.

property constrained: A flag indicating if the proxied Parameter is constrained.

getValue(): Get the value of this Literal.

setConst(const=True, value=None)[source]

Toggle the Parameter as constant.

const: Flag indicating if the parameter is constant (default True).

value: An optional value for the parameter (default None). If this is not None, then the parameter will get a new value, constant or otherwise.

Returns:: Returns self so that mutators can be chained.
Return type:: self

setValue(val)[source]

Set the value of the Parameter and the bounds.

val: The value to assign.

lb: The lower bounds for the bounds list. If this is None (default), then the lower bound will not be alterered.

ub: The upper bounds for the bounds list. If this is None (default), then the upper bound will not be alterered.

Returns:: Returns self so that mutators can be chained.
Return type:: self

diffpy.srfit.fitbase.parameterset module

ParameterSet class.

ParameterSets organize Parameters, Constraints, Restraints and other ParameterSets. They provide attribute-access of other ParameterSets and embedded Parameters.

class diffpy.srfit.fitbase.parameterset.ParameterSet(name)[source]

Bases: RecipeOrganizer

Class for organizing Parameters and other ParameterSets.

ParameterSets are hierarchical organizations of Parameters, Constraints, Restraints and other ParameterSets.

Contained Parameters and other ParameterSets can be accessed by name as attributes in order to facilitate multi-level constraints and restraints. These constraints and restraints can be placed at any level and a flattened list of them can be retrieved with the getConstraints and getRestraints methods.

name: A name for this organizer.

_calculators: A managed dictionary of Calculators, indexed by name.

_constraints: A set of constrained Parameters. Constraints can be added using the ‘constrain’ methods.

_parameters: A managed OrderedDict of parameters.

_restraints: A set of Restraints. Restraints can be added using the ‘restrain’ methods.

_parsets: A managed dictionary of ParameterSets.

_eqfactory: A diffpy.srfit.equation.builder.EquationFactory instance that is used to create constraints and restraints from string equations.

names: Variable names (read only). See getNames.

values: Variable values (read only). See getValues.

addParameter(par, check=True)

Store a Parameter.

Parameters added in this way are registered with the _eqfactory.

par: The Parameter to be stored.

check: If True (default), a ValueError is raised a Parameter of the specified name has already been inserted.

Raises ValueError if the Parameter has no name. Raises ValueError if the Parameter has the same name as a contained RecipeContainer.

addParameterSet(parset)[source]

Add a ParameterSet to the hierarchy.

parset: The ParameterSet to be stored.

Raises ValueError if the ParameterSet has no name. Raises ValueError if the ParameterSet has the same name as some other managed object.

newParameter(name, value, check=True)

Add a new Parameter to the container.

This creates a new Parameter and adds it to the container using the _addParameter method.

Returns the Parameter.

removeParameter(par)

Remove a parameter.

This de-registers the Parameter with the _eqfactory. The Parameter will remain part of built equations.

Note that constraints and restraints involving the Parameter are not modified.

Raises ValueError if par is not part of the RecipeOrganizer.

removeParameterSet(parset)[source]

Remove a ParameterSet from the hierarchy.

Raises ValueError if parset is not managed by this object.

setConst(const=True)[source]

Set every parameter within the set to a constant.

const: Flag indicating if the parameter is constant (default True).

diffpy.srfit.fitbase.profile module

The Profile class containing the physical and calculated data.

Profile holds the arrays representing an observed profile, a selected subset of the observed profile and a calculated profile. Profiles are used by Calculators to store a calculated signal, and by FitContributions to help calculate a residual equation.

class diffpy.srfit.fitbase.profile.Parameter(name, value=None, const=False)[source]

Bases: ParameterInterface, Argument, Validatable

Parameter class.

name: A name for this Parameter.

const: A flag indicating whether this is considered a constant.

_value: The value of the Parameter. Modified with ‘setValue’.

value: Property for ‘getValue’ and ‘setValue’.

constrained: A flag indicating if the Parameter is constrained (default False).

bounds: A 2-list defining the bounds on the Parameter. This can be used by some optimizers when the Parameter is varied. See FitRecipe.getBounds and FitRecipe.boundsToRestraints.

boundRange(lb=None, ub=None)[source]

Set lower and upper bound of the Parameter.

lb: The lower bound for the bounds list.

ub: The upper bound for the bounds list.

Returns:: Returns self so that mutators can be chained.
Return type:: self

boundWindow(lr=0, ur=None)[source]

Create bounds centered on the current value of the Parameter.

lr: The radius of the lower bound (default 0). The lower bound is computed as value - lr.

ur: The radius of the upper bound. The upper bound is computed as value + ur. If this is None (default), then the value of the lower radius is used.

Returns:: Returns self so that mutators can be chained.
Return type:: self

setConst(const=True, value=None)[source]

Toggle the Parameter as constant.

const: Flag indicating if the parameter is constant (default True).

value: An optional value for the parameter (default None). If this is not None, then the parameter will get a new value, constant or otherwise.

Returns:: Returns self so that mutators can be chained.
Return type:: self

setValue(val)[source]

Set the value of the Parameter and the bounds.

val: The value to assign.

lb: The lower bounds for the bounds list. If this is None (default), then the lower bound will not be alterered.

ub: The upper bounds for the bounds list. If this is None (default), then the upper bound will not be alterered.

Returns:: Returns self so that mutators can be chained.
Return type:: self

class diffpy.srfit.fitbase.profile.Profile[source]

Bases: Observable, Validatable

Observed and calculated profile container.

Profile is an Observable. The xpar, ypar and dypar attributes are observed by the Profile, which can in turn be observed by some other object.

Attributes

_xobs: A numpy array of the observed independent variable (default None)

xobs: Read-only property of _xobs.

_yobs: A numpy array of the observed signal (default None)

yobs: Read-only property of _yobs.

_dyobs: A numpy array of the uncertainty of the observed signal (default None, optional).

dyobs: Read-only property of _dyobs.

x: A numpy array of the calculated independent variable (default None, property for xpar accessors).

y: The profile over the calculation range (default None, property for ypar accessors).

dy: The uncertainty in the profile over the calculation range (default None, property for dypar accessors).

ycalc: A numpy array of the calculated signal (default None).

xpar: A Parameter that stores x (named “x”).

ypar: A Parameter that stores y (named “y”).

dypar: A Parameter that stores dy (named “dy”).

ycpar: A Parameter that stores ycalc (named “ycalc”). This is not observed by the profile, but it is present so it can be constrained to.

meta: A dictionary of metadata. This is only set if provided by a parser.

property dy

property dyobs

loadParsedData(parser)[source]

Load parsed data from a ProfileParser.

This sets the xobs, yobs, dyobs arrays as well as the metadata.

loadtxt(*args, **kw)[source]

Use numpy.loadtxt to load data.

Arguments are passed to numpy.loadtxt. unpack = True is enforced. The first two arrays returned by numpy.loadtxt are assumed to be x and y. If there is a third array, it is assumed to by dy. Any other arrays are ignored. These are passed to setObservedProfile.

Raises ValueError if the call to numpy.loadtxt returns fewer than 2 arrays.

Returns:

x – x array loaded from the file.
y – y array loaded from the file.
dy – dy array loaded from the file.

savetxt(fname, **kwargs)[source]

Call numpy.savetxt with x, ycalc, y, dy.

Parameters:

fname (filename or file handle) – This is passed to numpy.savetxt.
**kwargs – The keyword arguments that are passed to numpy.savetxt. We preset file header “x ycalc y dy”. Use header='' to save data without any header.

Raises:

SrFitError – When self.ycalc has not been set.

diffpy.srfit.fitbase.profilegenerator module

The ProfileGenerator class for generating a profile.

ProfileGenerators encapsulate the evaluation and required Parameters and ParameterSets of a profile calculator. The ProfileGenerator class can be associated with a FitContribution to help calculate a profile.

To define a ProfileGenerator, one must implement the required Parameters and ParameterSets as well as overload the __call__ method with the calculation. A very simple example is

class Gaussian(ProfileGenerator):
    def __init__(self):
        # Initialize and give this a name
        ProfileGenerator.__init__(self, "g")
        # Add amplitude, center and width parameters
        self.newParameter("amp", 0)
        self.newParameter("center", 0)
        self.newParameter("width", 0)
    def __call__(self, x):
        a = self.amp.getValue()
        x0 = self.center.getValue()
        w = self.width.getValue()
        return a * exp(-0.5*((x-x0)/w)**2)

More examples can be found in the example directory of the documentation.

class diffpy.srfit.fitbase.profilegenerator.ProfileGenerator(name)[source]

Bases: Operator, ParameterSet

Base class for profile generators.

A ProfileGenerator organizes Parameters and has a __call__ method that can generate a profile. ProfileGenerator is also an Operator (diffpy.srfit.equation.literals.operators), so it can be used directly in an evaluation network.

name: A name for this organizer.

profile: A Profile instance that contains the calculation range and will contain the generated profile.

meta: A dictionary of metadata needed by the generator.

eq: The Equation object used to wrap this ProfileGenerator. This is set when the ProfileGenerator is added to a FitContribution.

_calculators: A managed dictionary of Calculators, indexed by name.

_constraints: A set of constrained Parameters. Constraints can be added using the ‘constrain’ methods.

_parameters: A managed OrderedDict of contained Parameters.

_parsets: A managed dictionary of ParameterSets.

_restraints: A set of Restraints. Restraints can be added using the ‘restrain’ or ‘confine’ methods.

_eqfactory: A diffpy.srfit.equation.builder.EquationFactory instance that is used create Equations from string.

args: List of Literal arguments, set with ‘addLiteral’

name: A name for this operator. e.g. “add” or “sin”

nin: Number of inputs (<1 means this is variable)

nout: Number of outputs

operation[source]: Function that performs the operation. e.g. numpy.add. In this case, operation is an instance method.

symbol: The symbolic representation. e.g. “+” or “sin”

_value: The value of the Operator.

value: Property for ‘getValue’.

names: Variable names (read only). See getNames.

values: Variable values (read only). See getValues.

nin = 0

nout = 1

operation()[source]

Evaluate the profile.

Return the result of __call__(profile.x).

processMetaData()[source]

Process the metadata.

This can be used to configure a ProfileGenerator upon a change in the metadata. This method gets called whenever the Profile is set.

setProfile(profile)[source]

Assign the profile.

profile: A Profile that specifies the calculation points and which will store the calculated signal.

property symbol

diffpy.srfit.fitbase.profileparser module

This module contains classes for parsing profiles from files.

ProfileParser is a base class for parsing data. It can interact with a Profile object to automatically set the Profile’s data and metadata. Each specific file format must be encapsulated in a ProfileParser subclass.

See the class documentation for more information.

class diffpy.srfit.fitbase.profileparser.ProfileParser[source]

Bases: object

Class for parsing data from a or string.

_format: Name of the data format that this parses (string, default “”). The format string is a unique identifier for the data format handled by the parser.

_banks

The data from each bank. Each bank contains a (x, y, dx, dy) tuple: x

A numpy array containing the independent variable read from the file.

y: A numpy array containing the profile from the file.
dx: A numpy array containing the uncertainty in x read from the file. This is None if the uncertainty cannot be read.
dy: A numpy array containing the uncertainty read from the file. This is None if the uncertainty cannot be read.

_x: Independent variable from the chosen bank

_y: Profile from the chosen bank

_dx: Uncertainty in independent variable from the chosen bank

_dy: Uncertainty in profile from the chosen bank

_meta: A dictionary containing metadata read from the file.

filename: The name of the file from which data was parsed. This key will not exist if data was not read from file.

nbanks: The number of banks parsed.

bank: The chosen bank number.

getData(index=None)[source]

Get the data.

This method should only be called after the data has been parsed. The chosen bank number is not persistent, and so must be re-selected if the parser is used to parse more data. This uses python list notation, so index -n returns the nth bank from the end.

Parameters:

index – index of bank (integer, starting at 0, default None). If index is None then the currently selected bank is used.
(x (This returns)
y
dx
cannot (dy) tuple for the bank. dx is 0 if it)
format. (be determined from the data)

getFormat()[source]: Get the format string.

getMetaData()[source]: Get the parsed metadata.

getNumBanks()[source]: Get the number of banks read by the parser.

parseFile(filename)[source]

Parse a file and set the _x, _y, _dx, _dy and _meta variables.

This wipes out the currently loaded data and selected bank number.

Parameters:

filename – The name of the file to parse
read (Raises IOError if the file cannot be)
parsed (Raises ParseError if the file cannot be)

parseString(patstring)[source]

Parse a string and set the _x, _y, _dx, _dy and _meta variables.

When _dx or _dy cannot be obtained in the data format it is set to None.

This wipes out the currently loaded data and selected bank number.

Parameters:

patstring – A string containing the pattern
parsed (Raises ParseError if the string cannot be)

selectBank(index)[source]

Select which bank to use.

This method should only be called after the data has been parsed. The chosen bank number is not persistent, and so must be re-selected if the parser is used to parse more data. This uses python list notation, so index -n returns the nth bank from the end.

Parameters:

index – index of bank (integer, starting at 0).
exist (Raises IndexError if requesting a bank that does not)

diffpy.srfit.fitbase.recipeorganizer module

Base classes and tools for constructing a FitRecipe.

RecipeContainer is the base class for organizing Parameters, and other RecipeContainers. RecipeOrganizer is an extended RecipeContainer that incorporates equation building, constraints and Restraints. equationFromString creates an Equation instance from a string.

class diffpy.srfit.fitbase.recipeorganizer.RecipeContainer(name)[source]

Bases: Observable, Configurable, Validatable

Base class for organizing pieces of a FitRecipe.

RecipeContainers are hierarchical organizations of Parameters and other RecipeContainers. This class provides attribute-access to these contained objects. Parameters and other RecipeContainers can be found within the hierarchy with the _locateManagedObject method.

A RecipeContainer can manage dictionaries for that store various objects. These dictionaries can be added to the RecipeContainer using the _manage method. RecipeContainer methods that add, remove or retrieve objects will work with any managed dictionary. This makes it easy to add new types of objects to be contained by a RecipeContainer. By default, the RecipeContainer is configured to manage an OrderedDict of Parameter objects.

RecipeContainer is an Observable, and observes its managed objects and Parameters. This allows hierarchical calculation elements, such as ProfileGenerator, to detect changes in Parameters and Restraints on which it may depend.

name: A name for this RecipeContainer. Names should be unique within a RecipeContainer and should be valid attribute names.

_parameters: A managed OrderedDict of contained Parameters.

__managed: A list of managed dictionaries. This is used for attribute access, addition and removal.

_configobjs: A set of configurable objects that must know of configuration changes within this object.

names: Variable names (read only). See getNames.

values: Variable values (read only). See getValues.

get(name, default=None)[source]: Get a managed object.

getNames()[source]: Get the names of managed parameters.

getValues()[source]: Get the values of managed parameters.

iterPars(pattern='', recurse=True)[source]

Iterate over the Parameters contained in this object.

Parameters:

pattern (str) – Iterate over parameters with names matching this regular expression (all parameters by default).
recurse (bool) – Recurse into managed objects when True (default).

property names

property values

class diffpy.srfit.fitbase.recipeorganizer.RecipeOrganizer(name)[source]

Bases: RecipeOrganizerInterface, RecipeContainer

Extended base class for organizing pieces of a FitRecipe.

This class extends RecipeContainer by organizing constraints and Restraints, as well as Equations that can be used in Constraint and Restraint equations. These constraints and Restraints can be placed at any level and a flattened list of them can be retrieved with the _getConstraints and _getRestraints methods.

name: A name for this organizer. Names should be unique within a RecipeOrganizer and should be valid attribute names.

_calculators: A managed dictionary of Calculators, indexed by name.

_parameters: A managed OrderedDict of contained Parameters.

_constraints: A dictionary of Constraints, indexed by the constrained Parameter. Constraints can be added using the ‘constrain’ method.

_restraints: A set of Restraints. Restraints can be added using the ‘restrain’ method.

_eqfactory: A diffpy.srfit.equation.builder.EquationFactory instance that is used create Equations from string.

names: Variable names (read only). See getNames.

values: Variable values (read only). See getValues.

Raises ValueError if the name is not a valid attribute identifier

addRestraint(res)[source]

Add a Restraint instance to the RecipeOrganizer.

res: A Restraint instance.

clearConstraints(recurse=False)[source]

Clear all constraints managed by this organizer.

recurse: Recurse into managed objects and clear all constraints found there as well.

This removes constraints that are held in this organizer, no matter where the constrained parameters are from.

clearRestraints(recurse=False)[source]

Clear all restraints.

recurse: Recurse into managed objects and clear all restraints found there as well.

constrain(par, con, ns={})[source]

Constrain a parameter to an equation.

Note that only one constraint can exist on a Parameter at a time.

par: The name of a Parameter or a Parameter to constrain.

con: A string representation of the constraint equation or a Parameter to constrain to. A constraint equation must consist of numpy operators and “known” Parameters. Parameters are known if they are in the ns argument, or if they are managed by this object.

ns: A dictionary of Parameters, indexed by name, that are used in the parameter, but not part of this object (default {}).

Raises ValueError if ns uses a name that is already used for a variable. Raises ValueError if par is a string but not part of this object or in ns. Raises ValueError if par is marked as constant.

evaluateEquation(eqstr, ns={})[source]

Evaluate a string equation.

eqstr: A string equation to evaluate. The equation is evaluated at the current value of the registered Parameters.

ns: A dictionary of Parameters, indexed by name, that are used in fstr, but not part of the FitRecipe (default {}).

Raises ValueError if ns uses a name that is already used for a variable.

getConstrainedPars(recurse=False)[source]

Get a list of constrained managed Parameters in this object.

recurse: Recurse into managed objects and retrieve their constrained Parameters as well (default False).

isConstrained(par)[source]

Determine if a Parameter is constrained in this object.

par: The name of a Parameter or a Parameter to check.

registerCalculator(f, argnames=None)[source]

Register a Calculator so it can be used within equation strings.

A Calculator is an elaborate function that can organize Parameters. This creates a function with this class that can be used within string equations. The resulting equation can be used in a string with arguments like a function or without, in which case the values of the Parameters created from argnames will be be used to compute the value.

f: The Calculator to register.

argnames: The names of the arguments to f (list or None). If this is None, then the argument names will be extracted from the function.

registerFunction(f, name=None, argnames=None)[source]

Register a function so it can be used within equation strings.

This creates a function with this class that can be used within string equations. The resulting equation does not require the arguments to be passed in the equation string, as this will be handled automatically.

f: The callable to register. If this is an Equation instance, then all that needs to be provided is a name.

name: The name of the function to be used in equations. If this is None (default), the method will try to determine the name of the function automatically.

argnames: The names of the arguments to f (list or None). If this is None (default), then the argument names will be extracted from the function.

Note that name and argnames can be extracted from regular python functions (of type ‘function’), bound class methods and callable classes.

Raises TypeError if name or argnames cannot be automatically extracted. Raises TypeError if an automatically extracted name is ‘<lambda>’. Raises ValueError if f is an Equation object and name is None.

Returns the callable Equation object.

registerStringFunction(fstr, name, ns={})[source]

Register a string function.

This creates a function with this class that can be used within string equations. The resulting equation does not require the arguments to be passed in the function string, as this will be handled automatically.

fstr: A string equation to register.

name: The name of the function to be used in equations.

ns: A dictionary of Parameters, indexed by name, that are used in fstr, but not part of the FitRecipe (default {}).

Raises ValueError if ns uses a name that is already used for another managed object. Raises ValueError if the function name is the name of another managed object.

Returns the callable Equation object.

restrain(res, lb=-inf, ub=inf, sig=1, scaled=False, ns={})[source]

Restrain an expression to specified bounds.

res: An equation string or Parameter to restrain.

lb: The lower bound on the restraint evaluation (default -inf).

ub: The lower bound on the restraint evaluation (default inf).

sig: The uncertainty on the bounds (default 1).

scaled: A flag indicating if the restraint is scaled (multiplied) by the unrestrained point-average chi^2 (chi^2/numpoints) (default False).

ns: A dictionary of Parameters, indexed by name, that are used in the equation string, but not part of the RecipeOrganizer (default {}).

The penalty is calculated as (max(0, lb - val, val - ub)/sig)**2 and val is the value of the calculated equation. This is multiplied by the average chi^2 if scaled is True.

Raises ValueError if ns uses a name that is already used for a Parameter. Raises ValueError if res depends on a Parameter that is not part of the RecipeOrganizer and that is not defined in ns.

Returns the Restraint object for use with the ‘unrestrain’ method.

show(pattern='', textwidth=78)[source]

Show the configuration hierarchy on the screen.

This will print out a summary of all contained objects.

Parameters:

pattern (str, optional) – Limit output to only those parameters that match this regular expression (match all by default).
textwidth (int, optional) – Trim formatted lines at this text width to avoid folding at the screen width. Do not trim when negative or 0.

unconstrain(*pars)[source]

Unconstrain a Parameter.

This removes any constraints on a Parameter.

\*pars: The names of Parameters or Parameters to unconstrain.

Raises ValueError if the Parameter is not constrained.

unrestrain(*ress)[source]

Remove a Restraint from the RecipeOrganizer.

\*ress: Restraints returned from the ‘restrain’ method or added with the ‘addRestraint’ method.

diffpy.srfit.fitbase.recipeorganizer.equationFromString(eqstr, factory, ns={}, buildargs=False, argclass=<class 'diffpy.srfit.fitbase.parameter.Parameter'>, argkw={})[source]

Make an equation from a string.

diffpy.srfit.fitbase.recipeorganizer.eqstr: A string representation of the equation. The equation must consist of numpy operators and “known” Parameters. Parameters are known if they are in ns, or already defined in the factory.

diffpy.srfit.fitbase.recipeorganizer.factory: An EquationFactory instance.

diffpy.srfit.fitbase.recipeorganizer.ns: A dictionary of Parameters indexed by name that are used in the eqstr but not already defined in the factory (default {}).

diffpy.srfit.fitbase.recipeorganizer.buildargs: A flag indicating whether missing Parameters can be created by the Factory (default False). If False, then the a ValueError will be raised if there are undefined arguments in the eqstr.

diffpy.srfit.fitbase.recipeorganizer.argclass: Class to use when creating new Arguments (default Parameter). The class constructor must accept the ‘name’ key word.

diffpy.srfit.fitbase.recipeorganizer.argkw: Key word dictionary to pass to the argclass constructor (default {}).

Raises ValueError if ns uses a name that is already defined in the factory. Raises ValueError if the equation has undefined parameters.

diffpy.srfit.fitbase.restraint module

Restraints class.

Restraints are used by RecipeOrganizers to organize restraint equations. Restraints store an Equation, bounds on its value, and the form of the penalty function for breaking a restraint. This penalty is added to the residual equation calculated by a FitRecipe.

class diffpy.srfit.fitbase.restraint.Restraint(eq, lb=-inf, ub=inf, sig=1, scaled=False)[source]

Bases: Validatable

Restraint class.

eq: An equation whose evaluation is compared against the restraint bounds.

lb: The lower bound on the restraint evaluation (default -inf).

ub: The lower bound on the restraint evaluation (default inf).

sig: The uncertainty on the bounds (default 1).

scaled: A flag indicating if the restraint is scaled (multiplied) by the unrestrained point-average chi^2 (chi^2/numpoints) (default False).

The penalty is calculated as (max(0, lb - val, val - ub)/sig)**2 and val is the value of the calculated equation. This is multiplied by the average chi^2 if scaled is True.

penalty(w=1.0)[source]

Calculate the penalty of the restraint.

w: The point-average chi^2 which is optionally used to scale the penalty (default 1.0).

Returns:: Returns the penalty as a float
Return type:: penalty

diffpy.srfit.fitbase.simplerecipe module

Simple FitRecipe class that includes a FitContribution and Profile.

class diffpy.srfit.fitbase.simplerecipe.SimpleRecipe(name='fit', conclass=<class 'diffpy.srfit.fitbase.fitcontribution.FitContribution'>)[source]

Bases: FitRecipe

SimpleRecipe class.

This is a FitRecipe with a built-in Profile (the ‘profile’ attribute) and FitContribution (the ‘contribution’ attribute). Unique methods from each of these are exposed through this class to facilitate the creation of a simple fit recipe.

profile: The built-in Profile object.

contribution: The built-in FitContribution object.

results: The built-in FitResults object.

name: A name for this FitRecipe.

fithook: An object to be called whenever within the residual (default FitHook()) that can pass information out of the system during a refinement.

_constraints: A dictionary of Constraints, indexed by the constrained Parameter. Constraints can be added using the ‘constrain’ method.

_oconstraints: An ordered list of the constraints from this and all sub-components.

_calculators: A managed dictionary of Calculators.

_contributions: A managed OrderedDict of FitContributions.

_parameters: A managed OrderedDict of parameters (in this case the parameters are varied).

_parsets: A managed dictionary of ParameterSets.

_eqfactory: A diffpy.srfit.equation.builder.EquationFactory instance that is used to create constraints and restraints from string

_fixed: A set of parameters that are not actually varied.

_restraintlist: A list of restraints from this and all sub-components.

_restraints: A set of Restraints. Restraints can be added using the ‘restrain’ or ‘confine’ methods.

_ready: A flag indicating if all attributes are ready for the calculation.

_tagdict: A dictionary of tags to variables.

_weights: List of weighing factors for each FitContribution. The weights are multiplied by the residual of the FitContribution when determining the overall residual.

names: Variable names (read only). See getNames.

values: Variable values (read only). See getValues.

loadParsedData(parser)[source]

Load parsed data from a ProfileParser.

This sets the xobs, yobs, dyobs arrays as well as the metadata.

loadtxt(*args, **kw)[source]

Use numpy.loadtxt to load data.

Arguments are passed to numpy.loadtxt. unpack = True is enforced. The first two arrays returned by numpy.loadtxt are assumed to be x and y. If there is a third array, it is assumed to by dy. Any other arrays are ignored. These are passed to setObservedProfile.

Raises ValueError if the call to numpy.loadtxt returns fewer

than 2 arrays.

Returns the x, y and dy arrays loaded from the file

printResults(header='', footer='')[source]

Format and print the results.

header: A header to add to the output (default “”)

footer: A footer to add to the output (default “”)

saveResults(filename, header='', footer='')[source]

Format and save the results.

Parameters:

filename – Name of the save file.
header – A header to add to the output (default “”)
footer – A footer to add to the output (default “”)

setCalculationPoints(x)[source]

Set the calculation points.

Parameters:

x – A non-empty numpy array containing the calculation points. If xobs exists, the bounds of x will be limited to its bounds.
xobs (This will create y and dy on the specified grid if)
and (yobs)
exist. (dyobs)

setCalculationRange(xmin=None, xmax=None, dx=None)[source]

Set epsilon-inclusive calculation range.

Adhere to the observed xobs points when dx is the same as in the data. xmin and xmax are clipped at the bounds of the observed data.

Parameters:

xmin (float or "obs", optional) – The minimum value of the independent variable. Keep the current minimum when not specified. If specified as “obs” reset to the minimum observed value.
xmax (float or "obs", optional) – The maximum value of the independent variable. Keep the current maximum when not specified. If specified as “obs” reset to the maximum observed value.
dx (float or "obs", optional) – The sample spacing in the independent variable. When different from the data, resample the x as anchored at xmin.
inclusive (Note that xmin is always inclusive (unless clipped). xmax is)
data. (if it is within the bounds of the observed)

Raises:

AttributeError – If there is no observed data.
ValueError – When xmin > xmax or if dx <= 0. Also if dx > xmax - xmin.

setEquation(eqstr, ns={})[source]

Set the profile equation for the FitContribution.

This sets the equation that will be used when generating the residual. The equation will be usable within setResidualEquation as “eq”, and it takes no arguments.

eqstr: A string representation of the equation. Variables will be extracted from this equation and be given an initial value of 0.

ns: A dictionary of Parameters, indexed by name, that are used in the eqstr, but not registered (default {}).

Raises ValueError if ns uses a name that is already used for a variable.

setObservedProfile(xobs, yobs, dyobs=None)[source]

Set the observed profile.

Parameters:

xobs – Numpy array of the independent variable
yobs – Numpy array of the observed signal.
dyobs – Numpy array of the uncertainty in the observed signal. If dyobs is None (default), it will be set to 1 at each observed xobs.

Raises ValueError if len(yobs) != len(xobs) Raises ValueError if dyobs != None and len(dyobs) != len(xobs)

diffpy.srfit.fitbase.validatable module

Validatable class.

A Validatable has state that must be validated before a FitRecipe can first calculate the residual.

class diffpy.srfit.fitbase.validatable.Validatable[source]

Bases: object

Validatable class.

A Validatable has state that must be validated by a FitRecipe.

Module contents

The base fitting classes for diffpy.srfit.

This package contains modules and subpackages that are used to define a fit problem in SrFit. Unaltered, these classes will help set up a fit problem that can be optimized within a fitting framework or with a standalone optimizer. They provide the basic framework for defining a forward calculator, and from that defining a fit problem with data, constraints and restraints. The classes involved in this collaboration can be tied to a fitting framework at various levels through inheritance. One can create a fitting problem using the FitContribution, Profile and FitRecipe classes.

Various code and design taken from Paul Kienzle’s PARK package. http://www.reflectometry.org/danse/park.html

class diffpy.srfit.fitbase.Calculator(name)[source]

Bases: Operator, ParameterSet

Base class for calculators.

A Calculator organizes Parameters and has a __call__ method that can calculate a generic signal.

name: A name for this organizer.

meta: A dictionary of metadata needed by the calculator.

_calculators: A managed dictionary of Calculators, indexed by name.

_constraints: A set of constrained Parameters. Constraints can be added using the ‘constrain’ methods.

_parameters: A managed OrderedDict of contained Parameters.

_parsets: A managed dictionary of ParameterSets.

_restraints: A set of Restraints. Restraints can be added using the ‘restrain’ or ‘confine’ methods.

_eqfactory: A diffpy.srfit.equation.builder.EquationFactory instance that is used create Equations from string.

args: List of Literal arguments

nin: Number of inputs (<1 means this is variable)

nout: Number of outputs (1)

operation[source]: Function that performs the operation, self.__call__

symbol: Same as name

_value: The value of the Operator.

value: Property for ‘getValue’.

names: Variable names (read only). See getNames.

values: Variable values (read only). See getValues.

nin = -1

nout = 1

operation(*args)[source]

property symbol

class diffpy.srfit.fitbase.FitContribution(name)[source]

Bases: ParameterSet

FitContribution class.

FitContributions organize an Equation that calculates the signal, and a Profile that holds the signal. ProfileGenerators and Calculators can be used as well. Constraints and Restraints can be created as part of a FitContribution.

name: A name for this FitContribution.

profile: A Profile that holds the measured (and calculated) signal.

_calculators: A managed dictionary of Calculators, indexed by name.

_constraints: A set of constrained Parameters. Constraints can be added using the ‘constrain’ methods.

_generators: A managed dictionary of ProfileGenerators.

_parameters: A managed OrderedDict of parameters.

_restraints: A set of Restraints. Restraints can be added using the ‘restrain’ method.

_parsets: A managed dictionary of ParameterSets.

_eqfactory: A diffpy.srfit.equation.builder.EquationFactory instance that is used to create constraints and restraints from string

_eq: The FitContribution equation that will be optimized.

_reseq: The residual equation.

_xname: Name of the x-variable

_yname: Name of the y-variable

_dyname: Name of the dy-variable

names: Variable names (read only). See getNames.

values: Variable values (read only). See getValues.

addProfileGenerator(gen, name=None)[source]

Add a ProfileGenerator to be used by this FitContribution.

The ProfileGenerator is given a name so that it can be used as part of the profile equation (see setEquation). This can be different from the name of the ProfileGenerator used for attribute access. FitContributions should not share ProfileGenerator instances. Different ProfileGenerators can share Parameters and ParameterSets, however.

Calling addProfileGenerator sets the profile equation to call the calculator and if there is not a profile equation already.

gen: A ProfileGenerator instance

name: A name for the calculator. If name is None (default), then the ProfileGenerator’s name attribute will be used.

Raises ValueError if the ProfileGenerator has no name. Raises ValueError if the ProfileGenerator has the same name as some other managed object.

evaluate()[source]: Evaluate the contribution equation and update profile.ycalc.

getEquation()[source]

Get math expression string for the active profile equation.

Return normalized math expression or an empty string if profile equation has not been set yet.

getResidualEquation()[source]

Get math expression string for the active residual equation.

Return normalized math formula or an empty string if residual equation has not been configured yet.

residual()[source]

Calculate the residual for this fitcontribution.

When this method is called, it is assumed that all parameters have been assigned their most current values by the FitRecipe. This will be the case when being called as part of a FitRecipe refinement.

The residual is by default an array chiv: chiv = (eq() - self.profile.y) / self.profile.dy The value that is optimized is dot(chiv, chiv).

The residual equation can be changed with the setResidualEquation method.

setEquation(eqstr, ns={})[source]

Set the profile equation for the FitContribution.

This sets the equation that will be used when generating the residual for this FitContribution. The equation will be usable within setResidualEquation as “eq”, and it takes no arguments.

eqstr: A string representation of the equation. Any Parameter registered by addParameter or setProfile, or function registered by setCalculator, registerFunction or registerStringFunction can be can be used in the equation by name. Other names will be turned into Parameters of this FitContribution.

ns: A dictionary of Parameters, indexed by name, that are used in the eqstr, but not registered (default {}).

Raises ValueError if ns uses a name that is already used for a variable.

setProfile(profile, xname=None, yname=None, dyname=None)[source]

Assign the Profile for this FitContribution.

profile: A Profile that specifies the calculation points and that will store the calculated signal.

xname: The name of the independent variable from the Profile. If this is None (default), then the name specified by the Profile for this parameter will be used. This variable is usable within string equations with the specified name.

yname: The name of the observed Profile. If this is None (default), then the name specified by the Profile for this parameter will be used. This variable is usable within string equations with the specified name.

dyname: The name of the uncertainty in the observed Profile. If this is None (default), then the name specified by the Profile for this parameter will be used. This variable is usable within string equations with the specified name.

setResidualEquation(eqstr)[source]

Set the residual equation for the FitContribution.

eqstr: A string representation of the residual. If eqstr is None (default), then the previous residual equation will be used, or the chi2 residual will be used if that does not exist.

Two residuals are preset for convenience, “chiv” and “resv”. chiv is defined such that dot(chiv, chiv) = chi^2. resv is defined such that dot(resv, resv) = Rw^2. You can call on these in your residual equation. Note that the quantity that will be optimized is the summed square of the residual equation. Keep that in mind when defining a new residual or using the built-in ones.

Raises SrFitError if the Profile is not yet defined. Raises ValueError if eqstr depends on a Parameter that is not part of the FitContribution.

class diffpy.srfit.fitbase.FitHook[source]

Bases: object

Base class for inspecting the progress of a FitRecipe refinement.

Can serve as a fithook for the FitRecipe class (see FitRecipe.pushFitHook method.) The methods in this class are called during the preparation of the FitRecipe for refinement, and during the residual call. See the class methods for a description of their purpose.

postcall(recipe, chiv)[source]

This is called within FitRecipe.residual, after the calculation.

recipe: The FitRecipe instance

chiv: The residual vector

precall(recipe)[source]

This is called within FitRecipe.residual, before the calculation.

recipe: The FitRecipe instance

reset(recipe)[source]

Reset the hook data.

This is called whenever FitRecipe._prepare is called, which is whenever a configurational change to the fit hierarchy takes place, such as adding a new ParameterSet, constraint or restraint.

class diffpy.srfit.fitbase.FitRecipe(name='fit')[source]

Bases: FitRecipeInterface, RecipeOrganizer

FitRecipe class.

name: A name for this FitRecipe.

fithooks: List of FitHook instances that can pass information out of the system during a refinement. By default, the is populated by a PrintFitHook instance.

_constraints: A dictionary of Constraints, indexed by the constrained Parameter. Constraints can be added using the ‘constrain’ method.

_oconstraints: An ordered list of the constraints from this and all sub-components.

_calculators: A managed dictionary of Calculators.

_contributions: A managed OrderedDict of FitContributions.

_parameters: A managed OrderedDict of parameters (in this case the parameters are varied).

_parsets: A managed dictionary of ParameterSets.

_eqfactory: A diffpy.srfit.equation.builder.EquationFactory instance that is used to create constraints and restraints from string

_restraintlist: A list of restraints from this and all sub-components.

_restraints: A set of Restraints. Restraints can be added using the ‘restrain’ or ‘confine’ methods.

_ready: A flag indicating if all attributes are ready for the calculation.

_tagmanager: A TagManager instance for managing tags on Parameters.

_weights: List of weighing factors for each FitContribution. The weights are multiplied by the residual of the FitContribution when determining the overall residual.

_fixedtag: “__fixed”, used for tagging variables as fixed. Don’t use this tag unless you want issues.

names: Variable names (read only). See getNames.

values: Variable values (read only). See getValues.

fixednames: Names of the fixed refinable variables (read only).

fixedvalues: Values of the fixed refinable variables (read only).

bounds: Bounds on parameters (read only). See getBounds.

bounds2: Bounds on parameters (read only). See getBounds2.

addContribution(con, weight=1.0)[source]

Add a FitContribution to the FitRecipe.

con: The FitContribution to be stored.

Raises ValueError if the FitContribution has no name Raises ValueError if the FitContribution has the same name as some other managed object.

addParameterSet(parset)[source]

Add a ParameterSet to the hierarchy.

parset: The ParameterSet to be stored.

Raises ValueError if the ParameterSet has no name. Raises ValueError if the ParameterSet has the same name as some other managed object.

addVar(par, value=None, name=None, fixed=False, tag=None, tags=[])[source]

Add a variable to be refined.

par: A Parameter that will be varied during a fit.

value: An initial value for the variable. If this is None (default), then the current value of par will be used.

name: A name for this variable. If name is None (default), then the name of the parameter will be used.

fixed: Fix the variable so that it does not vary (default False).

tag: A tag for the variable. This can be used to retrieve, fix or free variables by tag (default None). Note that a variable is automatically tagged with its name and “all”.

tags: A list of tags (default []). Both tag and tags can be applied.

Returns:: ParameterProxy (variable) for the passed Parameter.
Return type:: vars

Raises ValueError if the name of the variable is already taken by another managed object. Raises ValueError if par is constant. Raises ValueError if par is constrained.

property bounds

property bounds2

boundsToRestraints(sig=1, scaled=False)[source]

Turn all bounded parameters into restraints.

The bounds become limits on the restraint.

sig: The uncertainty on the bounds (scalar or iterable, default 1).

scaled: Scale the restraints, see restrain.

clearFitHooks()[source]: Clear the FitHook sequence.

constrain(par, con, ns={})[source]

Constrain a parameter to an equation.

Note that only one constraint can exist on a Parameter at a time.

This is overloaded to set the value of con if it represents a variable and its current value is None. A constrained variable will be set as fixed.

par: The Parameter to constrain.

con: A string representation of the constraint equation or a Parameter to constrain to. A constraint equation must consist of numpy operators and “known” Parameters. Parameters are known if they are in the ns argument, or if they are managed by this object.

ns: A dictionary of Parameters, indexed by name, that are used in the eqstr, but not part of this object (default {}).

Raises ValueError if ns uses a name that is already used for a variable. Raises ValueError if eqstr depends on a Parameter that is not part of the FitRecipe and that is not defined in ns. Raises ValueError if par is marked as constant.

delVar(var)[source]

Remove a variable.

Note that constraints and restraints involving the variable are not modified.

var: A variable of the FitRecipe.

Raises ValueError if var is not part of the FitRecipe.

fix(*args, **kw)[source]

Fix a parameter by reference, name or tag.

A fixed variable is not refined. Variables are free by default.

This method accepts string or variable arguments. An argument of “all” selects all variables. Keyword arguments must be parameter names, followed by a value to assign to the fixed variable.

Raises ValueError if an unknown Parameter, name or tag is passed, or if a tag is passed in a keyword.

property fixednames: names of the fixed refinable variables

property fixedvalues: values of the fixed refinable variables

free(*args, **kw)[source]

Free a parameter by reference, name or tag.

A free variable is refined. Variables are free by default. Constrained variables are not free.

This method accepts string or variable arguments. An argument of “all” selects all variables. Keyword arguments must be parameter names, followed by a value to assign to the fixed variable.

Raises ValueError if an unknown Parameter, name or tag is passed, or if a tag is passed in a keyword.

getBounds()[source]

Get the bounds on variables in a list.

Returns a list of (lb, ub) pairs, where lb is the lower bound and ub is the upper bound.

getBounds2()[source]

Get the bounds on variables in two lists.

Returns lower- and upper-bound lists of variable bounds.

getFitHooks()[source]: Get the sequence of FitHook instances.

getNames()[source]: Get the names of the variables in a list.

getValues()[source]: Get the current values of the variables in a list.

isFree(var)[source]: Check if a variable is fixed.

newVar(name, value=None, fixed=False, tag=None, tags=[])[source]

Create a new variable of the fit.

This method lets new variables be created that are not tied to a Parameter. Orphan variables may cause a fit to fail, depending on the optimization routine, and therefore should only be created to be used in constraint or restraint equations.

name: The name of the variable. The variable will be able to be used by this name in restraint and constraint equations.

value: An initial value for the variable. If this is None (default), then the variable will be given the value of the first non-None-valued Parameter constrained to it. If this fails, an error will be thrown when ‘residual’ is called.

fixed: Fix the variable so that it does not vary (default False). The variable will still be managed by the FitRecipe.

tag: A tag for the variable. This can be used to fix and free variables by tag (default None). Note that a variable is automatically tagged with its name and “all”.

tags: A list of tags (default []). Both tag and tags can be applied.

Returns the new variable (Parameter instance).

popFitHook(fithook=None, index=-1)[source]

Remove a FitHook by index or reference.

fithook: FitHook instance to remove from the sequence. If this is None (default), default to index.

index: Index of FitHook instance to remove (default -1).

Raises ValueError if fithook is not None, but is not present in the sequence. Raises IndexError if the sequence is empty or index is out of range.

pushFitHook(fithook, index=None)[source]

Add a FitHook to be called within the residual method.

The hook is an object for reporting updates, or more fundamentally, passing information out of the system during a refinement. See the diffpy.srfit.fitbase.fithook.FitHook class for the required interface. Added FitHooks will be called sequentially during refinement.

fithook: FitHook instance to add to the sequence

index: Index for inserting fithook into the list of fit hooks. If this is None (default), the fithook is added to the end.

removeParameterSet(parset)[source]

Remove a ParameterSet from the hierarchy.

Raises ValueError if parset is not managed by this object.

residual(p=[])[source]

Calculate the vector residual to be optimized.

Parameters:

p – The list of current variable values, provided in the same order as the ‘_parameters’ list. If p is an empty iterable (default), then it is assumed that the parameters have already been updated in some other way, and the explicit update within this function is skipped.
each (The residual is by default the weighted concatenation of)
residual (FitContribution's)
array (plus the value of each restraint. The)
returned
chiv (denoted)
that (is such)
dot(chiv
restraints. (chiv) = chi^2 +)

scalarResidual(p=[])[source]

Calculate the scalar residual to be optimized.

Parameters:

p – The list of current variable values, provided in the same order as the ‘_parameters’ list. If p is an empty iterable (default), then it is assumed that the parameters have already been updated in some other way, and the explicit update within this function is skipped.
each (The residual is by default the weighted concatenation of)
residual (FitContribution's)
array (plus the value of each restraint. The)
returned
chiv (denoted)
that (is such)
dot(chiv
restraints. (chiv) = chi^2 +)

setWeight(con, weight)[source]: Set the weight of a FitContribution.

unconstrain(*pars)[source]

Unconstrain a Parameter.

This removes any constraints on a Parameter. If the Parameter is also a variable of the recipe, it will be freed as well.

\*pars: The names of Parameters or Parameters to unconstrain.

Raises ValueError if the Parameter is not constrained.

class diffpy.srfit.fitbase.FitResults(recipe, update=True, showfixed=True, showcon=False)[source]

Bases: object

Class for processing, presenting and storing results of a fit.

recipe: The recipe containing the results.

cov: The covariance matrix from the recipe.

conresults: An ordered dictionary of ContributionResults for each FitContribution, indexed by the FitContribution name.

derivstep: The fractional step size for calculating numeric derivatives. Default 1e-8.

varnames: Names of the variables in the recipe.

varvals: Values of the variables in the recipe.

varunc: Uncertainties in the variable values.

showfixed: Show fixed variables (default True).

fixednames: Names of the fixed variables of the recipe.

fixedvals: Values of the fixed variables of the recipe.

showcon: Show constraint values in the output (default False).

connames: Names of the constrained parameters.

convals: Values of the constrained parameters.

conunc: Uncertainties in the constraint values.

residual: The scalar residual of the recipe.

penalty: The penalty to residual from the restraints.

chi2: The chi2 of the recipe.

cumchi2: The cumulative chi2 of the recipe.

rchi2: The reduced chi2 of the recipe.

rw: The Rw of the recipe.

cumrw: The cumulative Rw of the recipe.

messages: A list of messages about the results.

precision: The precision of numeric output (default 8).

_dcon: The derivatives of the constraint equations with respect to the variables. This is used internally.

Each of these attributes, except the recipe, are created or updated when the update method is called.

formatResults(header='', footer='', update=False)[source]

Format the results and return them in a string.

This function is called by printResults and saveResults. Overloading the formatting here will change all three functions.

header: A header to add to the output (default “”)

footer: A footer to add to the output (default “”)

update[source]: Flag indicating whether to call update() (default False).

Returns:: a string containing the formatted results.
Return type:: out

printResults(header='', footer='', update=False)[source]

Format and print the results.

Parameters:

header – A header to add to the output (default “”)
footer – A footer to add to the output (default “”)
update – Flag indicating whether to call update() (default False).

saveResults(filename, header='', footer='', update=False)[source]

Format and save the results.

Parameters:

filename – Name of the save file.
header – A header to add to the output (default “”)
footer – A footer to add to the output (default “”)
update – Flag indicating whether to call update() (default False).

update()[source]: Update the results according to the current state of the recipe.

class diffpy.srfit.fitbase.PlotFitHook[source]

Bases: FitHook

This FitHook has live plotting of whatever is being refined.

postcall(recipe, chiv)[source]

This is called within FitRecipe.residual, after the calculation.

Find data and plot it.

recipe: The FitRecipe instance

chiv: The residual vector

reset(recipe)[source]: Set up the plot.

class diffpy.srfit.fitbase.Profile[source]

Bases: Observable, Validatable

Observed and calculated profile container.

Profile is an Observable. The xpar, ypar and dypar attributes are observed by the Profile, which can in turn be observed by some other object.

Attributes

_xobs: A numpy array of the observed independent variable (default None)

xobs: Read-only property of _xobs.

_yobs: A numpy array of the observed signal (default None)

yobs: Read-only property of _yobs.

_dyobs: A numpy array of the uncertainty of the observed signal (default None, optional).

dyobs: Read-only property of _dyobs.

x: A numpy array of the calculated independent variable (default None, property for xpar accessors).

y: The profile over the calculation range (default None, property for ypar accessors).

dy: The uncertainty in the profile over the calculation range (default None, property for dypar accessors).

ycalc: A numpy array of the calculated signal (default None).

xpar: A Parameter that stores x (named “x”).

ypar: A Parameter that stores y (named “y”).

dypar: A Parameter that stores dy (named “dy”).

ycpar: A Parameter that stores ycalc (named “ycalc”). This is not observed by the profile, but it is present so it can be constrained to.

meta: A dictionary of metadata. This is only set if provided by a parser.

property dy

property dyobs

loadParsedData(parser)[source]

Load parsed data from a ProfileParser.

This sets the xobs, yobs, dyobs arrays as well as the metadata.

loadtxt(*args, **kw)[source]

Use numpy.loadtxt to load data.

Arguments are passed to numpy.loadtxt. unpack = True is enforced. The first two arrays returned by numpy.loadtxt are assumed to be x and y. If there is a third array, it is assumed to by dy. Any other arrays are ignored. These are passed to setObservedProfile.

Raises ValueError if the call to numpy.loadtxt returns fewer than 2 arrays.

Returns:

x – x array loaded from the file.
y – y array loaded from the file.
dy – dy array loaded from the file.

savetxt(fname, **kwargs)[source]

Call numpy.savetxt with x, ycalc, y, dy.

Parameters:

fname (filename or file handle) – This is passed to numpy.savetxt.
**kwargs – The keyword arguments that are passed to numpy.savetxt. We preset file header “x ycalc y dy”. Use header='' to save data without any header.

Raises:

SrFitError – When self.ycalc has not been set.