From a93de94fa1241efd35465a547f063be0afbe08e5 Mon Sep 17 00:00:00 2001 From: David Wells Date: Thu, 5 Dec 2019 11:08:27 -0500 Subject: [PATCH] Clean up FunctionParser's documentation a bit. Reflow comments, use doxygen commands, improve some formatting. --- include/deal.II/base/function_parser.h | 57 ++++++++++++-------------- source/base/function_parser.cc | 35 ++++++---------- 2 files changed, 39 insertions(+), 53 deletions(-) diff --git a/include/deal.II/base/function_parser.h b/include/deal.II/base/function_parser.h index 34529dae0d..27e71cb1c4 100644 --- a/include/deal.II/base/function_parser.h +++ b/include/deal.II/base/function_parser.h @@ -91,8 +91,8 @@ class Vector; * @code * // set up problem: * std::string variables = "x,y"; - * std::string expression = "cos(x)+sqrt(y)"; - * std::map constants; + * std::string expression = "cos(x) + sqrt(y)"; + * std::map constants; * * // FunctionParser with 2 variables and 1 component: * FunctionParser<2> fp(1); @@ -113,7 +113,7 @@ class Vector; * The second example is a bit more complex: * @code * // Define some constants that will be used by the function parser - * std::map constants; + * std::map constants; * constants["pi"] = numbers::PI; * * // Define the variables that will be used inside the expressions @@ -162,7 +162,7 @@ class Vector; * at http://muparser.beltoforion.de/ . * * For a wrapper of the FunctionParser class that supports ParameterHandler, - * see ParsedFunction. + * see Functions::ParsedFunction. * * Vector-valued functions can either be declared using strings where the * function components are separated by semicolons, or using a vector of @@ -186,10 +186,8 @@ class Vector; * function.initialize(variables, * expression, * constants, - * true); // This tells the parser that - * // it is a time-dependent function - * // and there is another variable - * // to be taken into account (t). + * // Treat the last variable ("t") as time. + * true); * @endcode * * The following is another example of how to instantiate a vector valued @@ -222,13 +220,12 @@ class FunctionParser : public AutoDerivativeFunction { public: /** - * Constructor for parsed functions. Its arguments are the same of - * the base class Function, with the additional parameter @p h, used - * for the computation of gradients using finite differences. This - * object needs to be initialized with the 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. + * Constructor. Its arguments are the same of the base class Function, with + * the additional parameter @p h, used for the computation of gradients + * using finite differences. This object needs to be initialized with the + * 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, @@ -238,7 +235,7 @@ public: * Constructor for parsed functions. Takes directly a semi-colon separated * list of expressions (one for each component of the function), an optional * comma-separated list of constants, variable names and step size for the - * computation of first order derivatives by finite difference. + * computation of first order derivatives by finite differences. */ FunctionParser(const std::string &expression, const std::string &constants = "", @@ -289,9 +286,9 @@ public: using ConstMapIterator = ConstMap::iterator; /** - * Initialize the function. This methods accepts the following parameters: + * Initialize the object by setting the actual parsed functions. * - * vars: a string with the variables that will be used by the + * @param[in] 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 @@ -300,27 +297,27 @@ public: * 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). + * 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 + * @param[in] expressions a list of strings containing the expressions that + * will be byte compiled by the internal parser (muParser). 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 + * @param[in] 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. + * @param[in] time_dependent If this is a time dependent function, then the + * last variable declared in @p vars is assumed to be the time variable, and + * FunctionTime::get_time() is used to initialize it when evaluating the + * function. Naturally the number of variables parsed by initialize() in + * this case is dim+1. The value of this parameter defaults to false, i.e., + * do not consider time. */ void initialize(const std::string & vars, @@ -351,8 +348,8 @@ public: /** * Return the value of the function at the given point. Unless there is only - * one component (i.e. the function is scalar), you should state the - * component you want to have evaluated; it defaults to zero, i.e. the first + * one component (i.e., the function is scalar), you should state the + * component you want to have evaluated; it defaults to zero, i.e., the first * component. */ virtual double diff --git a/source/base/function_parser.cc b/source/base/function_parser.cc index 1c40150bfa..c9f27cd1b9 100644 --- a/source/base/function_parser.cc +++ b/source/base/function_parser.cc @@ -112,37 +112,26 @@ FunctionParser::initialize(const std::string & variables, AssertThrow(((time_dependent) ? dim + 1 : dim) == var_names.size(), ExcMessage("Wrong number of variables")); - // We check that the number of - // components of this function - // matches the number of components - // passed in as a vector of - // strings. + // We check that the number of components of this function matches the + // number of components passed in as a vector of strings. AssertThrow(this->n_components == expressions.size(), ExcInvalidExpressionSize(this->n_components, expressions.size())); - // Now we define how many variables - // we expect to read in. We - // distinguish between two cases: - // Time dependent problems, and not - // time dependent problems. In the - // first case the number of - // variables is given by the - // dimension plus one. In the other - // case, the number of variables is - // equal to the dimension. Once we - // parsed the variables string, if - // none of this is the case, then - // an exception is thrown. + // Now we define how many variables we expect to read in. We distinguish + // between two cases: Time dependent problems, and not time dependent + // problems. In the first case the number of variables is given by the + // dimension plus one. In the other case, the number of variables is equal + // to the dimension. Once we parsed the variables string, if none of this is + // the case, then an exception is thrown. if (time_dependent) n_vars = dim + 1; else n_vars = dim; - // create a parser object for the current thread we can then query - // in value() and vector_value(). this is not strictly necessary - // because a user may never call these functions on the current - // thread, but it gets us error messages about wrong formulas right - // away + // create a parser object for the current thread we can then query in + // value() and vector_value(). this is not strictly necessary because a user + // may never call these functions on the current thread, but it gets us + // error messages about wrong formulas right away init_muparser(); // finally set the initialization bit -- 2.39.5