Line data    Source code

       1             : #ifndef __PLUMED_lepton_ParsedExpression_h
       2             : #define __PLUMED_lepton_ParsedExpression_h
       3             : 
       4             : /* -------------------------------------------------------------------------- *
       5             :  *                                   lepton                                   *
       6             :  * -------------------------------------------------------------------------- *
       7             :  * This is part of the lepton expression parser.                              *
       8             :  * See https://openmm.org/development.                                        *
       9             :  *                                                                            *
      10             :  * Portions copyright (c) 2009-2022 Stanford University and the Authors.      *
      11             :  * Authors: Peter Eastman                                                     *
      12             :  * Contributors:                                                              *
      13             :  *                                                                            *
      14             :  * Permission is hereby granted, free of charge, to any person obtaining a    *
      15             :  * copy of this software and associated documentation files (the "Software"), *
      16             :  * to deal in the Software without restriction, including without limitation  *
      17             :  * the rights to use, copy, modify, merge, publish, distribute, sublicense,   *
      18             :  * and/or sell copies of the Software, and to permit persons to whom the      *
      19             :  * Software is furnished to do so, subject to the following conditions:       *
      20             :  *                                                                            *
      21             :  * The above copyright notice and this permission notice shall be included in *
      22             :  * all copies or substantial portions of the Software.                        *
      23             :  *                                                                            *
      24             :  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR *
      25             :  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,   *
      26             :  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL    *
      27             :  * THE AUTHORS, CONTRIBUTORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,    *
      28             :  * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR      *
      29             :  * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE  *
      30             :  * USE OR OTHER DEALINGS IN THE SOFTWARE.                                     *
      31             :  * -------------------------------------------------------------------------- */
      32             : 
      33             : #include "ExpressionTreeNode.h"
      34             : #include "windowsIncludes.h"
      35             : #include <map>
      36             : #include <string>
      37             : 
      38             : namespace PLMD {
      39             : namespace lepton {
      40             : 
      41             : class CompiledExpression;
      42             : class ExpressionProgram;
      43             : 
      44             : /**
      45             :  * This class represents the result of parsing an expression.  It provides methods for working with the
      46             :  * expression in various ways, such as evaluating it, getting the tree representation of the expresson, etc.
      47             :  */
      48             : 
      49     2039170 : class LEPTON_EXPORT ParsedExpression {
      50             : public:
      51             :     /**
      52             :      * Create an uninitialized ParsedExpression.  This exists so that ParsedExpressions can be put in STL containers.
      53             :      * Doing anything with it will produce an exception.
      54             :      */
      55             :     ParsedExpression();
      56             :     /**
      57             :      * Create a ParsedExpression.  Normally you will not call this directly.  Instead, use the Parser class
      58             :      * to parse expression.
      59             :      */
      60             :     ParsedExpression(const ExpressionTreeNode& rootNode);
      61             :     /**
      62             :      * Get the root node of the expression's abstract syntax tree.
      63             :      */
      64             :     const ExpressionTreeNode& getRootNode() const;
      65             :     /**
      66             :      * Evaluate the expression.  If the expression involves any variables, this method will throw an exception.
      67             :      */
      68             :     double evaluate() const;
      69             :     /**
      70             :      * Evaluate the expression.
      71             :      *
      72             :      * @param variables    a map specifying the values of all variables that appear in the expression.  If any
      73             :      *                     variable appears in the expression but is not included in this map, an exception
      74             :      *                     will be thrown.
      75             :      */
      76             :     double evaluate(const std::map<std::string, double>& variables) const;
      77             :     /**
      78             :      * Create a new ParsedExpression which produces the same result as this one, but is faster to evaluate.
      79             :      */
      80             :     ParsedExpression optimize() const;
      81             :     /**
      82             :      * Create a new ParsedExpression which produces the same result as this one, but is faster to evaluate.
      83             :      *
      84             :      * @param variables    a map specifying values for a subset of variables that appear in the expression.
      85             :      *                     All occurrences of these variables in the expression are replaced with the values
      86             :      *                     specified.
      87             :      */
      88             :     ParsedExpression optimize(const std::map<std::string, double>& variables) const;
      89             :     /**
      90             :      * Create a new ParsedExpression which is the analytic derivative of this expression with respect to a
      91             :      * particular variable.
      92             :      *
      93             :      * @param variable     the variable with respect to which the derivate should be taken
      94             :      */
      95             :     ParsedExpression differentiate(const std::string& variable) const;
      96             :     /**
      97             :      * Create an ExpressionProgram that represents the same calculation as this expression.
      98             :      */
      99             :     ExpressionProgram createProgram() const;
     100             :     /**
     101             :      * Create a CompiledExpression that represents the same calculation as this expression.
     102             :      */
     103             :     CompiledExpression createCompiledExpression() const;
     104             :     /**
     105             :      * Create a new ParsedExpression which is identical to this one, except that the names of some
     106             :      * variables have been changed.
     107             :      *
     108             :      * @param replacements    a map whose keys are the names of variables, and whose values are the
     109             :      *                        new names to replace them with
     110             :      */
     111             :     ParsedExpression renameVariables(const std::map<std::string, std::string>& replacements) const;
     112             : private:
     113             :     static double evaluate(const ExpressionTreeNode& node, const std::map<std::string, double>& variables);
     114             :     static ExpressionTreeNode preevaluateVariables(const ExpressionTreeNode& node, const std::map<std::string, double>& variables);
     115             :     static ExpressionTreeNode precalculateConstantSubexpressions(const ExpressionTreeNode& node, std::map<int, ExpressionTreeNode>& nodeCache);
     116             :     static ExpressionTreeNode substituteSimplerExpression(const ExpressionTreeNode& node, std::map<int, ExpressionTreeNode>& nodeCache);
     117             :     static ExpressionTreeNode differentiate(const ExpressionTreeNode& node, const std::string& variable, std::map<int, ExpressionTreeNode>& nodeCache);
     118             :     static bool isConstant(const ExpressionTreeNode& node);
     119             :     static double getConstantValue(const ExpressionTreeNode& node);
     120             :     static ExpressionTreeNode renameNodeVariables(const ExpressionTreeNode& node, const std::map<std::string, std::string>& replacements);
     121             :     ExpressionTreeNode rootNode;
     122             : };
     123             : 
     124             : LEPTON_EXPORT std::ostream& operator<<(std::ostream& out, const ExpressionTreeNode& node);
     125             : 
     126             : LEPTON_EXPORT std::ostream& operator<<(std::ostream& out, const ParsedExpression& exp);
     127             : 
     128             : } // namespace lepton
     129             : } // namespace PLMD
     130             : 
     131             : 
     132             : #endif // __PLUMED_lepton_ParsedExpression_h