---

Expr.h

Go to the documentation of this file.

#ifndef EXPR_H
#define EXPR_H

#include "SundanceDefs.h"

#include "TSFArray.h"
#include "BasisFamily.h"
#include "DenseSerialVector.h"
#include "TSFVector.h"
#include "ExprHandle.h"
#include "ExprArray.h"
#include "LogicalExpr.h"
#include "ExprBase.h"
#include "Defaults.h"

namespace Sundance
{

  using namespace TSF;
  using std::string;

  using std::ostream;


  class MultiIndex;
  class QuadratureFamily;
  class WorkSet;
  class Cell;
  class CellSet;
  class AbstractFunctionSpace;

  /**
   * \ingroup UserLevelSymbolics

   \brief Expr represents a mathematical expression. An Expr
   can be an atomic entity
   such as a constant, a function, or a differential operator; or an expr
   can be a compound object such as a sum, project, or list of exprs.
   <A HREF="../ExprDoc.html"> More... </A>

  */

  class Expr
    {
    public:
      /** \name Constructors */
      //@{
      /** The empty constructor builds an uninitialized, null expr */
      Expr();
      /** Construct an Expr by assuming control of an ExprBase pointer */
      Expr(ExprBase* ptr);
      /** Construct an Expr with constant real value  */
      Expr(const double& value);
      //@}
      //      Expr(funcOfX f, const Expr& rangeSpecifier, const string& name="");

      ~Expr();
      Expr(const Expr& other);
      const Expr& operator=(const Expr& other);

      /** \name Math operations */
      //@{
      /** Unary minus */
      Expr operator-() const ;
      /** Reflexive add */
      const Expr& operator+=(const Expr& other) ;
      /** Reflexive subtract */
      const Expr& operator-=(const Expr& other) ;
      /** Reflexive multiply */
      const Expr& operator*=(const Expr& other) ;
      /** Reflexive divide */
      const Expr& operator/=(const Expr& other) ;
      /** Raise to a constant real power */
      Expr pow(const double& p) const ;
      //@}

      /** \name Listing */
      //@{
      /** read-only access to the i-th element of a list */
      const Expr& operator[](int i) const ;
      /** read/write access to the i-th element of a list */
      Expr& operator[](int i) ;
      /** the number of elements in the current level of a list */
      int length() const ;
      /** the total number of elements in all levels of a list */
      int size() const ;
      /** append a new element to a list */
      Expr append(const Expr& other);
      /** flatten a list into one dimension */
      Expr flatten() const ;
      //@}

      /** \name Linearization, variations, and substitution */
      //@{
      /** variation wrt a function u */
      Expr variation(const Expr& u) const ;

      /** variation of a function. Returns a test function with the same
       * basis as this function */
      Expr variation() const ;

      /** linearization wrt a function u about a point u0 */
      Expr linearization(const Expr& u, const Expr& u0) const ;

      /** Compute the sensitivity of an expression wrt u, evaluated
       * at a point u0 */
      Expr directSensitivity(const Expr& u, const Expr& u0) const ;

      /** Derive an equation for the sensitivity of u with respect
       * to alpha at the point alpha0 */
      Expr sensitivityEquation(const Expr& u, const Expr& alpha,
                               const Expr& alpha0) const ;

      /** return a function representing the unknown sensitivity of
       * this expr with respect to alpha */
      Expr sensitivity(const Expr& alpha) const ;

      /** differential of a function. Returns an unknown function with the
       * same basis as this function */
      Expr differential() const ;

      /** return a new expression with u0 in place of u throughout */
      Expr substitute(const Expr& u, const Expr& u0) const ;

      /** differential */
      Expr differential(const Expr& u, const Expr& du) const ;

      /** set the differential of a function */
      void setDifferential(const Expr& du) ;

      /** set the variation of a function */
      void setVariation(const Expr& v) ;

      /** */
      void setFunctionValue(const Expr& u0) ;
      //@}

      /** \name relational operators */
      //@{
      /** equality test */
      LogicalExpr operator==(const Expr& other) const ;
      /** not-equals test */
      LogicalExpr operator!=(const Expr& other) const ;
      /** less-than test */
      LogicalExpr operator<(const Expr& other) const ;
      /** greater-than test */
      LogicalExpr operator>(const Expr& other) const ;
      /**  */
      LogicalExpr operator<=(const Expr& other) const ;
      /** greater-than test */
      LogicalExpr operator>=(const Expr& other) const ;

      /** \name Probing at a cell or group of cells */
      //@{
      /** compute average value on a cell */
      ExprValue average(const Cell& cell) const ;
      /** compute average value on a cell set */
      ExprValue average(const Mesh& mesh, const CellSet& cellSet) const ;
      /** probe value at a point */
      double probeAtMeshPoint(int localPointIndex) const ;

      /** get values at a set of points in a cell */
      void evaluate(const AbstractFunctionSpace& targetSpace, const TSFArray<Cell>& cells,
                    const TSFArray<int>& cellIndices,
                    const TSFArray<int>& dofIndices,
                    const TSFArray<Point>& x,
                    DenseSerialVector& values) const ;

      /** evaluate a functional with u0 in place of the unknown u */
      double evaluateFunctional(const Mesh& mesh,
                                const Expr& u, const Expr& u0) const ;

      /** evaluate a functional */
      double evaluateFunctional(const Mesh& mesh) const ;


      //@}

      /** */
      const Expr& getRegionalExpr(const string& region) const ;

      /** */
      bool isDefinedOnRegion(const string& region) const ;

      /** */
      void setRegionalExpr(const string& region, const Expr& expr);

      /** \name Integrals and Norms */
      //@{

      /** Integral over all maximal cells of the specified mesh, using the
       * specified quadrature family.*/
      double integral(const Mesh& mesh,
                      const QuadratureFamily& quad = Defaults::quadratureFamily()) const ;

      /** Integral over the specified cell set using default quadrature */
      double integral(const Mesh& mesh,
                      const CellSet& cellSet,
                      const QuadratureFamily& quad = Defaults::quadratureFamily()) const ;

      /** Integral over all maximal cells of the implied mesh, using the
       * specified quadrature family.*/
      double integral(const QuadratureFamily& quad = Defaults::quadratureFamily()) const ;

      /** Integral over the specified cell set of the implied mesh
       * using the specified quadrature family */
      double integral(const CellSet& cellSet,
                      const QuadratureFamily& quad = Defaults::quadratureFamily()) const ;

      /** L-p norm over all maximal cells of the specified mesh, using the
       * specified quadrature family.*/
      double norm(int p,
                  const Mesh& mesh,
                  const QuadratureFamily& quad = Defaults::quadratureFamily()) const ;

      /** L-p norm over the specified cell set using default quadrature */
      double norm(int p,
                  const Mesh& mesh,
                  const CellSet& cellSet,
                  const QuadratureFamily& quad = Defaults::quadratureFamily()) const ;

      /** L-p norm over all maximal cells of the implied mesh, using the
       * specified quadrature family.*/
      double norm(int p,
                  const QuadratureFamily& quad = Defaults::quadratureFamily()) const ;

      /** L-p norm over the specified cell set of the implied mesh
       * using the specified quadrature family */
      double norm(int p,
                  const CellSet& cellSet,
                  const QuadratureFamily& quad = Defaults::quadratureFamily()) const ;

      /** quick L-2 norm of underlying vector. This takes no account of cell areas and
       * is therefore not necessarily the L2 norm of the expression. It will suffice
       * for some purposes, however, and is fast because it doesn't have to do
       * any integration. */
      double quickNorm() const ;

      /** L-infinity norm */
      double maxNorm() const ;
      //@}

      /** \name Output */
      //@{
      /** return a string representation of an Expr */
      string toString(bool paren=false) const ;
      /** return a very verbose representation of an Expr */
      string fullForm() const ;
      /** return an XML representation of an Expr */
      XMLObject toXML() const ;
      /** write a discrete scalar function to a matlab file */
      void matlabDump(ostream& os) const ;
      /** print all discrete functions in this expr */
      void printDiscreteFunctions(ostream& os) const ;
      //@}

      /** \name Low-level methods -- not for user-level code */
      //@{
      /** low-level differential */
      void differential(const Expr& u, const Expr& du, Expr& result) const ;

      /**   take derivative */
      Expr derivative(const MultiIndex& d) const ;
      /**   get multiindex */
      const MultiIndex& multiIndex() const ;

      /**  Replace rvalue of LHS ptr with contents of RHS  */
      const Expr& assignUsingLHSPtr(const Expr& other);
      /**  Replace LHS ptr with RHS ptr */
      const Expr& assignUsingRHSPtr(const Expr& other);

      /**  Get the real value of a constant real Expr */
      double value() const ;
      void setParameterValue(const double& alpha);
      /**  Get the name of a function */
      const string& name() const ;

      /** Create a HoldExpr from this one, preventing it from being expanded.
       * This can save computation time in certain contexts, e.g., norms and
       * integrals, by reducing the number of monomials that must be processed. */
      Expr hold() const ;

      /** evaluate a scalar expr on a workset */
      void evaluate(const WorkSet& workSet,
                    const QuadratureFamily& quadFamily,
                    DenseSerialVector& result) const ;

      /** */
      void watchOn() ;
      /** */
      void watchOff() ;

      /** */
      bool watching() const ;

      /**  return the vector associated with a discrete function */
      void getVector(TSFVector& vector) const ;

      /**  set the vector associated with a discrete function */
      void setVector(const TSFVector& vector) ;

      /** read a vector of values from a file */
      void readValues(const string& filename) ;

      /** return the DOF map associated with a discrete function */
      void getDOFMap(TSFSmartPtr<DOFMapBase>& map) const ;

      /** return the index of a discrete function into a list */
      int getReducedIndex() const ;

      /**  true if two exprs are structurally and numerically equal */
      //      bool operator==(const Expr& other) const ;
      bool equals(const Expr& other) const ;
      /**  test if LHS is < RHS */
      bool lessThan(const Expr& other) const ;
      /**  test if LHS is > RHS */
      bool greaterThan(const Expr& other) const ;

      /**  return the sorting key of the subtype handled by this expr */
      int sortPriority() const ;

      /**  True if Expr is null */
      bool isNull() const {return handle()==0;}
      /**  True if Expr's numerical value is identically zero */
      bool isZero() const ;
      /**  True if Expr is a constant */
      bool isConstant() const ;
      /**  True if Expr is a sum */
      bool isSumExpr() const ;
      /**  True if Expr is a product */
      bool isProductExpr() const ;
      /**  True if Expr is a TermList */
      bool isTermListExpr() const ;
      /**  True if Expr is a function */
      bool isFuncExpr() const ;
      /**  True is Expr is a differentiation operator */
      bool isDerivative() const ;
      /**  True if Expr is an Expr times a derivative */
      bool isDiffOp() const ;
      /**  True if Expr is a variational function */
      bool isVariational() const ;
      /**  True if Expr is an unknown function */
      bool isUnknown() const ;
      /**  True if Expr is a coordinate function */
      bool isCoordExpr() const ;
      /**  True if Expr is a discrete function */
      bool isDiscreteFunction() const ;
      /**  True if expr is a user-defined function */
      bool isUserFuncExpr() const ;
      /**  True if expr is a design parameter */
      bool isParameterExpr() const ;
      /**  True if expr is a hold expr */
      bool isHoldExpr() const ;
      /**  True if expr is a regional expr */
      bool isRegionalExpr() const ;
      /**  True if expr is a cell diameter expr */
      bool isCellDiameterExpr() const ;
      /**  True if expr is a cell normal expr */
      bool isCellNormalExpr() const ;
      /**  True if expr is an integral expr */
      bool isIntegralExpr() const ;
      /** */
      bool isTestParameter() const ;
      /** */
      bool isUnknownParameter() const ;
      /** returns true if expr structurally constant in space */
      bool isSpatiallyConstant() const ;

      /** returns true if the expression contains an unknown */
      bool containsUnknown() const ;
      /** returns true if the expression contains a test function */
      bool containsTest() const ;
      /** returns true if the expression contains an unknown parameter */
      bool containsUnknownParameter() const ;
      /** returns true if the expression contains a test parameter */
      bool containsTestParameter() const ;

      /** */
      bool hasChildren() const ;

      /** */
      void getChildren(ExprArray& children) const ;


      /** Look up the function index of a function expr */
      int funcID() const ;

      /** return the constant term in a sum, or the constant factor
          in a product */
      double constant() const ;

      /** access the ExprBase pointer contained in the handle */
      const ExprBase* ptr() const {return handle()->ptr();}

      /** Find a possible constant factor in a product, and return the rremaining
          Expr */
      Expr extractPrefactor(double& prefactor) const ;

      /** do a deep copy of an expr */
      Expr clone() const ;

      /** check to see if the LHS appears on the RHS, e.g. x=x+y */
      bool lhsAppearsOnRHS(const Expr& lhs) const;
      /** */
      void replaceWithCloneOfAssignmentLHS(const Expr& lhs,
                                           const Expr& lhsClone);
      /** print */
      void print(ostream& os, bool paren=false) const ;


      /** return the basis of a function */
      BasisFamily getBasis() const ;
      /** count the number of irreducable monomials in an expr */
      int countMonomials() const ;
      /** return a list of the irreducable monomials in an expr */
      ExprArray getMonomials() const ;
      /** low-level function used in getMonomials() */
      void getMonomials(ExprArray& monomials, int& offset) const ;
      /** partition a monomial into a coeff, an unknown, and a test function.
       * If the monomial contains more than one unknown or test function,
       * or if it contains no test function, it is not a valid weak form
       * and this function will return false. If valid, return true. */
      bool getValidWeakForm(Expr& coeff, Expr& var, Expr& unk) const ;

      bool getMesh(Mesh& mesh) const ;
      /** get the cell sets on which this function is defined */
      void getDomain(TSFNonDupArray<CellSet>& domain) const ;

      //@}
      // letting these guys be friends of Expr saves a copy operation
      /** create a list containing one expr */
      friend Expr List(const Expr& a);
      /** create a list of two exprs */
      friend Expr List(const Expr& a, const Expr& b);
      /** create a list of three exprs */
      friend Expr List(const Expr& a, const Expr& b, const Expr& c);
      /** create a list of four exprs */
      friend Expr List(const Expr& a, const Expr& b, const Expr& c, const Expr& d);

      int hashCode() const ;

      static Expr& dummy();


    private:
      void considerSuicide();
      bool readyToDie() const ;
      void initializeRefCount();
      void initializeHandle(ExprHandle* handlePtr);
      void decrementRefCount() {(*refCount_)--;}
      void incrementRefCount() {(*refCount_)++;}
      ExprBase* ptr() {return handle()->ptr();}
      void nullCheck(const string& funcName) const ;
      ExprHandle* handle() {return *ptrToHandle_;}
      const ExprHandle* handle() const {return *ptrToHandle_;}


      ExprHandle** ptrToHandle_;
      int* refCount_;

    };


  inline string toString(const Expr& expr)
    {
      return expr.toString();
    }


  inline ostream& operator<<(ostream& os, const Expr& expr)
    {
      expr.print(os);
      return os;
    }

  inline int hashCode(const Expr& expr)
    {
      return expr.hashCode();
    }

  /**
   * \relates Expr
   * Join two exprs e1 and e2 to form a list {e1, e2}
   */
  Expr join(const Expr& e1, const Expr& e2);


  /**
   * \relates Expr
   * Add a and b. Both terms must have the same list structure.
   */
  Expr operator+(const Expr& a, const Expr& b);

  /**
   * \relates Expr
   * Subtract b from a. Both terms must have the same list structure.
   */
  Expr operator-(const Expr& a, const Expr& b);

  /**
   * \relates Expr
   * Multiply a and b.
   */
  Expr operator*(const Expr& a, const Expr& b);

  /**
   * \relates Expr
   * Divide a and b. The denominator must be a scalar-valued expr.
   */
  Expr operator/(const Expr& a, const Expr& b);

  /**
   * \relates Expr
   * Raise an expr to a constant real power. The expr must be scalar valued.
   */
  Expr pow(const Expr& expr, const double& p);


  Expr Scalar();

  /** \relates Expr
   * Create a non-expandable version of an expression
   */
  Expr hold(const Expr& expr);
}
#endif

---

Contact:

Kevin Long (krlong@ca.sandia.gov)


Documentation generated by