From: wolf Date: Thu, 30 Jun 2005 23:39:26 +0000 (+0000) Subject: Rewrite parts of the documentation X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=00f968b7f2420b5dc20923cf0e69d44e4f9ec76e;p=dealii-svn.git Rewrite parts of the documentation git-svn-id: https://svn.dealii.org/trunk@11027 0785d39b-7218-0410-832d-ea1e28bc413d --- diff --git a/deal.II/base/include/base/function_parser.h b/deal.II/base/include/base/function_parser.h index ae308ab42c..8bb5f9e4c9 100644 --- a/deal.II/base/include/base/function_parser.h +++ b/deal.II/base/include/base/function_parser.h @@ -31,57 +31,57 @@ namespace fparser * FunctionParser is not used. */ class FunctionParser {}; - }; #endif -template class Point; -template class Tensor; -template class Tensor<1,dim>; -template class Vector; +template class Point; +template class Tensor; +template class Tensor<1,dim>; +template class Vector; + /** - * Function Parser. Wrapper class for the fparser library (see - * http://www.students.tut.fi/~warp/FunctionParser/). This class lets - * you evaluate strings such as "sqrt(1-x^2+y^2)" with given values of - * 'x' and 'y'. Some of the informations contained here are copied - * verbatim from the fparser.txt file that comes with the fparser - * library. Please refer also to that file both for clarifications on - * how this wrapper works, as well as for any issue regarding the - * licence that applies to this class. + * This class implements a function object that gets its value by parsing a + * string describing this function. It is a wrapper class for the fparser + * library (see http://www.students.tut.fi/~warp/FunctionParser/). This class + * lets you evaluate strings such as "sqrt(1-x^2+y^2)" for given values of + * 'x' and 'y'. Some of the information contained here is copied verbatim + * from the fparser.txt file that comes with the fparser library. Please refer + * also to that file both for clarifications on how this wrapper works, as + * well as for any issue regarding the licence that applies to this class. * - * By using this class you indicate that you accept the terms of the - * licence that comes with the fparser library. + * By using this class you indicate that you accept the terms of the licence + * that comes with the fparser library. If you do not agree with them, you + * should not use this class or configure the deal.II library without the + * function parser (see the ReadMe file of deal.II on instructions for this). * * The following example shows how to use this class: - @verbatim - - - // Define some constants that will be used by the function parser - std::map constants; - constants["pi"] = M_PI; - - // Define the variables that will be used inside the expressions - std::string variables = "x,y,z"; - - // Define the expressions of the vector_valued function. - std::vector expressions(2); - expressions[0] = "sin(2*pi*x)+sinh(pi*z)"; - expressions[1] = "sin(2*pi*y)*exp(x^2)"; - - // Generate an empty function with two components - ParsedFunction<3> vector_function(2); + * @verbatim + // Define some constants that will be used by the function parser + std::map constants; + constants["pi"] = deal_II_numbers::PI; + + // Define the variables that will be used inside the expressions + std::string variables = "x,y,z"; - // And populate it with the newly created objects. - vector_function.initialize(variables, - expressions, - constants); + // Define the expressions of the individual components of a + // vector valued function with two components: + std::vector expressions(2); + expressions[0] = "sin(2*pi*x)+sinh(pi*z)"; + expressions[1] = "sin(2*pi*y)*exp(x^2)"; + + // Generate an empty function for these two components. + ParsedFunction<3> vector_function(2); - @endverbatim + // And populate it with the newly created objects. + vector_function.initialize(variables, + expressions, + constants); + @endverbatim * * See http://www.students.tut.fi/~warp/FunctionParser/ for an - * explanation on how the underlining library works. + * explanation on how the underlying library works. * From the fparser.txt file: @@ -94,60 +94,19 @@ template class Vector; is very fast (specially compared to libraries which evaluate functions by just interpreting the raw function string). - The library is made in ISO C++ and requires a standard-conforming C++ - compiler. - @endverbatim - * This object overloads for you the virtual methods value() and - * vector_value() of the Function base class with the byte compiled - * versions of the expressions given to the initialize() methods. * - * @author Luca Heltai, 2005 - */ -template -class FunctionParser : public Function -{ - public: - /** - * Constructor for Parsed - * functions. Its arguments are - * the same of the base class - * Function. The only difference - * is that this object needs to - * be initialized with - * initialize() method before you - * can use it. If an attempt to - * use this function is made - * before the initialize() method - * has been called, then an - * exception is thrown. - */ - FunctionParser (const unsigned int n_components = 1, - const double initial_time = 0.0); - - /** - * Destructor. Explicitly delete - * the FunctionParser objects - * (there is one for each - * component of the function). - */ - ~FunctionParser(); - - /** - * Type for the constant - * map. Used by the initialize() - * method. - */ - typedef std::map ConstMap; - - /** - * Iterator for the constants - * map. Used by the initialize() - * method. - */ - typedef ConstMap::iterator ConstMapIterator; - - /** Initialize the function. From the fparser.txt file: + * This class overloads for you the virtual methods value() and + * vector_value() of the Function base class with the byte compiled versions + * of the expressions given to the initialize() methods. Note that the class + * will not work unless you call the initialize() method first, that accepts + * the text description of the function as an argument (among other + * things). The reason for this is that this text description may be read from + * an input file, and may therefore not be available at object construction + * time yet. + * + * The syntax to describe a function follows usual programming practice, + * and is explained in this snippet from the fparser.txt file: @verbatim The function string understood by the class is very similar to the C-syntax. Arithmetic float expressions can be created from float literals, variables @@ -240,48 +199,118 @@ class FunctionParser : public Function call is safe. In any other place it will cause an infinite recursion (which will make the program eventually run out of memory). @endverbatim + * + * @author Luca Heltai, 2005 + */ +template +class FunctionParser : public Function +{ + public: + /** + * Constructor for Parsed + * functions. Its arguments are + * the same of the base class + * Function. The only difference + * is that this object needs to + * be initialized with + * initialize() method before you + * can use it. If an attempt to + * use this function is made + * before the initialize() method + * has been called, then an + * exception is thrown. + */ + FunctionParser (const unsigned int n_components = 1, + const double initial_time = 0.0); - This methods accepts the following parameters: - - - vars. It contains a string with the variables that will be - used by the expressions to be evaluated. Note that the variables - can have any name (of course different from the function names - defined above!), but the order IS important. The first variable - will correspond to the first component of the point in which the - function is evaluated, the second variable to the second component - and so forth. If this function is also time dependent, then it is - necessary to specify it by setting the #time_dependent parameter - to true. - An Exception is thrown if the number of variables specified here - is different from dim (if this function is not time-dependent) or - from dim+1 (if it is time-dependent). - - - expressions. This is a list of strings containing the - expressions that will be byte compiled by the internal parser - (FunctionParser). Note that the size of this vector must match - exactly the number of components of the FunctionParser. If this is - not the case, an exception is thrown. + /** + * Destructor. Explicitly delete + * the FunctionParser objects + * (there is one for each + * component of the function). + */ + ~FunctionParser(); - - constants. The map of constants is used to pass any - necessary constant that we want to specify in our expressions (in - the example above the number pi). An expression is valid if and - only if it contains only defined variables and defined constants - (other than the functions specified above). If a constant is given - whose name is not valid (eg: constants["sin"] = 1.5;) an - exception is thrown. + /** + * Type for the constant + * map. Used by the initialize() + * method. + */ + typedef std::map ConstMap; - - time_dependent. If this is a time dependent function, then - the last variable is assumed to be the time variable, and - this->get_time() is passed to the function. Naturally the number - of variables parsed by the initialize() method in this case is - dim+1. It defaults to false, i.e.. do not consider time. + /** + * Iterator for the constants + * map. Used by the initialize() + * method. + */ + typedef ConstMap::iterator ConstMapIterator; - - use_degrees. Parameter to decide if the trigonometric - functions work in radians or degrees. The default for this - parameter is false, i.e. use radians and not degrees. - - - */ + /** + * Initialize the function. This methods + * accepts the following parameters: + * + * vars: a string with + * the variables that will be used by the + * expressions to be evaluated. Note that + * the variables can have any name (of + * course different from the function + * names defined above!), but the order + * IS important. The first variable will + * correspond to the first component of + * the point in which the function is + * evaluated, the second variable to the + * second component and so forth. If this + * function is also time dependent, then + * it is necessary to specify it by + * setting the #time_dependent parameter + * to true. An exception is thrown if + * the number of variables specified here + * is different from dim (if this + * function is not time-dependent) or + * from dim+1 (if it is time-dependent). + * + * expressions: a list of strings + * containing the expressions that will + * be byte compiled by the internal + * parser (FunctionParser). Note that the + * size of this vector must match exactly + * the number of components of the + * FunctionParser, as declared in the + * constructor. If this is not the case, + * an exception is thrown. + * + * + * constants: a map of constants + * used to pass any necessary constant + * that we want to specify in our + * expressions (in the example above the + * number pi). An expression is valid if + * and only if it contains only defined + * variables and defined constants (other + * than the functions specified + * above). If a constant is given whose + * name is not valid (eg: + * constants["sin"] = 1.5;) an + * exception is thrown. + * + * time_dependent. If this is a + * time dependent function, then the last + * variable declared in vars is + * assumed to be the time variable, and + * this->get_time() is used to initialize + * it when evaluating the + * function. Naturally the number of + * variables parsed by the initialize() + * method in this case is dim+1. The + * value of this parameter defaults to + * false, i.e. do not consider time. + * + * use_degrees. Parameter to + * decide if the trigonometric functions + * work in radians or degrees. The + * default for this parameter is false, + * i.e. use radians and not degrees. + */ void initialize(const std::string vars, const std::vector expressions, const ConstMap constants, @@ -363,8 +392,8 @@ class FunctionParser : public Function * defaults to zero, i.e. the * first component. */ - virtual double value (const Point &p, - const unsigned int component = 0) const; + virtual double value (const Point &p, + const unsigned int component = 0) const; /** * Return all components of a @@ -375,23 +404,23 @@ class FunctionParser : public Function * right size beforehand, * i.e. #n_components. */ - virtual void vector_value (const Point &p, - Vector &values) const; + virtual void vector_value (const Point &p, + Vector &values) const; - /** @addtogroup Exceptions - * @{ */ - DeclException2 (ExcParseError, - int, char*, - << "Parsing Error at Column " << arg1 - << ". The parser said: " << arg2); + /** @addtogroup Exceptions + * @{ */ + DeclException2 (ExcParseError, + int, char*, + << "Parsing Error at Column " << arg1 + << ". The parser said: " << arg2); - DeclException2 (ExcInvalidExpressionSize, - int, int, - << "The number of components (" << arg1 - << ") is not equal to the number of expressions (" - << arg2 << ")."); + DeclException2 (ExcInvalidExpressionSize, + int, int, + << "The number of components (" << arg1 + << ") is not equal to the number of expressions (" + << arg2 << ")."); - //@} + //@} private: /** * A pointer to the actual @@ -421,7 +450,7 @@ class FunctionParser : public Function * the variables parsed by the * initialize() method, then an * exception is thrown. - */ + */ unsigned int n_vars; };