diffpy.srfit.equation package
Subpackages
- diffpy.srfit.equation.literals package
- Submodules
- diffpy.srfit.equation.literals.abcs module
- diffpy.srfit.equation.literals.argument module
- diffpy.srfit.equation.literals.literal module
- diffpy.srfit.equation.literals.operators module
- Module contents
- diffpy.srfit.equation.visitors 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.ArgumentBuilder(value=None, name=None, const=False, arg=None)[source]
Bases:
BaseBuilderBaseBuilder 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.
- literal
The Argument wrapped by this instance.
- class diffpy.srfit.equation.builder.BaseBuilder[source]
Bases:
objectClass for building equations.
Equation builder objects can be composed like a normal function where the arguments can be other BaseBuilder instances or constants.
- literal
The equation Literal being built by this instance.
- class diffpy.srfit.equation.builder.EquationFactory[source]
Bases:
objectA 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)[source]
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={})[source]
Make an equation from an equation string.
- Parameters:
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 {}).
string. (Returns a callable Literal representing the equation)
- registerArgument(name, arg)[source]
Register a named Argument with the factory.
Returns the registered builder.
- registerBuilder(name, builder)[source]
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)[source]
Register a named constant with the factory.
Returns the registered builder.
- registerFunction(name, func, argnames)[source]
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)[source]
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)[source]
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.OperatorBuilder(name, op=None)[source]
Bases:
BaseBuilderBaseBuilder wrapper around an Operator literal.
- literal
The Operator wrapped by this instance.
- name
The name of the operator to be wrapped
- diffpy.srfit.equation.builder.getBuilder(name)[source]
Get an operator from the global builders dictionary.
- diffpy.srfit.equation.builder.wrapFunction(name, func, nin=2, nout=1)[source]
Wrap a function in an OperatorBuilder instance.
- diffpy.srfit.equation.builder.name
The name of the function
- diffpy.srfit.equation.builder.func
A callable python object
- diffpy.srfit.equation.builder.nin
The number of input arguments (default 2)
- diffpy.srfit.equation.builder.nout
The number of return values (default 1)
- Returns the OperatorBuilder instance that wraps the function.
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)[source]
Bases:
OperatorClass 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.
- root
The root Literal of the equation tree
- argdict
An OrderedDict of Arguments from the root.
- args
Property that gets the values of argdict.
- 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
- symbol
The symbolic representation. e.g. “+” or “sin”.
- _value
The value of the Operator.
- value
Property for ‘getValue’.
- property args
The type of the None singleton.
- nin = None
- nout = 1
- operation(*args, **kw)[source]
Evaluate this Equation object.
Same as the __call__ method. This method is used via the Operator interface.
- setRoot(root)[source]
Set the root of the Literal tree.
Raises: ValueError if errors are found in the Literal tree.
- swap(oldlit, newlit)[source]
Swap a literal in the equation for another.
Note that this may change the root and the operation interface
- property 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)[source]
Bases:
OperatorClass 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.
- root
The root Literal of the equation tree
- argdict
An OrderedDict of Arguments from the root.
- args
Property that gets the values of argdict.
- 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
- symbol
The symbolic representation. e.g. “+” or “sin”.
- _value
The value of the Operator.
- value
Property for ‘getValue’.
- property args
The type of the None singleton.
- nin = None
- nout = 1
- operation(*args, **kw)[source]
Evaluate this Equation object.
Same as the __call__ method. This method is used via the Operator interface.
- setRoot(root)[source]
Set the root of the Literal tree.
Raises: ValueError if errors are found in the Literal tree.
- swap(oldlit, newlit)[source]
Swap a literal in the equation for another.
Note that this may change the root and the operation interface
- property symbol