diffpy.srfit.equation package

Submodules

diffpy.srfit.equation.builder module

Classes and utilities for creating equations.

The EquationFactory class is used to create an equation (an Equation instance) from a string equation. User-defined Literals can be registered with the factory so that they are used in the equation. Registered Literals are referenced by name, and when a new Literal of the same name is registered, the factory will swap out the old Literal for the new one in all equations built by the factory.

An example using the EquationFactory: The makeEquation method turns the string-representation of an equation into a callable object. > factory = EquationFactory() > eq = factory.makeEquation(“A*sin(a*x)”) will create an equation that evaluates as “A*sin(a*x)”. The equation takes no arguments.

Custom Arguments and constants can be included in the equation: > factory.registerConstant(“offset”, 3) > A = Argument(name = “A”, value = 1.0) > factory.registerArgument(“A”, A) > eq = factory.makeEquation(“A*sin(a*x) + offset”) This includes a constant offset in the equation and makes sure that the user-defined Argument is in the equation. This can be used to assure that the same instance of an Argument appears in multiple equations. Other literals can be registered in a similar fashion.

The BaseBuilder class does the hard work of making an equation from a string in EquationFactory.makeEquation. BaseBuilder can be used directly to create equations. BaseBuilder is specified in the ArgumentBuilder and OperatorBuilder classes. You can create builders from Literals or equations by using the “wrap” methods within this module or by using the builder classes directly.

With a collection of BaseBuilder objects, one can simply write the equation using normal python syntax: > A = ArgumentBuilder(name = “A”) > a = ArgumentBuilder(name = “a”) > x = ArgumentBuilder(name = “x”) > # sin is defined in this module as an OperatorBuilder > sin = getBuilder(“sin”) > beq = A*sin(a*x) > eq = beq.getEquation()

The equation builder can also handle scalar constants. Staring with the above setup: > beq2 = A*sin(a*x) + 3 > eq2 = beq2.getEquation() Here, we didn’t have to wrap ‘3’ in an ArgumentBuilder. Non scalars, constant or otherwise, must be wrapped as ArgumentBuilders in order to be used in this way.

BaseBuilder can make use of user-defined functions. Any callable python object can be wrapped as an OperatorBuilder with the wrapFunction method. For example. > _f = lambda a, b : (a-b)/(a+b) > f = wrapFunction(“f”, _f) > # Using BaseBuilder > a = ArgumentBuilder(name = “a”) > b = ArgumentBuilder(name = “b”) > c = ArgumentBuilder(name = “c”) > beq = c*f(a,b) > eq = beq.makeEquation()

class diffpy.srfit.equation.builder.EquationFactory

Bases: object

A Factory for equations.

builders – A dictionary of BaseBuilders registered with the
factory, indexed by name.
newargs – A set of new arguments created by makeEquation. This is
redefined whenever makeEquation is called.

equations – Set of equations that have been built by the EquationFactory.

deRegisterBuilder(name)

De-register a builder by name.

This does not change the equations that use the Literal wrapped by the builder.

ignore = ('(', ',', ')')
makeEquation(eqstr, buildargs=True, argclass=<class 'diffpy.srfit.equation.literals.argument.Argument'>, argkw={})

Make an equation from an equation string.

Arguments eqstr – An equation in string form using standard python

syntax. The equation string can use any function registered literal or function, including numpy ufuncs that are automatically registered.
buildargs – A flag indicating whether missing arguments can be
created by the Factory (default True). If False, then the a ValueError will be raised if there are undefined arguments in the eqstr. Built arguments will be of type argclass.
argclass – Class to use when creating new Arguments (default
diffpy.srfit.equation.literals.Argument). The class constructor must accept the ‘name’ key word.
argkw – Key word dictionary to pass to the argclass constructor
(default {}).

Returns a callable Literal representing the equation string.

registerArgument(name, arg)

Register a named Argument with the factory.

Returns the registered builder.

registerBuilder(name, builder)

Register builder in this module so it can be used in makeEquation.

If an extant builder with the given name is already registered, this will replace all instances of the old builder’s literal in the factory’s equation set with the new builder’s literal. Note that this may lead to errors if one of the replacements causes a self-reference.

Raises ValueError if the new builder’s literal causes a self-reference in an existing equation.

registerConstant(name, value)

Register a named constant with the factory.

Returns the registered builder.

registerFunction(name, func, argnames)

Register a named function with the factory.

This will register a builder for the function.

name – The name of the function func – A callable python object argnames– The argument names for func. If these names do not

correspond to builders, then new constants with value 0 will be created for each name.

Returns the registered builder.

registerOperator(name, op)

Register an Operator literal with the factory.

Operators can be used with or without arguments (or parentheses) in an equation string. If used with arguments, then the Operator will use the passed arguments as arguments for the operation. If used without arguments, it is assumed that the operator is already populated with arguments, and those will be used.

Returns the registered builder.

symbols = ('+', '-', '*', '/', '**', '%', '|')
wipeout(eq)

Invalidate the specified equation and remove it from the factory.

This will remove the equation from the purview of the factory and also change its formula to return NaN. This ensures that eq does not observe any object in the factory and thus prevents its indirect pickling with the factory because of observer callback function.

No return value.

class diffpy.srfit.equation.builder.BaseBuilder

Bases: object

Class for building equations.

Equation builder objects can be composed like a normal function where the arguments can be other BaseBuilder instances or constants.

Attributes literal – The equation Literal being built by this instance.

getEquation()

Get the equation built by this object.

The equation will given the name “_eq_<root>” where “<root>” is the name of the root node.

class diffpy.srfit.equation.builder.ArgumentBuilder(value=None, name=None, const=False, arg=None)

Bases: diffpy.srfit.equation.builder.BaseBuilder

BaseBuilder wrapper around an Argument literal.

Equation builder objects can be composed like a normal function where the arguments can be other BaseBuilder instances or constants.

Attributes literal – The Argument wrapped by this instance.

class diffpy.srfit.equation.builder.OperatorBuilder(name, op=None)

Bases: diffpy.srfit.equation.builder.BaseBuilder

BaseBuilder wrapper around an Operator literal.

Attributes literal – The Operator wrapped by this instance. name – The name of the operator to be wrapped

diffpy.srfit.equation.builder.wrapArgument(name, arg)

Wrap an Argument as a builder.

diffpy.srfit.equation.builder.wrapOperator(name, op)

Wrap an Operator as a builder.

diffpy.srfit.equation.builder.wrapFunction(name, func, nin=2, nout=1)

Wrap a function in an OperatorBuilder instance.

name – The name of the function func – A callable python object nin – The number of input arguments (default 2) nout – The number of return values (default 1)

Returns the OperatorBuilder instance that wraps the function.

diffpy.srfit.equation.builder.getBuilder(name)

Get an operator from the global builders dictionary.

diffpy.srfit.equation.equationmod module

The Equation class for holding and evaluating an equation.

Equation is a functor that holds a Literal tree that defines an equation. It’s __call__ method evaluates the equation at the most recent value of its Arguments. The non-constant arguments are accessible as attributes of the Equation instance and can be passed as arguments to __call__.

Example > # make a Literal tree. Here’s a simple one > add = AdditionOperator() > a = Argument(name=”a”) # Don’t forget to name these! > b = Argument(name=”b”) > add.addLiteral(a) > add.addLiteral(b) > # make an Equation instance and pass the root > eq = Equation(root = add) > eq(a=3, b=4) # returns 7 > eq(a=2) # remembers b=4, returns 6 > eq.a.setValue(-3) > eq.b.setValue(3) > eq() # uses last assignment of a and b, returns 0

See the class documentation for more information.

class diffpy.srfit.equation.equationmod.Equation(name=None, root=None)

Bases: diffpy.srfit.equation.literals.operators.Operator

Class for holding and evaluating a Literal tree.

Instances have attributes that are the non-const Arguments of the tree (accessed by name) and a __call__ method that evaluates the tree. It is assumed, but not enforced that Arguments have unique names. If this is not the case, then one should keep its own list of Arguments.

The tree is scanned for errors when it is added. Thus, the tree should be complete before putting it inside an Equation.

Equations can act as Operator nodes within a literal tree. In this context, they evaluate as the root node, but provide a calling interface that accepts new argument values for the literal tree.

Attributes root – The root Literal of the equation tree argdict – An OrderedDict of Arguments from the root. args – Property that gets the values of argdict.

Operator Attributes 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 – Function that performs the operation. e.g. numpy.add. symbol – The symbolic representation. e.g. “+” or “sin”. _value – The value of the Operator. value – Property for ‘getValue’.

addLiteral(literal)

Cannot add a literal to an Equation.

args
identify(visitor)

Identify self to a visitor.

nin = None
nout = 1
operation(*args, **kw)

Evaluate this Equation object.

Same as the __call__ method. This method is used via the Operator interface.

Return the result of __call__(*args, **kw).

setRoot(root)

Set the root of the Literal tree.

Raises: ValueError if errors are found in the Literal tree.

swap(oldlit, newlit)

Swap a literal in the equation for another.

Note that this may change the root and the operation interface

symbol

Module contents

The core equation evaluator for diffpy.srfit.

This package contains modules and subpackages that are used to create Equation objects. The Equation class is an encapsulation of a lazy evaluation network that is used throughout SrFit. The EquationsFactory class is used to create Equation objects from strings and can incorporate user-defined functions as well as default operations.

The subpackages define various pieces of the evaluation network.

class diffpy.srfit.equation.Equation(name=None, root=None)

Bases: diffpy.srfit.equation.literals.operators.Operator

Class for holding and evaluating a Literal tree.

Instances have attributes that are the non-const Arguments of the tree (accessed by name) and a __call__ method that evaluates the tree. It is assumed, but not enforced that Arguments have unique names. If this is not the case, then one should keep its own list of Arguments.

The tree is scanned for errors when it is added. Thus, the tree should be complete before putting it inside an Equation.

Equations can act as Operator nodes within a literal tree. In this context, they evaluate as the root node, but provide a calling interface that accepts new argument values for the literal tree.

Attributes root – The root Literal of the equation tree argdict – An OrderedDict of Arguments from the root. args – Property that gets the values of argdict.

Operator Attributes 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 – Function that performs the operation. e.g. numpy.add. symbol – The symbolic representation. e.g. “+” or “sin”. _value – The value of the Operator. value – Property for ‘getValue’.

addLiteral(literal)

Cannot add a literal to an Equation.

args
identify(visitor)

Identify self to a visitor.

nin = None
nout = 1
operation(*args, **kw)

Evaluate this Equation object.

Same as the __call__ method. This method is used via the Operator interface.

Return the result of __call__(*args, **kw).

setRoot(root)

Set the root of the Literal tree.

Raises: ValueError if errors are found in the Literal tree.

swap(oldlit, newlit)

Swap a literal in the equation for another.

Note that this may change the root and the operation interface

symbol