diffpy.srfit 3.1.0rc0__py3-none-any.whl

diffpy/srfit/equation/equationmod.py

@@ -0,0 +1,213 @@
+#!/usr/bin/env python
+##############################################################################
+#
+# diffpy.srfit      by DANSE Diffraction group
+#                   Simon J. L. Billinge
+#                   (c) 2008 The Trustees of Columbia University
+#                   in the City of New York.  All rights reserved.
+#
+# File coded by:    Chris Farrow
+#
+# See AUTHORS.txt for a list of people who contributed.
+# See LICENSE_DANSE.txt for license information.
+#
+##############################################################################
+"""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.
+"""
+
+__all__ = ["Equation"]
+
+from collections import OrderedDict
+
+from diffpy.srfit.equation.literals.literal import Literal
+from diffpy.srfit.equation.literals.operators import Operator
+from diffpy.srfit.equation.visitors import getArgs, swap, validate
+
+
+class Equation(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'.
+    """
+
+    # define abstract attributes from the Operator base.
+    nin = None
+    nout = 1
+
+    def __init__(self, name=None, root=None):
+        """Initialize.
+
+        name    --  A name for this Equation.
+        root    --  The root node of the Literal tree (default None). If root
+                    is not passed here, you must call the 'setRoot' method to
+                    set or change the root node.
+        """
+        # Operator stuff. We circumvent Operator.__init__ since we're using
+        # args as a property. We cannot set it, as the Operator tries to do.
+        if name is None and root is not None:
+            name = "eq_%s" % root.name
+        Literal.__init__(self, name)
+        self.root = None
+        self.argdict = OrderedDict()
+        if root is not None:
+            self.setRoot(root)
+        return
+
+    @property
+    def symbol(self):
+        return self.name
+
+    def operation(self, *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).
+        """
+        return self.__call__(*args, **kw)
+
+    def _getArgs(self):
+        return list(self.argdict.values())
+
+    args = property(_getArgs)
+
+    def __getattr__(self, name):
+        """Gives access to the Arguments as attributes."""
+        # Avoid infinite loop on argdict lookup.
+        argdict = object.__getattribute__(self, "argdict")
+        if name not in argdict:
+            raise AttributeError("No argument named '%s' here" % name)
+        return argdict[name]
+
+    # Ensure there is no __dir__ override in the base class.
+    assert getattr(Operator, "__dir__", None) is getattr(
+        object, "__dir__", None
+    )
+
+    def __dir__(self):
+        "Return sorted list of attributes for this object."
+        rv = set(dir(type(self)))
+        rv.update(self.__dict__, self.argdict)
+        rv = sorted(rv)
+        return rv
+
+    def setRoot(self, root):
+        """Set the root of the Literal tree.
+
+        Raises:
+        ValueError if errors are found in the Literal tree.
+        """
+
+        # Validate the new root
+        validate(root)
+
+        # Stop observing the old root
+        if self.root is not None:
+            self.root.removeObserver(self._flush)
+
+        # Add the new root
+        self.root = root
+        self.root.addObserver(self._flush)
+        self._flush(other=(self,))
+
+        # Get the args
+        args = getArgs(root, getconsts=False)
+        self.argdict = OrderedDict([(arg.name, arg) for arg in args])
+
+        # Set Operator attributes
+        self.nin = len(self.args)
+
+        return
+
+    def __call__(self, *args, **kw):
+        """Call the equation.
+
+        New Argument values are accepted as arguments or keyword
+        assignments (or both).  The order of accepted arguments is given
+        by the args attribute. The Equation will remember values set in
+        this way.
+
+        Raises ValueError when a passed argument cannot be found
+        """
+        # Process args
+        for idx, val in enumerate(args):
+            if idx >= len(self.argdict):
+                raise ValueError("Too many arguments")
+            arg = self.args[idx]
+            arg.setValue(val)
+
+        # Process kw
+        for name, val in kw.items():
+            arg = self.argdict.get(name)
+            if arg is None:
+                raise ValueError("No argument named '%s' here" % name)
+            arg.setValue(val)
+
+        self._value = self.root.getValue()
+        return self._value
+
+    def swap(self, oldlit, newlit):
+        """Swap a literal in the equation for another.
+
+        Note that this may change the root and the operation interface
+        """
+        newroot = swap(self.root, oldlit, newlit)
+        self.setRoot(newroot)
+        return
+
+    # Operator methods
+
+    def addLiteral(self, literal):
+        """Cannot add a literal to an Equation."""
+        raise RuntimeError("Cannot add literals to an Equation.")
+
+    # Visitors can treat us differently than an Operator.
+
+    def identify(self, visitor):
+        """Identify self to a visitor."""
+        return visitor.onEquation(self)
+
+
+# End of file

diffpy/srfit/equation/literals/__init__.py

@@ -0,0 +1,71 @@
+#!/usr/bin/env python
+##############################################################################
+#
+# diffpy.srfit      by DANSE Diffraction group
+#                   Simon J. L. Billinge
+#                   (c) 2008 The Trustees of Columbia University
+#                   in the City of New York.  All rights reserved.
+#
+# File coded by:    Chris Farrow
+#
+# See AUTHORS.txt for a list of people who contributed.
+# See LICENSE_DANSE.txt for license information.
+#
+##############################################################################
+"""Building blocks for defining a lazy evaluation network.
+
+Literals are the building blocks of the evaluation network. An Argument
+holds the name and value of an equation variable. Operators are used to
+compose other Literals to produce a new value.
+
+Literal networks can be evaluated or have other actions performed on
+them by Visitors (in diffpy.srfit.equation.visitors). The Literal-
+Visitor relationship is that described by the Visitor pattern (
+
+http://en.wikipedia.org/wiki/Visitor_pattern).
+"""
+
+__all__ = [
+    "Argument",
+    "Operator",
+    "BinaryOperator",
+    "CustomOperator",
+    "AdditionOperator",
+    "SubtractionOperator",
+    "MultiplicationOperator",
+    "DivisionOperator",
+    "ExponentiationOperator",
+    "RemainderOperator",
+    "NegationOperator",
+    "ConvolutionOperator",
+    "SumOperator",
+    "UFuncOperator",
+    "ArrayOperator",
+    "PolyvalOperator",
+    "makeOperator",
+]
+
+
+# Import the operators
+
+from diffpy.srfit.equation.literals.argument import Argument
+from diffpy.srfit.equation.literals.operators import (
+    AdditionOperator,
+    ArrayOperator,
+    BinaryOperator,
+    ConvolutionOperator,
+    CustomOperator,
+    DivisionOperator,
+    ExponentiationOperator,
+    MultiplicationOperator,
+    NegationOperator,
+    Operator,
+    PolyvalOperator,
+    RemainderOperator,
+    SubtractionOperator,
+    SumOperator,
+    UFuncOperator,
+    makeOperator,
+)
+
+# End of file

diffpy/srfit/equation/literals/abcs.py

@@ -0,0 +1,81 @@
+#!/usr/bin/env python
+##############################################################################
+#
+# diffpy.srfit      by DANSE Diffraction group
+#                   Simon J. L. Billinge
+#                   (c) 2008 The Trustees of Columbia University
+#                   in the City of New York.  All rights reserved.
+#
+# File coded by:    Chris Farrow
+#
+# See AUTHORS.txt for a list of people who contributed.
+# See LICENSE_DANSE.txt for license information.
+#
+##############################################################################
+"""Abstract Base Classes for Literals."""
+
+__all__ = ["LiteralABC", "ArgumentABC", "OperatorABC"]
+
+
+from abc import ABCMeta, abstractmethod, abstractproperty
+
+import six
+
+
+@six.add_metaclass(ABCMeta)
+class LiteralABC(object):
+    """Abstract Base Class for Literal.
+
+    See Literal for usage.
+    """
+
+    @abstractmethod
+    def identify(self, visitor):
+        pass
+
+    @abstractmethod
+    def getValue(self):
+        pass
+
+    name = abstractproperty(None, None)
+
+
+# End class LiteralABC
+
+
+class ArgumentABC(LiteralABC):
+    """Abstract Base Class for Argument.
+
+    See Argument for usage.
+    """
+
+    @abstractmethod
+    def setValue(self, value):
+        pass
+
+    const = abstractproperty(None, None)
+    value = abstractproperty(None, None)
+
+
+# End class ArgumentABC
+
+
+class OperatorABC(LiteralABC):
+    """Abstract Base Class for Operator.
+
+    See Operator for usage.
+    """
+
+    @abstractmethod
+    def addLiteral(self, literal):
+        pass
+
+    args = abstractproperty(None, None)
+    nin = abstractproperty(None, None)
+    nout = abstractproperty(None, None)
+    operation = abstractproperty(None, None)
+    symbol = abstractproperty(None, None)
+    value = abstractproperty(None, None)
+
+
+# End class OperatorABC

diffpy/srfit/equation/literals/argument.py

@@ -0,0 +1,76 @@
+#!/usr/bin/env python
+##############################################################################
+#
+# diffpy.srfit      by DANSE Diffraction group
+#                   Simon J. L. Billinge
+#                   (c) 2008 The Trustees of Columbia University
+#                   in the City of New York.  All rights reserved.
+#
+# File coded by:    Chris Farrow
+#
+# See AUTHORS.txt for a list of people who contributed.
+# See LICENSE_DANSE.txt for license information.
+#
+##############################################################################
+"""Argument class.
+
+Arguments are the leaves of an equation tree, in essence a variable or a
+constant.
+"""
+
+__all__ = ["Argument"]
+
+from numpy import array_equal, ndarray
+
+from diffpy.srfit.equation.literals.abcs import ArgumentABC
+from diffpy.srfit.equation.literals.literal import Literal
+
+
+class Argument(Literal, ArgumentABC):
+    """Argument class.
+
+    Attributes
+    name    --  A name for this Argument.
+    const   --  A flag indicating whether this is considered a constant.
+                Constants may be given special treatment by the Visitors.
+    _value  --  The value of the Argument. Modified with 'setValue'.
+    value   --  Property for 'getValue' and 'setValue'.
+    """
+
+    const = None
+
+    def __init__(self, name=None, value=None, const=False):
+        """Initialization."""
+        Literal.__init__(self, name)
+        self.const = const
+        self.value = value
+        return
+
+    def identify(self, visitor):
+        """Identify self to a visitor."""
+        return visitor.onArgument(self)
+
+    def getValue(self):
+        """Get the value of this Literal."""
+        return self._value
+
+    def setValue(self, val):
+        """Set the value of the Literal.
+
+        val --  The value to assign
+        """
+        if isinstance(self._value, ndarray) or isinstance(val, ndarray):
+            notequiv = not array_equal(self._value, val)
+        else:
+            notequiv = self._value != val
+        if notequiv:
+            self._value = val
+            self.notify()
+        return
+
+    value = property(
+        lambda self: self.getValue(), lambda self, val: self.setValue(val)
+    )
+
+
+# End of file

diffpy/srfit/equation/literals/literal.py

@@ -0,0 +1,69 @@
+#!/usr/bin/env python
+##############################################################################
+#
+# diffpy.srfit      by DANSE Diffraction group
+#                   Simon J. L. Billinge
+#                   (c) 2008 The Trustees of Columbia University
+#                   in the City of New York.  All rights reserved.
+#
+# File coded by:    Chris Farrow
+#
+# See AUTHORS.txt for a list of people who contributed.
+# See LICENSE_DANSE.txt for license information.
+#
+##############################################################################
+"""Literal base class used to construct equation trees.
+
+Literals are base pieces of the equation hierarchy. The 'identify'
+method identifies the Literal to a visitor by calling the identifying
+method of the vistior.
+"""
+
+__all__ = ["Literal"]
+
+from diffpy.srfit.equation.literals.abcs import LiteralABC
+from diffpy.srfit.util.observable import Observable
+
+
+class Literal(Observable, LiteralABC):
+    """Abstract class for equation pieces, such as operators and arguments.
+
+    Literal derives from Observable. See diffpy.srfit.util.observable.
+
+    Attributes
+    name    --  A name for this Literal (default None).
+    _value  --  The value of the Literal.
+    """
+
+    name = None
+    _value = None
+
+    def __init__(self, name=None):
+        """Initialization."""
+        Observable.__init__(self)
+        if name is not None:
+            self.name = name
+        return
+
+    def getValue(self):
+        """Get the value of the Literal."""
+        raise NotImplementedError("Define in derived class")
+
+    def identify(self, visitor):
+        """Identify self to a visitor."""
+        m = "'%s' must override 'identify'" % self.__class__.__name__
+        raise NotImplementedError(m)
+
+    def _flush(self, other):
+        """Invalidate my state and notify observers."""
+        if self._value is None:
+            return
+        self._value = None
+        self.notify(other)
+        return
+
+    def __str__(self):
+        return "%s(%s)" % (self.__class__.__name__, self.name)
+
+
+# End of file